@symbiote-native/components 0.1.0

package/build/state/pressable.js

@@ -0,0 +1,236 @@
+// Pressable, the logic half (framework-agnostic, zero render, zero framework imports). The
+// press lifecycle RN's Pressability runs in JS (pressIn/pressOut/press synthesis, the
+// long-press timer, unstable_pressDelay deferral, and the pressRetentionOffset drift test)
+// lives here as a pure state machine over a mutable runtime plus an adapter-supplied host. The
+// adapter owns only the lifecycle wiring: React holds the runtime in a ref and flips `pressed`
+// via setState; Vue holds it in setup scope and flips a ref. Both call the SAME handlers.
+//
+// Framework-specific, stays in the adapter: the `pressed` state cell (it drives a
+// re-render, so each framework owns its reactive primitive) and the raw frame-measure (the host
+// node plus its measure call). The rest (the timers, the geometry, the suppression flags,
+// the decision of when each callback fires) is here, shared by every adapter.
+import { dlog, Platform } from '@symbiote-native/engine';
+export const DEFAULT_DELAY_LONG_PRESS_MS = 500;
+// RN's default extra slop kept around a press once it is active, before a drift fires pressOut.
+// The PressRect extension (Pressability.js DEFAULT_PRESS_RECT_OFFSETS). Per-edge, deeper bottom.
+export const DEFAULT_PRESS_RECT_OFFSETS = { top: 20, left: 20, bottom: 30, right: 20 };
+// ---- geometry (pure) --------------------------------------------------------------------------
+// A rect offset is a per-edge object (not the scalar shorthand). Reads the asymmetric form
+// without a cast.
+function isEdgeInsets(value) {
+    return typeof value === 'object';
+}
+// Normalize a scalar-or-rect offset to a per-edge rect: a number expands all four edges,
+// mirroring RN's normalizeRect (StyleSheet/Rect.js). Absent edges read 0.
+export function normalizeRect(offset) {
+    if (offset === undefined)
+        return { top: 0, left: 0, bottom: 0, right: 0 };
+    if (isEdgeInsets(offset)) {
+        const { top = 0, left = 0, bottom = 0, right = 0 } = offset;
+        return { top, left, bottom, right };
+    }
+    return { top: offset, left: offset, bottom: offset, right: offset };
+}
+// The widest single edge, for the radius fallback when no measured rect is available (headless).
+export function maxEdge(insets) {
+    return Math.max(insets.top, insets.left, insets.bottom, insets.right);
+}
+// Is a touch page-point inside the measured responder region, expanded per-edge by hitSlop then
+// pressRectOffset? Direct port of Pressability.js `_isTouchWithinResponderRegion`: left/top
+// shrink the bound, right/bottom grow it; strict inequalities.
+export function isTouchWithinRegion(point, region, hitSlop, pressRectOffset) {
+    const left = region.left - hitSlop.left - pressRectOffset.left;
+    const right = region.right + hitSlop.right + pressRectOffset.right;
+    const top = region.top - hitSlop.top - pressRectOffset.top;
+    const bottom = region.bottom + hitSlop.bottom + pressRectOffset.bottom;
+    return point.x > left && point.x < right && point.y > top && point.y < bottom;
+}
+// Page coordinate of a single-touch native event, or undefined when it carried no numeric coords
+// (then the retention drift check is skipped, never guessed).
+export function readPoint(event) {
+    const { pageX, pageY } = event.nativeEvent;
+    if (typeof pageX === 'number' && typeof pageY === 'number')
+        return { x: pageX, y: pageY };
+    return undefined;
+}
+// Build the responder region from a measured frame, or undefined for an all-zero frame (the view
+// is not laid out, RN's _measureCallback ignores it).
+export function computeRegion(width, height, pageX, pageY) {
+    if (!width && !height && !pageX && !pageY)
+        return undefined;
+    return { left: pageX, top: pageY, right: pageX + width, bottom: pageY + height };
+}
+// Build the Android native-feedback prop the inner View carries from the ripple config. RN runs
+// the color through processColor → a native int; we have no native bridge in JS, so we keep the
+// string and let Android resolve it (a null color is the documented "no tint"). Inert on iOS.
+export function rippleProps(config) {
+    if (Platform.OS !== 'android')
+        return undefined;
+    const background = {
+        type: 'RippleAndroid',
+        color: config.color ?? null,
+        borderless: config.borderless === true,
+        rippleRadius: config.radius,
+    };
+    return config.foreground === true
+        ? { nativeForegroundAndroid: background }
+        : { nativeBackgroundAndroid: background };
+}
+export function createPressRuntime() {
+    return {
+        longPressCancel: undefined,
+        longPressFired: false,
+        pressDelayCancel: undefined,
+        pressOrigin: undefined,
+        driftedOut: false,
+        region: undefined,
+    };
+}
+// Measure the responder's on-screen frame and cache it as the retention region for the life of
+// the press (RN measures on responder grant, _measureResponderRegion). When measure is
+// unavailable (no node yet, an uncommitted node, or a host slot without a measure method,
+// headless) the region stays undefined and the move test falls back to the radius bound. The
+// try/catch guards that last case: a slot lacking measure throws rather than no-opping.
+function measureRegion(runtime, measureFn) {
+    runtime.region = undefined;
+    if (measureFn === undefined)
+        return;
+    dlog('Pressable measuring responder region');
+    try {
+        measureFn((_x, _y, width, height, pageX, pageY) => {
+            const region = computeRegion(width, height, pageX, pageY);
+            if (region === undefined)
+                return;
+            runtime.region = region;
+            dlog('Pressable responder region measured');
+        });
+    }
+    catch {
+        dlog('Pressable measure unavailable — retention falls back to radius');
+    }
+}
+// Build the four responder handlers over the config + runtime + host. The whole press lifecycle
+// (the React adapter's useMemo body) lives here, shared by every adapter. The adapter rebuilds
+// these per render (the closures capture the live config) while the runtime persists across them.
+export function createPressHandlers(config, runtime, host) {
+    const { onPress, onPressIn, onPressOut, onPressMove, onLongPress, delayLongPress, unstable_pressDelay, } = config;
+    // Per-edge offsets for the measured-rect retention test (RN's hitSlop + pressRectOffset).
+    // pressRetentionOffset defaults to RN's DEFAULT_PRESS_RECT_OFFSETS when unset; hitSlop to zero.
+    const hitSlopRect = normalizeRect(config.hitSlop);
+    const pressRectOffset = config.pressRetentionOffset === undefined
+        ? DEFAULT_PRESS_RECT_OFFSETS
+        : normalizeRect(config.pressRetentionOffset);
+    // Radius fallback bound (headless): widest hitSlop edge + widest retention edge.
+    const fallbackThreshold = maxEdge(hitSlopRect) + maxEdge(pressRectOffset);
+    // True iff the touch still belongs to the active press: against the measured rect when we have
+    // one (the RN-faithful path), else the symmetric radius fallback.
+    function isWithinRetention(point) {
+        const region = runtime.region;
+        if (region !== undefined) {
+            return isTouchWithinRegion(point, region, hitSlopRect, pressRectOffset);
+        }
+        const origin = runtime.pressOrigin;
+        if (origin === undefined)
+            return true;
+        return Math.hypot(point.x - origin.x, point.y - origin.y) <= fallbackThreshold;
+    }
+    function clearLongPress() {
+        if (runtime.longPressCancel !== undefined) {
+            runtime.longPressCancel();
+            runtime.longPressCancel = undefined;
+        }
+    }
+    // The real activation: flip pressed-state on, arm the long-press timer, fire onPressIn. Split
+    // out so unstable_pressDelay can defer it behind a timer while an early release flushes it.
+    function activate(event) {
+        dlog('Pressable pressIn');
+        host.setPressed(true);
+        runtime.longPressFired = false;
+        if (onLongPress) {
+            runtime.longPressCancel = host.schedule(() => {
+                runtime.longPressCancel = undefined;
+                runtime.longPressFired = true;
+                dlog('Pressable longPress timer fired');
+                onLongPress(event);
+            }, delayLongPress);
+        }
+        onPressIn?.(event);
+    }
+    // Flush a still-pending pressDelay timer immediately, so a pressOut/press that arrives before
+    // the delay elapsed still sees an activated press.
+    function flushPressDelay(event) {
+        if (runtime.pressDelayCancel !== undefined) {
+            runtime.pressDelayCancel();
+            runtime.pressDelayCancel = undefined;
+            activate(event);
+        }
+    }
+    return {
+        handlePressIn(event) {
+            runtime.pressOrigin = readPoint(event);
+            runtime.driftedOut = false;
+            // Measure now so the move stream tests against the real frame, not a press-start radius.
+            measureRegion(runtime, host.getMeasureFn());
+            if (unstable_pressDelay > 0) {
+                dlog(`Pressable pressIn deferred ${unstable_pressDelay}ms`);
+                runtime.pressDelayCancel = host.schedule(() => {
+                    runtime.pressDelayCancel = undefined;
+                    activate(event);
+                }, unstable_pressDelay);
+                return;
+            }
+            activate(event);
+        },
+        handlePressOut(event) {
+            dlog('Pressable pressOut');
+            flushPressDelay(event);
+            clearLongPress();
+            runtime.pressOrigin = undefined;
+            runtime.region = undefined;
+            host.setPressed(false);
+            onPressOut?.(event);
+        },
+        handlePress(event) {
+            dlog('Pressable press');
+            flushPressDelay(event);
+            clearLongPress();
+            // A drift past the retention region cancels the tap (RN); reset and suppress.
+            if (runtime.driftedOut) {
+                runtime.driftedOut = false;
+                dlog('Pressable press suppressed by drift past retention region');
+                return;
+            }
+            // A fired long press cancels the tap: reset the flag and suppress onPress.
+            if (runtime.longPressFired) {
+                runtime.longPressFired = false;
+                dlog('Pressable press suppressed by prior longPress');
+                return;
+            }
+            onPress?.(event);
+        },
+        // Responder-move stream of the Pressable's own View. onPressMove fires on every move while
+        // the press is live (RN). Then the retention test: a move outside the measured region
+        // (expanded by hitSlop+pressRectOffset) fires an early pressOut and marks the tap suppressed;
+        // a move back inside re-activates.
+        handleResponderMove(event) {
+            onPressMove?.(event);
+            const here = readPoint(event);
+            if (!here)
+                return;
+            if (!isWithinRetention(here)) {
+                if (!runtime.driftedOut) {
+                    dlog('Pressable drifted past retention region — deactivating');
+                    runtime.driftedOut = true;
+                    clearLongPress();
+                    host.setPressed(false);
+                    onPressOut?.(event);
+                }
+            }
+            else if (runtime.driftedOut) {
+                dlog('Pressable returned inside retention region — reactivating');
+                runtime.driftedOut = false;
+                activate(event);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,46 @@
+import type { ISymbioteNode } from '@symbiote-native/engine';
+import type { IScrollViewHandle } from '../scroll-view-commands';
+export interface ISection<ItemT> {
+    title: string;
+    data: readonly ItemT[];
+}
+export type ISectionEntry<ItemT> = {
+    kind: 'header';
+    section: ISection<ItemT>;
+    sectionIndex: number;
+} | {
+    kind: 'item';
+    item: ItemT;
+    section: ISection<ItemT>;
+    sectionIndex: number;
+    itemIndex: number;
+} | {
+    kind: 'footer';
+    section: ISection<ItemT>;
+    sectionIndex: number;
+} | {
+    kind: 'section-separator';
+    sectionIndex: number;
+};
+export interface IVirtualizedSectionListHandle {
+    scrollToLocation(params: {
+        sectionIndex: number;
+        itemIndex: number;
+        viewOffset?: number;
+        viewPosition?: number;
+        animated?: boolean;
+    }): void;
+    flashScrollIndicators(): void;
+    getNativeScrollRef(): IScrollViewHandle | null;
+    getScrollableNode(): IScrollViewHandle | null;
+    getScrollResponder(): IScrollViewHandle | null;
+    getScrollNode(): ISymbioteNode | null;
+    recordInteraction(): void;
+}
+export declare function flattenSections<ItemT>(sections: ReadonlyArray<ISection<ItemT>>, withSeparators: boolean): {
+    entries: ISectionEntry<ItemT>[];
+    headerIndices: number[];
+};
+export declare function unwrapEntryItem<ItemT>(entry: ISectionEntry<ItemT> | undefined): ItemT | undefined;
+export declare function sectionEntryKey<ItemT>(entry: ISectionEntry<ItemT>, index: number, keyExtractor?: (item: ItemT, index: number) => string): string;
+export declare function scrollLocationToFlatIndex(headerIndices: number[], sectionIndex: number, itemIndex: number): number | undefined;

package/build/state/section-list.js

@@ -0,0 +1,51 @@
+// SectionList logic: the framework-agnostic section flattening over VirtualizedList. Each
+// section contributes a header row, its item rows, then a footer row (RN counts 2 per
+// section around the items); the flattened sequence feeds VirtualizedList as one tagged
+// stream, so headers, items, and footers are windowed by the same machinery. All of this
+// is pure transform — every adapter reuses it; the adapter supplies only the per-entry
+// element creation (renderSectionHeader / renderItem / …) and the ref wiring.
+// Flatten sections into entries AND record where each section header lands in the flat
+// stream, so scrollToLocation can map (sectionIndex, itemIndex) -> flat index without
+// re-deriving the layout. withSeparators inserts a section separator between adjacent
+// sections (never before the first / after the last).
+export function flattenSections(sections, withSeparators) {
+    const entries = [];
+    const headerIndices = [];
+    sections.forEach((section, sectionIndex) => {
+        if (withSeparators && sectionIndex > 0) {
+            entries.push({ kind: 'section-separator', sectionIndex });
+        }
+        headerIndices[sectionIndex] = entries.length;
+        entries.push({ kind: 'header', section, sectionIndex });
+        section.data.forEach((item, itemIndex) => {
+            entries.push({ kind: 'item', item, section, sectionIndex, itemIndex });
+        });
+        entries.push({ kind: 'footer', section, sectionIndex });
+    });
+    return { entries, headerIndices };
+}
+// Unwrap an entry separator-prop into its underlying ItemT (or undefined for a non-item
+// entry: header/footer/section-separator gaps have no item), so the user's
+// ItemSeparatorComponent, typed on ItemT, sees real items.
+export function unwrapEntryItem(entry) {
+    return entry !== undefined && entry.kind === 'item' ? entry.item : undefined;
+}
+export function sectionEntryKey(entry, index, keyExtractor) {
+    if (entry.kind === 'header')
+        return `section-${entry.sectionIndex}`;
+    if (entry.kind === 'footer')
+        return `section-${entry.sectionIndex}:footer`;
+    if (entry.kind === 'section-separator')
+        return `section-${entry.sectionIndex}:separator`;
+    if (keyExtractor)
+        return keyExtractor(entry.item, entry.itemIndex);
+    return `entry-${index}`;
+}
+// RN's itemIndex is offset by 1 so itemIndex 0 targets the header and itemIndex >= 1
+// targets that section's items. Returns undefined when the section is out of range.
+export function scrollLocationToFlatIndex(headerIndices, sectionIndex, itemIndex) {
+    const headerFlatIndex = headerIndices[sectionIndex];
+    if (headerFlatIndex === undefined)
+        return undefined;
+    return headerFlatIndex + itemIndex;
+}

package/build/state/switch.d.ts

@@ -0,0 +1,12 @@
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+export type ISwitchState = {
+    lastNativeReport: boolean | null;
+};
+export type ISwitchAction = {
+    type: 'native-reported';
+    value: boolean;
+};
+export declare function createInitialSwitchState(): ISwitchState;
+export declare function switchReducer(state: ISwitchState, action: ISwitchAction): ISwitchState;
+export declare function valueFromChange(event: ISymbioteEvent): boolean | undefined;
+export declare function shouldSnapBack(state: ISwitchState, fabricValue: boolean): boolean;

package/build/state/switch.js

@@ -0,0 +1,31 @@
+// Switch: the logic half (framework-agnostic, zero render). Switch is controlled exactly
+// like RN's: `value` is a real Fabric prop the parent owns, so the only state the component
+// itself holds is what native LAST reported, kept so the lifecycle layer can detect a
+// rejected toggle and snap native back. The reducer + the two pure predicates here are the
+// whole state machine; the adapter supplies the hook (useReducer / ref / watch) around it.
+export function createInitialSwitchState() {
+    return { lastNativeReport: null };
+}
+export function switchReducer(state, action) {
+    switch (action.type) {
+        case 'native-reported':
+            // Always a fresh object, even when the boolean is unchanged from the prior report:
+            // the snap-back effect keys on state identity so it re-fires on every report (native
+            // may re-toggle to a value JS keeps rejecting, and must be commanded back each time).
+            return { lastNativeReport: action.value };
+    }
+}
+// The change payload carries the new boolean as nativeEvent.value; a non-boolean payload is
+// ignored upstream (no onValueChange, no report). nativeEvent is an untyped Record, so narrow.
+export function valueFromChange(event) {
+    const value = event.nativeEvent.value;
+    return typeof value === 'boolean' ? value : undefined;
+}
+// Snap-back fires only when native reported a value that disagrees with the JS-held value:
+// the parent rejected the toggle (its onValueChange did not update `value`). A plain prop
+// re-push cannot cover this: when the handler is a no-op the prop never changes, so the
+// retained tree never diverges and nothing re-commits. The imperative command is the only
+// correction path. No report yet (null) or agreement → no command.
+export function shouldSnapBack(state, fabricValue) {
+    return state.lastNativeReport !== null && state.lastNativeReport !== fabricValue;
+}

package/build/state/text-input.d.ts

@@ -0,0 +1,103 @@
+import type { ISymbioteEvent, ITextStyle } from '@symbiote-native/engine';
+import type { IAccessibilityProps, IAriaProps } from '../accessibility-props';
+export type IInputMode = 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
+export type IEnterKeyHint = 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';
+export type ISubmitBehavior = 'submit' | 'blurAndSubmit' | 'newline';
+export type ITextInputSelection = {
+    start: number;
+    end?: number;
+};
+export type ITextInputEventHandler = (event: ISymbioteEvent) => void;
+export declare const INITIAL_EVENT_COUNT = 0;
+export declare const SELECTION_NONE = -1;
+export declare function mapAutoComplete(map: Record<string, string>, token: string): string | undefined;
+export declare function foldAutoComplete(token: string | undefined): {
+    autoComplete: string | undefined;
+    textContentType: string | undefined;
+};
+export declare function foldSubmitBehavior(submitBehavior: string | undefined, blurOnSubmit: boolean | undefined, multiline: boolean): string;
+export declare function foldText(value: string | undefined, defaultValue: string | undefined): string | undefined;
+export declare function textFromChange(event: ISymbioteEvent): string | undefined;
+export declare function eventCountFromChange(event: ISymbioteEvent): number | undefined;
+export declare function shouldCommandText(lastNativeText: string | undefined, value: string | undefined): value is string;
+export type ITextInputFoldInput = {
+    inputMode?: string;
+    keyboardType?: string;
+    enterKeyHint?: string;
+    returnKeyType?: string;
+    readOnly?: boolean;
+    editable?: boolean;
+    submitBehavior?: string;
+    blurOnSubmit?: boolean;
+    multiline: boolean;
+    cursorColor?: string;
+    selectionColor?: string;
+    selectionHandleColor?: string;
+    autoComplete?: string;
+    textContentType?: string;
+    showSoftInputOnFocus?: boolean;
+    underlineColorAndroid?: string;
+};
+export type IFoldedTextInputProps = {
+    keyboardType: string | undefined;
+    returnKeyType: string | undefined;
+    editable: boolean | undefined;
+    submitBehavior: string;
+    selectionColor: string | undefined;
+    cursorColor: string | undefined;
+    selectionHandleColor: string | undefined;
+    underlineColorAndroid: string;
+    autoComplete: string | undefined;
+    textContentType: string | undefined;
+    showSoftInputOnFocus: boolean | undefined;
+};
+export declare function resolveTextInputProps(input: ITextInputFoldInput): IFoldedTextInputProps;
+export type ITextInputProps = IAccessibilityProps & IAriaProps & {
+    value?: string;
+    defaultValue?: string;
+    placeholder?: string;
+    placeholderTextColor?: string;
+    editable?: boolean;
+    keyboardType?: string;
+    secureTextEntry?: boolean;
+    maxLength?: number;
+    multiline?: boolean;
+    selection?: ITextInputSelection;
+    autoCapitalize?: 'none' | 'sentences' | 'words' | 'characters';
+    autoCorrect?: boolean;
+    autoComplete?: string;
+    textContentType?: string;
+    autoFocus?: boolean;
+    showSoftInputOnFocus?: boolean;
+    returnKeyType?: string;
+    selectTextOnFocus?: boolean;
+    scrollEnabled?: boolean;
+    numberOfLines?: number;
+    textAlign?: 'left' | 'center' | 'right';
+    blurOnSubmit?: boolean;
+    inputMode?: IInputMode;
+    enterKeyHint?: IEnterKeyHint;
+    readOnly?: boolean;
+    submitBehavior?: ISubmitBehavior;
+    cursorColor?: string;
+    selectionColor?: string;
+    selectionHandleColor?: string;
+    underlineColorAndroid?: string;
+    inputAccessoryViewID?: string;
+    style?: ITextStyle;
+    onValueChange?: (text: string, event: ISymbioteEvent) => void;
+    onFocus?: ITextInputEventHandler;
+    onBlur?: ITextInputEventHandler;
+    onEndEditing?: ITextInputEventHandler;
+    onSubmitEditing?: ITextInputEventHandler;
+    onKeyPress?: ITextInputEventHandler;
+    onSelectionChange?: ITextInputEventHandler;
+    onContentSizeChange?: ITextInputEventHandler;
+};
+export type ITextInputHandle = {
+    focus(): void;
+    blur(): void;
+    clear(): void;
+    isFocused(): boolean;
+    setSelection(start: number, end: number): void;
+};