@symbiote-native/react 3.2.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/descriptor-to-react/with-children.d.ts

@@ -0,0 +1,4 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { IDescriptor } from '@symbiote-native/components';
+/** The element of a descriptor with the app children after its own, for wrappers */
+export declare function descriptorToReactWithChildren(node: IDescriptor, children: ReactNode): ReactElement;

package/build/descriptor-to-react/with-children.js

@@ -0,0 +1,6 @@
+import { createElement } from 'react';
+import { descriptorToReact } from './index.js';
+/** The element of a descriptor with the app children after its own, for wrappers */
+export function descriptorToReactWithChildren(node, children) {
+    return createElement(node.type, node.props, ...node.children.map(child => typeof child === 'string' ? child : descriptorToReact(child)), children);
+}

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-event.d.ts

@@ -0,0 +1,6 @@
+import type { IEventEmitterOf, IEventName, IEventPayload, IEventsMap } from '@symbiote-native/engine';
+/** Calls the listener for each event, the latest one, and stops when the component unmounts */
+export declare function useEventListener<TEventsMap extends IEventsMap, TName extends IEventName<TEventsMap>>(emitter: IEventEmitterOf<TEventsMap>, eventName: TName, listener: TEventsMap[TName]): void;
+/** The payload of the last event, `initialValue` (or `null`) until the first one */
+export declare function useEvent<TEventsMap extends IEventsMap, TName extends IEventName<TEventsMap>>(emitter: IEventEmitterOf<TEventsMap>, eventName: TName, initialValue: IEventPayload<TEventsMap, TName>): IEventPayload<TEventsMap, TName>;
+export declare function useEvent<TEventsMap extends IEventsMap, TName extends IEventName<TEventsMap>>(emitter: IEventEmitterOf<TEventsMap>, eventName: TName): IEventPayload<TEventsMap, TName> | null;

package/build/hooks/use-event.js

@@ -0,0 +1,15 @@
+// React twins of `useEvent` and `useEventListener` of the `expo` package, for any emitter
+import { useEffect, useRef, useState } from 'react';
+import { bindEventListener } from '@symbiote-native/engine';
+/** Calls the listener for each event, the latest one, and stops when the component unmounts */
+export function useEventListener(emitter, eventName, listener) {
+    // Read at each event, so a listener that changes with every render is not a new subscription
+    const latest = useRef(listener);
+    latest.current = listener;
+    useEffect(() => bindEventListener(emitter, eventName, () => latest.current), [emitter, eventName]);
+}
+export function useEvent(emitter, eventName, initialValue = null) {
+    const [event, setEvent] = useState(initialValue);
+    useEffect(() => bindEventListener(emitter, eventName, () => setEvent), [emitter, eventName]);
+    return event;
+}

package/build/hooks/use-native-view-controller.d.ts

@@ -0,0 +1,3 @@
+import type { ReactElement, Ref } from 'react';
+import type { ICreateNativeViewController } from '@symbiote-native/components';
+export declare function useNativeViewController<THandle>(ref: Ref<THandle> | undefined, createController: ICreateNativeViewController<THandle>, props: object): ReactElement | null;

package/build/hooks/use-native-view-controller.js

@@ -0,0 +1,15 @@
+import { useEffect, useImperativeHandle, useState } from 'react';
+import { createHostNodeHolder } from '@symbiote-native/components';
+import { descriptorToReact } from '../descriptor-to-react/index.js';
+// The body of a React component over a package's native view: one controller per mounted view,
+// its handle goes to the `ref` and its descriptor is bridged to an element
+export function useNativeViewController(ref, createController, props) {
+    const [{ host, controller }] = useState(() => {
+        const holder = createHostNodeHolder();
+        return { host: holder, controller: createController(holder.getNode) };
+    });
+    useImperativeHandle(ref, () => controller.handle, [controller]);
+    useEffect(() => () => controller.dispose?.(), [controller]);
+    const descriptor = controller.render(props);
+    return descriptor ? descriptorToReact(host.capture(descriptor)) : null;
+}

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;