@symbiote-native/components 0.1.0

package/build/responder-props.d.ts

@@ -0,0 +1,18 @@
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+type IResponderGate = (event: ISymbioteEvent) => boolean;
+type IResponderHandler = (event: ISymbioteEvent) => void;
+export interface IResponderProps {
+    onStartShouldSetResponder?: IResponderGate;
+    onStartShouldSetResponderCapture?: IResponderGate;
+    onMoveShouldSetResponder?: IResponderGate;
+    onMoveShouldSetResponderCapture?: IResponderGate;
+    onResponderGrant?: IResponderHandler;
+    onResponderReject?: IResponderHandler;
+    onResponderStart?: IResponderHandler;
+    onResponderMove?: IResponderHandler;
+    onResponderEnd?: IResponderHandler;
+    onResponderRelease?: IResponderHandler;
+    onResponderTerminate?: IResponderHandler;
+    onResponderTerminationRequest?: IResponderGate;
+}
+export {};

package/build/responder-props.js

@@ -0,0 +1,9 @@
+// The gesture-responder handler props a View accepts. They are the public face of the
+// responder negotiation @symbiote-native/engine's events run: the should-set gates decide who owns a
+// touch (capture root->target, then bubble target->root, first true wins), and the lifecycle
+// handlers receive the grant/move/release/terminate of the gesture. PanResponder produces
+// exactly this shape as its `panHandlers`; a caller can also set any of these directly on a
+// View. The should-set / termination-request gates return a boolean; the rest are
+// side-effecting. Framework-agnostic (only ISymbioteEvent), so it lives in @symbiote-native/components
+// and every adapter re-exports it as the base of its View props.
+export {};

package/build/scroll-view-commands.d.ts

@@ -0,0 +1,23 @@
+import { type AnimatedValue, type IStyleProp, type ISymbioteEvent, type ISymbioteNode, type IViewStyle } from '@symbiote-native/engine';
+type IScrollHandler = (event: ISymbioteEvent) => void;
+export interface IScrollViewHandle {
+    scrollTo(options?: {
+        x?: number;
+        y?: number;
+        animated?: boolean;
+    }): void;
+    scrollToEnd(options?: {
+        animated?: boolean;
+    }): void;
+    flashScrollIndicators(): void;
+    getScrollNode(): ISymbioteNode | null;
+}
+export declare function splitLayoutProps(style: IStyleProp<IViewStyle> | undefined): {
+    outer: Record<string, unknown>;
+    inner: Record<string, unknown>;
+};
+export declare function isSymbioteEvent(value: unknown): value is ISymbioteEvent;
+export declare function forwardScrollEvent(handler: IScrollHandler, args: readonly unknown[]): void;
+export declare function buildScrollViewHandle(getNode: () => ISymbioteNode | null): IScrollViewHandle;
+export declare function attachStickyScroll(node: ISymbioteNode, value: AnimatedValue): () => void;
+export {};

package/build/scroll-view-commands.js

@@ -0,0 +1,123 @@
+// ScrollView: the imperative + style-routing module (framework-agnostic, no 3-layer split:
+// ScrollView has no state machine). The imperative handle, the layout/visual style split for
+// the Android RefreshControl wrap, the scroll-event guard/forwarder, and the native sticky
+// scroll-attach are all platform- and framework-invariant, so they live here. The adapter
+// supplies the lifecycle (the node getter, the effect) and re-exports these.
+import { attachNativeEvent, dispatchViewCommand, dlog, flattenStyle, } from '@symbiote-native/engine';
+// RN's splitLayoutProps key partition (StyleSheet/splitLayoutProps.js): the LAYOUT keys
+// that belong on the OUTER box when a layout-affecting wrapper sits between the laid-out
+// frame and the visual content. Everything NOT in this set (background*, padding*, border*,
+// opacity, overflow, …) is VISUAL and stays on the inner view. Replicated exactly from RN's
+// switch cases so the Android RefreshControl wrap routes style the way RN does.
+const LAYOUT_KEYS = new Set([
+    'margin',
+    'marginHorizontal',
+    'marginVertical',
+    'marginBottom',
+    'marginTop',
+    'marginLeft',
+    'marginRight',
+    'flex',
+    'flexGrow',
+    'flexShrink',
+    'flexBasis',
+    'alignSelf',
+    'height',
+    'minHeight',
+    'maxHeight',
+    'width',
+    'minWidth',
+    'maxWidth',
+    'position',
+    'left',
+    'right',
+    'bottom',
+    'top',
+    'transform',
+    'transformOrigin',
+    'rowGap',
+    'columnGap',
+    'gap',
+]);
+// Split a flattened style into the LAYOUT props that drive the outer wrapper's frame and the
+// VISUAL props that paint the inner content, RN's splitLayoutProps. The Android build uses
+// this when a RefreshControl wraps the scroll view: layout (margin/flex/size/position/…) goes
+// on the AndroidSwipeRefreshLayout wrapper, visual (background/padding/border/…) stays on the
+// inner scroll view, instead of dumping the whole style on the wrapper and hardcoding flex:1.
+export function splitLayoutProps(style) {
+    const outer = {};
+    const inner = {};
+    // Reads keys off the style, so flatten the StyleProp (array/nested) to one object first.
+    const flat = flattenStyle(style);
+    for (const key of Object.keys(flat)) {
+        const value = Reflect.get(flat, key);
+        if (LAYOUT_KEYS.has(key))
+            outer[key] = value;
+        else
+            inner[key] = value;
+    }
+    return { outer, inner };
+}
+export function isSymbioteEvent(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const nativeEvent = Reflect.get(value, 'nativeEvent');
+    return typeof nativeEvent === 'object' && nativeEvent !== null;
+}
+// Forward a wrapped scroll event to the user's ScrollHandler. The Animated.event listener
+// hands raw args; the first is the original SymbioteEvent, which we narrow with a runtime
+// guard (no cast) and pass through unchanged so the user sees the same event RN would deliver.
+export function forwardScrollEvent(handler, args) {
+    const first = args[0];
+    if (isSymbioteEvent(first))
+        handler(first);
+}
+// The imperative handle is identical across platforms: every method dispatches a view
+// command on the SAME scroll-view node; only the surrounding element assembly diverges
+// (iOS sibling RefreshControl vs Android wrap). So it is built once here and both platform
+// files back it with their scroll node getter. Commands and arg order mirror RN's
+// ScrollViewCommands: scrollTo [x, y, animated], scrollToEnd [animated], flashScrollIndicators [].
+//
+// `getNode` is a LAZY getter (React `() => ref.current`, Vue `() => nodeRef.value`), read on
+// every call, NOT the node captured once. The node is null at mount and only set after the
+// element commits, so an eager capture would freeze `null` and every command would no-op.
+export function buildScrollViewHandle(getNode) {
+    return {
+        scrollTo: (options) => {
+            const node = getNode();
+            if (node === null)
+                return;
+            const x = options?.x ?? 0;
+            const y = options?.y ?? 0;
+            const animated = options?.animated ?? true;
+            dlog(`ScrollView.scrollTo x=${x} y=${y} animated=${animated}`);
+            dispatchViewCommand(node, 'scrollTo', [x, y, animated]);
+        },
+        scrollToEnd: (options) => {
+            const node = getNode();
+            if (node === null)
+                return;
+            const animated = options?.animated ?? true;
+            dlog(`ScrollView.scrollToEnd animated=${animated}`);
+            dispatchViewCommand(node, 'scrollToEnd', [animated]);
+        },
+        flashScrollIndicators: () => {
+            const node = getNode();
+            if (node === null)
+                return;
+            dlog('ScrollView.flashScrollIndicators');
+            dispatchViewCommand(node, 'flashScrollIndicators', []);
+        },
+        getScrollNode: () => getNode(),
+    };
+}
+// Attach the scroll event to the scroll-offset value on the NATIVE driver, RN's
+// _updateAnimatedNodeAttachment / AnimatedImplementation.attachNativeEvent (ScrollView.js:1087).
+// The value then tracks scroll on the UI thread and the sticky-header interpolations ride it
+// natively (no JS jitter). Returns the detach function the adapter's effect calls on cleanup.
+export function attachStickyScroll(node, value) {
+    const attachment = attachNativeEvent(node, 'onScroll', [
+        { nativeEvent: { contentOffset: { y: value } } },
+    ]);
+    return () => attachment.detach();
+}

package/build/state/drawer-layout-android.d.ts

@@ -0,0 +1,22 @@
+import { type ISymbioteEvent, type ISymbioteNode } from '@symbiote/engine';
+export type IDrawerPosition = 'left' | 'right';
+export type IDrawerLockMode = 'unlocked' | 'locked-closed' | 'locked-open';
+export type IKeyboardDismissMode = 'none' | 'on-drag';
+export type IDrawerState = 'Idle' | 'Dragging' | 'Settling';
+export interface IDrawerSlideEvent {
+    offset: number;
+}
+export interface IDrawerLayoutAndroidHandle {
+    openDrawer(): void;
+    closeDrawer(): void;
+}
+export declare const DRAWER_VIEW_NAME = "AndroidDrawerLayout";
+export declare const OPEN_DRAWER_COMMAND = "openDrawer";
+export declare const CLOSE_DRAWER_COMMAND = "closeDrawer";
+export declare const DRAWER_STATES: ReadonlyArray<IDrawerState>;
+export declare const DEFAULT_DRAWER_BACKGROUND_COLOR = "white";
+export declare const DEFAULT_DRAWER_POSITION: IDrawerPosition;
+export declare function offsetFromSlide(event: ISymbioteEvent): number;
+export declare function stateFromChange(event: ISymbioteEvent): IDrawerState;
+export declare function dispatchDrawerCommand(node: ISymbioteNode | null, command: string): void;
+export declare function buildDrawerHandle(getNode: () => ISymbioteNode | null): IDrawerLayoutAndroidHandle;

package/build/state/drawer-layout-android.js

@@ -0,0 +1,53 @@
+// DrawerLayoutAndroid: the framework-agnostic logic half. AndroidDrawerLayout is Android-only, so
+// this module holds only the platform-invariant contract every adapter shares — the drawer-position
+// / lock-mode / keyboard-dismiss / state TYPES, the native view + command NAMES, the slide/state
+// event NORMALIZATION, and the imperative open/close HANDLE. The adapter supplies only its lifecycle
+// (refs / reactivity) + the descriptor→element bridge; the view (style/prop) math lives in
+// view/render-drawer-layout-android.ts. No Platform.OS read; the adapter's filename selects the build
+// (ADR 0019). The wolf-tui twin shape is the shared state module pulled out of each reconciler.
+import { dispatchViewCommand, dlog, } from '@symbiote/engine';
+// The native view name registered by AndroidDrawerLayoutNativeComponent's
+// codegenNativeComponent('AndroidDrawerLayout'): the derive-by-default name (any non-`symbiote-*`
+// type flows through descriptorFor untouched, the engine deriving its events from the ViewConfig).
+export const DRAWER_VIEW_NAME = 'AndroidDrawerLayout';
+export const OPEN_DRAWER_COMMAND = 'openDrawer';
+export const CLOSE_DRAWER_COMMAND = 'closeDrawer';
+// RN's drawerState int -> string mapping (android DRAWER_STATES indexed by the native drawerState):
+// 0=Idle, 1=Dragging, 2=Settling.
+export const DRAWER_STATES = ['Idle', 'Dragging', 'Settling'];
+export const DEFAULT_DRAWER_BACKGROUND_COLOR = 'white';
+export const DEFAULT_DRAWER_POSITION = 'left';
+// Slide-event normalization: pull the native drag offset (RN onDrawerSlide nativeEvent.offset).
+export function offsetFromSlide(event) {
+    const offset = event.nativeEvent.offset;
+    return typeof offset === 'number' ? offset : 0;
+}
+// State-change normalization: map the native drawerState int onto its DRAWER_STATES label.
+export function stateFromChange(event) {
+    const index = event.nativeEvent.drawerState;
+    if (typeof index === 'number' && index >= 0 && index < DRAWER_STATES.length) {
+        return DRAWER_STATES[index];
+    }
+    return 'Idle';
+}
+// Issue a drawer command against the committed host node, or log a silent no-op when there is no
+// node yet (the first render has not committed). Mirrors Switch's dispatchViewCommand path.
+export function dispatchDrawerCommand(node, command) {
+    if (node === null) {
+        dlog(`DrawerLayoutAndroid ${command} no-op: no committed host node`);
+        return;
+    }
+    dlog(`DrawerLayoutAndroid dispatch ${command}`);
+    dispatchViewCommand(node, command, []);
+}
+// The imperative handle is identical across adapters: openDrawer / closeDrawer dispatch the matching
+// view command on the SAME host node. Built once here; each adapter backs it with its lazy node
+// getter (React `() => ref.current`, Vue `() => nodeRef.value`), read on every call — the node is
+// null until the element commits, so an eager capture would freeze null and every command no-op.
+// The Vue twin of React's useImperativeHandle(ref, …); mirrors buildScrollViewHandle.
+export function buildDrawerHandle(getNode) {
+    return {
+        openDrawer: () => dispatchDrawerCommand(getNode(), OPEN_DRAWER_COMMAND),
+        closeDrawer: () => dispatchDrawerCommand(getNode(), CLOSE_DRAWER_COMMAND),
+    };
+}

package/build/state/flat-list.d.ts

@@ -0,0 +1,12 @@
+import type { IViewableItemsChangedInfo, IViewToken } from './virtualized-list';
+export declare const SINGLE_COLUMN = 1;
+export interface IRow<ItemT> {
+    items: ItemT[];
+    startIndex: number;
+}
+export declare function chunkIntoRows<ItemT>(data: readonly ItemT[], columns: number): IRow<ItemT>[];
+export declare function rowKeyExtractor<ItemT>(row: IRow<ItemT>): string;
+export declare function expandRowToken<ItemT>(token: IViewToken<IRow<ItemT>>, keyExtractor?: (item: ItemT, index: number) => string): IViewToken<ItemT>[];
+export declare function expandRowViewability<ItemT>(info: IViewableItemsChangedInfo<IRow<ItemT>>, keyExtractor?: (item: ItemT, index: number) => string): IViewableItemsChangedInfo<ItemT>;
+export declare function lastItemOfRow<ItemT>(row: IRow<ItemT> | undefined): ItemT | undefined;
+export declare function firstItemOfRow<ItemT>(row: IRow<ItemT> | undefined): ItemT | undefined;

package/build/state/flat-list.js

@@ -0,0 +1,40 @@
+// FlatList logic: the framework-agnostic data adaptation over VirtualizedList. A plain
+// `data` array becomes getItem/getItemCount; numColumns packs items into rows so the
+// virtualized stream is rows, not items (RN's FlatList). Viewability over rows expands
+// back to per-item tokens, and the row separator unwraps to the flanking items. All of
+// this is pure transform — every adapter (React, Vue) reuses it; the adapter supplies
+// only the element creation (createElement / h) for a row and the ref wiring.
+export const SINGLE_COLUMN = 1;
+export function chunkIntoRows(data, columns) {
+    const rows = [];
+    for (let start = 0; start < data.length; start += columns) {
+        rows.push({ items: data.slice(start, start + columns), startIndex: start });
+    }
+    return rows;
+}
+export function rowKeyExtractor(row) {
+    return `row-${row.startIndex}`;
+}
+// Expand a row's viewable token to one token per item in that row, all sharing the row's
+// isViewable flag, so the caller sees item-level visibility rather than row-level.
+export function expandRowToken(token, keyExtractor) {
+    return token.item.items.map((item, column) => {
+        const index = token.item.startIndex + column;
+        const key = keyExtractor ? keyExtractor(item, index) : String(index);
+        return { item, key, index, isViewable: token.isViewable };
+    });
+}
+export function expandRowViewability(info, keyExtractor) {
+    return {
+        viewableItems: info.viewableItems.flatMap(token => expandRowToken(token, keyExtractor)),
+        changed: info.changed.flatMap(token => expandRowToken(token, keyExtractor)),
+    };
+}
+// The divider between rows shows real items, not the IRow wrapper: its leading item is the
+// LAST item of the row above, its trailing item the FIRST item of the row below.
+export function lastItemOfRow(row) {
+    return row !== undefined ? row.items[row.items.length - 1] : undefined;
+}
+export function firstItemOfRow(row) {
+    return row !== undefined ? row.items[0] : undefined;
+}

package/build/state/modal.d.ts

@@ -0,0 +1,11 @@
+export type IModalState = {
+    isRendered: boolean;
+};
+export declare function createInitialModalState(isVisible: boolean): IModalState;
+export type IModalAction = {
+    type: 'show';
+} | {
+    type: 'hide';
+};
+export declare function modalReducer(state: IModalState, action: IModalAction): IModalState;
+export declare function shouldRenderModal(isVisible: boolean, state: IModalState): boolean;

package/build/state/modal.js

@@ -0,0 +1,28 @@
+// Modal: the logic half (framework-agnostic). RN keeps the modal mounted through its exit
+// animation (Modal.js _shouldShowModal: visible===true || state.isRendered===true) so the
+// native onDismiss event can arrive before the node unmounts. `isRendered` is PURELY that
+// keep-alive; it never itself fires onDismiss (on Fabric onDismiss is a real native
+// DirectEvent delivered via the host's onDismiss prop). The reducer mirrors RN's guarded
+// transitions: arm the keep-alive on show, drop it on hide. The adapter drives the transition
+// AFTER its render (React useEffect / Vue post-flush watch) so one keep-alive frame survives.
+// On first render the keep-alive matches `visible`: a modal that starts visible is rendered,
+// one that starts hidden contributes no node (the render gate returns null).
+export function createInitialModalState(isVisible) {
+    return { isRendered: isVisible };
+}
+// Identity-stable when nothing changes (returns the same object) so the adapter's effect/watch
+// triggers no spurious re-render, matching React's guarded setState in Modal.js's effect.
+export function modalReducer(state, action) {
+    switch (action.type) {
+        case 'show':
+            return state.isRendered ? state : { isRendered: true };
+        case 'hide':
+            return state.isRendered ? { isRendered: false } : state;
+    }
+}
+// The visible gate with the keep-alive: a fully hidden modal (not visible AND no longer
+// rendered) contributes no node, exactly as RN's render returns null when _shouldShowModal()
+// is false.
+export function shouldRenderModal(isVisible, state) {
+    return isVisible || state.isRendered;
+}

package/build/state/pressable.d.ts

@@ -0,0 +1,90 @@
+import { type ISymbioteEvent } from '@symbiote-native/engine';
+export declare const DEFAULT_DELAY_LONG_PRESS_MS = 500;
+export declare const DEFAULT_PRESS_RECT_OFFSETS: {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+};
+export interface IEdgeInsets {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+export interface IResponderRegion {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+export interface IPressState {
+    pressed: boolean;
+}
+export type IPressHandler = (event: ISymbioteEvent) => void;
+export type IRectOffset = number | {
+    top?: number;
+    left?: number;
+    bottom?: number;
+    right?: number;
+};
+export interface IPressableAndroidRippleConfig {
+    color?: string;
+    borderless?: boolean;
+    radius?: number;
+    foreground?: boolean;
+}
+export interface IRippleBackground {
+    type: 'RippleAndroid';
+    color: string | null;
+    borderless: boolean;
+    rippleRadius?: number;
+}
+export declare function normalizeRect(offset: IRectOffset | undefined): IEdgeInsets;
+export declare function maxEdge(insets: IEdgeInsets): number;
+export declare function isTouchWithinRegion(point: {
+    x: number;
+    y: number;
+}, region: IResponderRegion, hitSlop: IEdgeInsets, pressRectOffset: IEdgeInsets): boolean;
+export declare function readPoint(event: ISymbioteEvent): {
+    x: number;
+    y: number;
+} | undefined;
+export declare function computeRegion(width: number, height: number, pageX: number, pageY: number): IResponderRegion | undefined;
+export declare function rippleProps(config: IPressableAndroidRippleConfig): Record<string, IRippleBackground> | undefined;
+export interface IPressRuntime {
+    longPressCancel: (() => void) | undefined;
+    longPressFired: boolean;
+    pressDelayCancel: (() => void) | undefined;
+    pressOrigin: {
+        x: number;
+        y: number;
+    } | undefined;
+    driftedOut: boolean;
+    region: IResponderRegion | undefined;
+}
+export declare function createPressRuntime(): IPressRuntime;
+export type IFrameCallback = (x: number, y: number, width: number, height: number, pageX: number, pageY: number) => void;
+export interface IPressHost {
+    setPressed: (pressed: boolean) => void;
+    getMeasureFn: () => ((callback: IFrameCallback) => void) | undefined;
+    schedule: (callback: () => void, ms: number) => () => void;
+}
+export interface IPressMachineConfig {
+    onPress?: IPressHandler;
+    onPressIn?: IPressHandler;
+    onPressOut?: IPressHandler;
+    onPressMove?: IPressHandler;
+    onLongPress?: IPressHandler;
+    delayLongPress: number;
+    unstable_pressDelay: number;
+    hitSlop?: IRectOffset;
+    pressRetentionOffset?: IRectOffset;
+}
+export interface IPressHandlers {
+    handlePressIn: IPressHandler;
+    handlePressOut: IPressHandler;
+    handlePress: IPressHandler;
+    handleResponderMove: IPressHandler;
+}
+export declare function createPressHandlers(config: IPressMachineConfig, runtime: IPressRuntime, host: IPressHost): IPressHandlers;