@symbiote-native/components 0.4.0 → 1.0.0

package/README.md

@@ -51,14 +51,22 @@ types and wires the reducer/render pair from here. Calling the render function d
 adapter itself does, to build its lifecycle wrapper:
 
 ```ts
-import { renderSwitch, createInitialSwitchState, switchReducer } from '@symbiote-native/components';
+import {
+  renderSwitch,
+  createInitialSwitchState,
+  switchReducer,
+} from '@symbiote-native/components';
 
 // inside an adapter's own hook/composable:
 const state = createInitialSwitchState();
 const next = switchReducer(state, { type: 'native-reported', value: true });
 const descriptor = renderSwitch(
   { value: true, disabled: false, passthrough: { onChange, ref } },
-  { trackColorProps: (value, trackColor) => ({ /* platform-specific prop names */ }) },
+  {
+    trackColorProps: (value, trackColor) => ({
+      /* platform-specific prop names */
+    }),
+  },
 );
 // descriptor is then handed to the adapter's own descriptorToReact / descriptorToVue bridge
 ```
@@ -80,17 +88,31 @@ host node untouched — the render function never names a framework type.
   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).
+- **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,89 +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/image.d.ts

@@ -0,0 +1,3 @@
+export declare const IMAGE_TAG = "symbiote-image";
+export declare function foldImagePayload(props: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export declare function registerImageBehavior(): void;

package/build/behaviors/image.js

@@ -0,0 +1,123 @@
+// Image's host behavior, and it carries NOTHING but a prop fold — no listeners, no timers, no
+// commit hook. That is what a "fold-only" primitive means: the wrapper's whole body was prop
+// mapping, so its lowered form owes exactly that and nothing else.
+//
+// The fold itself is not written here. `mapImageProps` in `../view/render-image` is the one
+// implementation, and this file only narrows a flat prop bag into the typed view it takes — the
+// same shape `behaviors/text-input.ts` uses (`stringOf` / `booleanOf` guards, then hand the shared
+// resolver a typed object). A second copy of the mapping is the exact drift this primitive has
+// already paid for once: `adapters/svelte/src/components/image/image-logic.ts` reproduces it by
+// hand and says so in its own header, because nothing was exported to call.
+//
+// WHY THIS MAY SHARE THE WRAPPER'S TAG, where TextInput needed `-managed`. A behavior fold is keyed
+// on the tag, and `renderImage` emits `symbiote-image` too — so on a wrapper-built node this fold
+// runs on ALREADY-FOLDED props. That is safe here and only here, because the mapping is idempotent:
+// every alias it consumes (`src`, `srcSet`, `alt`, `width`, `height`, …) is absent from its own
+// output, `source` comes back in the array shape `normalizeSource` guarantees, and
+// `loadingIndicatorSource` leaves under a DIFFERENT name (`loadingIndicatorSrc`), so a second pass
+// finds nothing left to fold. Idempotence is asserted in `image.test.ts` rather than assumed — the
+// audit rule's point is that a double fold is invisible precisely when it happens to be harmless,
+// so the property has to be pinned or it is an accident waiting to be broken.
+import { registerHostBehavior, } from '@symbiote-native/engine';
+import { IMAGE_VIEW_PROP_NAMES, mapImageProps, } from '../view/render-image/index.js';
+export const IMAGE_TAG = 'symbiote-image';
+const RESIZE_MODES = new Set([
+    'cover',
+    'contain',
+    'stretch',
+    'repeat',
+    'center',
+]);
+const CROSS_ORIGINS = new Set([
+    'anonymous',
+    'use-credentials',
+]);
+const CONSUMED = new Set(IMAGE_VIEW_PROP_NAMES);
+function stringOf(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function numberOf(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+function resizeModeOf(value) {
+    if (typeof value !== 'string' || !RESIZE_MODES.has(value))
+        return undefined;
+    // Narrowed by the set membership above, then re-stated as the union through a switch rather than
+    // a cast: the set and the type are two declarations of one list, and only this makes them agree.
+    switch (value) {
+        case 'cover':
+        case 'contain':
+        case 'stretch':
+        case 'repeat':
+        case 'center':
+            return value;
+        default:
+            return undefined;
+    }
+}
+function crossOriginOf(value) {
+    if (typeof value !== 'string' || !CROSS_ORIGINS.has(value))
+        return undefined;
+    return value === 'anonymous' ? 'anonymous' : 'use-credentials';
+}
+// A source is an asset id (number), a `{uri}` object, or an array of those. Anything else cannot be
+// resolved and is dropped rather than forwarded — a malformed source reaching Fabric paints nothing
+// and reports nothing, which is worse than an image that is simply absent.
+function sourceOf(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    if (typeof Reflect.get(value, 'uri') === 'string')
+        return { ...value };
+    return undefined;
+}
+// A StyleProp is an object, an array of them, or a registered class array — all of which
+// `flattenStyle` already handles. The only thing to exclude is a scalar.
+function styleOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    return { ...value };
+}
+export function foldImagePayload(props) {
+    const passthrough = {};
+    for (const key of Object.keys(props)) {
+        if (!CONSUMED.has(key))
+            passthrough[key] = props[key];
+    }
+    return mapImageProps({
+        source: sourceOf(props.source),
+        defaultSource: sourceOf(props.defaultSource),
+        loadingIndicatorSource: sourceOf(props.loadingIndicatorSource),
+        style: styleOf(props.style),
+        resizeMode: resizeModeOf(props.resizeMode),
+        tintColor: stringOf(props.tintColor),
+        src: stringOf(props.src),
+        srcSet: stringOf(props.srcSet),
+        alt: stringOf(props.alt),
+        width: numberOf(props.width),
+        height: numberOf(props.height),
+        crossOrigin: crossOriginOf(props.crossOrigin),
+        referrerPolicy: stringOf(props.referrerPolicy),
+        passthrough,
+    });
+}
+// Required by IHostBehavior and deliberately empty: Image owns no per-node runtime. Written out
+// rather than shared with a `noop` helper so the emptiness reads as a decision.
+function attach(_node) {
+    // nothing to set up
+}
+function detach(_node) {
+    // nothing to release
+}
+export function registerImageBehavior() {
+    registerHostBehavior(IMAGE_TAG, {
+        attach,
+        detach,
+        foldPayload: foldImagePayload,
+    });
+}

package/build/behaviors/input-accessory-view.d.ts

@@ -0,0 +1,3 @@
+export declare const INPUT_ACCESSORY_VIEW_TAG = "symbiote-input-accessory-view";
+export declare function foldInputAccessoryViewPayload(props: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export declare function registerInputAccessoryViewBehavior(): void;

package/build/behaviors/input-accessory-view.js

@@ -0,0 +1,70 @@
+// InputAccessoryView's host behavior — a prop fold and nothing else. No listeners, no timers, no
+// commit hook: the wrapper's whole body was prop mapping, so its lowered form owes exactly that.
+//
+// The fold is NOT written here. `mapInputAccessoryViewProps` in
+// `../view/render-input-accessory-view` is the one implementation and this file only narrows a flat
+// bag into the typed view it takes, the `stringOf` / `styleOf` guard idiom `behaviors/image.ts`
+// uses. Counted before starting, which is step one of the fold-only recipe: unlike Image, which had
+// THREE implementations, all five adapters already call the shared render fn and Svelte's
+// `input-accessory-view-props.ts` is a type declaration rather than a second mapping. So there was
+// one implementation to extract, not three to collapse.
+//
+// SHARES THE WRAPPER'S TAG, no `-managed` twin. The two questions the recipe separates both answer
+// no: the fold is idempotent (there is no aliasing at all — every consumed name leaves under the
+// same name, so a second pass rewrites the same values), and the behavior carries no machine, so
+// nothing can end up with two owners on one node. Idempotence is asserted rather than reasoned.
+//
+// PLATFORM. This is the only primitive in its group that is not platform-invariant in what it
+// COMMITS TO: `symbiote-input-accessory-view` resolves to `RCTInputAccessoryView` on iOS and to a
+// plain `RCTView` on Android. The fold itself is platform-invariant on purpose — it reproduces the
+// wrapper's mapping exactly, on both platforms, so the lowered and wrapped paths cannot diverge
+// per-platform. What it does NOT do is fix the pre-existing Android divergence underneath it:
+// upstream RN renders NOTHING there (`InputAccessoryView.js` — `console.warn('<InputAccessoryView>
+// is only supported on iOS.'); return null`), while we commit an RCTView, and `backgroundColor` is
+// a declared prop of the iOS view but a style key on RCTView. Both predate this behavior and are
+// identical on both paths; neither is in scope here, and a fold that "fixed" one silently would
+// make the two paths disagree.
+import { registerHostBehavior, } from '@symbiote-native/engine';
+import { INPUT_ACCESSORY_VIEW_PROP_NAMES, mapInputAccessoryViewProps, } from '../view/render-input-accessory-view.js';
+export const INPUT_ACCESSORY_VIEW_TAG = 'symbiote-input-accessory-view';
+const CONSUMED = new Set(INPUT_ACCESSORY_VIEW_PROP_NAMES);
+function stringOf(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+// A StyleProp is an object, an array of them, or a registered class array — all shapes
+// `flattenStyle` already handles. Only a scalar has to be excluded.
+function styleOf(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    return { ...value };
+}
+export function foldInputAccessoryViewPayload(props) {
+    const passthrough = {};
+    for (const key of Object.keys(props)) {
+        if (!CONSUMED.has(key))
+            passthrough[key] = props[key];
+    }
+    return mapInputAccessoryViewProps({
+        nativeID: stringOf(props.nativeID),
+        backgroundColor: stringOf(props.backgroundColor),
+        style: styleOf(props.style),
+        passthrough,
+    });
+}
+// Required by IHostBehavior and deliberately empty: this primitive owns no per-node runtime.
+// Written out rather than shared with a `noop` so the emptiness reads as a decision.
+function attach(_node) {
+    // nothing to set up
+}
+function detach(_node) {
+    // nothing to release
+}
+export function registerInputAccessoryViewBehavior() {
+    registerHostBehavior(INPUT_ACCESSORY_VIEW_TAG, {
+        attach,
+        detach,
+        foldPayload: foldInputAccessoryViewPayload,
+    });
+}

package/build/behaviors/pressable.d.ts

@@ -0,0 +1,2 @@
+export declare const PRESSABLE_TAG = "symbiote-pressable";
+export declare function registerPressableBehavior(): void;