@symbiote-native/components 0.5.0 → 2.0.0

package/README.md

@@ -30,8 +30,7 @@ supplies only the third:
    bridges the `Descriptor` to `React.createElement`; Vue wires it through `ref`/`watch` and
    bridges to `h()`. This is the ONLY part a new adapter has to write.
 
-`Switch` is the canonical reference for a full three-layer component; `ActivityIndicator` is the
-canonical render-only reference (no state machine needed).
+`Switch` is the canonical reference for a full three-layer component.
 
 ### Install
 
@@ -86,19 +85,33 @@ host node untouched — the render function never names a framework type.
   canonical `accessibility*` transform, shared so every adapter folds identically.
 - **Components with a full state + render split** — `Switch`, `Modal` (its reducer gates the iOS
   keep-alive frame).
-- **Render-only components** (no state machine) — `ActivityIndicator`, `Image`,
-  `ImageBackground`, `InputAccessoryView`.
-- **Pure logic/plumbing without a `Descriptor`** — `Pressable`'s press state machine
-  (`createPressHandlers` / `createPressRuntime`), the `Touchable*` timing constants,
-  `Button`'s shared text-style fold, `TextInput`'s controlled-value/event-count handshake
-  (`resolveTextInputProps`, `foldText`, `eventCountFromChange`, …), `KeyboardAvoidingView`'s inset
-  math, `ScrollView`'s intrinsics/sticky-header math (no full 3-layer split — the adapter owns the
-  element assembly).
+- **Render-only components** (no state machine) — `Image`, `ImageBackground`,
+  `InputAccessoryView`.
+- **Pure logic/plumbing without a full `Descriptor`** — `Pressable`'s press state machine
+  (`createPressHandlers` / `createPressRuntime` in `state/pressable`) plus its render-decision
+  helpers (`buildPressableListeners`, `resolveDisabledAccessibilityState`, `shouldClaimResponder`,
+  … in `view/render-pressable`), the `Touchable*` timing constants, `Button`'s shared text-style
+  fold, `TextInput`'s controlled-value/event-count handshake (`resolveTextInputProps`, `foldText`,
+  `eventCountFromChange`, …), `KeyboardAvoidingView`'s inset math, `ScrollView`'s
+  intrinsics/sticky-header math (no full 3-layer split — the adapter owns the element assembly).
+- **Two more shared reducers, driven by every adapter's reactive glue**: the sticky-header effect
+  machine (`reduceSticky` / `createInitialStickyState`, the zero-swallow gate + debounce pick every
+  sticky-header consumer needs) and the list orchestration reducer (`reduceList` /
+  `createInitialListState`, the after-commit effect skeleton — window recompute → edge →
+  viewability → initial-scroll → MVCP — every list adapter runs).
 - **The `VirtualizedList` family's windowing engine** — `computeWindow`, `buildListPlan`,
   viewability tracking (`computeViewableSet`, `diffViewable`), and the `FlatList`/`SectionList`
   row/section folding helpers. Lists have no `view/render-*.ts` (a cell's content is the
   framework's own children) — the shared layer here is pure state/logic, reused verbatim by every
   adapter.
+- **Host behaviors (`src/behaviors/*.ts`)** — tier-2 host-primitive lowering: a primitive's state
+  machine and prop folds registered directly on the engine node (`registerPressableBehavior`,
+  `registerSwitchBehavior`, `registerImageBehavior`, `registerTextInputBehavior`,
+  `registerInputAccessoryViewBehavior`, plus the folds a lowered element still needs —
+  `foldImagePayload`, `foldInputAccessoryViewPayload`, `buildTextInputHandle`) so a
+  `Pressable`/`Switch`/`TextInput`/`Image`/`InputAccessoryView` can compile to a bare intrinsic tag
+  instead of a framework component. Built on `@symbiote-native/engine`'s `registerHostBehavior`
+  seam; see `.claude/rules/host-primitive-tier.md`.
 
 ## What it does NOT do
 

package/build/accessibility-props.d.ts

@@ -61,4 +61,15 @@ export interface IAriaProps {
     'aria-valuenow'?: number;
     'aria-valuetext'?: string;
 }
+/**
+ * The typed entry point adapters import. The FOLD itself now lives in `@symbiote-native/engine`
+ * (`core/engine/src/accessibility-props.ts`) so it runs at the layer every path goes through —
+ * including a LOWERED element, which has no component wrapper to run it. This function stays here
+ * because the public types do, and because it keeps the typed gate: `hasAnyAriaKey` is checked
+ * before anything is allocated, so the ~99% of nodes carrying no alias cost the same as before.
+ *
+ * Idempotent by construction, and that is load-bearing now that the engine folds too: pass 1 blanks
+ * every alias, so a wrapper still calling this after the engine has run finds nothing and returns
+ * by identity.
+ */
 export declare function resolveAccessibilityProps<T extends IAccessibilityProps & IAriaProps>(props: T): T;

package/build/accessibility-props.js

@@ -8,43 +8,11 @@
 //
 // Framework-agnostic (imports only @symbiote-native/engine), so every adapter (React,
 // Vue, and the next) folds aria/role into accessibility* identically.
-import { dlog } from '@symbiote-native/engine';
-// RN's web `role` → native `accessibilityRole`. Where the web role has no native
-// counterpart it is forwarded unchanged (the AccessibilityRole union stays open),
-// so the map only lists the values that actually differ.
-const ROLE_TO_ACCESSIBILITY_ROLE = {
-    alert: 'alert',
-    button: 'button',
-    checkbox: 'checkbox',
-    combobox: 'combobox',
-    grid: 'grid',
-    heading: 'header',
-    img: 'image',
-    link: 'link',
-    list: 'list',
-    listitem: 'list',
-    menu: 'menu',
-    menubar: 'menubar',
-    menuitem: 'menuitem',
-    none: 'none',
-    presentation: 'none',
-    progressbar: 'progressbar',
-    radio: 'radio',
-    radiogroup: 'radiogroup',
-    scrollbar: 'scrollbar',
-    searchbox: 'search',
-    slider: 'adjustable',
-    spinbutton: 'spinbutton',
-    summary: 'summary',
-    switch: 'switch',
-    tab: 'tab',
-    tablist: 'tablist',
-    timer: 'timer',
-    toolbar: 'toolbar',
-};
-function accessibilityRoleFromRole(role) {
-    return ROLE_TO_ACCESSIBILITY_ROLE[role] ?? role;
-}
+import { foldAriaProps } from '@symbiote-native/engine';
+// The gate's key list, typed against `IAriaProps` so a new alias added to that interface and
+// forgotten here is a type error. The engine carries its own untyped copy for the lowered path;
+// `core/engine/src/accessibility-props.ts` is the single implementation of the FOLD, this is only
+// the cheap probe that decides whether to call it.
 const ARIA_KEYS = [
     'role',
     'aria-label',
@@ -62,90 +30,34 @@ const ARIA_KEYS = [
     'aria-valuenow',
     'aria-valuetext',
 ];
+// An indexed loop rather than `.some(key => …)`: the callback captures `props`, so the closure is
+// allocated on every call, and this runs once per accessibility-bearing component instance — 8 000
+// of them on one benchmark create. The fifteen property reads it replaces the closure with are
+// cheaper than the allocation.
 function hasAnyAriaKey(props) {
-    return ARIA_KEYS.some(key => props[key] !== undefined);
+    for (let index = 0; index < ARIA_KEYS.length; index += 1) {
+        if (props[ARIA_KEYS[index]] !== undefined)
+            return true;
+    }
+    return false;
 }
-// Fold the web-alias `aria-*` / `role` props into the canonical `accessibility*`
-// props, mirroring RN's View.js transform. Canonical props take precedence per
-// View.js: each aria value fills in via `??` only where the canonical field is
-// still empty. The alias keys are blanked to `undefined` in the result so they
-// never reach native (the commit layer drops undefined props); the returned
-// object keeps type `T`, spreadable straight into createElement. When no alias
-// is present the input passes through untouched (cheap fast path).
+/**
+ * The typed entry point adapters import. The FOLD itself now lives in `@symbiote-native/engine`
+ * (`core/engine/src/accessibility-props.ts`) so it runs at the layer every path goes through —
+ * including a LOWERED element, which has no component wrapper to run it. This function stays here
+ * because the public types do, and because it keeps the typed gate: `hasAnyAriaKey` is checked
+ * before anything is allocated, so the ~99% of nodes carrying no alias cost the same as before.
+ *
+ * Idempotent by construction, and that is load-bearing now that the engine folds too: pass 1 blanks
+ * every alias, so a wrapper still calling this after the engine has run finds nothing and returns
+ * by identity.
+ */
 export function resolveAccessibilityProps(props) {
     if (!hasAnyAriaKey(props))
         return props;
-    dlog('resolveAccessibilityProps: folding aria/role aliases into accessibility* props');
-    const { role, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-live': ariaLive, 'aria-hidden': ariaHidden, 'aria-busy': ariaBusy, 'aria-checked': ariaChecked, 'aria-disabled': ariaDisabled, 'aria-expanded': ariaExpanded, 'aria-selected': ariaSelected, 'aria-modal': ariaModal, 'aria-valuemax': ariaValueMax, 'aria-valuemin': ariaValueMin, 'aria-valuenow': ariaValueNow, 'aria-valuetext': ariaValueText, } = props;
-    const next = {
-        ...props,
-        role: undefined,
-        'aria-label': undefined,
-        'aria-labelledby': undefined,
-        'aria-live': undefined,
-        'aria-hidden': undefined,
-        'aria-busy': undefined,
-        'aria-checked': undefined,
-        'aria-disabled': undefined,
-        'aria-expanded': undefined,
-        'aria-selected': undefined,
-        'aria-modal': undefined,
-        'aria-valuemax': undefined,
-        'aria-valuemin': undefined,
-        'aria-valuenow': undefined,
-        'aria-valuetext': undefined,
-    };
-    if (ariaLabelledBy !== undefined &&
-        next.accessibilityLabelledBy === undefined) {
-        next.accessibilityLabelledBy = ariaLabelledBy.split(/\s*,\s*/g);
-    }
-    if (ariaLabel !== undefined && next.accessibilityLabel === undefined) {
-        next.accessibilityLabel = ariaLabel;
-    }
-    if (ariaLive !== undefined && next.accessibilityLiveRegion === undefined) {
-        next.accessibilityLiveRegion = ariaLive === 'off' ? 'none' : ariaLive;
-    }
-    if (ariaHidden !== undefined) {
-        if (next.accessibilityElementsHidden === undefined) {
-            next.accessibilityElementsHidden = ariaHidden;
-        }
-        if (ariaHidden === true && next.importantForAccessibility === undefined) {
-            next.importantForAccessibility = 'no-hide-descendants';
-        }
-    }
-    if (ariaModal !== undefined && next.accessibilityViewIsModal === undefined) {
-        next.accessibilityViewIsModal = ariaModal;
-    }
-    if (role !== undefined && next.accessibilityRole === undefined) {
-        next.accessibilityRole = accessibilityRoleFromRole(role);
-    }
-    const existingState = props.accessibilityState;
-    if (existingState !== undefined ||
-        ariaBusy !== undefined ||
-        ariaChecked !== undefined ||
-        ariaDisabled !== undefined ||
-        ariaExpanded !== undefined ||
-        ariaSelected !== undefined) {
-        next.accessibilityState = {
-            busy: ariaBusy ?? existingState?.busy,
-            checked: ariaChecked ?? existingState?.checked,
-            disabled: ariaDisabled ?? existingState?.disabled,
-            expanded: ariaExpanded ?? existingState?.expanded,
-            selected: ariaSelected ?? existingState?.selected,
-        };
-    }
-    const existingValue = props.accessibilityValue;
-    if (existingValue !== undefined ||
-        ariaValueMax !== undefined ||
-        ariaValueMin !== undefined ||
-        ariaValueNow !== undefined ||
-        ariaValueText !== undefined) {
-        next.accessibilityValue = {
-            max: ariaValueMax ?? existingValue?.max,
-            min: ariaValueMin ?? existingValue?.min,
-            now: ariaValueNow ?? existingValue?.now,
-            text: ariaValueText ?? existingValue?.text,
-        };
-    }
-    return next;
+    // `Object.entries` rather than a spread: an interface has no index signature, so a spread of `T`
+    // is not assignable to `Record<string, unknown>` and the alternative would be a cast. Paid only
+    // on the folding path, never on the gate.
+    const folded = foldAriaProps(Object.fromEntries(Object.entries(props)));
+    return Object.assign({}, props, folded);
 }

package/build/behaviors/activity-indicator/index.android.d.ts

@@ -0,0 +1 @@
+export declare function registerActivityIndicatorBehavior(): void;

package/build/behaviors/activity-indicator/index.android.js

@@ -0,0 +1,16 @@
+// ActivityIndicator's behavior on Android, where the spinner is `AndroidProgressBar` and needs two
+// props RN's iOS branch never sends (`ActivityIndicator.js:106`, spread only at `:118`):
+//
+//   styleAttr      drives ProgressBar.setStyle(); without it the view throws "setStyle() not called"
+//   indeterminate  the spinner has no determinate mode here
+//
+// and where the default colour is the THEME — expressed as null so the fold omits the key entirely
+// rather than handing Fabric's colour parser a null it rejects.
+import { registerActivityIndicatorBehaviors } from './shared.js';
+const ANDROID_STYLE_ATTR = 'Normal';
+export function registerActivityIndicatorBehavior() {
+    registerActivityIndicatorBehaviors({
+        defaultColor: null,
+        nativeExtras: { styleAttr: ANDROID_STYLE_ATTR, indeterminate: true },
+    });
+}

package/build/behaviors/activity-indicator/index.d.ts

@@ -0,0 +1,3 @@
+export { registerActivityIndicatorBehavior } from './index.ios';
+export { ACTIVITY_INDICATOR_SPINNER_TAG, ACTIVITY_INDICATOR_TAG, } from './shared';
+export type { IActivityIndicatorProps, IActivityIndicatorSize } from './shared';

package/build/behaviors/activity-indicator/index.ios.d.ts

@@ -0,0 +1 @@
+export declare function registerActivityIndicatorBehavior(): void;

package/build/behaviors/activity-indicator/index.ios.js

@@ -0,0 +1,14 @@
+// ActivityIndicator's behavior on iOS: `ActivityIndicatorView` takes the size enum and a GRAY
+// default colour, and needs no extra native props. That is the entire platform half.
+//
+// This file is also the base the folder's `index.ts` re-exports for headless, matching every other
+// platform-split module in this tree.
+import { registerActivityIndicatorBehaviors } from './shared.js';
+// RN's iOS default spinner colour (`ActivityIndicator.js:25`, GRAY).
+const IOS_DEFAULT_COLOR = '#999999';
+export function registerActivityIndicatorBehavior() {
+    registerActivityIndicatorBehaviors({
+        defaultColor: IOS_DEFAULT_COLOR,
+        nativeExtras: {},
+    });
+}

package/build/behaviors/activity-indicator/index.js

@@ -0,0 +1,5 @@
+// The base of the folder-as-module group: Metro picks `index.ios` / `index.android` per platform,
+// and everything else (tsx, vitest, headless) lands here. iOS is the default, matching every other
+// platform-split module in this tree.
+export { registerActivityIndicatorBehavior } from './index.ios.js';
+export { ACTIVITY_INDICATOR_SPINNER_TAG, ACTIVITY_INDICATOR_TAG, } from './shared.js';

package/build/behaviors/activity-indicator/shared.d.ts

@@ -0,0 +1,18 @@
+import { type IStyleProp, type ISymbioteEvent, type IViewStyle } from '@symbiote-native/engine';
+import type { IAccessibilityProps, IAriaProps } from '../../accessibility-props';
+export declare const ACTIVITY_INDICATOR_TAG = "activity-indicator";
+export declare const ACTIVITY_INDICATOR_SPINNER_TAG = "activity-indicator-spinner";
+export type IActivityIndicatorSize = 'small' | 'large' | number;
+export interface IActivityIndicatorProps extends IAccessibilityProps, IAriaProps {
+    animating?: boolean;
+    color?: string;
+    size?: IActivityIndicatorSize;
+    hidesWhenStopped?: boolean;
+    style?: IStyleProp<IViewStyle>;
+    onLayout?: (event: ISymbioteEvent) => void;
+}
+export type IActivityIndicatorPlatform = {
+    defaultColor: string | null;
+    nativeExtras: Readonly<Record<string, unknown>>;
+};
+export declare function registerActivityIndicatorBehaviors(platform: IActivityIndicatorPlatform): void;

package/build/behaviors/activity-indicator/shared.js

@@ -0,0 +1,149 @@
+// ActivityIndicator's host behavior: the composition and the prop fold, below the framework, so the
+// primitive is a bare `activity-indicator` tag and not five wrapper components.
+//
+// THE TWO-NODE SHAPE IS RN'S, not ours to collapse. `ActivityIndicator.js:112` opens a centering
+// `<View>` around the native spinner, so the tag is that View and `buildStructure` builds
+// `activity-indicator-spinner` under it. The container cannot be folded INTO the spinner either: it
+// carries `alignItems`/`justifyContent`, which centre the spinner inside the space it was given,
+// and moved onto the spinner they would centre its children, of which it has none.
+//
+// THE PLATFORM HALF IS THE SPINNER'S DEFAULTS AND NOTHING ELSE. iOS defaults the colour to RN's GRAY
+// and needs no extra native props; Android's default is the theme, which means OMITTING the key
+// rather than sending null (Fabric's colour parser rejects a null), plus `styleAttr` and
+// `indeterminate` — without the first, AndroidProgressBar throws "setStyle() not called".
+// `index.ios` / `index.android` supply them, the same file split `behaviors/scroll-view` uses.
+//
+// WHERE THE APP'S PROPS GO. `slotPropsExcept` is the COMPLEMENT of a rename map: everything an app
+// writes on the tag routes to the spinner under its own name except `ACTIVITY_INDICATOR_HOST_PROPS`,
+// which is RN's own split (`ActivityIndicator.js:99` spreads `...restProps` onto the spinner; `:113`
+// keeps `onLayout` and `style` on the View). The set that moves is OPEN — every aria alias, every
+// accessibility prop, whatever an app writes next — so a name map cannot express it.
+//
+// THE SIZE TRANSLATION IS PLATFORM-INVARIANT and lives here beside the fold that applies it: RN maps
+// 'small'/'large' to a native size enum AND a fixed box style, while a NUMBER never reaches native
+// at all (it sizes the spinner through style alone).
+//
+// Registered by all five adapters since 2026-09-09, in the same commit that deleted the five
+// wrappers — the registry is keyed by TAG, so registering while a wrapper still painted its own
+// spinner would have given every indicator two.
+import { appendChild, createElement, registerHostBehavior, } from '@symbiote-native/engine';
+import { descriptorFor } from '../../component-names';
+export const ACTIVITY_INDICATOR_TAG = 'activity-indicator';
+// The NATIVE spinner — `ActivityIndicatorView` on iOS, `AndroidProgressBar` on Android. Built by
+// `buildStructure` below and by nothing else; no app writes it.
+export const ACTIVITY_INDICATOR_SPINNER_TAG = 'activity-indicator-spinner';
+// Fixed pixel boxes RN gives the two named sizes (styles.sizeSmall/sizeLarge).
+const SIZE_SMALL_PX = 20;
+const SIZE_LARGE_PX = 36;
+// RN's own default when the app writes no `size` (ActivityIndicator.js:72).
+const DEFAULT_SIZE = 'small';
+// Centering wrapper RN puts around the spinner (styles.container).
+const CONTAINER_STYLE = {
+    alignItems: 'center',
+    justifyContent: 'center',
+};
+// The props that stay on the centering host instead of travelling to the spinner: RN's own two
+// (`ActivityIndicator.js:113`) plus the spellings the ENGINE resolves against a node's own style.
+const ACTIVITY_INDICATOR_HOST_PROPS = [
+    // A layout callback measures the box the spinner is centred IN, which is this node.
+    'onLayout',
+    // The composed `StyleSheet.compose(styles.container, style)` array (`:114`).
+    'style',
+    // A class NAME resolves to a style (`routeProp`'s class branch), so a class written on the tag has
+    // to reach the centering view — the node `style` lands on — or the app's rule paints a spinner it
+    // was never written for.
+    'class',
+    'className',
+];
+function resolveSize(size) {
+    if (size === 'small') {
+        return {
+            sizeStyle: { width: SIZE_SMALL_PX, height: SIZE_SMALL_PX },
+            sizeProp: 'small',
+        };
+    }
+    if (size === 'large') {
+        return {
+            sizeStyle: { width: SIZE_LARGE_PX, height: SIZE_LARGE_PX },
+            sizeProp: 'large',
+        };
+    }
+    return { sizeStyle: { width: size, height: size } };
+}
+// The HOST's fold: RN's `StyleSheet.compose(styles.container, style)` (ActivityIndicator.js:114).
+// Base first, so an app style still wins.
+const hostFold = props => ({
+    ...props,
+    style: [CONTAINER_STYLE, props.style],
+});
+function isActivityIndicatorSize(value) {
+    return value === 'small' || value === 'large' || typeof value === 'number';
+}
+// The SPINNER's fold — RN's own body (`ActivityIndicator.js:99-118`) applied to the node the app
+// never names.
+function spinnerFold(platform) {
+    return props => {
+        const size = isActivityIndicatorSize(props.size)
+            ? props.size
+            : DEFAULT_SIZE;
+        const { sizeStyle, sizeProp } = resolveSize(size);
+        const next = {
+            ...props,
+            // RN defaults both to true and every wrapper spelled that `!== false`. A tag has no
+            // destructuring default, so the fold is where the default has to live.
+            animating: props.animating !== false,
+            hidesWhenStopped: props.hidesWhenStopped !== false,
+            style: sizeStyle,
+        };
+        // A NUMBER never reaches native: it sizes the spinner through style alone, and the native enum
+        // takes 'small'/'large' only. So the key has to leave, not merely go unwritten.
+        if (sizeProp === undefined)
+            delete next.size;
+        else
+            next.size = sizeProp;
+        const color = typeof props.color === 'string' ? props.color : platform.defaultColor;
+        // Omitted rather than sent as null — Android's theme default is null and Fabric's colour parser
+        // rejects one.
+        if (color === null)
+            delete next.color;
+        else
+            next.color = color;
+        return next;
+    };
+}
+// The composition. Returns the spinner as the slot because the prop redirect is gated on
+// `childHost` being set — the redirect is what this slot is FOR, and NOT where children go: RN's
+// ActivityIndicator renders only the spinner (`ActivityIndicator.js:112-118`) and takes no children
+// at all. Hence `slotTakesNoChildren` below; without it a stray child would mount INSIDE the native
+// spinner, which on Android is a `ProgressBar` and not a `ViewGroup` — the `addView` crash
+// `IHostBehavior.slotTakesNoChildren` records for ImageBackground's Image.
+function buildSpinner(platform) {
+    return (node) => {
+        const descriptor = descriptorFor(ACTIVITY_INDICATOR_SPINNER_TAG);
+        const spinner = createElement(descriptor.component, descriptor.isText, ACTIVITY_INDICATOR_SPINNER_TAG);
+        // Constants of the platform, never a function of a prop, so they are seeded at build time the
+        // way ScrollView seeds `collapsable: false` — empty on iOS, AndroidProgressBar's two
+        // requirements on Android.
+        spinner.props = { ...platform.nativeExtras };
+        spinner.payloadFold = spinnerFold(platform);
+        appendChild(node, spinner);
+        return spinner;
+    };
+}
+function activityIndicatorBehavior(platform) {
+    return {
+        slotPropsExcept: ACTIVITY_INDICATOR_HOST_PROPS,
+        slotTakesNoChildren: true,
+        buildStructure: buildSpinner(platform),
+        foldPayload: hostFold,
+        // Required by the interface and deliberately empty: this primitive owns no timer, no listener
+        // and no native handshake. Written out rather than shared with a `noop` so the emptiness reads
+        // as a decision.
+        attach() { },
+        detach() { },
+    };
+}
+// Called by the platform files; nothing else should.
+export function registerActivityIndicatorBehaviors(platform) {
+    registerHostBehavior(ACTIVITY_INDICATOR_TAG, activityIndicatorBehavior(platform));
+}

package/build/behaviors/button.d.ts

@@ -0,0 +1,2 @@
+export declare const BUTTON_TAG = "button";
+export declare function registerButtonBehavior(): void;