@symbiote-native/react 3.3.0 → 3.4.0

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

@@ -0,0 +1,85 @@
+import type { ComponentType, ReactElement, ReactNode } from 'react';
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import type { IAccessibilityProps, IAriaProps, ICellRendererBaseProps, IInnerViewRef, ISeparatorProps, ISeparators, IViewabilityConfig, IViewabilityConfigCallbackPair, IViewableItemsChangedInfo } from '@symbiote-native/components';
+import type { IStyleProp, IViewStyle } from '../../utils/styles';
+export type IListItemInfo<ItemT> = {
+    item: ItemT;
+    index: number;
+    separators: ISeparators;
+};
+export type IRenderItem<ItemT> = (info: IListItemInfo<ItemT>) => ReactNode;
+export type ICellRendererProps<ItemT> = ICellRendererBaseProps<ItemT> & {
+    children?: ReactNode;
+};
+export type ICellRendererComponent<ItemT> = (props: ICellRendererProps<ItemT>) => ReactNode;
+export type IListSlot = ComponentType<Record<string, never>> | ReactElement | undefined;
+export type ISeparatorComponent<ItemT> = ComponentType<ISeparatorProps<ItemT>> | ReactElement;
+export type IVirtualizedListProps<ItemT> = IAccessibilityProps & IAriaProps & {
+    data: unknown;
+    getItem: (data: unknown, index: number) => ItemT;
+    getItemCount: (data: unknown) => number;
+    renderItem?: IRenderItem<ItemT>;
+    ListItemComponent?: ComponentType<IListItemInfo<ItemT>>;
+    keyExtractor?: (item: ItemT, index: number) => string;
+    getItemLayout?: (data: unknown, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
+    ItemSeparatorComponent?: ISeparatorComponent<ItemT>;
+    CellRendererComponent?: ICellRendererComponent<ItemT>;
+    ListHeaderComponent?: IListSlot;
+    ListFooterComponent?: IListSlot;
+    ListEmptyComponent?: IListSlot;
+    ListHeaderComponentStyle?: IStyleProp<IViewStyle>;
+    ListFooterComponentStyle?: IStyleProp<IViewStyle>;
+    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;
+    disableVirtualization?: boolean;
+    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;
+    onContentSizeChange?: (width: number, height: number) => void;
+    scrollEventThrottle?: number;
+    keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
+    keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+    removeClippedSubviews?: boolean;
+    nestedScrollEnabled?: boolean;
+    stickyHeaderHiddenOnScroll?: boolean;
+    innerViewRef?: IInnerViewRef;
+    style?: IStyleProp<IViewStyle>;
+    contentContainerStyle?: IStyleProp<IViewStyle>;
+    className?: string;
+};

package/build/components/virtualized-list/virtualized-list-props.js

@@ -0,0 +1,2 @@
+// Public prop types of the React VirtualizedList
+export {};

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

@@ -1,12 +1,20 @@
 import { type ComponentType, type ReactElement, type ReactNode, type Ref } from 'react';
 import { type ISymbioteEvent } from '@symbiote-native/engine';
-import { type ISection, type IVirtualizedSectionListHandle } from '@symbiote-native/components';
-import { type ISeparators, type ISeparatorProps } from '../virtualized-list';
-import type { IAccessibilityProps, IAriaProps } from '@symbiote-native/components';
+import { type ISection as ICoreSection, type IVirtualizedSectionListHandle } from '@symbiote-native/components';
+import { type ICellRendererComponent, type ISeparatorComponent, type ISeparators } from '../virtualized-list';
+import type { IAccessibilityProps, IAriaProps, IInnerViewRef } from '@symbiote-native/components';
 import type { IStyleProp, IViewStyle } from '../../utils/styles';
-export type { ISection } from '@symbiote-native/components';
 export type { IVirtualizedSectionListHandle };
-export interface IVirtualizedSectionListProps<ItemT> extends IAccessibilityProps, IAriaProps {
+export type ISection<ItemT> = ICoreSection<ItemT> & {
+    renderItem?: (info: {
+        item: ItemT;
+        index: number;
+        section: ISection<ItemT>;
+        separators: ISeparators;
+    }) => ReactNode;
+    ItemSeparatorComponent?: ISeparatorComponent<ItemT>;
+};
+export type IVirtualizedSectionListProps<ItemT> = IAccessibilityProps & IAriaProps & {
     sections: ReadonlyArray<ISection<ItemT>>;
     renderItem: (info: {
         item: ItemT;
@@ -20,7 +28,7 @@ export interface IVirtualizedSectionListProps<ItemT> extends IAccessibilityProps
     renderSectionFooter?: (info: {
         section: ISection<ItemT>;
     }) => ReactNode;
-    SectionSeparatorComponent?: ComponentType<Record<string, never>> | ReactElement;
+    SectionSeparatorComponent?: ISeparatorComponent<ItemT>;
     keyExtractor?: (item: ItemT, index: number) => string;
     getItemLayout?: (data: ReadonlyArray<ISection<ItemT>> | null, index: number) => {
         length: number;
@@ -29,10 +37,13 @@ export interface IVirtualizedSectionListProps<ItemT> extends IAccessibilityProps
     };
     stickySectionHeadersEnabled?: boolean;
     extraData?: unknown;
-    ItemSeparatorComponent?: ComponentType<ISeparatorProps<ItemT>>;
+    ItemSeparatorComponent?: ISeparatorComponent<ItemT>;
+    CellRendererComponent?: ICellRendererComponent<unknown>;
     ListHeaderComponent?: ComponentType<Record<string, never>> | ReactElement;
     ListFooterComponent?: ComponentType<Record<string, never>> | ReactElement;
     ListEmptyComponent?: ComponentType<Record<string, never>> | ReactElement;
+    ListHeaderComponentStyle?: IStyleProp<IViewStyle>;
+    ListFooterComponentStyle?: IStyleProp<IViewStyle>;
     onEndReached?: (info: {
         distanceFromEnd: number;
     }) => void;
@@ -49,7 +60,9 @@ export interface IVirtualizedSectionListProps<ItemT> extends IAccessibilityProps
     maxToRenderPerBatch?: number;
     updateCellsBatchingPeriod?: number;
     windowSize?: number;
+    disableVirtualization?: boolean;
     inverted?: boolean;
+    horizontal?: boolean;
     maintainVisibleContentPosition?: {
         minIndexForVisible: number;
         autoscrollToTopThreshold?: number;
@@ -59,15 +72,18 @@ export interface IVirtualizedSectionListProps<ItemT> extends IAccessibilityProps
     onScrollEndDrag?: (event: ISymbioteEvent) => void;
     onMomentumScrollBegin?: (event: ISymbioteEvent) => void;
     onMomentumScrollEnd?: (event: ISymbioteEvent) => void;
+    onContentSizeChange?: (width: number, height: number) => void;
     scrollEventThrottle?: number;
     keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
     keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
     removeClippedSubviews?: boolean;
     nestedScrollEnabled?: boolean;
+    stickyHeaderHiddenOnScroll?: boolean;
+    innerViewRef?: IInnerViewRef;
     style?: IStyleProp<IViewStyle>;
     contentContainerStyle?: IStyleProp<IViewStyle>;
     className?: string;
-}
+};
 export declare function VirtualizedSectionList<ItemT>(props: IVirtualizedSectionListProps<ItemT> & {
     ref?: Ref<IVirtualizedSectionListHandle>;
 }): ReactElement;

package/build/components/virtualized-section-list/index.js

@@ -5,113 +5,109 @@
 // mapping are shared from @symbiote-native/components; this file wires React's lifecycle (refs +
 // useImperativeHandle + the per-entry render dispatch). Lower layer in RN's
 // SectionList -> VirtualizedSectionList -> VirtualizedList stack.
-import { createElement, useImperativeHandle, useRef, } from 'react';
-import { dlog, Platform, } from '@symbiote-native/engine';
-import { flattenSections, resolveStickySectionHeaders, scrollLocationToFlatIndex, sectionEntryKey, unwrapEntryItem, } from '@symbiote-native/components';
+import { createElement, useImperativeHandle, useRef, useState, } from 'react';
+import { dlog, Platform } from '@symbiote-native/engine';
+import { cellGapsFor, createSeparatorBoard, flattenSections, resolveStickySectionHeaders, layoutOverSections, renderSectionEntry, resolveScrollLocation, routeScrollHandle, sectionEntryKey, } from '@symbiote-native/components';
 import { VirtualizedList, } from '../virtualized-list/index.js';
-function resolveSeparator(component) {
-    if (component === undefined)
-        return undefined;
-    if (typeof component === 'function')
-        return createElement(component, {});
-    return component;
-}
-export function VirtualizedSectionList(props) {
-    const { ref, sections, renderItem, renderSectionHeader, renderSectionFooter, SectionSeparatorComponent, 
-    // Pulled out of `rest`: the user's separator is typed on ItemT, but the inner VirtualizedList
-    // streams ISectionEntry<ItemT>, so we wrap it to unwrap each entry back to its ItemT.
-    ItemSeparatorComponent, keyExtractor, 
-    // Also pulled out of `rest`: the inner list streams entries, the user's callback expects
-    // sections. See entryItemLayout below.
-    getItemLayout, stickySectionHeadersEnabled, ...rest } = props;
-    const { entries, headerIndices } = flattenSections(sections, SectionSeparatorComponent !== undefined);
-    // RN sticks section headers by default only on iOS; Android does not unless asked. headerIndices
-    // are the flat positions of every section header; VirtualizedList forwards the in-window ones.
-    const stickyHeaderIndices = resolveStickySectionHeaders(stickySectionHeadersEnabled, headerIndices, Platform.OS);
-    // The handle reaches into the inner VirtualizedList to drive scrollToIndex.
-    const listRef = useRef(null);
-    dlog(`VirtualizedSectionList: ${sections.length} sections flattened to ${entries.length} entries`);
-    useImperativeHandle(ref ?? null, () => ({
+import { SectionItemCell } from './section-item-cell.js';
+// Kept apart so the component body stays readable: the handle only forwards to the inner list
+function buildSectionHandle(listRef, headerIndices, stickyHeaderIndices) {
+    return {
         scrollToLocation: (params) => {
-            const flatIndex = scrollLocationToFlatIndex(headerIndices, params.sectionIndex, params.itemIndex);
-            if (flatIndex === undefined) {
+            const target = resolveScrollLocation(headerIndices, stickyHeaderIndices, params);
+            if (target === undefined) {
                 dlog(`VirtualizedSectionList scrollToLocation: section ${params.sectionIndex} out of range`);
                 return;
             }
             dlog(`VirtualizedSectionList scrollToLocation section=${params.sectionIndex} ` +
-                `item=${params.itemIndex} -> flat ${flatIndex}`);
-            listRef.current?.scrollToIndex({
-                index: flatIndex,
-                viewOffset: params.viewOffset,
-                viewPosition: params.viewPosition,
-                animated: params.animated,
-            });
-        },
-        flashScrollIndicators: () => {
-            listRef.current?.flashScrollIndicators();
-        },
-        getNativeScrollRef: () => listRef.current?.getNativeScrollRef() ?? null,
-        getScrollableNode: () => listRef.current?.getScrollableNode() ?? null,
-        getScrollResponder: () => listRef.current?.getScrollResponder() ?? null,
-        getScrollNode: () => listRef.current?.getScrollNode() ?? null,
-        recordInteraction: () => {
-            listRef.current?.recordInteraction();
+                `item=${params.itemIndex} -> flat ${target.index}`);
+            listRef.current?.scrollToIndex(target);
         },
-    }), [headerIndices]);
-    const renderEntry = (info) => {
-        const entry = info.item;
-        if (entry.kind === 'header') {
-            return renderSectionHeader
-                ? renderSectionHeader({ section: entry.section })
-                : undefined;
-        }
-        if (entry.kind === 'footer') {
-            return renderSectionFooter
-                ? renderSectionFooter({ section: entry.section })
-                : undefined;
-        }
-        if (entry.kind === 'section-separator') {
-            return resolveSeparator(SectionSeparatorComponent);
-        }
-        return renderItem({
-            item: entry.item,
-            index: entry.itemIndex,
-            section: entry.section,
-            separators: info.separators,
-        });
+        ...routeScrollHandle(() => listRef.current),
     };
-    // The user's ItemSeparatorComponent is typed on ItemT; the inner stream is the entry wrapper, so
-    // unwrap each entry back to its ItemT (shared unwrapEntryItem) before handing it to the user.
-    const entrySeparatorComponent = ItemSeparatorComponent === undefined
-        ? undefined
-        : (entryProps) => createElement(ItemSeparatorComponent, {
-            ...entryProps,
-            leadingItem: unwrapEntryItem(entryProps.leadingItem),
-            trailingItem: unwrapEntryItem(entryProps.trailingItem),
-        });
-    const entryKeyExtractor = (entry, index) => sectionEntryKey(entry, index, keyExtractor);
-    // Hand the callback `sections`, not the entries: RN's inner VirtualizedList gets
-    // `data={this.props.sections}` (VirtualizedSectionList.js:216) while ours streams the FLATTENED
-    // entries, so the same user code would otherwise see a different argument here than on RN.
-    //
-    // UPSTREAM-DIVERGENCE(react-native): the flat INDEX matches RN's (two rows per section, header
-    // and footer) only while SectionSeparatorComponent is unset. With it, flattenSections emits an
-    // extra 'section-separator' row per boundary that RN renders inside the neighbouring cell, so
-    // indices shift by one per boundary from the second section on. Deliberate - that row is how this
-    // adapter paints the separator; a caller combining the two must account for it.
-    const entryItemLayout = getItemLayout === undefined
-        ? undefined
-        : (_entries, index) => getItemLayout(sections, index);
+}
+// The handle reaches into the inner list to drive `scrollToIndex`, so it owns the list ref
+function useSectionHandle(ref, headerIndices, stickyHeaderIndices) {
+    const listRef = useRef(null);
+    useImperativeHandle(ref ?? null, () => buildSectionHandle(listRef, headerIndices, stickyHeaderIndices), [headerIndices, stickyHeaderIndices]);
+    return listRef;
+}
+function flattenLogged(sections) {
+    const flat = flattenSections(sections);
+    dlog(`VirtualizedSectionList: ${sections.length} sections flattened to ${flat.entries.length} entries`);
+    return flat;
+}
+// The flat stream plus the board its item cells share their separator state through
+function useSectionEntries(sections, keyExtractor, stickySectionHeadersEnabled) {
+    const [board] = useState(() => createSeparatorBoard());
+    const keyOf = (entry) => sectionEntryKey(entry, keyExtractor);
+    const { entries, headerIndices } = flattenLogged(sections);
+    // RN sticks section headers by default only on iOS; Android does not unless asked
+    const stickyHeaderIndices = resolveStickySectionHeaders(stickySectionHeadersEnabled, headerIndices, Platform.OS);
+    return { entries, headerIndices, stickyHeaderIndices, board, keyOf };
+}
+// A separator component by the kind of gap it sits in: the section one, or the item one where a
+// section's own `ItemSeparatorComponent` beats the list's
+function separatorFor(gap, renderers) {
+    if (gap.kind === 'section')
+        return renderers.SectionSeparatorComponent;
+    if (gap.kind === 'item')
+        return (gap.props.section.ItemSeparatorComponent ??
+            renderers.ItemSeparatorComponent);
+    return undefined;
+}
+// The inner list's single `renderItem`, one renderer per entry kind. An item entry becomes a
+// cell that paints its own separators, so the inner list gets no `ItemSeparatorComponent`
+function entryRendererFor(renderers) {
+    return info => renderSectionEntry({
+        header: ({ section }) => renderers.renderSectionHeader?.({ section }),
+        footer: ({ section }) => renderers.renderSectionFooter?.({ section }),
+        item: entry => {
+            const gaps = cellGapsFor(renderers.entries, info.index);
+            const previous = renderers.entries[info.index - 1];
+            return createElement((SectionItemCell), {
+                board: renderers.board,
+                cellKey: renderers.keyOf(entry),
+                prevCellKey: previous === undefined ? undefined : renderers.keyOf(previous),
+                item: entry.item,
+                index: entry.itemIndex,
+                section: entry.section,
+                renderItem: entry.section.renderItem ?? renderers.renderItem,
+                leadingGap: gaps.leading,
+                trailingGap: gaps.trailing,
+                LeadingSeparatorComponent: separatorFor(gaps.leading, renderers),
+                TrailingSeparatorComponent: separatorFor(gaps.trailing, renderers),
+                inverted: renderers.inverted === true,
+            });
+        },
+    }, info.item);
+}
+export function VirtualizedSectionList(props) {
+    const { ref, sections, renderItem, renderSectionHeader, renderSectionFooter, SectionSeparatorComponent, 
+    // Pulled out of `rest`, these are typed on ItemT while the inner list streams entries
+    ItemSeparatorComponent, keyExtractor, getItemLayout, stickySectionHeadersEnabled, inverted, ...rest } = props;
+    const { entries, headerIndices, stickyHeaderIndices, board, keyOf } = useSectionEntries(sections, keyExtractor, stickySectionHeadersEnabled);
+    const listRef = useSectionHandle(ref, headerIndices, stickyHeaderIndices);
     return createElement((VirtualizedList), {
         ref: listRef,
         data: entries,
         getItem: (_source, index) => entries[index],
         getItemCount: () => entries.length,
-        renderItem: renderEntry,
-        keyExtractor: entryKeyExtractor,
-        getItemLayout: entryItemLayout,
+        renderItem: entryRendererFor({
+            renderItem,
+            renderSectionHeader,
+            renderSectionFooter,
+            SectionSeparatorComponent,
+            ItemSeparatorComponent,
+            inverted,
+            entries,
+            board,
+            keyOf,
+        }),
+        keyExtractor: keyOf,
+        getItemLayout: layoutOverSections(getItemLayout, sections),
         stickyHeaderIndices,
-        ItemSeparatorComponent: entrySeparatorComponent,
+        inverted,
         ...rest,
     });
 }

package/build/components/virtualized-section-list/section-item-cell.d.ts

@@ -0,0 +1,23 @@
+import { type ReactElement, type ReactNode } from 'react';
+import { type ISeparatorBoard, type ISeparatorGap } from '@symbiote-native/components';
+import type { ISeparatorComponent, ISeparators } from '../virtualized-list';
+export type ISectionItemCellProps<ItemT, SectionT> = {
+    board: ISeparatorBoard<Record<string, unknown>>;
+    cellKey: string;
+    prevCellKey: string | undefined;
+    item: ItemT;
+    index: number;
+    section: SectionT;
+    renderItem: (info: {
+        item: ItemT;
+        index: number;
+        section: SectionT;
+        separators: ISeparators;
+    }) => ReactNode;
+    leadingGap: ISeparatorGap<ItemT, SectionT>;
+    trailingGap: ISeparatorGap<ItemT, SectionT>;
+    LeadingSeparatorComponent: ISeparatorComponent<ItemT> | undefined;
+    TrailingSeparatorComponent: ISeparatorComponent<ItemT> | undefined;
+    inverted: boolean;
+};
+export declare function SectionItemCell<ItemT, SectionT>(props: ISectionItemCellProps<ItemT, SectionT>): ReactElement;

package/build/components/virtualized-section-list/section-item-cell.js

@@ -0,0 +1,48 @@
+// Item cell with its separators around it, as in RN's `ItemWithSeparator`
+// Their state sits in a shared board, т.к. `highlight()` also lights the previous cell's one
+import { createElement, Fragment, isValidElement, useEffect, useSyncExternalStore, } from 'react';
+import { createCellSeparators, } from '@symbiote-native/components';
+function paint(separator) {
+    const { Component, gap, isHighlighted, override } = separator;
+    if (Component === undefined)
+        return null;
+    if (isValidElement(Component))
+        return Component;
+    return createElement(Component, {
+        highlighted: isHighlighted,
+        ...gap.props,
+        ...override,
+    });
+}
+export function SectionItemCell(props) {
+    const { board, cellKey, prevCellKey } = props;
+    const state = useSyncExternalStore(listener => board.subscribe(cellKey, listener), () => board.read(cellKey));
+    useEffect(() => () => board.release(cellKey), [board, cellKey]);
+    const separators = createCellSeparators(board, () => ({
+        cellKey,
+        prevCellKey,
+        has: {
+            leading: props.LeadingSeparatorComponent !== undefined,
+            trailing: props.TrailingSeparatorComponent !== undefined,
+        },
+    }));
+    const leading = paint({
+        Component: props.LeadingSeparatorComponent,
+        gap: props.leadingGap,
+        isHighlighted: state.leadingHighlighted,
+        override: state.leadingOverride,
+    });
+    const trailing = paint({
+        Component: props.TrailingSeparatorComponent,
+        gap: props.trailingGap,
+        isHighlighted: state.trailingHighlighted,
+        override: state.trailingOverride,
+    });
+    const element = props.renderItem({
+        item: props.item,
+        index: props.index,
+        section: props.section,
+        separators,
+    });
+    return createElement(Fragment, null, props.inverted ? trailing : leading, element, props.inverted ? leading : trailing);
+}

package/build/components.d.ts

@@ -1,10 +1,10 @@
 import type { Ref, ReactNode } from 'react';
 import type { ISymbioteEvent } from '@symbiote-native/engine';
 import type { IHostInstance } from './host-instance';
-import type { IAccessibilityProps, IAriaProps } from '@symbiote-native/components';
+import type { IAccessibilityProps, IAriaProps, ITextNativeOnlyProps } from '@symbiote-native/components';
 import type { IResponderProps } from './utils/responder-props';
 import type { IStyleProp, ITextStyle, IViewStyle } from './utils/styles';
-export interface IViewProps extends IAccessibilityProps, IAriaProps, IResponderProps {
+export type IViewProps = IAccessibilityProps & IAriaProps & IResponderProps & {
     style?: IStyleProp<IViewStyle>;
     className?: string;
     onPress?: (event: ISymbioteEvent) => void;
@@ -29,8 +29,8 @@ export interface IViewProps extends IAccessibilityProps, IAriaProps, IResponderP
     needsOffscreenAlphaCompositing?: boolean;
     ref?: Ref<IHostInstance>;
     children?: ReactNode;
-}
-export interface ITextProps extends IAccessibilityProps, IAriaProps {
+};
+export type ITextProps = IAccessibilityProps & IAriaProps & ITextNativeOnlyProps & {
     style?: IStyleProp<ITextStyle>;
     className?: string;
     onPress?: (event: ISymbioteEvent) => void;
@@ -50,4 +50,4 @@ export interface ITextProps extends IAccessibilityProps, IAriaProps {
     selectionColor?: string;
     ref?: Ref<IHostInstance>;
     children?: ReactNode;
-}
+};

package/build/hooks/use-animated-value.d.ts

@@ -0,0 +1,7 @@
+import { type AnimatedColor, type AnimatedValue, type AnimatedValueXY, type IAnimatedValueConfig, type IColorInput } from '@symbiote-native/engine';
+export declare function useAnimatedValue(initialValue: number, config?: IAnimatedValueConfig): AnimatedValue;
+export declare function useAnimatedValueXY(initialValue: {
+    x: number;
+    y: number;
+}, config?: IAnimatedValueConfig): AnimatedValueXY;
+export declare function useAnimatedColor(inputValue?: IColorInput, config?: IAnimatedValueConfig): AnimatedColor;

package/build/hooks/use-animated-value.js

@@ -0,0 +1,19 @@
+// RN's `useAnimatedValue`, `useAnimatedValueXY` and `useAnimatedColor`: the instance is built on
+// the first render and kept, so later renders ignore their arguments
+import { useRef } from 'react';
+import { createAnimatedColor, createAnimatedValue, createAnimatedValueXY, } from '@symbiote-native/engine';
+// `useRef(factory())` would build a throwaway instance on every render
+function useOnce(create) {
+    const ref = useRef(null);
+    ref.current ??= create();
+    return ref.current;
+}
+export function useAnimatedValue(initialValue, config) {
+    return useOnce(() => createAnimatedValue(initialValue, config));
+}
+export function useAnimatedValueXY(initialValue, config) {
+    return useOnce(() => createAnimatedValueXY(initialValue, config));
+}
+export function useAnimatedColor(inputValue, config) {
+    return useOnce(() => createAnimatedColor(inputValue, config));
+}

package/build/hooks/use-color-scheme.d.ts

@@ -1,2 +1,2 @@
-import { type IColorSchemeName } from '@symbiote-native/engine';
-export declare function useColorScheme(): IColorSchemeName | null;
+import type { IColorSchemeName } from '@symbiote-native/engine';
+export declare const useColorScheme: () => IColorSchemeName | null | undefined;

package/build/hooks/use-color-scheme.js

@@ -1,13 +1,4 @@
-// useColorScheme subscribes a component to the device color scheme and re-renders
-// on change. Mirrors RN's Libraries/Utilities/useColorScheme.js: a thin
-// useSyncExternalStore over Appearance's change event + current scheme read.
-import { useSyncExternalStore } from 'react';
-import { Appearance } from '@symbiote-native/engine';
-const subscribe = (onStoreChange) => {
-    const subscription = Appearance.addChangeListener(onStoreChange);
-    return () => subscription.remove();
-};
-const getSnapshot = () => Appearance.getColorScheme();
-export function useColorScheme() {
-    return useSyncExternalStore(subscribe, getSnapshot);
-}
+// RN's own `useColorScheme`, typed here because the source ships none
+// @ts-expect-error - untyped Flow source
+import useColorSchemeUpstream from 'react-native/Libraries/Utilities/useColorScheme';
+export const useColorScheme = useColorSchemeUpstream;

package/build/hooks/use-pressability.d.ts

@@ -0,0 +1,34 @@
+import { type IPressabilityHandlers, type ISymbioteEvent } from '@symbiote-native/engine';
+export type { IPressabilityHandlers } from '@symbiote-native/engine';
+type IRectOrSize = number | {
+    top?: number;
+    left?: number;
+    bottom?: number;
+    right?: number;
+};
+type IPressHandler = (event: ISymbioteEvent) => unknown;
+export type IPressabilityConfig = {
+    cancelable?: boolean | null;
+    disabled?: boolean | null;
+    hitSlop?: IRectOrSize | null;
+    pressRectOffset?: IRectOrSize | null;
+    android_disableSound?: boolean | null;
+    delayHoverIn?: number | null;
+    delayHoverOut?: number | null;
+    delayLongPress?: number | null;
+    delayPressIn?: number | null;
+    delayPressOut?: number | null;
+    minPressDuration?: number | null;
+    onBlur?: IPressHandler | null;
+    onFocus?: IPressHandler | null;
+    onHoverIn?: IPressHandler | null;
+    onHoverOut?: IPressHandler | null;
+    onLongPress?: IPressHandler | null;
+    onPress?: IPressHandler | null;
+    onPressIn?: IPressHandler | null;
+    onPressMove?: IPressHandler | null;
+    onPressOut?: IPressHandler | null;
+    blockNativeResponder?: boolean | null;
+};
+export declare function usePressability(config: IPressabilityConfig): IPressabilityHandlers;
+export declare function usePressability(config: IPressabilityConfig | null | undefined): IPressabilityHandlers | null;

package/build/hooks/use-pressability.js

@@ -0,0 +1,39 @@
+// RN's `usePressability`, over RN's own `Pressability` class, which `bootstrapHost` hands to the
+// engine. RN's class expects its synthetic events, so each handler gets the event with `persist()`
+import { useInsertionEffect, useRef } from 'react';
+import { loadPressability, } from '@symbiote-native/engine';
+// An event of ours answers everything RN's class reads, `persist` apart: nothing is pooled here
+function withPersist(event) {
+    return Object.assign(Object.create(event), { persist: () => { } });
+}
+function persistingHandlers(handlers) {
+    return Object.fromEntries(Object.entries(handlers).map(([name, handler]) => [
+        name,
+        (event) => handler(withPersist(event)),
+    ]));
+}
+export function usePressability(config) {
+    const ref = useRef(null);
+    if (config != null && ref.current === null) {
+        const Pressability = loadPressability();
+        const pressability = new Pressability(config);
+        ref.current = {
+            pressability,
+            handlers: persistingHandlers(pressability.getEventHandlers()),
+        };
+    }
+    const instance = ref.current;
+    // A no-op on the first mount, on an update it points `Pressability` at the new config
+    useInsertionEffect(() => {
+        if (config != null && instance !== null) {
+            instance.pressability.configure(config);
+        }
+    }, [config, instance]);
+    // On unmount only, not when `config` changes: pending timers and state go
+    useInsertionEffect(() => {
+        if (instance === null)
+            return undefined;
+        return () => instance.pressability.reset();
+    }, [instance]);
+    return instance === null ? null : instance.handlers;
+}

package/build/hooks/use-window-dimensions.js

@@ -1,26 +1,22 @@
-// useWindowDimensions is the preferred API for components that need window metrics,
-// a port of RN's Libraries/Utilities/useWindowDimensions.js. It seeds from
-// Dimensions.get('window'), subscribes to 'change', and re-checks once after
-// subscribing to close the gap between the render-time get and the effect-time
-// listener. Only the window metrics changing triggers a re-render.
+// Port of RN's `useWindowDimensions`: seeds from `Dimensions.get('window')`, subscribes to 'change'
+// TODO(rn-port): RN's module loads `NativeDeviceInfo` eagerly, which needs a bridge itests lack
 import { useEffect, useState } from 'react';
 import { Dimensions, } from '@symbiote-native/engine';
 export function useWindowDimensions() {
     const [dimensions, setDimensions] = useState(() => Dimensions.get('window'));
     useEffect(() => {
         function handleChange(window) {
-            if (dimensions.width !== window.width ||
+            const hasChanged = dimensions.width !== window.width ||
                 dimensions.height !== window.height ||
                 dimensions.scale !== window.scale ||
-                dimensions.fontScale !== window.fontScale) {
+                dimensions.fontScale !== window.fontScale;
+            if (hasChanged)
                 setDimensions(window);
-            }
         }
         const subscription = Dimensions.addEventListener('change', (set) => {
             handleChange(set.window);
         });
-        // We may have missed an update between calling `get` in render and subscribing
-        // here; re-check now. If nothing changed, React filters the no-op set.
+        // An update may land between `get` in render and the subscription, so re-check now
         handleChange(Dimensions.get('window'));
         return () => {
             subscription.remove();