@symbiote-native/components 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @symbiote-native/components
+
+The **framework-agnostic component layer** of [SymbioteJS](../../README.md) — pure state machines
+and pure render functions for every visual component (`Switch`, `Modal`, `ScrollView`, the
+`FlatList`/`SectionList` family, …), written **once** and inherited by every framework adapter
+(`@symbiote-native/react`, `@symbiote-native/vue`, `@symbiote-native/angular`, and the ones after them). It
+exists so that "add component X to a new adapter" means writing a thin lifecycle + descriptor
+bridge, not re-implementing X's logic per framework.
+
+> New to SymbioteJS? The [root README](../../README.md) has the architecture. This package is
+> "Workstream B" — the piece that makes cross-adapter feature parity **structural** instead of a
+> promise kept by hand.
+
+---
+
+## The split this package embodies
+
+A component's logic splits into three layers; this package owns the first two, an adapter
+supplies only the third:
+
+1. **Logic — `src/state/*.ts`.** A pure reducer `(state, action) => state`, a
+   `createInitial*State` factory, and pure predicates. Zero framework, zero render —
+   `switchReducer` / `shouldSnapBack` / `valueFromChange` for `Switch`, `modalReducer` for `Modal`,
+   the `virtualized-list` windowing math for the list family.
+2. **View — `src/view/render-*.ts`.** A pure function `render*(viewState, platform) => Descriptor`.
+   State and visuals enter **only through arguments**; out comes a tree of `Descriptor` nodes
+   (`{ type, props, children, key }`, built with `el()` / `txt()`) over the intrinsic primitives
+   (`symbiote-view`, `symbiote-switch`, …). No framework, no state, no events.
+3. **Lifecycle — the adapter.** React wires the reducer through `useReducer`/`useLayoutEffect` and
+   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).
+
+---
+
+## Usage
+
+Nearly every consumer reaches this package **through an adapter**, not directly — an app imports
+`Switch` from `@symbiote-native/react` (or `@symbiote-native/vue`), and that adapter re-exports the prop
+types and wires the reducer/render pair from here. Calling the render function directly is what an
+adapter itself does, to build its lifecycle wrapper:
+
+```ts
+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 */ }) },
+);
+// descriptor is then handed to the adapter's own descriptorToReact / descriptorToVue bridge
+```
+
+The `passthrough` bag on each view-props type is the seam that keeps `render*` framework-agnostic:
+an adapter folds its `ref`, event handlers, and accessibility props into it, and they land on the
+host node untouched — the render function never names a framework type.
+
+---
+
+## What's in here
+
+- **The `Descriptor` model** — `el()` / `txt()`, the `IDescriptor` tree every `render*` function
+  builds, and `descriptorFor` / `COMPONENT_DESCRIPTORS` (the `symbiote-*` intrinsic → Fabric
+  view-name resolution table, platform-split so the name tables can never drift between adapters).
+- **Accessibility folding** — `resolveAccessibilityProps`, the web-alias (`aria-*`/`role`) →
+  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).
+- **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.
+
+## What it does NOT do
+
+- It does not touch the DOM, Fabric, or any framework's reactivity system — it depends only on
+  `@symbiote-native/engine`'s agnostic types (`IStyleProp`, `ISymbioteEvent`, accessibility types).
+- It does not own `children`, refs, or render-callback props — a prop type with a framework
+  element in it (`IViewProps`, `IPressableProps`, `renderItem`) is declared **per adapter**, over
+  an agnostic base this package may still supply.
+- It is not itself renderable — a `Descriptor` tree only becomes native views once an adapter's
+  `descriptorTo<Framework>` bridge turns it into a host element and the reconciler commits it
+  through `@symbiote-native/engine`.
+
+## Related packages
+
+- [`@symbiote-native/engine`](../engine) — the retained-tree/clone-on-write engine this package's
+  render output ultimately commits through.
+- [`@symbiote-native/react`](../../adapters/react) / [`@symbiote-native/vue`](../../adapters/vue) /
+  [`@symbiote-native/angular`](../../adapters/angular) — the adapters that supply the lifecycle layer
+  over these state machines and render functions.
+
+## Test it
+
+```bash
+pnpm test              # vitest, from the workspace root — reducers + render-fn snapshots, headless
+```

package/build/accessibility-props.d.ts

@@ -0,0 +1,64 @@
+import { type ISymbioteEvent } from '@symbiote-native/engine';
+export type IAccessibilityRole = 'none' | 'button' | 'dropdownlist' | 'togglebutton' | 'link' | 'search' | 'image' | 'keyboardkey' | 'text' | 'adjustable' | 'imagebutton' | 'header' | 'summary' | 'alert' | 'checkbox' | 'combobox' | 'menu' | 'menubar' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'scrollbar' | 'spinbutton' | 'switch' | 'tab' | 'tabbar' | 'tablist' | 'timer' | 'list' | 'toolbar' | 'grid' | 'pager' | 'scrollview' | 'horizontalscrollview' | 'viewgroup' | 'webview' | 'drawerlayout' | 'slidingdrawer' | 'iconmenu' | (string & {});
+export type IRole = 'alert' | 'alertdialog' | 'application' | 'article' | 'banner' | 'button' | 'cell' | 'checkbox' | 'columnheader' | 'combobox' | 'complementary' | 'contentinfo' | 'definition' | 'dialog' | 'directory' | 'document' | 'feed' | 'figure' | 'form' | 'grid' | 'group' | 'heading' | 'img' | 'link' | 'list' | 'listitem' | 'log' | 'main' | 'marquee' | 'math' | 'menu' | 'menubar' | 'menuitem' | 'meter' | 'navigation' | 'none' | 'note' | 'option' | 'presentation' | 'progressbar' | 'radio' | 'radiogroup' | 'region' | 'row' | 'rowgroup' | 'rowheader' | 'scrollbar' | 'searchbox' | 'separator' | 'slider' | 'spinbutton' | 'status' | 'summary' | 'switch' | 'tab' | 'table' | 'tablist' | 'tabpanel' | 'term' | 'timer' | 'toolbar' | 'tooltip' | 'tree' | 'treegrid' | 'treeitem';
+export interface IAccessibilityStateValue {
+    disabled?: boolean;
+    selected?: boolean;
+    checked?: boolean | 'mixed';
+    busy?: boolean;
+    expanded?: boolean;
+}
+export interface IAccessibilityValue {
+    min?: number;
+    max?: number;
+    now?: number;
+    text?: string;
+}
+export interface IAccessibilityActionInfo {
+    name: string;
+    label?: string;
+}
+export interface IAccessibilityProps {
+    testID?: string;
+    nativeID?: string;
+    accessible?: boolean;
+    accessibilityLabel?: string;
+    accessibilityHint?: string;
+    accessibilityRole?: IAccessibilityRole;
+    accessibilityState?: IAccessibilityStateValue;
+    accessibilityValue?: IAccessibilityValue;
+    accessibilityActions?: ReadonlyArray<IAccessibilityActionInfo>;
+    accessibilityLabelledBy?: string | string[];
+    importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants';
+    accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
+    screenReaderFocusable?: boolean;
+    accessibilityViewIsModal?: boolean;
+    accessibilityElementsHidden?: boolean;
+    accessibilityIgnoresInvertColors?: boolean;
+    accessibilityLanguage?: string;
+    accessibilityRespondsToUserInteraction?: boolean;
+    accessibilityShowsLargeContentViewer?: boolean;
+    accessibilityLargeContentTitle?: string;
+    onAccessibilityAction?: (event: ISymbioteEvent) => void;
+    onAccessibilityTap?: (event: ISymbioteEvent) => void;
+    onMagicTap?: (event: ISymbioteEvent) => void;
+    onAccessibilityEscape?: (event: ISymbioteEvent) => void;
+}
+export interface IAriaProps {
+    role?: IRole;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-live'?: 'polite' | 'assertive' | 'off';
+    'aria-hidden'?: boolean;
+    'aria-busy'?: boolean;
+    'aria-checked'?: boolean | 'mixed';
+    'aria-disabled'?: boolean;
+    'aria-expanded'?: boolean;
+    'aria-selected'?: boolean;
+    'aria-modal'?: boolean;
+    'aria-valuemax'?: number;
+    'aria-valuemin'?: number;
+    'aria-valuenow'?: number;
+    'aria-valuetext'?: string;
+}
+export declare function resolveAccessibilityProps<T extends IAccessibilityProps & IAriaProps>(props: T): T;

package/build/accessibility-props.js

@@ -0,0 +1,150 @@
+// The accessibility prop surface shared by every user-facing component. symbiote
+// forwards any non-function / non-style prop straight to Fabric (engine's
+// fabricProps pass-through), so the canonical `accessibility*` props need no
+// wiring beyond being declared here. The web-alias `aria-*` / `role` props are
+// the exception: native reads only `accessibility*`, so they must be normalized
+// in JS before commit; `resolveAccessibilityProps` does that, mirroring RN's
+// own View.js transform. Types are kept in sync with RN's ViewAccessibility.js.
+//
+// Framework-agnostic (imports only @symbiote-native/engine), so every adapter (React,
+// Vue, and the next) folds aria/role into accessibility* identically (ADR 0024).
+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;
+}
+const ARIA_KEYS = [
+    'role',
+    'aria-label',
+    'aria-labelledby',
+    'aria-live',
+    'aria-hidden',
+    'aria-busy',
+    'aria-checked',
+    'aria-disabled',
+    'aria-expanded',
+    'aria-selected',
+    'aria-modal',
+    'aria-valuemax',
+    'aria-valuemin',
+    'aria-valuenow',
+    'aria-valuetext',
+];
+function hasAnyAriaKey(props) {
+    return ARIA_KEYS.some(key => props[key] !== undefined);
+}
+// 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).
+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;
+}

package/build/component-names/index.android.d.ts

@@ -0,0 +1,3 @@
+export type { ISymbioteIntrinsic, IComponentDescriptor } from './shared';
+export declare const COMPONENT_DESCRIPTORS: Readonly<Record<string, import("./shared").IComponentDescriptor>>;
+export declare const descriptorFor: (type: string) => import("./shared").IComponentDescriptor;

package/build/component-names/index.android.js

@@ -0,0 +1,32 @@
+// Android Fabric component names. Metro picks this file on an Android host. See ADR 0020.
+// Each name is the ViewManager's REACT_CLASS in react-native/ReactAndroid/.../views/**.
+// device-verify-pending: source-confirmed from RN's Android ViewManagers, proven on a
+// real host by the absence of a "Can't find ViewManager '<name>'" red box.
+import { buildDescriptors, makeDescriptorFor } from './shared';
+const ANDROID_NAMES = {
+    'symbiote-view': 'RCTView',
+    'symbiote-text': 'RCTText',
+    'symbiote-image': 'RCTImageView',
+    'symbiote-scroll-view': 'RCTScrollView',
+    // RN's VScrollContentViewNativeComponent is `Platform.OS === 'android' ? View : …`,
+    // so a vertical scroll's content is a plain RCTView on Android, not RCTScrollContentView.
+    'symbiote-scroll-content': 'RCTView',
+    // Horizontal scroll on Android is its own ViewManager; RCTScrollView is vertical-only and
+    // ignores `horizontal`. RN routes it to AndroidHorizontalScrollView with a dedicated content
+    // view (HScrollViewNativeComponents.js: `Platform.OS === 'android' ? AndroidHorizontal… : …`).
+    'symbiote-horizontal-scroll-view': 'AndroidHorizontalScrollView',
+    'symbiote-horizontal-scroll-content': 'AndroidHorizontalScrollContentView',
+    // Android has one text-input ViewManager for both single- and multiline.
+    'symbiote-text-input': 'AndroidTextInput',
+    'symbiote-text-input-multiline': 'AndroidTextInput',
+    'symbiote-switch': 'AndroidSwitch',
+    'symbiote-activity-indicator': 'AndroidProgressBar',
+    'symbiote-safe-area-view': 'RCTSafeAreaView',
+    'symbiote-modal': 'RCTModalHostView',
+    'symbiote-refresh-control': 'AndroidSwipeRefreshLayout',
+    // iOS-only primitive; RN ships no Android InputAccessoryView. Degrade to a plain
+    // container so an iOS-targeted usage doesn't red-box on Android.
+    'symbiote-input-accessory-view': 'RCTView',
+};
+export const COMPONENT_DESCRIPTORS = buildDescriptors(ANDROID_NAMES);
+export const descriptorFor = makeDescriptorFor(COMPONENT_DESCRIPTORS);

package/build/component-names/index.d.ts

@@ -0,0 +1 @@
+export * from './index.ios';

package/build/component-names/index.ios.d.ts

@@ -0,0 +1,3 @@
+export type { ISymbioteIntrinsic, IComponentDescriptor } from './shared';
+export declare const COMPONENT_DESCRIPTORS: Readonly<Record<string, import("./shared").IComponentDescriptor>>;
+export declare const descriptorFor: (type: string) => import("./shared").IComponentDescriptor;

package/build/component-names/index.ios.js

@@ -0,0 +1,26 @@
+// iOS Fabric component names. Metro picks this file on an iOS host; it is also the base
+// (component-names.ts re-exports it) for headless tsx / tsc / web fallback. See ADR 0020.
+// Fabric names are the codegen spec's registered name (the new-arch name), not the legacy
+// paperComponentName (RCTSwitch, …).
+import { buildDescriptors, makeDescriptorFor } from './shared';
+const IOS_NAMES = {
+    'symbiote-view': 'RCTView',
+    'symbiote-text': 'RCTText',
+    'symbiote-image': 'RCTImageView',
+    'symbiote-scroll-view': 'RCTScrollView',
+    'symbiote-scroll-content': 'RCTScrollContentView',
+    // iOS uses one scroll view for both axes; horizontal is RCTScrollView with the
+    // `horizontal` prop set, so these resolve identically to the vertical pair.
+    'symbiote-horizontal-scroll-view': 'RCTScrollView',
+    'symbiote-horizontal-scroll-content': 'RCTScrollContentView',
+    'symbiote-text-input': 'RCTSinglelineTextInputView',
+    'symbiote-text-input-multiline': 'RCTMultilineTextInputView',
+    'symbiote-switch': 'Switch',
+    'symbiote-activity-indicator': 'ActivityIndicatorView',
+    'symbiote-safe-area-view': 'SafeAreaView',
+    'symbiote-modal': 'ModalHostView',
+    'symbiote-refresh-control': 'PullToRefreshView',
+    'symbiote-input-accessory-view': 'RCTInputAccessoryView',
+};
+export const COMPONENT_DESCRIPTORS = buildDescriptors(IOS_NAMES);
+export const descriptorFor = makeDescriptorFor(COMPONENT_DESCRIPTORS);

package/build/component-names/index.js

@@ -0,0 +1,5 @@
+// Base / default component-name table: re-exports the iOS table. Metro overrides this
+// with component-names.ios.ts / component-names.android.ts on a real host; under tsx /
+// tsc / web (no Metro) the host config resolves here. Filename is the selector, no
+// Platform.OS read. See ADR 0020.
+export * from './index.ios';

package/build/component-names/shared.d.ts

@@ -0,0 +1,7 @@
+export type ISymbioteIntrinsic = 'symbiote-view' | 'symbiote-text' | 'symbiote-image' | 'symbiote-scroll-view' | 'symbiote-scroll-content' | 'symbiote-horizontal-scroll-view' | 'symbiote-horizontal-scroll-content' | 'symbiote-text-input' | 'symbiote-text-input-multiline' | 'symbiote-switch' | 'symbiote-activity-indicator' | 'symbiote-safe-area-view' | 'symbiote-modal' | 'symbiote-refresh-control' | 'symbiote-input-accessory-view';
+export interface IComponentDescriptor {
+    component: string;
+    isText: boolean;
+}
+export declare function buildDescriptors(names: Readonly<Record<ISymbioteIntrinsic, string>>): Readonly<Record<string, IComponentDescriptor>>;
+export declare function makeDescriptorFor(descriptors: Readonly<Record<string, IComponentDescriptor>>): (type: string) => IComponentDescriptor;

package/build/component-names/shared.js

@@ -0,0 +1,36 @@
+// The intrinsic JSX types symbiote's host config maps to Fabric components, plus the
+// machinery to turn a platform name table into the descriptors the host config reads.
+// Per ADR 0020 the Fabric NAME of a primitive is platform-specific (iOS 'Switch' vs
+// Android 'AndroidSwitch'), so the name tables live in component-names.ios.ts /
+// .android.ts and the filename selects, no Platform.OS read. The isText flag is
+// platform-invariant, so it lives here once and both tables share it.
+// The only text-laying intrinsic; drives the RCTText / RCTVirtualText nesting choice
+// (a <Text> inside another <Text> becomes a virtual span). Platform-invariant, so it is
+// not part of the per-platform name table.
+const TEXT_INTRINSICS = new Set(['symbiote-text']);
+// Assemble the descriptor map a platform file exports: each intrinsic's Fabric name from
+// the platform table, paired with its invariant isText flag.
+export function buildDescriptors(names) {
+    const descriptors = {};
+    for (const [intrinsic, component] of Object.entries(names)) {
+        descriptors[intrinsic] = { component, isText: TEXT_INTRINSICS.has(intrinsic) };
+    }
+    return descriptors;
+}
+// Resolve an intrinsic type to its descriptor, against the platform-selected map. The
+// logic is identical for every adapter (and was duplicated in React's host-config and
+// Vue's component-names), so it lives here once; each platform file binds it to its own
+// COMPONENT_DESCRIPTORS. A `symbiote-*` miss is a typo in our own code; any other string
+// is a raw Fabric view name from a library's codegen component and flows through untouched
+// (the engine derives its events/processors from the view's ViewConfig, no per-library glue).
+export function makeDescriptorFor(descriptors) {
+    return type => {
+        const descriptor = descriptors[type];
+        if (descriptor !== undefined)
+            return descriptor;
+        if (type.startsWith('symbiote-')) {
+            throw new Error(`Unknown symbiote component type: ${type}`);
+        }
+        return { component: type, isText: false };
+    };
+}

package/build/descriptor.d.ts

@@ -0,0 +1,11 @@
+export type IDescriptorType = string;
+export type IDescriptorProps = Record<string, unknown>;
+export type IDescriptorChild = IDescriptor | string;
+export type IDescriptor = {
+    type: IDescriptorType;
+    props: IDescriptorProps;
+    children: IDescriptorChild[];
+    key?: string;
+};
+export declare function el(type: IDescriptorType, props?: IDescriptorProps, children?: IDescriptorChild[], key?: string): IDescriptor;
+export declare function txt(props?: IDescriptorProps, children?: IDescriptorChild[]): IDescriptor;

package/build/descriptor.js

@@ -0,0 +1,17 @@
+// The framework-agnostic node a render function paints. A `Descriptor` is a tiny VDOM
+// description, `{ type, props, children, key }`, that each adapter maps to its own
+// element (`descriptorToReact` → React.createElement, `descriptorToVue` → h()). The
+// adapter's host element then flows on through its reconciler → engine → Fabric.
+//
+// The wolf-tui twin is `internal/shared/src/wnode/types.ts` (`WNode` + `wbox`/`wtext`).
+// We diverge in one way: `type` is an open host-component string, not a closed two-member
+// union, because symbiote paints one host element PER native component
+// (`symbiote-activity-indicator`, `symbiote-switch`, …), not just box/text.
+// el(): a host element of any type. txt(): shorthand for the `symbiote-text` primitive.
+// Mirror wolf-tui's `wbox` / `wtext`.
+export function el(type, props = {}, children = [], key) {
+    return { type, props, children, key };
+}
+export function txt(props = {}, children = []) {
+    return { type: 'symbiote-text', props, children };
+}

package/build/index.d.ts

@@ -0,0 +1,51 @@
+export { el, txt } from './descriptor';
+export type { IDescriptor, IDescriptorType, IDescriptorProps, IDescriptorChild, } from './descriptor';
+export { resolveAccessibilityProps } from './accessibility-props';
+export type { IAccessibilityProps, IAriaProps, IAccessibilityRole, IRole, IAccessibilityStateValue, IAccessibilityValue, IAccessibilityActionInfo, } from './accessibility-props';
+export { descriptorFor, COMPONENT_DESCRIPTORS } from './component-names';
+export { buildDescriptors, makeDescriptorFor } from './component-names/shared';
+export type { ISymbioteIntrinsic, IComponentDescriptor } from './component-names/shared';
+export { renderActivityIndicator } from './view/render-activity-indicator';
+export type { IActivityIndicatorProps, IActivityIndicatorViewProps, IActivityIndicatorPlatform, IActivityIndicatorSize, } from './view/render-activity-indicator';
+export { renderSwitch } from './view/render-switch';
+export type { ISwitchProps, ISwitchViewProps, ISwitchPlatform, ISwitchTrackColor, } from './view/render-switch';
+export type { IResponderProps } from './responder-props';
+export { switchReducer, createInitialSwitchState, shouldSnapBack, valueFromChange, } from './state/switch';
+export type { ISwitchState, ISwitchAction } from './state/switch';
+export { resolveDecelerationRate, selectScrollIntrinsics, readLayoutDimension, didContentSizeChange, SCROLL_VIEW_BASE_HORIZONTAL, SCROLL_VIEW_BASE_VERTICAL, } from './view/render-scroll-view';
+export type { IScrollIntrinsics, IContentSize } from './view/render-scroll-view';
+export { buildScrollViewHandle, splitLayoutProps, attachStickyScroll, isSymbioteEvent, forwardScrollEvent, } from './scroll-view-commands';
+export type { IScrollViewHandle } from './scroll-view-commands';
+export { computeStickyInterpolation, nextStickyHeaderY, stickyDebounceMs, readLayoutNumber, STICKY_HEADER_Z_INDEX, } from './view/render-scroll-sticky';
+export type { IStickyHeaderProps, IStickyInterpolationParams } from './view/render-scroll-sticky';
+export type { IImageSource, IImageStatics, IImageSourceProp, IResizeMode, IImageSize, IImageCacheStatus, IImageProps, IImageViewProps, } from './view/render-image';
+export { renderImage, imageStatics, setImageSourceResolver } from './view/render-image';
+export { renderImageBackground } from './view/render-image-background';
+export type { IImageBackgroundViewProps } from './view/render-image-background';
+export { renderInputAccessoryView } from './view/render-input-accessory-view';
+export type { IInputAccessoryViewViewProps } from './view/render-input-accessory-view';
+export { renderModal } from './view/render-modal';
+export type { IModalViewProps, IModalAnimationType, IModalPresentationStyle, IModalOrientation, IModalOrientationChangeEvent, } from './view/render-modal';
+export { modalReducer, createInitialModalState, shouldRenderModal } from './state/modal';
+export type { IModalState, IModalAction } from './state/modal';
+export { computeInset, readKeyboardFrame, readLayoutFrame, resolveKeyboardAvoidingLayout, DEFAULT_VERTICAL_OFFSET, } from './view/render-keyboard-avoiding-view';
+export type { IKeyboardAvoidingBehavior, IMeasuredFrame, IKeyboardFrame, IKeyboardAvoidingLayout, IResolveKeyboardAvoidingLayoutParams, } from './view/render-keyboard-avoiding-view';
+export { createPressHandlers, createPressRuntime, normalizeRect, maxEdge, isTouchWithinRegion, readPoint, computeRegion, rippleProps, DEFAULT_DELAY_LONG_PRESS_MS, DEFAULT_PRESS_RECT_OFFSETS, } from './state/pressable';
+export type { IPressState, IPressHandler, IPressHandlers, IPressHost, IPressRuntime, IPressMachineConfig, IFrameCallback, IRectOffset, IEdgeInsets, IResponderRegion, IPressableAndroidRippleConfig, IRippleBackground as IPressableRippleBackground, } from './state/pressable';
+export { buildPressableListeners, resolveDisabledAccessibilityState, noteHoverNoop, } from './view/render-pressable';
+export { computePressOutWait, DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, RESTING_OPACITY, DEFAULT_HIGHLIGHT_CHILD_OPACITY, DEFAULT_UNDERLAY_COLOR, DEFAULT_MIN_PRESS_DURATION_MS, } from './state/touchable';
+export type { IPressTimingProps, ITouchableHandler } from './state/touchable';
+export { backgroundProps, canUseNativeForeground, selectableBackground, selectableBackgroundBorderless, rippleBackground, } from './view/render-touchable-native-feedback';
+export type { INativeFeedbackBackground, IThemeAttrBackground, IRippleBackground, } from './view/render-touchable-native-feedback';
+export { BUTTON_ACCESSIBILITY_ROLE, buttonTextStyle, resolveButtonTextStyle, } from './view/render-button';
+export type { IButtonProps } from './view/render-button';
+export { resolveTextInputProps, foldText, foldAutoComplete, foldSubmitBehavior, mapAutoComplete, textFromChange, eventCountFromChange, shouldCommandText, INITIAL_EVENT_COUNT, SELECTION_NONE, } from './state/text-input';
+export type { ITextInputProps, ITextInputHandle, ITextInputSelection, ITextInputEventHandler, ITextInputFoldInput, IFoldedTextInputProps, IInputMode, IEnterKeyHint, ISubmitBehavior, } from './state/text-input';
+export { renderTextInput } from './view/render-text-input';
+export type { ITextInputViewProps } from './view/render-text-input';
+export { DEFAULT_WINDOW_SIZE, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_END_REACHED_THRESHOLD, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_VIEW_AREA_COVERAGE_PERCENT_THRESHOLD, DEFAULT_START_REACHED_THRESHOLD, FIRST_INDEX, EMPTY_OFFSET, NO_INDEX, NO_CONTENT_LENGTH_SENT, INVERTED_Y_STYLE, INVERTED_X_STYLE, readScrollOffset, readLayoutLength, buildOffsets, computeWindow, throttleWindow, visiblePercent, isCellViewable, offsetForIndex, averageMeasuredLength, highestMeasuredIndex, computeEndReached, computeStartReached, buildViewabilityPairs, computeViewableSet, diffViewable, maxMinimumViewTime, buildListPlan, } from './state/virtualized-list';
+export type { ICellLayout, ISeparators, ISeparatorProps, IViewToken, IViewableItemsChangedInfo, IViewabilityConfig, IViewabilityConfigCallbackPair, IVirtualizedListHandle, IViewableSetParams, IListCellPlan, IListPlan, IListPlanParams, } from './state/virtualized-list';
+export { SINGLE_COLUMN, chunkIntoRows, rowKeyExtractor, expandRowToken, expandRowViewability, lastItemOfRow, firstItemOfRow, } from './state/flat-list';
+export type { IRow } from './state/flat-list';
+export { flattenSections, unwrapEntryItem, sectionEntryKey, scrollLocationToFlatIndex, } from './state/section-list';
+export type { ISection, ISectionEntry, IVirtualizedSectionListHandle } from './state/section-list';

package/build/index.js

@@ -0,0 +1,63 @@
+// @symbiote-native/components: the framework-agnostic component layer. Pure state machines
+// (`state/`) and render functions (`view/`) that paint `Descriptor` trees; every adapter
+// wires state→render with ITS lifecycle (React hooks / Vue reactivity) and maps the
+// Descriptor onto its own element. See CLAUDE.md <components_split_logic_view_lifecycle>.
+export { el, txt } from './descriptor';
+// Accessibility folding: the web-alias (aria-*/role) → canonical accessibility* transform
+// and its types. Framework-agnostic (ADR 0024), so React, Vue, and the next adapter all fold
+// identically; moved here from @symbiote-native/react. RefreshControl/SafeAreaView/ScrollView consume it.
+export { resolveAccessibilityProps } from './accessibility-props';
+// Intrinsic (`symbiote-*`) → Fabric view-name resolution. Shared by every adapter so the
+// names CANNOT drift between them (one engine, one Fabric). The name tables are
+// Metro-split (.ios/.android, filename selects, no Platform.OS read, ADR 0020); the base
+// re-exports iOS for headless. descriptorFor is the per-platform-bound resolver.
+export { descriptorFor, COMPONENT_DESCRIPTORS } from './component-names';
+export { buildDescriptors, makeDescriptorFor } from './component-names/shared';
+export { renderActivityIndicator } from './view/render-activity-indicator';
+export { renderSwitch } from './view/render-switch';
+// Switch is the first STATE machine off this layer (ActivityIndicator was render-only):
+// the reducer + the two pure predicates are the logic half, the adapter supplies the hook.
+export { switchReducer, createInitialSwitchState, shouldSnapBack, valueFromChange, } from './state/switch';
+// ScrollView: pure render/command helpers (no state machine, no 3-layer split). The adapter
+// owns the refs/effects/element assembly and the sticky-header component; these supply the
+// platform-invariant math and plumbing every adapter shares (ADR 0024).
+export { resolveDecelerationRate, selectScrollIntrinsics, readLayoutDimension, didContentSizeChange, SCROLL_VIEW_BASE_HORIZONTAL, SCROLL_VIEW_BASE_VERTICAL, } from './view/render-scroll-view';
+export { buildScrollViewHandle, splitLayoutProps, attachStickyScroll, isSymbioteEvent, forwardScrollEvent, } from './scroll-view-commands';
+export { computeStickyInterpolation, nextStickyHeaderY, stickyDebounceMs, readLayoutNumber, STICKY_HEADER_Z_INDEX, } from './view/render-scroll-sticky';
+export { renderImage, imageStatics, setImageSourceResolver } from './view/render-image';
+// ImageBackground: render-only composition (absolute-fill image behind, children on top).
+export { renderImageBackground } from './view/render-image-background';
+// InputAccessoryView: render-only host assembly (nativeID/backgroundColor).
+export { renderInputAccessoryView } from './view/render-input-accessory-view';
+// Modal: full 3-layer split (state machine gates the iOS keep-alive frame).
+export { renderModal } from './view/render-modal';
+export { modalReducer, createInitialModalState, shouldRenderModal } from './state/modal';
+// KeyboardAvoidingView: pure inset/behavior math; the adapter owns the Keyboard subscription.
+export { computeInset, readKeyboardFrame, readLayoutFrame, resolveKeyboardAvoidingLayout, DEFAULT_VERTICAL_OFFSET, } from './view/render-keyboard-avoiding-view';
+// Pressable: the press state machine (logic) + render decisions. The pure lifecycle (timers,
+// geometry, drift test, suppression flags) lives in state/pressable; the responder-listener +
+// accessibilityState + ripple render decisions in view/render-pressable. Every adapter supplies
+// only its reactive `pressed` cell + the View's measure handle (see the 3-layer split).
+export { createPressHandlers, createPressRuntime, normalizeRect, maxEdge, isTouchWithinRegion, readPoint, computeRegion, rippleProps, DEFAULT_DELAY_LONG_PRESS_MS, DEFAULT_PRESS_RECT_OFFSETS, } from './state/pressable';
+export { buildPressableListeners, resolveDisabledAccessibilityState, noteHoverNoop, } from './view/render-pressable';
+// Touchable*: shared press-timing constants + the deactivation-floor math (the Animated feedback
+// itself stays per-adapter), and TouchableNativeFeedback's pure static factories + background map.
+export { computePressOutWait, DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, RESTING_OPACITY, DEFAULT_HIGHLIGHT_CHILD_OPACITY, DEFAULT_UNDERLAY_COLOR, DEFAULT_MIN_PRESS_DURATION_MS, } from './state/touchable';
+export { backgroundProps, canUseNativeForeground, selectableBackground, selectableBackgroundBorderless, rippleBackground, } from './view/render-touchable-native-feedback';
+// Button: shared base text style, role constant, and color fold (the adapter composes its own
+// TouchableOpacity + Text).
+export { BUTTON_ACCESSIBILITY_ROLE, buttonTextStyle, resolveButtonTextStyle, } from './view/render-button';
+// TextInput: the controlled-value / event-count handshake. The logic half is the pure
+// folds/maps + the controlled-write predicate (not a single reducer: count must re-render the
+// imperative handle, lastNativeText must not); the view half picks the intrinsic and maps the
+// resolved native props. Both shared verbatim across React and Vue; the adapter owns only the
+// hooks/reactivity + the imperative handle.
+export { resolveTextInputProps, foldText, foldAutoComplete, foldSubmitBehavior, mapAutoComplete, textFromChange, eventCountFromChange, shouldCommandText, INITIAL_EVENT_COUNT, SELECTION_NONE, } from './state/text-input';
+export { renderTextInput } from './view/render-text-input';
+// VirtualizedList family: the framework-agnostic windowing engine + data shapes. Lists
+// have NO view/render-*.ts (the cell content is the framework's own children, so there is
+// no Descriptor render fn) — the shared layer for lists is this STATE/logic, reused
+// verbatim by React and Vue. See core/components/.docs-note-lists.md.
+export { DEFAULT_WINDOW_SIZE, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_END_REACHED_THRESHOLD, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_VIEW_AREA_COVERAGE_PERCENT_THRESHOLD, DEFAULT_START_REACHED_THRESHOLD, FIRST_INDEX, EMPTY_OFFSET, NO_INDEX, NO_CONTENT_LENGTH_SENT, INVERTED_Y_STYLE, INVERTED_X_STYLE, readScrollOffset, readLayoutLength, buildOffsets, computeWindow, throttleWindow, visiblePercent, isCellViewable, offsetForIndex, averageMeasuredLength, highestMeasuredIndex, computeEndReached, computeStartReached, buildViewabilityPairs, computeViewableSet, diffViewable, maxMinimumViewTime, buildListPlan, } from './state/virtualized-list';
+export { SINGLE_COLUMN, chunkIntoRows, rowKeyExtractor, expandRowToken, expandRowViewability, lastItemOfRow, firstItemOfRow, } from './state/flat-list';
+export { flattenSections, unwrapEntryItem, sectionEntryKey, scrollLocationToFlatIndex, } from './state/section-list';