Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 68 additions & 4 deletions docs/content/docs/api-surface.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,9 @@ WebAPI.URL WebAPI.Fetch WebAPI.UIEvents
WebAPI.Observers WebAPI.Media WebAPI.WebAudio
WebAPI.Storage WebAPI.Messaging WebAPI.Workers
WebAPI.Crypto WebAPI.Performance WebAPI.ViewTransitions
WebAPI.DOMTree WebAPI.CSSOMCore
WebAPI.Touch WebAPI.DataTransfer WebAPI.FileEntries
WebAPI.FormData
WebAPI.History WebAPI.Location
WebAPI.SafeFetch
```
Expand Down Expand Up @@ -115,23 +118,73 @@ and depends only on the core `WebAPI.DOM` feature. `WebAPI.Window` includes both
features, so existing Window consumers keep the same API and type identities.

For React bindings that need element, event, window, document, history, and location
types without the complete Window API, select:
types without the DOM operation modules, select:

```json
{
"dependencies": [
{
"name": "@rescript/webapi",
"features": ["WebAPI.DOMNodes", "WebAPI.History", "WebAPI.Location"]
"features": ["WebAPI.DOMTree", "WebAPI.History", "WebAPI.Location"]
}
]
}
```

DOMNodes already includes DOM transitively. This selection does not expose
`WebAPI.Window` or `WebAPI.Document`; add `WebAPI.Window` if you need their methods.
DOMTree includes the lightweight DOM types and the shared CSSOMCore records.
It does not enable Element, Node, or HTMLCollection operation modules. The small
CSS declaration modules are kept intact, including their own operations. Select
DOMNodes for element/node operations and CSSOM for the complete CSS API,
and Window for Window or Document methods. Existing operation features include
their required type features automatically.
An unrestricted WebAPI dependency elsewhere in the dependency graph enables all features.

## Narrow touch, clipboard and form-data features

Select `WebAPI.Touch` for Touch/TouchList and `WebAPI.FormData` for FormData and
its unboxed string/file entry values. Each depends only on basic DOM and compiles
five source modules including that dependency.

`WebAPI.DataTransfer` includes its item/list APIs, DOMTree for `setDragImage`,
and `WebAPI.FileEntries` for the existing `webkitGetAsEntry` operation.
FileEntries is the five-module legacy entry family, not the modern filesystem
handle or stream APIs. UIEvents, Fetch, and File continue to include all their
previous modules through these smaller features.

For React bindings selecting DOMTree, History, and Location, adding Touch,
DataTransfer, and FormData selects **27 WebAPI source modules**, rather than
102 with broad UIEvents and Fetch. These are source counts, not speed claims.
Basic DOM is unchanged. FileList operations still require WebAPI.File; a
DataTransfer's `files` field exposes the core file-list type and its length.

```json
{
"dependencies": [
{
"name": "@rescript/webapi",
"features": [
"WebAPI.DOMTree",
"WebAPI.History",
"WebAPI.Location",
"WebAPI.Touch",
"WebAPI.DataTransfer",
"WebAPI.FormData"
]
}
]
}
```

Use `Touch.init` for constructor options and `Touch.Direct` / `Touch.Stylus`
for its touch-type variant. Existing broad event and fetch APIs accept these
same types without casts. FormDataEntryValue remains an **unboxed** union;
it is not interchangeable with a separately defined boxed React variant.

The declared private empty FormData representation is unchanged. ReScript
13.0.0-alpha.7 still accepts an empty-record literal for this type, as it did
before this split; use the FormData constructor rather than constructing records.
The split does not claim to fix that existing compiler limitation.

## Fetch

Use `WebAPI.Fetch.fetch` for string URLs and `WebAPI.Fetch.fetchWithRequest`
Expand Down Expand Up @@ -434,6 +487,17 @@ let redirect = WebAPI.Response.redirect(~url="/login", ~status=302)

## DOM

`WebAPI.DOM` stays lightweight: it supplies basic types such as window, document,
and event without pulling in the rich element or CSS declaration records.
`WebAPI.DOMTree` is the independently selectable rich DOM type surface, including
recursive element fields and HTML element styles. `WebAPI.CSSOMCore` supplies
the required CSS declaration modules without selecting Event or DOMTree.

```ReScript
let parentNode = (element: WebAPI.DOMTree.element) => element.parentNode
let style = (element: WebAPI.DOMTree.htmlElement) => element.style
```

DOM values are operated on through public interface modules.

```ReScript
Expand Down
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@
"check:consumer": "node scripts/check-consumer.mjs",
"check:release": "node --test scripts/validate-release-artifact.test.mjs scripts/check-release.test.mjs && node scripts/check-release.mjs",
"check:docs-links": "node --test scripts/check-doc-links.test.mjs scripts/check-doc-type-links.test.mjs && node scripts/check-doc-links.mjs",
"format": "rescript format && oxfmt ./tests/index.js ./tests/fixtures.json ./tests/browser/*.mjs ./scripts/negative-fixtures.json ./scripts/validate-release-artifact.mjs ./scripts/validate-release-artifact.test.mjs ./playwright.config.mjs ./astro.config.mjs ./scripts/check-consumer.mjs ./scripts/check-release.mjs ./scripts/check-release.test.mjs ./scripts/check-features.mjs ./scripts/check-features.test.mjs ./scripts/check-doc-links.mjs ./scripts/check-doc-links.test.mjs ./scripts/check-doc-type-links.test.mjs ./package.json ./README.md ./CHANGELOG.md ./docs && prettier --write .github/workflows/*.yml ./docs/pages",
"format:check": "rescript format --check && oxfmt ./tests/index.js ./tests/fixtures.json ./tests/browser/*.mjs ./scripts/negative-fixtures.json ./scripts/validate-release-artifact.mjs ./scripts/validate-release-artifact.test.mjs ./playwright.config.mjs ./astro.config.mjs ./scripts/check-consumer.mjs ./scripts/check-release.mjs ./scripts/check-release.test.mjs ./scripts/check-features.mjs ./scripts/check-features.test.mjs ./scripts/check-doc-links.mjs ./scripts/check-doc-links.test.mjs ./scripts/check-doc-type-links.test.mjs ./package.json ./README.md ./CHANGELOG.md ./docs --check && prettier --check .github/workflows/*.yml ./docs/pages",
"format": "rescript format && oxfmt ./tests/index.js ./tests/fixtures.json ./tests/browser/*.mjs ./scripts/negative-fixtures.json ./scripts/validate-release-artifact.mjs ./scripts/validate-release-artifact.test.mjs ./playwright.config.mjs ./astro.config.mjs ./scripts/check-consumer.mjs ./scripts/check-release.mjs ./scripts/check-release.test.mjs ./scripts/check-features.mjs ./scripts/check-features.test.mjs ./scripts/data-feature-consumers.mjs ./scripts/check-doc-links.mjs ./scripts/check-doc-links.test.mjs ./scripts/check-doc-type-links.test.mjs ./package.json ./README.md ./CHANGELOG.md ./docs && prettier --write .github/workflows/*.yml ./docs/pages",
"format:check": "rescript format --check && oxfmt ./tests/index.js ./tests/fixtures.json ./tests/browser/*.mjs ./scripts/negative-fixtures.json ./scripts/validate-release-artifact.mjs ./scripts/validate-release-artifact.test.mjs ./playwright.config.mjs ./astro.config.mjs ./scripts/check-consumer.mjs ./scripts/check-release.mjs ./scripts/check-release.test.mjs ./scripts/check-features.mjs ./scripts/check-features.test.mjs ./scripts/data-feature-consumers.mjs ./scripts/check-doc-links.mjs ./scripts/check-doc-links.test.mjs ./scripts/check-doc-type-links.test.mjs ./package.json ./README.md ./CHANGELOG.md ./docs --check && prettier --check .github/workflows/*.yml ./docs/pages",
"docs": "astro dev",
"prebuild:docs": "node docs/llm.js",
"build:docs": "astro build"
Expand Down
71 changes: 48 additions & 23 deletions rescript.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,11 @@
"WebAPI.DOMPlatform": ["WebAPI.Event", "DOMPlatform"],
"WebAPI.Animation": ["WebAPI.Event", "Animation"],
"WebAPI.Geometry": ["WebAPI.DOM", "Geometry"],
"WebAPI.CSSOM": ["WebAPI.Event", "CSSOM"],
"WebAPI.CSSOMCore": ["CSSOMCore"],
"WebAPI.CSSOM": ["WebAPI.Event", "WebAPI.CSSOMCore", "CSSOM"],
"WebAPI.DOMTree": ["WebAPI.DOM", "WebAPI.CSSOMCore", "DOMTree"],
"WebAPI.DOMNodes": [
"WebAPI.DOMTree",
"WebAPI.DOMPlatform",
"WebAPI.Animation",
"WebAPI.CSSOM",
Expand Down Expand Up @@ -41,7 +44,9 @@
"WebAPI.Geometry",
"Observers"
],
"WebAPI.UIEvents": ["WebAPI.DOMNodes", "WebAPI.File", "UIEvents"],
"WebAPI.Touch": ["WebAPI.DOM", "Touch"],
"WebAPI.DataTransfer": ["WebAPI.DOMTree", "WebAPI.FileEntries", "DataTransfer"],
"WebAPI.UIEvents": ["WebAPI.DOMNodes", "WebAPI.File", "WebAPI.Touch", "WebAPI.DataTransfer", "UIEvents"],
"WebAPI.Canvas": [
"WebAPI.Geometry",
"WebAPI.HTML",
Expand All @@ -59,9 +64,11 @@
"WebAPI.Workers",
"Navigator"
],
"WebAPI.File": ["WebAPI.Event", "File"],
"WebAPI.FileEntries": ["WebAPI.DOM", "FileEntries"],
"WebAPI.File": ["WebAPI.Event", "WebAPI.FileEntries", "File"],
"WebAPI.URL": ["WebAPI.DOM", "URL"],
"WebAPI.Fetch": ["WebAPI.Event", "WebAPI.File", "WebAPI.URL", "Fetch"],
"WebAPI.FormData": ["WebAPI.DOM", "FormData"],
"WebAPI.Fetch": ["WebAPI.Event", "WebAPI.File", "WebAPI.URL", "WebAPI.FormData", "Fetch"],
"WebAPI.SafeFetch": ["WebAPI.Fetch", "SafeFetch"],
"WebAPI.CSSFontLoading": ["WebAPI.Event", "CSSFontLoading"],
"WebAPI.Device": ["WebAPI.Event", "Device"],
Expand Down Expand Up @@ -90,6 +97,18 @@
"DOMTokenList"
]
},
{
"dir": "src/cssom-core",
"subdirs": true,
"feature": "CSSOMCore",
"public": ["CSSStyleDeclaration", "CSSStyleValue", "MediaList", "StylePropertyMap", "StylePropertyMapReadOnly", "StyleSheet", "StyleSheetList"]
},
{
"dir": "src/dom-tree",
"subdirs": true,
"feature": "DOMTree",
"public": ["DOMTree"]
},
{
"dir": "src/dom-nodes",
"subdirs": true,
Expand All @@ -102,7 +121,6 @@
"CharacterData",
"Comment",
"DOMImplementation",
"DOMTree",
"DocumentFragment",
"Element",
"ElementInternals",
Expand Down Expand Up @@ -138,14 +156,7 @@
"feature": "CSSOM",
"public": [
"CSSRuleList",
"CSSStyleDeclaration",
"CSSStyleValue",
"MediaList",
"MediaQueryList",
"StylePropertyMap",
"StylePropertyMapReadOnly",
"StyleSheet",
"StyleSheetList"
"MediaQueryList"
]
},
{
Expand Down Expand Up @@ -343,8 +354,6 @@
"public": [
"BodyInit",
"Fetch",
"FormData",
"FormDataEntryValue",
"Headers",
"HeadersInit",
"Request",
Expand All @@ -365,10 +374,7 @@
"Blob",
"File",
"FileList",
"FileSystemDirectoryEntry",
"FileSystemDirectoryHandle",
"FileSystemDirectoryReader",
"FileSystemEntry",
"FileSystemFileHandle",
"FileSystemHandle",
"FileSystemWritableFileStream",
Expand Down Expand Up @@ -481,23 +487,42 @@
"WorkerLocation"
]
},
{
"dir": "src/touch",
"subdirs": true,
"feature": "Touch",
"public": ["Touch", "TouchList"]
},
{
"dir": "src/form-data",
"subdirs": true,
"feature": "FormData",
"public": ["FormData", "FormDataEntryValue"]
},
{
"dir": "src/file-entries",
"subdirs": true,
"feature": "FileEntries",
"public": ["FileSystemEntry", "FileSystemDirectoryEntry", "FileSystemDirectoryReader"]
},
{
"dir": "src/data-transfer",
"subdirs": true,
"feature": "DataTransfer",
"public": ["DataTransfer", "DataTransferItem", "DataTransferItemList"]
},
{
"dir": "src/ui-events",
"subdirs": true,
"feature": "UIEvents",
"public": [
"CompositionEvent",
"DataTransfer",
"DataTransferItem",
"DataTransferItemList",
"FocusEvent",
"InputEvent",
"KeyboardEvent",
"MouseEvent",
"PointerEvent",
"Touch",
"TouchEvent",
"TouchList",
"UIEvent",
"WheelEvent"
]
Expand Down
21 changes: 21 additions & 0 deletions scripts/check-consumer.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import os from "node:os";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { validateReleaseArtifact } from "./validate-release-artifact.mjs";
import { dataFeatureConsumers } from "./data-feature-consumers.mjs";

const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const packageJson = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8"));
Expand Down Expand Up @@ -193,6 +194,14 @@ const checkConsumers = async () => {

if (!negativeOnly) {
const scenarios = [
...dataFeatureConsumers.map((consumer) => ({
...consumer,
fixture: `scripts/${consumer.fixture}`,
expectedFailure:
consumer.missingModule === undefined
? null
: `The module or file WebAPI.${consumer.missingModule} can\'t be found.`,
})),
{ name: "default", fixture: "scripts/consumer-default.res", features: null },
{
name: "concrete public types",
Expand Down Expand Up @@ -240,6 +249,18 @@ const checkConsumers = async () => {
projectDirectory,
);
console.log(`[ok] packed consumer runtime using ReScript ${compilerVersion}`);
writeProject(projectDirectory, "scripts/consumer-data-form-runtime.res", ["WebAPI.FormData"]);
compile(projectDirectory);
runCommand(
process.execPath,
[
"--input-type=module",
"--eval",
`await import(${JSON.stringify(pathToFileURL(path.join(projectDirectory, "src/Consumer.js")).href)} + "?formdata")`,
],
projectDirectory,
);
console.log("[ok] packed narrow FormData runtime");
}

const negativeCases = JSON.parse(
Expand Down
Loading
Loading