Skip to content

feat(react): adopt selective WebAPI DOM types [Codex] - #165

Draft
jderochervlk wants to merge 3 commits into
rescript-lang:masterfrom
jderochervlk:feat/webapi-dom-upstream
Draft

jderochervlk wants to merge 3 commits into
rescript-lang:masterfrom
jderochervlk:feat/webapi-dom-upstream

Conversation

@jderochervlk

@jderochervlk jderochervlk commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Use WebAPI types in the React DOM bindings so elements, native events, event targets, clipboard data, touch lists, FormData, and files interoperate with WebAPI without identity casts.

Select WebAPI.DOMTree, WebAPI.History, WebAPI.Location, WebAPI.Touch, WebAPI.DataTransfer, and WebAPI.FormData. These features compile 27 WebAPI source modules; consumers can opt into additional operation modules.

Changes

  • Use WebAPI.DOMTree.element for roots, portals, refs, and DOM test helpers, and WebAPI history/location types in the router.
  • Give every event family precise native-event and target types. Convert nullable currentTarget, related targets, and UI/pointer view to options; expose pointer IDs as integers.
  • Return option<WebAPI.DataTransfer.t> from clipboard data getters and WebAPI.TouchList.t from touch-list getters.
  • Alias ReactDOM.FormData.t to WebAPI.FormData.t and files to WebAPI.DOM.file. Preserve React helper names and boxed String/File return variants while sharing FormData across form actions and status values.
  • Normalize nullable DOM queries and document bodies in ReactTestUtils.
  • Ship migration documentation and replace the disabled test command with isolated packed-consumer type, feature-selection, and JavaScript binding checks, including clipboard/touch contracts, FormData identity, and direct WebAPI dependency deduplication. CI uses lockfile installs.

These are public type changes. Event targets require runtime narrowing before element-specific access; callers must handle absent currentTarget, view, and clipboard data. Touch lists are not arrays, and React's boxed form values are distinct from WebAPI's unboxed entry values. JSX, style, and synthetic-event tag identities are unchanged.

Types versus operations

Inside @rescript/react, the WebAPI references in this change are type aliases and annotations. React's own externals remain in place: the router, DOM helpers, event getters, and FormData helpers are not rewritten to call WebAPI operations. The generated library JavaScript has no WebAPI module imports.

The shared types make WebAPI operations usable directly by consumers, without casts or conversion wrappers. The examples below use actual WebAPI bindings. Many such bindings are externals that compile to direct JavaScript property/method access rather than an extra runtime wrapper.

This is not entirely a type-only change: the nullable getter annotations normalize JavaScript null and undefined to ReScript None. Callers must handle the resulting options. React's boxed FormData String/File values are still distinct from WebAPI's unboxed entry values.

Consumer examples

Consumers that name WebAPI modules should add @rescript/webapi as a direct package dependency using the same pinned snapshot as React, and select the features they use in rescript.json. For the clipboard, touch, and FormData examples:

{
  "dependencies": [
    "@rescript/react",
    {
      "name": "@rescript/webapi",
      "features": ["WebAPI.DataTransfer", "WebAPI.Touch", "WebAPI.FormData"]
    }
  ]
}

Read clipboard text through a WebAPI binding. The React getter returns an optional DataTransfer; getData operates on the same value once present. The result is option<string>.

let clipboard = (event: ReactEvent.Clipboard.t): option<WebAPI.DataTransfer.t> =>
  event->ReactEvent.Clipboard.clipboardData

let clipboardText = (event: ReactEvent.Clipboard.t) =>
  event->clipboard->Option.map(data => data->WebAPI.DataTransfer.getData("text/plain"))

Access an individual touch. A TouchList is not an array. WebAPI's item binding returns a nullable Touch, which is null when the index is absent.

let touches = (event: ReactEvent.Touch.t): WebAPI.TouchList.t => event->ReactEvent.Touch.touches

let firstTouch = (event: ReactEvent.Touch.t): Null.t<WebAPI.Touch.t> =>
  event->touches->WebAPI.TouchList.item(0)

Use WebAPI FormData operations in a React form action. The action already receives a ReactDOM.FormData.t, which now shares its identity with WebAPI.FormData.t. No conversion is necessary; ReactDOM.Sync marks synchronous completion.

let action: ReactDOM.formStatusAction = form => {
  form->WebAPI.FormData.append(~name="action", ~value="called")
  ReactDOM.Sync
}

Pass a WebAPI element directly to React. For this example, additionally select WebAPI.DOMNodes in the consumer's WebAPI features to enable element operations. querySelector returns a nullable element; after converting it to an option, it can be passed straight to createRoot.

let createRootFromElement = (parent: WebAPI.Element.t) =>
  parent
  ->WebAPI.Element.querySelector("#root")
  ->Null.toOption
  ->Option.map(ReactDOM.Client.createRoot)

An event's target is still an EventTarget, not necessarily an Element. These shared types do not justify casting arbitrary event targets to elements.

Release dependency

This is a draft pending a published WebAPI version containing the selected features. The dependency currently uses immutable source snapshot 691bc3f20dc5d621d22f5bf9931b4ec086542d5f, with compiler/runtime requirements aligned to ReScript 13.0.0-alpha.7. Replace that snapshot with the corresponding published release and rerun the packed-consumer checks before landing for production.

Benchmark tools and raw measurements are maintained separately on the fork's existing feat/webapi-dom-profile branch; none are included in this branch. The comparison below measures the exact current source revision 14d7200.

Build measurements

Thirty runs per configuration and build mode, with randomized configuration order within each round. Medians in milliseconds:

Configuration Clean Cached no-op Single-file rebuild
Unchanged upstream, ReScript 12.3.1 132.81 46.46 78.95
Unchanged upstream, ReScript 13.0.0-alpha.7 87.81 43.70 64.49
This migration, ReScript 13.0.0-alpha.7 129.88 50.75 69.98

Against unchanged v13, this migration's medians are 47.9% higher for clean builds, 16.1% higher for cached builds, and 8.5% higher for single-file rebuilds. This is an interoperability/type-safety change, not a build-speed improvement. The migrated configuration requires v13 and was not run on v12.

The report documents source revisions, ranges, bootstrap intervals, and methodology limitations. Raw results retain all 270 samples and compiler output. OS caches, CPU affinity, and power settings were not controlled; the results describe this machine and these dependency revisions.

@pkg-pr-new

pkg-pr-new Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@rescript/react@165

commit: 14d7200

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant