Type-safe props, events, and refs for react-strict-dom

[yaminyassin]

Summary

This change replaces the $FlowFixMe suppressions with real types, moves the prop-building mutation out of the hook bodies so it stops fighting the React hook rules, and pins the result down with Flow tests.

This is a types-only change. It does not alter runtime behavior, so it can land on its own and be reviewed as such.

Motivation

$FlowFixMe is a checked-in promise to come back later. For the event props it had two costs:

1. No checking on handler arguments. onClick={(e) => e.tpye} typed clean.
2. No editor autocomplete on the event payload, so authors guessed field names
   or read the source.

The props are the public surface of the library. They are the right place to spend the type budget.

What changed

Event payloads are typed. A new StrictReactDOMEvents module holds the event shapes the native factories actually construct: change, input, key, click, and image load/error. Handlers whose runtime shape is defined by the platform (most pointer, mouse, touch, and clipboard events) use a single StrictOpaqueEventHandler instead of $FlowFixMe. The payload types are re-exported from the native and web entry points so consumers can annotate their own handlers.

Prop mutation moved out of the hooks. The native factories build their nativeProps by mutating an object (role defaults, the display:block emulation, the hidden polyfill). Doing that inside a hook body needed a react-rule-hook-mutation suppression. That logic now lives in plain helpers (applyViewProps, applyHtmlProps) that take the nativeProps and write to it directly, so the suppressions are gone.

HostInstance routes through the type boundary. types/renderer.native.js now exports HostInstance from react-native

How this improves DX

• Event handlers are checked. A typo in a payload field or a wrong handler signature is a Flow error at the call site, not a runtime surprise.
• Editors autocomplete the payload fields, so authors stop reading the source to find out what onChange hands them.
• The payload types ship from the package entrypoints, so a consumer can write (event: StrictChangeEvent) => void and have it stay in sync with the library.
• The hook bodies read as straight data flow now. The mutation helpers say what they own in their signatures instead of leaning on per-line suppressions.

Type safety in practice

A typo in a payload field is a Flow error where it is written, not a runtime undefined:

<html.input
  onChange={(event) => {
    setValue(event.target.valeu);
    //                  ^^^^^ Flow: property `valeu` is missing in StrictChangeEvent
  }}
/>;

The click payload carries the modifier and position fields it actually has, so reaching past them is caught:

<html.div
  onClick={(event) => {
    if (event.shiftKey) selectRange();   // ok
    event.preventDefault();              // ok
    console.log(event.clientX);
    //                ^^^^^^^ Flow: property `clientX` is missing (it is `pageX`)
  }}
/>;

Key handlers get a stable key field across platforms:

<html.input
  onKeyDown={(event) => {
    if (event.key === 'Enter') submit();
  }}
/>;

Annotating a handler defined outside JSX uses the exported payload types, which stay in sync with the library:

import { html } from 'react-strict-dom';
import type { StrictChangeEvent } from 'react-strict-dom';

function handleChange(event: StrictChangeEvent) {
  setValue(event.target.value);
}

<html.input onChange={handleChange} />;

A handler whose signature does not match the prop is rejected, so a web payload shape cannot be assumed on a strict element:

// Flow: expected (event: StrictChangeEvent) => void
<html.input onChange={(event: SyntheticEvent<HTMLInputElement>) => {}} />;

The opaque handlers still pass the event through, but unknown forces a check before use rather than handing back any:

<html.div
  onPointerMove={(event) => {
    // event: unknown — narrow before reading off it
    if (event != null && typeof event === 'object' && 'clientX' in event) {
      track(event.clientX);
    }
  }}
/>;

Compat Table

✅ means the native runtime wires the handler today; ⚪ means the type exists and the event passes through, but no native module wires it yet.

Handlers	Native	Web intent	Notes
onChange, onInput, onClick, onKeyDown, onLoad, onError	✅	re-synthesized	RSD builds a strict, narrowed payload: type + target.value, a stable key payload, or a normalized image load/error shape.
onPointer* (Down/Up/Move/Enter/Leave/Over/Out/Cancel), onGotPointerCapture, onLostPointerCapture	✅	pass-through (PointerEvent)	Raw pointer payload forwarded.
onTouchStart/End/Move/Cancel	✅	pass-through (TouchEvent)	Raw touch payload forwarded.
onMouseDown/Up/Enter/Leave/Over/Out	✅	pass-through (MouseEvent)	Raw mouse payload forwarded.
onBlur, onFocus	✅	pass-through (FocusEvent)	Raw focus payload forwarded.
onScroll (UIEvent), onSelectionChange (FormEvent)	✅	pass-through	Raw payload forwarded.
onAuxClick, onContextMenu, onMouseMove, onCopy, onCut, onPaste, onWheel, onKeyUp, onBeforeInput, onInvalid, onSelect, onFullscreenChange, onFullscreenError, onFocusIn, onFocusOut	⚪	pass-through	Forwarded; native runtime not wired yet.

Notes for reviewers

A few calls I would like a second opinion on:

1. The exported payload types (StrictChangeEvent, StrictClickEvent...) are new public API. If the names or shapes are wrong, now is the time to change them.
2. Should the ⚪ re-synthesized and pass-through handlers get concrete payload types now, or stay opaque until a native implementation wires each one?

[github-actions]

workflow: benchmarks/size

Comparison of minified (terser) and compressed (brotli) size results, measured in bytes. Smaller is better.

Results	Base	Patch	Ratio
react-strict-dom/dist/web/index.js
· compressed	3,251	3,251	1.00
· minified	10,375	10,375	1.00
react-strict-dom/dist/web/runtime.js
· compressed	1,645	1,645	1.00
· minified	4,131	4,131	1.00
react-strict-dom/dist/native/index.js
· compressed	16,618	16,718	1.01	+
· minified	64,626	65,007	1.01	+
react-strict-animated/dist/web/index.js
· compressed	6,861	6,861	1.00
· minified	23,486	23,486	1.00
react-strict-animated/dist/native/index.js
· compressed	797	797	1.00
· minified	2,518	2,518	1.00

[github-actions]

workflow: benchmarks/perf (native)

Comparison of performance test results, measured in operations per second. Larger is better.

Results	Base	Patch	Ratio
css.create
· small	1,147,965	1,141,587	0.99	-
· small with units	496,405	485,186	0.98	-
· small with variables	666,058	669,902	1.01	+
· several small	355,112	346,399	0.98	-
· large	201,309	195,875	0.97	-
· large with polyfills	147,568	145,891	0.99	-
· complex	101,224	100,017	0.99	-
· unsupported	208,848	207,596	0.99	-
css.createTheme
· simple theme	224,878	226,243	1.01	+
· polyfill theme	213,851	214,805	1.00	+