@symbiote-native/react 3.3.0 → 3.4.0

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

@@ -0,0 +1,79 @@
+// The list's child elements: header, the windowed cells with their spacers, footer
+import { createElement } from 'react';
+import { FIRST_INDEX, LIST_SEGMENT_KIND, cellStyleOf, listStyleOf, planFromMetrics, resolveItemKey, spacerStyleOf, } from '@symbiote-native/components';
+import { renderItemElement, renderSeparatorElement, resolveElement, } from './list-elements.js';
+function spacerElement(segment, horizontal) {
+    return createElement('view', {
+        key: segment.key,
+        style: spacerStyleOf(segment.extent, horizontal),
+    });
+}
+// The separator lives INSIDE the cell's measuring wrapper, a sibling would be an extra flex child
+// that lands every cell below a collapsed spacer short by the separator plus the gap
+// It gates on the last index of the DATA, or a cell's measured height would change with the window
+function separatorOf(args, index) {
+    const { config, metrics, separators } = args;
+    if (index >= metrics.count - 1)
+        return undefined;
+    return renderSeparatorElement(config.ItemSeparatorComponent, config.getItem(config.data, index), config.getItem(config.data, index + 1), separators.overridesRef.current.get(index));
+}
+// A cell the app flagged sticky is wrapped in the `sticky-header` TAG, which pins by document
+// order and so survives windowing, nothing here computes a child index
+function cellElement(args, segment, stickySet) {
+    const { config, separators } = args;
+    const item = config.getItem(config.data, segment.index);
+    const content = renderItemElement(config, {
+        item,
+        index: segment.index,
+        separators: separators.makeSeparators(segment.index),
+    });
+    const isSticky = stickySet?.has(segment.index) === true;
+    const cellProps = {
+        key: `cell-${segment.key}`,
+        onLayout: args.measureCell(segment.index),
+        onFocus: args.focusCell(segment.index),
+        style: cellStyleOf(config),
+    };
+    const separator = separatorOf(args, segment.index);
+    if (config.CellRendererComponent === undefined) {
+        return createElement(isSticky ? 'sticky-header' : 'view', cellProps, content, separator);
+    }
+    const custom = createElement(config.CellRendererComponent, { ...cellProps, cellKey: segment.key, index: segment.index, item }, content, separator);
+    // RN pins the custom component itself, the sticky wrapper only holds it
+    return isSticky
+        ? createElement('sticky-header', { key: cellProps.key }, custom)
+        : custom;
+}
+function windowChildren(args) {
+    const { config, metrics } = args;
+    if (metrics.count === FIRST_INDEX) {
+        const empty = resolveElement(config.ListEmptyComponent);
+        return empty === undefined
+            ? []
+            : [
+                createElement('view', { key: 'list-empty', style: listStyleOf(config, undefined) }, empty),
+            ];
+    }
+    const { plan, stickySet } = planFromMetrics(metrics, index => resolveItemKey(config.getItem(config.data, index), index, config.keyExtractor), config.stickyHeaderIndices);
+    return plan.segments.map(segment => segment.kind === LIST_SEGMENT_KIND.spacer
+        ? spacerElement(segment, config.horizontal)
+        : cellElement(args, segment, stickySet));
+}
+// RN wires `onLayout` on the header wrapper only to assign `_headerLength` in VirtualizedList.js
+// (facebook/react-native, `_onLayoutHeader`); nothing reads it, so no handler is registered here
+function slotChild(config, slot, slotStyle, key) {
+    const element = resolveElement(slot);
+    return element === undefined
+        ? []
+        : [
+            createElement('view', { key, style: listStyleOf(config, slotStyle) }, element),
+        ];
+}
+export function buildListChildren(args) {
+    const { config } = args;
+    return [
+        ...slotChild(config, config.ListHeaderComponent, config.ListHeaderComponentStyle, 'list-header'),
+        ...windowChildren(args),
+        ...slotChild(config, config.ListFooterComponent, config.ListFooterComponentStyle, 'list-footer'),
+    ];
+}

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

@@ -0,0 +1,11 @@
+import type { IVirtualizedListProps } from './virtualized-list-props';
+export type IListConfig<ItemT> = IVirtualizedListProps<ItemT> & {
+    horizontal: boolean;
+    inverted: boolean;
+    initialNumToRender: number;
+    maxToRenderPerBatch: number;
+    updateCellsBatchingPeriod: number;
+    windowSize: number;
+    findFirstChildWithMore?: (first: number, last: number) => number | null;
+};
+export declare function resolveListConfig<ItemT>(props: IVirtualizedListProps<ItemT>, findFirstChildWithMore?: IListConfig<ItemT>['findFirstChildWithMore']): IListConfig<ItemT>;

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

@@ -0,0 +1,14 @@
+// Props with their defaults applied
+import { DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_WINDOW_SIZE, } from '@symbiote-native/components';
+export function resolveListConfig(props, findFirstChildWithMore) {
+    return {
+        ...props,
+        findFirstChildWithMore,
+        horizontal: props.horizontal ?? false,
+        inverted: props.inverted ?? false,
+        initialNumToRender: props.initialNumToRender ?? DEFAULT_INITIAL_NUM_TO_RENDER,
+        maxToRenderPerBatch: props.maxToRenderPerBatch ?? DEFAULT_MAX_TO_RENDER_PER_BATCH,
+        updateCellsBatchingPeriod: props.updateCellsBatchingPeriod ?? DEFAULT_UPDATE_CELLS_BATCHING_PERIOD,
+        windowSize: props.windowSize ?? DEFAULT_WINDOW_SIZE,
+    };
+}

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

@@ -0,0 +1,11 @@
+import { type ComponentType, type ReactNode } from 'react';
+import { type ISeparatorProps } from '@symbiote-native/components';
+import type { IListItemInfo, IListSlot, IRenderItem, ISeparatorComponent } from './virtualized-list-props';
+type IItemRenderers<ItemT> = {
+    renderItem?: IRenderItem<ItemT>;
+    ListItemComponent?: ComponentType<IListItemInfo<ItemT>>;
+};
+export declare function renderItemElement<ItemT>(renderers: IItemRenderers<ItemT>, info: IListItemInfo<ItemT>): ReactNode;
+export declare function resolveElement(component: IListSlot): ReactNode;
+export declare function renderSeparatorElement<ItemT>(component: ISeparatorComponent<ItemT> | undefined, leadingItem: ItemT, trailingItem: ItemT, overrides: Partial<ISeparatorProps<ItemT>> | undefined): ReactNode;
+export {};

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

@@ -0,0 +1,26 @@
+// Small element builders shared by the list's child walk
+import { createElement, isValidElement, } from 'react';
+import { buildSeparatorProps, drawItem, } from '@symbiote-native/components';
+// RN's `_renderElement`: the component wins over `renderItem`, one of the two has to be there
+export function renderItemElement(renderers, info) {
+    return drawItem({
+        renderItem: renderers.renderItem,
+        component: renderers.ListItemComponent,
+    }, info, (Component, given) => createElement(Component, given));
+}
+export function resolveElement(component) {
+    if (component === undefined)
+        return undefined;
+    if (typeof component === 'function')
+        return createElement(component, {});
+    return component;
+}
+// The `ItemSeparatorComponent` element for the gap between two items, with the highlight flag and
+// any handle-pushed overrides merged on top, RN renders `<ItemSeparatorComponent {...props} />`
+export function renderSeparatorElement(component, leadingItem, trailingItem, overrides) {
+    if (component === undefined)
+        return undefined;
+    if (isValidElement(component))
+        return component;
+    return createElement(component, buildSeparatorProps(leadingItem, trailingItem, overrides));
+}

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

@@ -0,0 +1,14 @@
+import { type ReactElement, type ReactNode, type RefObject } from 'react';
+import type { ISymbioteNode } from '@symbiote-native/engine';
+import type { IAccessibilityProps, IAriaProps, IListNesting } from '@symbiote-native/components';
+import type { IListConfig } from './list-config';
+import { type IScrollTagProps } from './list-scroll-props';
+export type IListHostArgs<ItemT> = {
+    config: IListConfig<ItemT>;
+    nesting: IListNesting<ItemT>;
+    scrollProps: IScrollTagProps;
+    accessibilityRest: IAccessibilityProps & IAriaProps;
+    nodeRef: RefObject<ISymbioteNode | null>;
+    children: ReactNode[];
+};
+export declare function listHostOf<ItemT>(args: IListHostArgs<ItemT>): ReactElement;

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

@@ -0,0 +1,24 @@
+// The host element a list renders: the scroll tag, or a plain view when it is nested in a list
+import { createElement, } from 'react';
+import { refreshControlOf } from './list-scroll-props.js';
+import { VirtualizedListScopeProvider } from './nested-scope.js';
+// The scroll TAG, not a wrapper: the engine builds the content node, `ref` hands back the engine
+// node that `buildScrollViewHandle` drives
+function scrollTagOf(args) {
+    const { config, scrollProps, nodeRef, children } = args;
+    return createElement(config.horizontal ? 'horizontal-scroll-view' : 'scroll-view', { ...scrollProps, ref: nodeRef }, refreshControlOf(config), ...children);
+}
+// The list above scrolls, so RN renders a `View` with no content container
+function nestedViewOf(args) {
+    const { scrollProps, accessibilityRest, nodeRef, children } = args;
+    return createElement('view', {
+        ...accessibilityRest,
+        style: scrollProps.style,
+        onLayout: scrollProps.onLayout,
+        ref: nodeRef,
+    }, ...children);
+}
+export function listHostOf(args) {
+    const { nesting } = args;
+    return createElement(VirtualizedListScopeProvider, { scope: nesting.scope }, nesting.isNested ? nestedViewOf(args) : scrollTagOf(args));
+}

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

@@ -0,0 +1,32 @@
+import { type ReactElement } from 'react';
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import { type IAccessibilityProps, type IAriaProps } from '@symbiote-native/components';
+import type { IScrollViewProps } from '../scroll-view/scroll-view-props';
+import type { IListConfig } from './list-config';
+import type { IVirtualizedListProps } from './virtualized-list-props';
+export type IScrollTagProps = IScrollViewProps & {
+    onLayout: (event: ISymbioteEvent) => void;
+    isInvertedVirtualizedList?: boolean;
+};
+export declare function accessibilityRestOf<ItemT>(props: IVirtualizedListProps<ItemT> & {
+    ref?: unknown;
+}): IAccessibilityProps & IAriaProps;
+export declare function refreshControlOf<ItemT>(config: IListConfig<ItemT>): ReactElement | undefined;
+export type IScrollTagInputs<ItemT> = {
+    config: IListConfig<ItemT>;
+    accessibilityRest: IAccessibilityProps & IAriaProps;
+    total: 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;
+    onLayout: (event: ISymbioteEvent) => void;
+    commandedOffset: {
+        x: number;
+        y: number;
+    } | undefined;
+    hasHeader: boolean;
+};
+export declare function buildScrollProps<ItemT>(inputs: IScrollTagInputs<ItemT>): IScrollTagProps;

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

@@ -0,0 +1,30 @@
+// The props handed to the scroll tag, and the accessibility rest that rides down with them
+import { createElement } from 'react';
+import { buildListScrollProps, } from '@symbiote-native/components';
+// The data access protocol and the slots, none of which the scroll tag takes
+function withoutDataAndSlots(props) {
+    const { data, getItem, getItemCount, renderItem, ListItemComponent, keyExtractor, getItemLayout, ItemSeparatorComponent, CellRendererComponent, ListHeaderComponent, ListFooterComponent, ListEmptyComponent, ...rest } = props;
+    return rest;
+}
+// Everything the list does not consume itself is accessibility surface for the ScrollView
+// The user's `onScroll` is among the consumed keys, composed with the internal handler instead
+export function accessibilityRestOf(props) {
+    const { horizontal, inverted, extraData, onEndReached, onEndReachedThreshold, onStartReached, onStartReachedThreshold, onRefresh, refreshing, progressViewOffset, onViewableItemsChanged, viewabilityConfig, viewabilityConfigCallbackPairs, onScrollToIndexFailed, initialNumToRender, initialScrollIndex, maxToRenderPerBatch, updateCellsBatchingPeriod, windowSize, disableVirtualization, stickyHeaderIndices, maintainVisibleContentPosition, style, contentContainerStyle, onScroll, onScrollBeginDrag, onScrollEndDrag, onMomentumScrollBegin, onMomentumScrollEnd, scrollEventThrottle, keyboardShouldPersistTaps, keyboardDismissMode, ref, ...rest } = withoutDataAndSlots(props);
+    return rest;
+}
+// With `onRefresh` the RefreshControl is an ordinary FIRST CHILD on both platforms, the scroll
+// behavior claims it and places it per platform
+export function refreshControlOf(config) {
+    if (config.onRefresh === undefined)
+        return undefined;
+    return createElement('refresh-control', {
+        key: 'refresh-control',
+        refreshing: config.refreshing ?? false,
+        onRefresh: config.onRefresh,
+        progressViewOffset: config.progressViewOffset,
+    });
+}
+export function buildScrollProps(inputs) {
+    const { config, accessibilityRest, ...tagInputs } = inputs;
+    return buildListScrollProps({ ...config, ...tagInputs }, accessibilityRest);
+}

package/build/components/virtualized-list/nested-scope.d.ts

@@ -0,0 +1,10 @@
+import { type ReactElement, type ReactNode } from 'react';
+import type { IListScope } from '@symbiote-native/components';
+export declare function useVirtualizedListScope(): IListScope | null;
+export declare function VirtualizedListScopeProvider(props: {
+    scope: IListScope;
+    children?: ReactNode;
+}): ReactElement;
+export declare function VirtualizedListScopeResetter(props: {
+    children?: ReactNode;
+}): ReactElement;

package/build/components/virtualized-list/nested-scope.js

@@ -0,0 +1,16 @@
+// The scope a list hands down to the lists nested in its cells, React's way to carry it
+// What it holds and how it behaves is `createListNesting` in the shared components package
+import { createContext, createElement, useContext, } from 'react';
+const VirtualizedListScope = createContext(null);
+// Null outside every list, the scope of the nearest list above otherwise
+export function useVirtualizedListScope() {
+    return useContext(VirtualizedListScope);
+}
+export function VirtualizedListScopeProvider(props) {
+    return createElement(VirtualizedListScope.Provider, { value: props.scope }, props.children);
+}
+// A portal-like component (Modal) renders outside its parent list's scroll, so its content must
+// not count itself as nested in it
+export function VirtualizedListScopeResetter(props) {
+    return createElement(VirtualizedListScope.Provider, { value: null }, props.children);
+}

package/build/components/virtualized-list/use-list-driver.d.ts

@@ -0,0 +1,22 @@
+import { type RefObject } from 'react';
+import { type ISymbioteNode } from '@symbiote-native/engine';
+import { type IListAction, type IListState } from '@symbiote-native/components';
+import type { IScrollViewHandle } from '../scroll-view/scroll-view-props';
+import type { IListConfig } from './list-config';
+export type ICommandedOffset = {
+    x: number;
+    y: number;
+};
+export type IScrollTarget = {
+    nodeRef: RefObject<ISymbioteNode | null>;
+    handle: IScrollViewHandle;
+    commandedOffset: ICommandedOffset | undefined;
+    clearCommandedOffset: () => void;
+    scrollToPixel: (offset: number, animated: boolean) => void;
+};
+export type IListDriver<ItemT> = {
+    state: IListState<ItemT>;
+    dispatch: (action: IListAction<ItemT>) => void;
+    scroll: IScrollTarget;
+};
+export declare function useListDriver<ItemT>(config: IListConfig<ItemT>): IListDriver<ItemT>;

package/build/components/virtualized-list/use-list-driver.js

@@ -0,0 +1,104 @@
+// The list's lifecycle: one folded state cell, native events turned into reducer actions, and the
+// returned effects run with React primitives
+import { useCallback, useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState, } from 'react';
+import { dlog } from '@symbiote-native/engine';
+import { EMPTY_OFFSET, LIST_ACTION_KIND, buildListReducerInputs, buildScrollViewHandle, buildViewabilityPairs, clearTimers, createInitialListState, listEffectSignature, reduceList, runListEffects, } from '@symbiote-native/components';
+// A `ref` on the scroll tag hands back the engine node, `buildScrollViewHandle` turns it into
+// RN's scroll surface, the node is null until commit
+function useScrollTarget(axisRef) {
+    const nodeRef = useRef(null);
+    const handle = useMemo(() => buildScrollViewHandle(() => nodeRef.current), []);
+    const [commandedOffset, setCommandedOffset] = useState(undefined);
+    const scrollToPixel = useCallback((offset, animated) => {
+        const clamped = Math.max(EMPTY_OFFSET, offset);
+        const horizontal = axisRef.current.horizontal;
+        const target = horizontal
+            ? { x: clamped, y: EMPTY_OFFSET }
+            : { x: EMPTY_OFFSET, y: clamped };
+        if (nodeRef.current === null) {
+            dlog(`VirtualizedList scrollTo offset=${clamped} pending-ref (horizontal=${horizontal})`);
+            setCommandedOffset(target);
+            return;
+        }
+        dlog(`VirtualizedList scrollTo offset=${clamped} animated=${animated} (horizontal=${horizontal})`);
+        handle.scrollTo({ x: target.x, y: target.y, animated });
+    }, [handle, axisRef]);
+    const clearCommandedOffset = useCallback(() => setCommandedOffset(undefined), []);
+    return {
+        nodeRef,
+        handle,
+        commandedOffset,
+        clearCommandedOffset,
+        scrollToPixel,
+    };
+}
+// The latest value of every render, read by handlers that must stay stable
+function useLatest(value) {
+    const ref = useRef(value);
+    ref.current = value;
+    return ref;
+}
+function useListState() {
+    const stateRef = useRef(null);
+    return (stateRef.current ??= createInitialListState());
+}
+// Dispatch and the effect host recurse into each other (a refill or a fired debounce dispatches a
+// follow-up action), so the host reaches `dispatch` through a ref
+function useDispatch(state, parts) {
+    const { inputsRef, callbacksRef, scrollToPixel } = parts;
+    const [, forceRender] = useReducer((tick) => tick + 1, 0);
+    const dispatchRef = useRef(() => { });
+    const viewableTimer = useRef(null);
+    const batchTimer = useRef(null);
+    const host = useMemo(() => ({
+        callbacks: () => callbacksRef.current,
+        scrollToPixel,
+        dispatch: () => dispatchRef.current,
+        viewableTimer,
+        batchTimer,
+    }), [callbacksRef, scrollToPixel]);
+    const dispatch = useCallback((action) => {
+        const result = reduceList(state, action, inputsRef.current);
+        runListEffects(result.effects, host);
+        if (result.changed)
+            forceRender();
+    }, [state, inputsRef, host]);
+    dispatchRef.current = dispatch;
+    useEffect(() => () => clearTimers([viewableTimer, batchTimer]), [viewableTimer, batchTimer]);
+    return { dispatch, host };
+}
+// The after-commit pass runs in a layout effect so MVCP's shift lands before paint, and only when
+// the signature changed, the same dedup key every adapter shares
+function useCommitPass(state, inputsRef, host) {
+    const commitSignature = listEffectSignature(state);
+    useLayoutEffect(() => {
+        const result = reduceList(state, { kind: LIST_ACTION_KIND.commit }, inputsRef.current);
+        runListEffects(result.effects, host);
+    }, [commitSignature, state, inputsRef, host]);
+}
+export function useListDriver(config) {
+    const viewabilityPairs = useMemo(() => buildViewabilityPairs(config.onViewableItemsChanged, config.viewabilityConfig, config.viewabilityConfigCallbackPairs), [
+        config.onViewableItemsChanged,
+        config.viewabilityConfig,
+        config.viewabilityConfigCallbackPairs,
+    ]);
+    const inputs = buildListReducerInputs(config, viewabilityPairs);
+    const inputsRef = useLatest(inputs);
+    const callbacksRef = useLatest({
+        onEndReached: config.onEndReached,
+        onStartReached: config.onStartReached,
+        onScrollToIndexFailed: config.onScrollToIndexFailed,
+        viewabilityPairs,
+    });
+    const state = useListState();
+    const scroll = useScrollTarget(inputsRef);
+    const { dispatch, host } = useDispatch(state, {
+        inputsRef,
+        callbacksRef,
+        scrollToPixel: scroll.scrollToPixel,
+    });
+    // The single derive per render, before anything reads the metrics
+    reduceList(state, { kind: LIST_ACTION_KIND.refreshMetrics }, inputs);
+    useCommitPass(state, inputsRef, host);
+    return { state, dispatch, scroll };
+}

package/build/components/virtualized-list/use-list-nesting.d.ts

@@ -0,0 +1,12 @@
+import { type RefObject } from 'react';
+import { type IListNesting, type IListScope, type INestedHandlers } from '@symbiote-native/components';
+import type { IListConfig } from './list-config';
+import type { IListDriver } from './use-list-driver';
+export declare function useNestedHandlersRef(): RefObject<INestedHandlers>;
+export type INestingArgs<ItemT> = {
+    config: IListConfig<ItemT>;
+    driver: IListDriver<ItemT>;
+    parent: IListScope | null;
+    handlersRef: RefObject<INestedHandlers>;
+};
+export declare function useListNesting<ItemT>(args: INestingArgs<ItemT>): IListNesting<ItemT>;

package/build/components/virtualized-list/use-list-nesting.js

@@ -0,0 +1,37 @@
+// The list's place among nested lists: the scope it hands down and its link to the list above
+import { useEffect, useMemo, useRef } from 'react';
+import { createListNesting, listHasMore, resolveItemKey, } from '@symbiote-native/components';
+const noop = () => { };
+const NO_HANDLERS = {
+    onScroll: noop,
+    onScrollBeginDrag: noop,
+    onScrollEndDrag: noop,
+    onMomentumScrollBegin: noop,
+    onMomentumScrollEnd: noop,
+    recordInteraction: noop,
+};
+// Holds the list's own handlers once they exist
+export function useNestedHandlersRef() {
+    return useRef(NO_HANDLERS);
+}
+export function useListNesting(args) {
+    const { parent, handlersRef } = args;
+    const latest = useRef(args);
+    latest.current = args;
+    const horizontal = args.config.horizontal;
+    const nesting = useMemo(() => createListNesting({
+        parent,
+        horizontal,
+        getState: () => latest.current.driver.state,
+        dispatch: action => latest.current.driver.dispatch(action),
+        getContainerNode: () => latest.current.driver.scroll.nodeRef.current,
+        getHasMore: () => listHasMore(latest.current.driver.state),
+        keyFor: index => {
+            const { config } = latest.current;
+            return resolveItemKey(config.getItem(config.data, index), index, config.keyExtractor);
+        },
+        handlers: () => handlersRef.current,
+    }), [parent, horizontal, handlersRef]);
+    useEffect(() => () => nesting.detach(), [nesting]);
+    return nesting;
+}

package/build/components/virtualized-list/use-list-parts.d.ts

@@ -0,0 +1,12 @@
+import type { IListNesting } from '@symbiote-native/components';
+import { type IListConfig } from './list-config';
+import { type IListDriver } from './use-list-driver';
+import { type IScrollHandlers } from './use-scroll-handlers';
+import type { IVirtualizedListProps } from './virtualized-list-props';
+export type IListParts<ItemT> = {
+    config: IListConfig<ItemT>;
+    driver: IListDriver<ItemT>;
+    nesting: IListNesting<ItemT>;
+    handlers: IScrollHandlers;
+};
+export declare function useListParts<ItemT>(props: IVirtualizedListProps<ItemT>): IListParts<ItemT>;

package/build/components/virtualized-list/use-list-parts.js

@@ -0,0 +1,20 @@
+// What a list renders from: config, folded state, place among nested lists, handlers
+import { useRef } from 'react';
+import { resolveListConfig } from './list-config.js';
+import { useVirtualizedListScope } from './nested-scope.js';
+import { useListDriver } from './use-list-driver.js';
+import { useListNesting, useNestedHandlersRef } from './use-list-nesting.js';
+import { useScrollHandlers } from './use-scroll-handlers.js';
+export function useListParts(props) {
+    const parent = useVirtualizedListScope();
+    // The config exists before the nesting does, so the window reads it through this ref
+    const nestingRef = useRef(null);
+    const config = resolveListConfig(props, (first, last) => nestingRef.current?.findFirstChildWithMore(first, last) ?? null);
+    const driver = useListDriver(config);
+    const handlersRef = useNestedHandlersRef();
+    const nesting = useListNesting({ config, driver, parent, handlersRef });
+    nestingRef.current = nesting;
+    const handlers = useScrollHandlers({ config, driver, nesting });
+    handlersRef.current = handlers;
+    return { config, driver, nesting, handlers };
+}

package/build/components/virtualized-list/use-scroll-handlers.d.ts

@@ -0,0 +1,17 @@
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import { type IListNesting, type INestedHandlers } from '@symbiote-native/components';
+import type { IListConfig } from './list-config';
+import type { IListDriver } from './use-list-driver';
+export type IScrollHandlers = INestedHandlers & {
+    onViewportLayout: (event: ISymbioteEvent) => void;
+    measureCell: (index: number) => (event: ISymbioteEvent) => void;
+    focusCell: (index: number) => () => void;
+    onContentSizeChange: (width: number, height: number) => void;
+};
+type IHandlerDeps<ItemT> = {
+    config: IListConfig<ItemT>;
+    driver: Pick<IListDriver<ItemT>, 'dispatch' | 'scroll'>;
+    nesting: IListNesting<ItemT>;
+};
+export declare function useScrollHandlers<ItemT>(deps: IHandlerDeps<ItemT>): IScrollHandlers;
+export {};

package/build/components/virtualized-list/use-scroll-handlers.js

@@ -0,0 +1,106 @@
+// Native scroll and layout events turned into reducer actions, and handed on to nested lists
+import { useCallback } from 'react';
+import { LIST_ACTION_KIND, contentSizeActionOf, layoutActionOf, measureActionOf, resolveItemKey, scrollActionOf, } from '@symbiote-native/components';
+// Each one reaches the lists nested in this one first, then the app's own handler
+function useDragHandlers(deps) {
+    const { config, driver, nesting } = deps;
+    const { dispatch } = driver;
+    const { fanOut } = nesting;
+    const { onScrollBeginDrag, onScrollEndDrag, onMomentumScrollBegin, onMomentumScrollEnd, } = config;
+    const recordInteraction = useCallback(() => {
+        fanOut.recordInteraction();
+        dispatch({ kind: LIST_ACTION_KIND.recordInteraction });
+    }, [fanOut, dispatch]);
+    const onBeginDrag = useCallback((event) => {
+        fanOut.onScrollBeginDrag(event);
+        dispatch({ kind: LIST_ACTION_KIND.recordInteraction });
+        onScrollBeginDrag?.(event);
+    }, [fanOut, dispatch, onScrollBeginDrag]);
+    const onEndDrag = useCallback((event) => {
+        fanOut.onScrollEndDrag(event);
+        onScrollEndDrag?.(event);
+    }, [fanOut, onScrollEndDrag]);
+    const onMomentumBegin = useCallback((event) => {
+        fanOut.onMomentumScrollBegin(event);
+        onMomentumScrollBegin?.(event);
+    }, [fanOut, onMomentumScrollBegin]);
+    const onMomentumEnd = useCallback((event) => {
+        fanOut.onMomentumScrollEnd(event);
+        onMomentumScrollEnd?.(event);
+    }, [fanOut, onMomentumScrollEnd]);
+    return {
+        recordInteraction,
+        onScrollBeginDrag: onBeginDrag,
+        onScrollEndDrag: onEndDrag,
+        onMomentumScrollBegin: onMomentumBegin,
+        onMomentumScrollEnd: onMomentumEnd,
+    };
+}
+// A nested list's viewport is the parent's, so its own scroll events carry nothing it can use
+function useScrollHandler(deps) {
+    const { config, driver, nesting } = deps;
+    const { horizontal, onScroll: userOnScroll } = config;
+    const { dispatch, scroll } = driver;
+    const { clearCommandedOffset } = scroll;
+    return useCallback((event) => {
+        nesting.fanOut.onScroll(event);
+        const timestamp = performance.now();
+        const action = nesting.isNested
+            ? nesting.parentScrollAction(event, timestamp)
+            : scrollActionOf(event, horizontal, timestamp);
+        if (action === undefined)
+            return;
+        // A real user or native scroll supersedes any pending commanded offset
+        clearCommandedOffset();
+        dispatch(action);
+        // Compose, don't clobber: the internal windowing ran first, now the user's handler
+        userOnScroll?.(event);
+    }, [nesting, horizontal, userOnScroll, dispatch, clearCommandedOffset]);
+}
+// RN's `_onContentSizeChange`: the list learns its content length, then the app's own handler
+function useContentSizeHandler(deps) {
+    const { horizontal, onContentSizeChange: userHandler } = deps.config;
+    const { dispatch } = deps.driver;
+    return useCallback((width, height) => {
+        dispatch(contentSizeActionOf(width, height, horizontal));
+        userHandler?.(width, height);
+    }, [horizontal, dispatch, userHandler]);
+}
+function useLayoutHandlers(deps) {
+    const { config, driver, nesting } = deps;
+    const { horizontal, getItem, data, keyExtractor } = config;
+    const { dispatch, scroll } = driver;
+    const onViewportLayout = useCallback((event) => {
+        if (nesting.isNested) {
+            const node = scroll.nodeRef.current;
+            if (node !== null)
+                nesting.attachAt(node);
+            nesting.child.measureLayoutRelativeToContainingList();
+            return;
+        }
+        const action = layoutActionOf(event, horizontal);
+        if (action !== undefined)
+            dispatch(action);
+    }, [horizontal, dispatch, nesting, scroll.nodeRef]);
+    const measureCell = useCallback((index) => (event) => {
+        const action = measureActionOf(event, index, horizontal);
+        if (action !== undefined)
+            dispatch(action);
+        const cellKey = resolveItemKey(getItem(data, index), index, keyExtractor);
+        nesting.scope.registerCellNode(event.currentTarget, cellKey);
+        nesting.remeasureCell(cellKey);
+    }, [horizontal, dispatch, nesting, getItem, data, keyExtractor]);
+    return { onViewportLayout, measureCell };
+}
+export function useScrollHandlers(deps) {
+    const { dispatch } = deps.driver;
+    const onScroll = useScrollHandler(deps);
+    const focusCell = useCallback((index) => () => dispatch({ kind: LIST_ACTION_KIND.cellFocused, index }), [dispatch]);
+    return {
+        onScroll,
+        focusCell,
+        onContentSizeChange: useContentSizeHandler(deps),
+        ...useDragHandlers(deps),
+        ...useLayoutHandlers(deps),
+    };
+}

package/build/components/virtualized-list/use-separators.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from 'react';
+import { type ISeparatorProps, type ISeparators } from '@symbiote-native/components';
+export type ISeparatorOverrides<ItemT> = Map<number, Partial<ISeparatorProps<ItemT>>>;
+export type IListSeparators<ItemT> = {
+    overridesRef: RefObject<ISeparatorOverrides<ItemT>>;
+    makeSeparators: (index: number) => ISeparators;
+};
+export declare function useSeparators<ItemT>(count: number): IListSeparators<ItemT>;

package/build/components/virtualized-list/use-separators.js

@@ -0,0 +1,17 @@
+// Per-gap separator overrides, render state read straight by the cell walk
+import { useCallback, useRef, useState } from 'react';
+import { EMPTY_OFFSET, buildSeparatorHandles, isSeparatorGapInRange, } from '@symbiote-native/components';
+export function useSeparators(count) {
+    const overridesRef = useRef(new Map());
+    const [, setVersion] = useState(EMPTY_OFFSET);
+    // A gap outside [0, count - 2] has no separator, so the write is a no-op, RN bails the same way
+    const mergeSeparator = useCallback((gapIndex, patch) => {
+        if (!isSeparatorGapInRange(gapIndex, count))
+            return;
+        const overrides = overridesRef.current;
+        overrides.set(gapIndex, { ...overrides.get(gapIndex), ...patch });
+        setVersion(version => version + 1);
+    }, [count]);
+    const makeSeparators = useCallback((index) => buildSeparatorHandles(index, mergeSeparator), [mergeSeparator]);
+    return { overridesRef, makeSeparators };
+}