@symbiote-native/react 0.1.0

package/build/components/text-input/index.d.ts

@@ -0,0 +1,50 @@
+import { type ISymbioteEvent } from '@symbiote-native/engine';
+import type { ITextInputProps as ITextInputBaseProps, ITextInputHandle } from '@symbiote-native/components';
+export type { ITextInputHandle } from '@symbiote-native/components';
+export type ITextInputProps = ITextInputBaseProps & {
+    className?: string;
+};
+export declare const TextInput: import("react").ForwardRefExoticComponent<import("@symbiote-native/components").IAccessibilityProps & import("@symbiote-native/components").IAriaProps & {
+    value?: string;
+    defaultValue?: string;
+    placeholder?: string;
+    placeholderTextColor?: string;
+    editable?: boolean;
+    keyboardType?: string;
+    secureTextEntry?: boolean;
+    maxLength?: number;
+    multiline?: boolean;
+    selection?: import("@symbiote-native/components").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?: import("@symbiote-native/components").IInputMode;
+    enterKeyHint?: import("@symbiote-native/components").IEnterKeyHint;
+    readOnly?: boolean;
+    submitBehavior?: import("@symbiote-native/components").ISubmitBehavior;
+    cursorColor?: string;
+    selectionColor?: string;
+    selectionHandleColor?: string;
+    underlineColorAndroid?: string;
+    inputAccessoryViewID?: string;
+    style?: import("@symbiote-native/engine").ITextStyle;
+    onValueChange?: (text: string, event: ISymbioteEvent) => void;
+    onFocus?: import("@symbiote-native/components").ITextInputEventHandler;
+    onBlur?: import("@symbiote-native/components").ITextInputEventHandler;
+    onEndEditing?: import("@symbiote-native/components").ITextInputEventHandler;
+    onSubmitEditing?: import("@symbiote-native/components").ITextInputEventHandler;
+    onKeyPress?: import("@symbiote-native/components").ITextInputEventHandler;
+    onSelectionChange?: import("@symbiote-native/components").ITextInputEventHandler;
+    onContentSizeChange?: import("@symbiote-native/components").ITextInputEventHandler;
+} & {
+    className?: string;
+} & import("react").RefAttributes<ITextInputHandle>>;

package/build/components/text-input/index.js

@@ -0,0 +1,167 @@
+// TextInput: the React lifecycle half. The folds/maps (value->text, the W3C/alias resolution)
+// and the controlled-write predicate live in @symbiote-native/components/state; the render (intrinsic
+// + native-prop mapping) in @symbiote-native/components/view; both shared verbatim with the Vue
+// adapter. Here React supplies only the lifecycle: useState for the acknowledged event count
+// (it must re-render so the imperative handle echoes the latest), a ref for the host node and
+// the last text native holds, the useLayoutEffect controlled-write, the mount autoFocus, and
+// useImperativeHandle for focus/blur/clear/isFocused/setSelection.
+//
+// The controlled handshake hinges on commanding native back with the ACKNOWLEDGED event count
+// (setTextAndSelection), never a plain prop re-push. See @symbiote-native/components/state/text-input.
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState, } from 'react';
+import { dispatchViewCommand, dlog, } from '@symbiote-native/engine';
+import { blurTextInput, setInputBlurred, setInputFocused } from '../../modules/text-input-state';
+import { resolveAccessibilityProps, resolveTextInputProps, renderTextInput, foldText, textFromChange, eventCountFromChange, shouldCommandText, INITIAL_EVENT_COUNT, SELECTION_NONE, } from '@symbiote-native/components';
+import { descriptorToReact } from '../../descriptor-to-react';
+export const TextInput = forwardRef((rawProps, forwardedRef) => {
+    // TextInput is its own host element (not a View wrapper), so it folds aria/role here.
+    const props = resolveAccessibilityProps(rawProps);
+    // Pull out the fields the lifecycle owns (controlled value, the wrapped handlers, the folded
+    // aliases) so they don't reach Fabric raw; everything else rides down via `passthrough`.
+    const { value, defaultValue, multiline, selection, onValueChange, onFocus, onBlur, inputMode, enterKeyHint, readOnly, submitBehavior, blurOnSubmit, cursorColor, selectionColor, selectionHandleColor, keyboardType, returnKeyType, editable, autoComplete, textContentType, autoFocus, showSoftInputOnFocus, underlineColorAndroid, ...passthrough } = props;
+    const isMultiline = multiline === true;
+    const folded = resolveTextInputProps({
+        inputMode,
+        keyboardType,
+        enterKeyHint,
+        returnKeyType,
+        readOnly,
+        editable,
+        submitBehavior,
+        blurOnSubmit,
+        multiline: isMultiline,
+        cursorColor,
+        selectionColor,
+        selectionHandleColor,
+        autoComplete,
+        textContentType,
+        showSoftInputOnFocus,
+        underlineColorAndroid,
+    });
+    const ref = useRef(null);
+    // JS-side focus state, mirrored from the focus/blur events for isFocused(). RN's
+    // TextInputState holds the same; native exposes no synchronous focus getter.
+    const focused = useRef(false);
+    // The count native last acknowledged. We echo it back on every controlled write so native's
+    // eventLag lands on 0 and the write applies.
+    const [mostRecentEventCount, setMostRecentEventCount] = useState(INITIAL_EVENT_COUNT);
+    // The last text native holds, as far as JS knows. Seeded from the mount-time value because the
+    // `text` prop already carries that value down via createNode, so the FIRST controlled value is
+    // not a divergence and must NOT re-command. Only later, post-keystroke divergences flow through
+    // setTextAndSelection.
+    const lastNativeText = useRef(foldText(value, defaultValue));
+    const handleChange = useCallback((event) => {
+        // Event seam: the controlled handshake hinges on the change payload carrying `text`
+        // (+ `eventCount`). iOS and Android Fabric can key these differently, so log the actual
+        // shape here; a missing `text` means onValueChange never fires.
+        dlog(`TextInput change keys=[${Object.keys(event.nativeEvent).join(',')}] ` +
+            `text=${JSON.stringify(event.nativeEvent.text)} count=${JSON.stringify(event.nativeEvent.eventCount)}`);
+        const text = textFromChange(event);
+        if (text !== undefined) {
+            lastNativeText.current = text;
+            onValueChange?.(text, event);
+        }
+        // Ordering matters: record the text first, then bump the acknowledged count, so the count
+        // never runs ahead of the text it stands for.
+        const count = eventCountFromChange(event);
+        if (count !== undefined)
+            setMostRecentEventCount(count);
+    }, [onValueChange]);
+    const text = foldText(value, defaultValue);
+    // Controlled write: when JS-side `value` diverges from what native reported, command the new
+    // text down with the acknowledged count. A plain prop re-push would race the user's keystrokes;
+    // the command is the only stale-safe path. No deps; it runs after every render and the
+    // predicate makes it a no-op unless the text diverged.
+    useLayoutEffect(() => {
+        const node = ref.current;
+        if (node === null)
+            return;
+        if (!shouldCommandText(lastNativeText.current, value))
+            return;
+        const selStart = selection?.start ?? SELECTION_NONE;
+        const selEnd = selection?.end ?? selection?.start ?? SELECTION_NONE;
+        dlog(`TextInput setTextAndSelection count=${mostRecentEventCount} text=${JSON.stringify(value)}`);
+        dispatchViewCommand(node, 'setTextAndSelection', [
+            mostRecentEventCount,
+            value,
+            selStart,
+            selEnd,
+        ]);
+        lastNativeText.current = value;
+    });
+    // autoFocus is driven in JS, not as a native prop: on mount, command `focus` down once (RN does
+    // the same via TextInputState.focusInput, TextInput.js:538). Empty deps so it fires only on
+    // mount; the native `focus` command is idempotent if already focused.
+    useEffect(() => {
+        if (autoFocus !== true)
+            return;
+        const node = ref.current;
+        if (node === null)
+            return;
+        dlog('TextInput autoFocus -> focus command');
+        dispatchViewCommand(node, 'focus', []);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const handleFocus = useCallback((event) => {
+        focused.current = true;
+        // Track focus app-wide so Keyboard.dismiss can blur this input without a ref.
+        if (ref.current !== null)
+            setInputFocused(ref.current);
+        onFocus?.(event);
+    }, [onFocus]);
+    const handleBlur = useCallback((event) => {
+        focused.current = false;
+        if (ref.current !== null)
+            setInputBlurred(ref.current);
+        onBlur?.(event);
+    }, [onBlur]);
+    // The imperative API RN exposes on the ref. focus/blur drive native view commands; clear and
+    // setSelection reuse setTextAndSelection (the same stale-safe path as a controlled write),
+    // echoing the acknowledged event count so native applies them.
+    useImperativeHandle(forwardedRef, () => ({
+        focus: () => {
+            const node = ref.current;
+            if (node !== null)
+                dispatchViewCommand(node, 'focus', []);
+        },
+        blur: () => {
+            // Routes through TextInputState so the app-wide focus tracking clears too.
+            blurTextInput(ref.current);
+        },
+        clear: () => {
+            const node = ref.current;
+            if (node === null)
+                return;
+            dispatchViewCommand(node, 'setTextAndSelection', [mostRecentEventCount, '', 0, 0]);
+            lastNativeText.current = '';
+        },
+        isFocused: () => focused.current,
+        setSelection: (start, end) => {
+            const node = ref.current;
+            if (node === null)
+                return;
+            const current = lastNativeText.current ?? '';
+            dispatchViewCommand(node, 'setTextAndSelection', [
+                mostRecentEventCount,
+                current,
+                start,
+                end,
+            ]);
+        },
+    }), [mostRecentEventCount]);
+    return descriptorToReact(renderTextInput({
+        multiline: isMultiline,
+        text,
+        mostRecentEventCount,
+        selection,
+        folded,
+        passthrough: {
+            ...passthrough,
+            ref,
+            onChange: handleChange,
+            onFocus: handleFocus,
+            onBlur: handleBlur,
+        },
+    }));
+});
+TextInput.displayName = 'TextInput';

package/build/components/touchable/index.d.ts

@@ -0,0 +1,20 @@
+import { type FC, type ReactNode } from 'react';
+import { type IPressTimingProps } from '@symbiote-native/components';
+import { type IPressableProps } from '../pressable';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+type ITouchableBaseProps = Omit<IPressableProps, 'style' | 'children'> & IPressTimingProps & {
+    style?: IStyleProp<IViewStyle>;
+    children?: ReactNode;
+};
+export interface ITouchableOpacityProps extends ITouchableBaseProps {
+    activeOpacity?: number;
+}
+export declare const TouchableOpacity: FC<ITouchableOpacityProps>;
+export interface ITouchableHighlightProps extends ITouchableBaseProps {
+    activeOpacity?: number;
+    underlayColor?: string;
+}
+export declare const TouchableHighlight: FC<ITouchableHighlightProps>;
+export type ITouchableWithoutFeedbackProps = ITouchableBaseProps;
+export declare const TouchableWithoutFeedback: FC<ITouchableWithoutFeedbackProps>;
+export {};

package/build/components/touchable/index.js

@@ -0,0 +1,95 @@
+// The Touchable* family, all built on Pressable. RN realizes their feedback with Animated, and so
+// do we. The press-timing constants and the deactivation-floor math are shared with every adapter
+// (@symbiote-native/components/state/touchable); here React owns only the Animated wiring + the press
+// scheduling refs:
+//   TouchableOpacity:   animate an Animated.Value opacity toward activeOpacity on press-in and
+//     back to 1 on press-out, driven imperatively from onPressIn/onPressOut.
+//   TouchableHighlight: paint underlayColor + lower child opacity while pressed, via Pressable's
+//     pressed-state style (RN drives this with setState, not Animated, faithfully).
+//   TouchableWithoutFeedback: no visual change, just the press wiring.
+import { createElement, useRef } from 'react';
+import { dlog } from '@symbiote-native/engine';
+import { computePressOutWait, DEFAULT_ACTIVE_OPACITY, DEFAULT_HIGHLIGHT_CHILD_OPACITY, DEFAULT_MIN_PRESS_DURATION_MS, DEFAULT_UNDERLAY_COLOR, OPACITY_ACTIVE_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, RESTING_OPACITY, } from '@symbiote-native/components';
+import { Pressable } from '../pressable';
+import { Animated } from '../../modules/animated';
+export const TouchableOpacity = props => {
+    const { activeOpacity = DEFAULT_ACTIVE_OPACITY, style, 
+    // className is pulled out here, like style, and applied to the inner Animated.View below —
+    // left in ...rest it would land on the outer Pressable instead, which is not where `style`
+    // (the opacity-fade node) goes.
+    className, children, onPressIn, onPressOut, delayPressIn = 0, delayPressOut = 0, minPressDuration = DEFAULT_MIN_PRESS_DURATION_MS, ...rest } = props;
+    // One Animated.Value per mount, resting at full opacity. The Animated.View leaf commits its
+    // current value every frame, so timing it animates the real view.
+    const opacity = useRef(new Animated.Value(RESTING_OPACITY)).current;
+    // The pending delayPressIn timer, so a release before it fires can flush it.
+    const pressInTimer = useRef(undefined);
+    // When the active visual actually started, to floor onPressOut by minPressDuration.
+    const activatedAt = useRef(undefined);
+    function setOpacityTo(toValue, duration) {
+        Animated.timing(opacity, {
+            toValue,
+            duration,
+            easing: Animated.Easing.inOut(Animated.Easing.quad),
+            useNativeDriver: false,
+        }).start();
+    }
+    function clearPressInTimer() {
+        if (pressInTimer.current !== undefined) {
+            clearTimeout(pressInTimer.current);
+            pressInTimer.current = undefined;
+        }
+    }
+    function activate(event) {
+        activatedAt.current = Date.now();
+        setOpacityTo(activeOpacity, OPACITY_ACTIVE_DURATION_MS);
+        onPressIn?.(event);
+    }
+    function deactivate(event) {
+        activatedAt.current = undefined;
+        setOpacityTo(RESTING_OPACITY, OPACITY_INACTIVE_DURATION_MS);
+        onPressOut?.(event);
+    }
+    // RN's _createPressabilityConfig forwards delayPressIn: defer the active visual and onPressIn
+    // behind the delay (a release before it elapses flushes it synchronously).
+    function handlePressIn(event) {
+        if (delayPressIn > 0) {
+            dlog(`TouchableOpacity pressIn deferred ${delayPressIn}ms`);
+            pressInTimer.current = setTimeout(() => {
+                pressInTimer.current = undefined;
+                activate(event);
+            }, delayPressIn);
+            return;
+        }
+        activate(event);
+    }
+    // delayPressOut + minPressDuration (RN _deactivate): the press-out waits at least minPress-
+    // Duration past activation (so a fast tap holds the active visual) and at least delayPressOut.
+    function handlePressOut(event) {
+        if (pressInTimer.current !== undefined) {
+            clearPressInTimer();
+            activate(event);
+        }
+        const heldFor = activatedAt.current === undefined ? 0 : Date.now() - activatedAt.current;
+        const wait = computePressOutWait(heldFor, minPressDuration, delayPressOut);
+        if (wait > 0) {
+            dlog(`TouchableOpacity pressOut deferred ${wait}ms`);
+            setTimeout(() => deactivate(event), wait);
+            return;
+        }
+        deactivate(event);
+    }
+    return createElement(Pressable, { ...rest, onPressIn: handlePressIn, onPressOut: handlePressOut }, createElement(Animated.View, { style: [style, { opacity }], className }, children));
+};
+export const TouchableHighlight = props => {
+    const { activeOpacity = DEFAULT_HIGHLIGHT_CHILD_OPACITY, underlayColor = DEFAULT_UNDERLAY_COLOR, style, children, ...rest } = props;
+    function pressedStyle({ pressed }) {
+        if (!pressed)
+            return style;
+        return [style, { backgroundColor: underlayColor, opacity: activeOpacity }];
+    }
+    return createElement(Pressable, { ...rest, style: pressedStyle }, children);
+};
+export const TouchableWithoutFeedback = props => {
+    const { children, ...rest } = props;
+    return createElement(Pressable, rest, children);
+};

package/build/components/touchable-native-feedback/index.d.ts

@@ -0,0 +1,18 @@
+import { type FC, type ReactNode } from 'react';
+import { type INativeFeedbackBackground, type IThemeAttrBackground, type IRippleBackground } from '@symbiote-native/components';
+import { type IPressableProps } from '../pressable';
+export type { INativeFeedbackBackground, IThemeAttrBackground, IRippleBackground, } from '@symbiote-native/components';
+type ITouchableNativeFeedbackBaseProps = Omit<IPressableProps, 'style' | 'children'> & {
+    background?: INativeFeedbackBackground;
+    useForeground?: boolean;
+    children?: ReactNode;
+};
+export type ITouchableNativeFeedbackProps = ITouchableNativeFeedbackBaseProps;
+interface ITouchableNativeFeedbackComponent extends FC<ITouchableNativeFeedbackProps> {
+    SelectableBackground: (rippleRadius?: number) => IThemeAttrBackground;
+    SelectableBackgroundBorderless: (rippleRadius?: number) => IThemeAttrBackground;
+    Ripple: (color: string, borderless: boolean, rippleRadius?: number) => IRippleBackground;
+    canUseNativeForeground: () => boolean;
+}
+declare const TouchableNativeFeedback: ITouchableNativeFeedbackComponent;
+export { TouchableNativeFeedback };

package/build/components/touchable-native-feedback/index.js

@@ -0,0 +1,32 @@
+// TouchableNativeFeedback: Android's ripple/state-drawable touchable, built on Pressable like the
+// rest of the family. RN realizes its feedback by cloning the child into an RCTView carrying native
+// ripple props; we instead nest the child under a feedback View that carries those props, inside a
+// Pressable that owns the press wiring. The native props (nativeBackgroundAndroid /
+// nativeForegroundAndroid) are read by Android's ReactViewManager; on iOS they are inert props, so
+// the component still renders its child with working press wiring. The static factories +
+// background mapping are shared in @symbiote-native/components/view. React only attaches them onto the
+// component value and nests the feedback View.
+import { createElement } from 'react';
+import { dlog } from '@symbiote-native/engine';
+import { backgroundProps, canUseNativeForeground, rippleBackground, selectableBackground, selectableBackgroundBorderless, } from '@symbiote-native/components';
+import { View } from '../../components';
+import { Pressable } from '../pressable';
+const TouchableNativeFeedbackImpl = props => {
+    const { background, useForeground = false, children, ...rest } = props;
+    // RN defaults a missing background to SelectableBackground() so the touchable always has
+    // feedback; mirror that here.
+    const resolved = background ?? selectableBackground();
+    dlog(`TouchableNativeFeedback render ${resolved.type} useForeground ${useForeground}`);
+    const nativeProps = backgroundProps(resolved, useForeground);
+    // The native ripple props ride a dedicated feedback View nested under the Pressable; the
+    // Pressable owns the press wiring, the feedback View owns the drawable.
+    const feedback = createElement(View, nativeProps, children);
+    return createElement(Pressable, rest, feedback);
+};
+const TouchableNativeFeedback = Object.assign(TouchableNativeFeedbackImpl, {
+    SelectableBackground: selectableBackground,
+    SelectableBackgroundBorderless: selectableBackgroundBorderless,
+    Ripple: rippleBackground,
+    canUseNativeForeground,
+});
+export { TouchableNativeFeedback };

package/build/components/virtualized-list/index.d.ts

@@ -0,0 +1,73 @@
+import { type ComponentType, type ReactElement, type ReactNode, type Ref } from 'react';
+import { type ISymbioteEvent } from '@symbiote-native/engine';
+import { type ICellLayout, type ISeparators, type ISeparatorProps, type IViewToken, type IViewableItemsChangedInfo, type IViewabilityConfig, type IViewabilityConfigCallbackPair, type IVirtualizedListHandle } from '@symbiote-native/components';
+import type { IAccessibilityProps, IAriaProps } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+export type { ICellLayout, ISeparators, ISeparatorProps, IViewToken, IViewableItemsChangedInfo, IViewabilityConfig, IViewabilityConfigCallbackPair, IVirtualizedListHandle, };
+type IRenderItem<ItemT> = (info: {
+    item: ItemT;
+    index: number;
+    separators: ISeparators;
+}) => ReactNode;
+export interface IVirtualizedListProps<ItemT> extends IAccessibilityProps, IAriaProps {
+    data: unknown;
+    getItem: (data: unknown, index: number) => ItemT;
+    getItemCount: (data: unknown) => number;
+    renderItem: IRenderItem<ItemT>;
+    keyExtractor?: (item: ItemT, index: number) => string;
+    getItemLayout?: (data: unknown, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
+    ItemSeparatorComponent?: ComponentType<ISeparatorProps<ItemT>>;
+    ListHeaderComponent?: ComponentType<Record<string, never>> | ReactElement;
+    ListFooterComponent?: ComponentType<Record<string, never>> | ReactElement;
+    ListEmptyComponent?: ComponentType<Record<string, never>> | ReactElement;
+    horizontal?: boolean;
+    inverted?: boolean;
+    extraData?: unknown;
+    onEndReached?: (info: {
+        distanceFromEnd: number;
+    }) => void;
+    onEndReachedThreshold?: number;
+    onStartReached?: (info: {
+        distanceFromStart: number;
+    }) => void;
+    onStartReachedThreshold?: number;
+    onRefresh?: () => void;
+    refreshing?: boolean | null;
+    progressViewOffset?: number;
+    onViewableItemsChanged?: (info: IViewableItemsChangedInfo<ItemT>) => void;
+    viewabilityConfig?: IViewabilityConfig;
+    viewabilityConfigCallbackPairs?: IViewabilityConfigCallbackPair<ItemT>[];
+    onScrollToIndexFailed?: (info: {
+        index: number;
+        highestMeasuredFrameIndex: number;
+        averageItemLength: number;
+    }) => void;
+    initialNumToRender?: number;
+    initialScrollIndex?: number;
+    maxToRenderPerBatch?: number;
+    updateCellsBatchingPeriod?: number;
+    windowSize?: number;
+    stickyHeaderIndices?: number[];
+    maintainVisibleContentPosition?: {
+        minIndexForVisible: number;
+        autoscrollToTopThreshold?: number;
+    };
+    onScroll?: (event: ISymbioteEvent) => void;
+    onScrollBeginDrag?: (event: ISymbioteEvent) => void;
+    onScrollEndDrag?: (event: ISymbioteEvent) => void;
+    onMomentumScrollBegin?: (event: ISymbioteEvent) => void;
+    onMomentumScrollEnd?: (event: ISymbioteEvent) => void;
+    scrollEventThrottle?: number;
+    keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
+    keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+    style?: IStyleProp<IViewStyle>;
+    contentContainerStyle?: IStyleProp<IViewStyle>;
+    className?: string;
+}
+export declare function VirtualizedList<ItemT>(props: IVirtualizedListProps<ItemT> & {
+    ref?: Ref<IVirtualizedListHandle>;
+}): ReactElement;