@octanejs/radix 0.1.2 → 0.1.3

package/README.md

@@ -1,7 +1,7 @@
 # @octanejs/radix
 
 [Radix UI Primitives](https://www.radix-ui.com/primitives) for the
-[octane](https://github.com/octanejs/octane) renderer — a port of
+[octane](https://github.com/octanejs/octane) UI framework — a port of
 [`@radix-ui/react`](https://www.npmjs.com/org/radix-ui) (headless, accessible UI
 primitives) on octane's hooks. It mirrors the unified `radix-ui` package's shape: the
 low-level composition utilities are exported directly, and each component is a namespace
@@ -98,3 +98,9 @@ Remaining (documented in
 coverage for the overlay/portal components and Phase-5 polish. The port surfaced —
 and fixed, in octane itself — fourteen runtime/compiler parity bugs along the way;
 each is pinned by an octane regression test and a changeset.
+
+## Status
+
+Current scope, known divergences, and verification status are tracked in the
+generated [bindings status table](../../docs/bindings-status.md), sourced from
+this package's [`status.json`](./status.json).

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@octanejs/radix",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "type": "module",
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
   "description": "Radix UI Primitives for the octane renderer — a port of @radix-ui/react (headless, accessible UI primitives) on octane's hooks, built on the same @octanejs/floating-ui substrate.",
   "author": {
     "name": "Dominic Gannaway",
@@ -28,11 +35,11 @@
   },
   "dependencies": {
     "aria-hidden": "^1.2.6",
-    "@octanejs/floating-ui": "0.1.2",
-    "octane": "0.1.3"
+    "@octanejs/floating-ui": "0.1.3",
+    "octane": "0.1.4"
   },
   "devDependencies": {
-    "@tsrx/react": "^0.2.33",
+    "@tsrx/react": "^0.2.37",
     "esbuild": "^0.28.1",
     "radix-ui": "^1.4.3",
     "react": "^19.2.0",

package/src/Checkbox.ts

@@ -2,15 +2,14 @@
 // .radix-primitives/packages/react/checkbox/src/checkbox.tsx). A `role=checkbox` button
 // (with `indeterminate` support) that — when inside a form — renders a hidden native
 // checkbox "bubble input" so native form machinery (FormData, validation, reset,
-// change listeners) reflects the state. The bubble input is uncontrolled; state syncs
-// imperatively via the native `checked` property setter + dispatched events.
+// change listeners) reflects the state.
 //
-// octane adaptations (documented; both stem from octane's native-event /
-// no-controlled-inputs model — see docs/react-parity-migration-plan.md):
+// octane adaptations (documented; see docs/react-parity-migration-plan.md):
 // - React's synthetic `event.isPropagationStopped()` → native `event.cancelBubble`.
-// - `defaultChecked` prop → the native `checked` ATTRIBUTE (HTML's default-state
-//   semantics; live state is driven through the property setter, which never touches
-//   the attribute).
+// - The source's uncontrolled bubble input (`defaultChecked` + prototype-descriptor
+//   `checked` writes) → a live CONTROLLED `checked` prop: octane's React-parity
+//   controlled form components write the DOM property at commit and reassert it after
+//   every event flush, so the bubble effect only dispatches events.
 // - The bubble effect ALSO dispatches a native `change` event after the source's
 //   `click`: React forms observe checkbox clicks through synthetic `onChange`, which
 //   octane doesn't have — a native bubbling `change` gives octane `<form onChange>`
@@ -230,7 +229,6 @@ export function BubbleInput(props: any): any {
 		control,
 		hasConsumerStoppedPropagationRef,
 		checked,
-		defaultChecked,
 		required,
 		disabled,
 		name,
@@ -244,23 +242,18 @@ export function BubbleInput(props: any): any {
 	const prevChecked = usePrevious(checked, subSlot(slot, 'prev'));
 	const controlSize = useSize(control, subSlot(slot, 'size'));
 
-	// Bubble checked change to parents (e.g form change event)
+	// Bubble checked change to parents (e.g form change event). The controlled
+	// `checked` prop below keeps the input's DOM state in sync, so — unlike the
+	// source's uncontrolled input — this effect only dispatches the events
+	// (`indeterminate` stays imperative: it is property-only, as in the source).
 	useEffect(
 		() => {
 			const input = bubbleInput;
 			if (!input) return;
 
-			const inputProto = window.HTMLInputElement.prototype;
-			const descriptor = Object.getOwnPropertyDescriptor(
-				inputProto,
-				'checked',
-			) as PropertyDescriptor;
-			const setChecked = descriptor.set;
-
 			const bubbles = !hasConsumerStoppedPropagationRef.current;
-			if (prevChecked !== checked && setChecked) {
+			if (prevChecked !== checked) {
 				input.indeterminate = isIndeterminate(checked);
-				setChecked.call(input, isIndeterminate(checked) ? false : checked);
 				input.dispatchEvent(new Event('click', { bubbles }));
 				// octane adaptation: also fire the native `change` React's synthetic
 				// onChange would have synthesised from the click (see file header).
@@ -271,16 +264,13 @@ export function BubbleInput(props: any): any {
 		subSlot(slot, 'e:bubble'),
 	);
 
-	const defaultCheckedRef = useRef(
-		isIndeterminate(checked) ? false : checked,
-		subSlot(slot, 'default'),
-	);
 	return createElement(Primitive.input, {
 		type: 'checkbox',
 		'aria-hidden': true,
-		// octane: the native `checked` ATTRIBUTE is HTML's default-checked state (there is
-		// no `defaultChecked` prop outside React's controlled model).
-		checked: (defaultChecked ?? defaultCheckedRef.current) || undefined,
+		// Live CONTROLLED checked (octane React-parity): the runtime writes the DOM
+		// property, mirrors only the INITIAL state to the attribute, and reasserts
+		// the property on every commit / after event flushes.
+		checked: isIndeterminate(checked) ? false : checked,
 		required,
 		disabled,
 		name,

package/src/OneTimePasswordField.ts

@@ -16,12 +16,11 @@
 //   with the corresponding user prop via `composeEventHandlers` (React fires them in that
 //   order for a native `input` event). The user's `onChange` prop is therefore folded
 //   into the `input` binding and NOT bound to native `change` (native change = commit).
-// - React's CONTROLLED `value={char}` cell has no octane equivalent (octane inputs are
-//   uncontrolled and native): the `value` prop renders as the native attribute, a layout
-//   effect imperatively syncs the DOM `.value` property whenever the cell's char state
-//   changes, and the composed input handler ends with React's controlled-value
-//   REASSERTION (restore `.value` to the state char when they diverge — e.g. an invalid
-//   character that produced no state change).
+// - React's CONTROLLED `value={char}` cell maps directly onto octane's controlled
+//   `value` prop (React-parity controlled form components): the runtime writes the DOM
+//   `.value` property at commit, reasserts it on every commit of the owning block, and
+//   restores it after each native event flush (React's controlled-value restoration —
+//   e.g. an invalid character that produced no state change snaps back automatically).
 // - The source's `unstable_createCollection` (state-backed, `.at`/`.from`/`.size`/
 //   `.indexOf`) has no shared octane port (the shared collection.ts is the legacy API,
 //   which registers items in passive effects and never re-renders consumers). Since the
@@ -638,24 +637,10 @@ export function OneTimePasswordFieldInput(props: any): any {
 		setElement,
 		subSlot(slot, 'refs'),
 	);
+	// The cell's `value={char}` is live CONTROLLED (octane React-parity): the runtime
+	// keeps the DOM `.value` in sync and restores it after event flushes — no
+	// imperative sync or post-handler reassertion needed here.
 	const char = context.value[index] ?? '';
-	// Latest char for the post-handler controlled-value reassertion (octane adaptation).
-	const charRef = useRef(char, subSlot(slot, 'char'));
-	charRef.current = char;
-
-	// octane adaptation: React's controlled `value={char}` → imperative `.value` property
-	// sync when the cell's state char changes (the attribute alone can't update a dirty
-	// input).
-	useLayoutEffect(
-		() => {
-			const input = inputRef.current;
-			if (input && input.value !== char) {
-				input.value = char;
-			}
-		},
-		[char],
-		subSlot(slot, 'e:value'),
-	);
 
 	const keyboardActionTimeoutRef = useRef<number | null>(null, subSlot(slot, 'timeout'));
 	useEffect(
@@ -807,16 +792,12 @@ export function OneTimePasswordFieldInput(props: any): any {
 					}
 				}),
 				// octane adaptation: ONE native `input` binding runs the source's onInput
-				// logic then its onChange logic (React's order for a native input event),
-				// then re-asserts the controlled value (React's controlled-input
-				// restoration, which runs regardless of handler outcomes).
+				// logic then its onChange logic (React's order for a native input event).
+				// React's controlled-input restoration is the runtime's: after the event
+				// flush, the controlled `value` snaps the DOM back to the rendered char.
 				onInput: (event: Event) => {
 					composeEventHandlers(onInputProp, handleInput)(event);
 					composeEventHandlers(onChangeProp, handleChange)(event);
-					const input = inputRef.current;
-					if (input && input.value !== charRef.current) {
-						input.value = charRef.current;
-					}
 				},
 				onKeyDown: composeEventHandlers(props?.onKeyDown, (event: KeyboardEvent) => {
 					switch (event.key) {

package/src/Radio.ts

@@ -1,10 +1,12 @@
 // Ported from @radix-ui/react-radio-group's internal radio (source:
 // .radix-primitives/packages/react/radio-group/src/radio.tsx). The single-radio
 // building block RadioGroup composes: a `role=radio` button + Presence indicator +
-// the hidden native-radio "bubble input" (same machinery as Checkbox). Same octane
-// adaptations as Checkbox.ts: `isPropagationStopped()` → `event.cancelBubble`;
-// `defaultChecked` → the native `checked` attribute; a native `change` dispatched
-// alongside the source's `click`.
+// the hidden native-radio "bubble input" (same machinery as Checkbox — a live
+// CONTROLLED `checked` prop keeps the DOM in sync, the bubble effect only dispatches
+// events). Same octane adaptations as Checkbox.ts: `isPropagationStopped()` →
+// `event.cancelBubble`; the source's uncontrolled input + descriptor `checked` writes
+// → octane's controlled `checked`; a native `change` dispatched alongside the
+// source's `click`.
 import { createElement, useEffect, useRef, useState } from 'octane';
 
 import { composeEventHandlers } from './compose-event-handlers';
@@ -199,22 +201,16 @@ export function RadioBubbleInput(props: any): any {
 	const prevChecked = usePrevious(checked, subSlot(slot, 'prev'));
 	const controlSize = useSize(control, subSlot(slot, 'size'));
 
-	// Bubble checked change to parents (e.g form change event)
+	// Bubble checked change to parents (e.g form change event). The controlled
+	// `checked` prop below keeps the input's DOM state in sync, so this effect
+	// only dispatches the events (see Checkbox.ts).
 	useEffect(
 		() => {
 			const input = bubbleInput;
 			if (!input) return;
 
-			const inputProto = window.HTMLInputElement.prototype;
-			const descriptor = Object.getOwnPropertyDescriptor(
-				inputProto,
-				'checked',
-			) as PropertyDescriptor;
-			const setChecked = descriptor.set;
-
 			const bubbles = !hasConsumerStoppedPropagationRef.current;
-			if (prevChecked !== checked && setChecked) {
-				setChecked.call(input, checked);
+			if (prevChecked !== checked) {
 				input.dispatchEvent(new Event('click', { bubbles }));
 				// octane adaptation: also fire the native `change` (see Checkbox.ts header).
 				input.dispatchEvent(new Event('change', { bubbles }));
@@ -224,12 +220,12 @@ export function RadioBubbleInput(props: any): any {
 		subSlot(slot, 'e:bubble'),
 	);
 
-	const defaultCheckedRef = useRef(checked, subSlot(slot, 'default'));
 	return createElement(Primitive.input, {
 		type: 'radio',
 		'aria-hidden': true,
-		// octane: native `checked` attribute = default-checked state (see Checkbox.ts).
-		checked: defaultCheckedRef.current || undefined,
+		// Live CONTROLLED checked (octane React-parity — see Checkbox.ts). The runtime's
+		// event-restore also re-syncs radio-group cousins after a dispatched `click`.
+		checked,
 		required,
 		disabled,
 		name,

package/src/Select.ts

@@ -18,13 +18,13 @@
 // - `SelectValue`'s `<React.Fragment key={placeholder|value}>` remount trick is dropped:
 //   octane's value-hole reconciliation replaces the placeholder/value content directly.
 // - The bubble `<select>`: React's `defaultValue={selectValue}` + `key={nativeSelectKey}`
-//   (re-built so the default option associates) has no octane equivalent (octane has no
-//   controlled/default-value model — inputs are native). Instead the select's `value` is
-//   synced imperatively: a silent property write whenever the rendered option set changes
-//   (mount/late option registration), while actual value CHANGES go through the native
-//   `value` setter + a dispatched bubbling `change` event (as in the source) so octane
-//   `<form onChange>` observes them. React's synthetic `onChange` on the select is the
-//   native `change` event (a `<select>` is not a text input, so no `onInput` remap).
+//   (re-built so the default option associates) → a live CONTROLLED `value` prop:
+//   octane's React-parity controlled form components re-project a select's value onto
+//   its options at every commit (so late-registering options associate without a
+//   rebuild) and restore it after event flushes. Value CHANGES additionally dispatch a
+//   bubbling native `change` event (as in the source) so octane `<form onChange>`
+//   observes them. React's synthetic `onChange` on the select is the native `change`
+//   event (a `<select>` is not a text input, so no `onInput` remap).
 // - jsdom-environment guards (same class as use-size.ts's ResizeObserver guard; no
 //   behavior change in browsers): `hasPointerCapture`/`releasePointerCapture` and
 //   `scrollIntoView` are called only when they exist.
@@ -113,7 +113,6 @@ interface SelectContextValue {
 	form?: string;
 	// Native `<option>` element descriptors registered by mounted ItemTexts.
 	nativeOptions: Set<any>;
-	nativeSelectKey: string;
 	isFormControl: boolean;
 }
 
@@ -181,14 +180,6 @@ export function Provider(props: any): any {
 	);
 	const contentId = useId(subSlot(slot, 'contentId'));
 
-	// The native `select` only associates the correct default value if the corresponding
-	// `option` is rendered as a child **at the same time** as itself. Because it might take
-	// a few renders for our items to gather the information to build the native `option`(s),
-	// this key tracks the option set (the bubble select re-syncs its value off it).
-	const nativeSelectKey = Array.from(nativeOptionsSet)
-		.map((option: any) => option?.props?.value)
-		.join(';');
-
 	const handleNativeOptionAdd = useCallback(
 		(option: any) => {
 			setNativeOptionsSet((prev: Set<any>) => new Set(prev).add(option));
@@ -229,7 +220,6 @@ export function Provider(props: any): any {
 		autoComplete,
 		form,
 		nativeOptions: nativeOptionsSet,
-		nativeSelectKey,
 		isFormControl,
 	};
 
@@ -1690,7 +1680,7 @@ export function BubbleInput(props: any): any {
 	const { __scopeSelect, ref: forwardedRef, ...selectProps } = props ?? {};
 	const context = useSelectContext(BUBBLE_INPUT_NAME, __scopeSelect);
 	const { value, onValueChange, required, disabled, name, autoComplete, form } = context;
-	const { nativeOptions, nativeSelectKey } = context;
+	const { nativeOptions } = context;
 	const ref = useRef<HTMLSelectElement | null>(null, subSlot(slot, 'ref'));
 	const composedRefs = useComposedRefs(forwardedRef, ref, subSlot(slot, 'refs'));
 	const selectValue = value ?? '';
@@ -1704,49 +1694,32 @@ export function BubbleInput(props: any): any {
 		(option: any) => (option?.props?.value ?? '') === '',
 	);
 
-	// Bubble value change to parents (e.g form change event)
+	// Bubble value change to parents (e.g form change event). The controlled
+	// `value` prop below keeps the select's DOM selection in sync (octane
+	// re-projects it at every commit, covering mount + late option registration
+	// — the source's `key={nativeSelectKey}` rebuild), so this effect only
+	// dispatches the event.
 	useEffect(
 		() => {
 			const select = ref.current;
 			if (!select) return;
 
-			const selectProto = window.HTMLSelectElement.prototype;
-			const descriptor = Object.getOwnPropertyDescriptor(
-				selectProto,
-				'value',
-			) as PropertyDescriptor;
-			const setValue = descriptor.set;
-			if (prevValue !== selectValue && setValue) {
-				const event = new Event('change', { bubbles: true });
-				setValue.call(select, selectValue);
-				select.dispatchEvent(event);
+			if (prevValue !== selectValue) {
+				select.dispatchEvent(new Event('change', { bubbles: true }));
 			}
 		},
 		[prevValue, selectValue],
 		subSlot(slot, 'e:bubble'),
 	);
 
-	// octane adaptation: React associates the default value by re-building the keyed
-	// `select` with `defaultValue` each time the option set changes; octane's native-input
-	// model has no defaultValue, so silently sync the `value` property once the rendered
-	// options can represent it (mount + whenever the option set changes).
-	useEffect(
-		() => {
-			const select = ref.current;
-			if (select && select.value !== selectValue) {
-				select.value = selectValue;
-			}
-		},
-		[nativeSelectKey, selectValue],
-		subSlot(slot, 'e:default'),
-	);
-
 	/**
 	 * We purposefully use a `select` here to support form autofill as much as
 	 * possible.
 	 *
-	 * We purposefully do not set the `value` attribute here to allow the value
-	 * to be set programmatically and bubble to any parent form `onChange` event.
+	 * The `value` is live CONTROLLED (octane React-parity): the runtime projects
+	 * it onto the options at every commit and restores it after event flushes;
+	 * value changes still bubble to any parent form `onChange` via the `change`
+	 * event dispatched above.
 	 *
 	 * We use visually hidden styles rather than `display: "none"` because
 	 * Safari autofill won't work otherwise.
@@ -1759,6 +1732,7 @@ export function BubbleInput(props: any): any {
 		autoComplete,
 		disabled,
 		form,
+		value: selectValue,
 		// React's synthetic onChange on a `<select>` is the native `change` event.
 		onChange: (event: Event) => onValueChange((event.target as HTMLSelectElement).value),
 		...selectProps,

package/src/Slider.ts

@@ -4,9 +4,10 @@
 // Horizontal/Vertical orientation layers translate pointer positions and step keys;
 // Impl owns pointer capture + slide events; Track/Range/Thumb render the parts (thumb
 // positions are percentage-based with an in-bounds offset). Each Thumb renders a
-// hidden native input "bubble input" inside forms (value synced via the native
-// `value` setter + a dispatched bubbling `input` event — octane's native `<form
-// onInput>` observes it directly, so no extra adaptation is needed here).
+// hidden native input "bubble input" inside forms (a live CONTROLLED `value` — octane's
+// React-parity controlled form components keep the DOM property in sync — plus a
+// dispatched bubbling `input` event, which octane's native `<form onInput>` observes
+// directly, so no extra adaptation is needed here).
 import { createElement, useEffect, useMemo, useRef, useState } from 'octane';
 
 import { createCollection } from './collection';
@@ -588,19 +589,16 @@ export function BubbleInput(props: any): any {
 	const composedRefs = useComposedRefs(ref, forwardedRef, subSlot(slot, 'refs'));
 	const prevValue = usePrevious(value, subSlot(slot, 'prev'));
 
-	// Bubble value change to parents (e.g form change event)
+	// Bubble value change to parents (e.g form change event). The controlled
+	// `value` prop below keeps the input's DOM value in sync (commit-time
+	// property write + reassert), so this effect only dispatches the event.
 	useEffect(
 		() => {
 			const input = ref.current;
 			if (!input) return;
 
-			const inputProto = window.HTMLInputElement.prototype;
-			const descriptor = Object.getOwnPropertyDescriptor(inputProto, 'value') as PropertyDescriptor;
-			const setValue = descriptor.set;
-			if (prevValue !== value && setValue) {
-				const event = new Event('input', { bubbles: true });
-				setValue.call(input, value);
-				input.dispatchEvent(event);
+			if (prevValue !== value) {
+				input.dispatchEvent(new Event('input', { bubbles: true }));
 			}
 		},
 		[prevValue, value],
@@ -610,10 +608,10 @@ export function BubbleInput(props: any): any {
 	// We purposefully do not use `type="hidden"` here otherwise forms that wrap it
 	// will not be able to access its value via the FormData API.
 	//
-	// octane: the source omits React's `value` prop (its controlled model would
-	// swallow the programmatic dispatch) and uses `defaultValue`; the octane
-	// equivalent of default-value semantics is the native `value` ATTRIBUTE, which
-	// the property setter above never touches.
+	// octane: the source uses `defaultValue` + a prototype-descriptor `value` write
+	// (React's controlled model would swallow the programmatic dispatch); octane's
+	// live CONTROLLED `value` has no such conflict — the runtime keeps the DOM
+	// property in sync and the effect above dispatches the bubbling `input` event.
 	return createElement(Primitive.input, {
 		style: { display: 'none' },
 		name,

package/src/Switch.ts

@@ -1,10 +1,11 @@
 // Ported from @radix-ui/react-switch (source:
 // .radix-primitives/packages/react/switch/src/switch.tsx). A `role=switch` button with
 // a Thumb; inside a form it renders the hidden native-checkbox "bubble input" (same
-// machinery as Checkbox — uncontrolled input, imperative `checked` setter + dispatched
-// events). Same octane adaptations as Checkbox.ts: `isPropagationStopped()` →
-// `event.cancelBubble`; `defaultChecked` → the native `checked` attribute; a native
-// `change` dispatched alongside the source's `click`.
+// machinery as Checkbox — a live CONTROLLED `checked` prop keeps the DOM in sync, the
+// bubble effect only dispatches events). Same octane adaptations as Checkbox.ts:
+// `isPropagationStopped()` → `event.cancelBubble`; the source's uncontrolled input +
+// descriptor `checked` writes → octane's controlled `checked`; a native `change`
+// dispatched alongside the source's `click`.
 import { createElement, useEffect, useRef, useState } from 'octane';
 
 import { composeEventHandlers } from './compose-event-handlers';
@@ -193,7 +194,6 @@ export function BubbleInput(props: any): any {
 		control,
 		hasConsumerStoppedPropagationRef,
 		checked,
-		defaultChecked,
 		required,
 		disabled,
 		name,
@@ -207,22 +207,16 @@ export function BubbleInput(props: any): any {
 	const prevChecked = usePrevious(checked, subSlot(slot, 'prev'));
 	const controlSize = useSize(control, subSlot(slot, 'size'));
 
-	// Bubble checked change to parents (e.g form change event)
+	// Bubble checked change to parents (e.g form change event). The controlled
+	// `checked` prop below keeps the input's DOM state in sync, so this effect
+	// only dispatches the events (see Checkbox.ts).
 	useEffect(
 		() => {
 			const input = bubbleInput;
 			if (!input) return;
 
-			const inputProto = window.HTMLInputElement.prototype;
-			const descriptor = Object.getOwnPropertyDescriptor(
-				inputProto,
-				'checked',
-			) as PropertyDescriptor;
-			const setChecked = descriptor.set;
-
 			const bubbles = !hasConsumerStoppedPropagationRef.current;
-			if (prevChecked !== checked && setChecked) {
-				setChecked.call(input, checked);
+			if (prevChecked !== checked) {
 				input.dispatchEvent(new Event('click', { bubbles }));
 				// octane adaptation: also fire the native `change` (see Checkbox.ts header).
 				input.dispatchEvent(new Event('change', { bubbles }));
@@ -232,12 +226,11 @@ export function BubbleInput(props: any): any {
 		subSlot(slot, 'e:bubble'),
 	);
 
-	const defaultCheckedRef = useRef(checked, subSlot(slot, 'default'));
 	return createElement(Primitive.input, {
 		type: 'checkbox',
 		'aria-hidden': true,
-		// octane: native `checked` attribute = default-checked state (see Checkbox.ts).
-		checked: (defaultChecked ?? defaultCheckedRef.current) || undefined,
+		// Live CONTROLLED checked (octane React-parity — see Checkbox.ts).
+		checked,
 		required,
 		disabled,
 		name,