@symbiote-native/vue 0.3.8 → 0.4.0

package/build/components/scroll-view/shared.js

@@ -1,23 +1,17 @@
-// ScrollView, the Vue lifecycle half. The Fabric tree is nested:
-// a scroll view wraps a content view that holds the children (RN's ScrollView.js shape). The
-// platform-invariant math (decelerationRate, the per-axis intrinsics/base style, the
-// content-size dedupe, the imperative handle, the aria/role fold) lives in @symbiote-native/components,
-// shared verbatim with React. Here Vue supplies only the reactivity: a shallowRef holds the host
-// node, a setup-scope `lastContentSize` dedupes onContentSizeChange, and expose() wires the
-// imperative handle. This is the Vue twin of the React adapter's useRef + buildScrollViewHandle.
+// ScrollView, the Vue lifecycle half. The Fabric tree is nested: a scroll view wraps a
+// content view holding the children (RN's ScrollView.js shape). Platform-invariant math
+// (decelerationRate, per-axis intrinsics/base style, content-size dedupe, imperative handle,
+// aria/role fold) lives in @symbiote-native/components, shared with React; Vue supplies only
+// the reactivity - shallowRef host node, setup-scope lastContentSize dedupe, expose() handle -
+// the twin of React's useRef + buildScrollViewHandle.
 //
-// Inputs arrive as attrs (untyped), so each is narrowed with a runtime guard rather than a cast.
-// contentSizeChange is synthesized as a typed Vue emit from the content onLayout. The legacy
-// onContentSizeChange callback key MUST be consumed if it arrives (it is NOT a ViewConfig event;
-// forwarding a function prop would reach Fabric and crash Android's folly::dynamic). Scroll events
-// (onScroll/onLayout/…) ARE ViewConfig events, so they forward raw and routeProp turns them into
-// listeners.
+// Attrs are untyped, so every field is narrowed with a runtime guard, never a cast. The legacy
+// onContentSizeChange callback key MUST be consumed if present: it is NOT a ViewConfig event,
+// and forwarding a function prop reaches Fabric and crashes Android's folly::dynamic.
 //
-// RefreshControl is wired through the platform assemble (iOS sibling /
-// Android wrap). Sticky headers are real. The scroll AnimatedValue (markRaw, held by
-// identity), the headerLayoutYs cross-talk map + bump, the viewport-height capture, and the
-// onScroll composition (native attach vs Animated.event) all live here; the per-header component and
-// the children wrap live in scroll-view-sticky-header.ts (the Vue twin of the React file).
+// Sticky headers are real: the scroll AnimatedValue, headerLayoutYs cross-talk map, viewport-
+// height capture, and onScroll composition (native attach vs Animated.event) live here; the
+// per-header component and children wrap live in sticky-header.ts.
 import { defineComponent, h, isVNode, markRaw, onBeforeUnmount, ref, shallowRef, watch, } from '@vue/runtime-core';
 import { attachStickyScroll, buildScrollViewHandle, didContentSizeChange, forwardScrollEvent, readLayoutDimension, resolveAccessibilityProps, resolveDecelerationRate, resolveScrollForwarding, selectScrollIntrinsics, } from '@symbiote-native/components';
 import { AnimatedValue, dlog, event as animatedEvent, isClassNameValue, isNativeAnimatedAvailable, isSymbioteNode, resolveClassName, } from '@symbiote-native/engine';
@@ -26,23 +20,15 @@ import { normalizeVueAttrs } from '../../utils/normalize-attrs.js';
 function isHandler(value) {
     return typeof value === 'function';
 }
-// Objects and arrays are valid StyleProp<ViewStyle> (ViewStyle | RecursiveArray | falsy; the
-// engine omits RN's RegisteredStyle brand, so no numeric form). Primitives/null degrade to
-// undefined; the engine flattens whatever object/array reaches it.
+// Objects and arrays are valid StyleProp<ViewStyle>; primitives/null degrade to undefined.
 function isStyleProp(value) {
     return typeof value === 'object' && value !== null;
 }
-// `class` is never in HANDLED_ATTRS (inheritAttrs:false means it also isn't auto-merged onto a
-// root), so it forwards raw to the inner scroll-view node via forwardAttrs, resolved later by
-// the renderer's own patchProp — fine for the single-node Phase 1 path. But the Android
-// RefreshControl wrap (index.android.ts) reads userStyle alone to splitLayoutProps() the outer
-// wrapper's layout style, BEFORE that later resolution ever runs, so a class-only layout prop
-// (flex, height, gap, …) never reaches the wrapper and it collapses to nothing.
-// isClassNameProp is @symbiote-native/engine's own isClassNameValue guard (shared, not redeclared —
-// routeProp's centralized class+style merge needs the identical narrowing).
+// `class` forwards raw via forwardAttrs, resolved later by the renderer's patchProp. But the
+// Android RefreshControl wrap (index.android.ts) reads userStyle alone to splitLayoutProps()
+// the outer wrapper BEFORE that later resolution runs, so a class-only layout prop (flex,
+// height, gap, …) would otherwise never reach the wrapper.
 const isClassNameProp = isClassNameValue;
-// decelerationRate is resolved per-platform (resolveDecelerationRate), so it must be narrowed to
-// its declared shape before that call, unlike the raw pass-through props.
 function asDecelerationRate(value) {
     if (typeof value === 'number')
         return value;
@@ -50,21 +36,16 @@ function asDecelerationRate(value) {
         return value;
     return undefined;
 }
-// stickyHeaderIndices arrives untyped (attrs); narrow to a number[] before the wrap reads it.
 function isNumberArray(value) {
     return Array.isArray(value) && value.every(entry => typeof entry === 'number');
 }
-// A StickyHeaderComponent override is a Vue component: a function (functional) or an object
-// (defineComponent). Narrowed before it is handed to wrapStickyHeaders (no cast).
 function isComponent(value) {
     return typeof value === 'function' || (typeof value === 'object' && value !== null);
 }
-// The prop/handler keys the lifecycle consumes itself; everything else (the scroll events,
-// snap/keyboard/zoom families, accessibility, testID, …) forwards onto the scroll-view node.
-// onContentSizeChange is consumed (synthesized from the content onLayout, never forwarded);
-// refreshControl is consumed by the platform assemble; the sticky-header props (indices / invert /
-// StickyHeaderComponent) are lifecycle-consumed by the children wrap and must NEVER reach Fabric.
-// style / contentContainerStyle / horizontal / decelerationRate are recomposed.
+// Prop/handler keys the lifecycle consumes itself; everything else forwards onto the scroll-view
+// node. onContentSizeChange is consumed (synthesized from the content onLayout); refreshControl
+// and the sticky-header props are consumed by the platform assemble / children wrap and must
+// NEVER reach Fabric.
 const HANDLED_ATTRS = [
     'style',
     'contentContainerStyle',
@@ -86,39 +67,29 @@ function forwardAttrs(attrs) {
 }
 export function createScrollView(platform) {
     return defineComponent((_props, { slots, attrs: rawAttrs, expose, emit }) => {
-        // shallowRef, NOT ref: the engine node must be held by IDENTITY. A plain ref() runs the
-        // node through Vue's toReactive(), handing back a reactive Proxy, a different object than
-        // the raw node the engine's mirror (a WeakMap) is keyed on, so dispatchViewCommand would
-        // miss and every scrollTo/scrollToEnd/flashScrollIndicators silently no-op. This is the
-        // same rule as the Switch host node.
+        // shallowRef, NOT ref: a plain ref() would run the node through Vue's toReactive(),
+        // handing back a Proxy the engine's WeakMap mirror doesn't recognize, so
+        // scrollTo/scrollToEnd/flashScrollIndicators would silently no-op. Same rule as Switch.
         const nodeRef = shallowRef(null);
         const setNodeRef = (el) => {
             nodeRef.value = isSymbioteNode(el) ? el : null;
         };
-        // The imperative handle reads the node through a LAZY getter (() => nodeRef.value), not the
-        // node captured once: it is null until the element commits, so an eager capture would freeze
-        // null and every command would no-op. expose() makes it the value a parent ref
-        // sees: the Vue twin of React's useImperativeHandle(forwardedRef, buildScrollViewHandle(…)).
+        // Lazy getter, not the node captured once: it is null until the element commits, so an
+        // eager capture would freeze null. Vue twin of useImperativeHandle(ref, buildScrollViewHandle).
         expose(buildScrollViewHandle(() => nodeRef.value));
-        // The last-seen content size, kept here (setup scope, persists across renders) to dedupe
-        // contentSizeChange: RN fires the content onLayout on every layout pass; only real size
-        // changes emit to the user (didContentSizeChange).
+        // RN fires the content onLayout on every layout pass; only a real size change emits.
         let lastContentSize = null;
-        // A single AnimatedValue tracks the scroll offset and drives every sticky header's translateY
-        // (RN's _scrollAnimatedValue). A setup-scope const (allocated once, stable across renders) so
-        // the headers' bindings survive re-renders, the Vue twin of React's useRef-stable value.
-        // markRaw: it is an engine object, held by IDENTITY, never run through toReactive (the
-        // reactivity rule; a deep ref would hand back a Proxy the engine's mirror misses). Allocated
-        // unconditionally (like React's unconditional hook); unused when no sticky headers are flagged.
+        // Drives every sticky header's translateY (RN's _scrollAnimatedValue). markRaw: an engine
+        // object held by identity, never run through toReactive. Allocated unconditionally
+        // (unused when no sticky headers are flagged), like React's unconditional hook.
         const scrollAnimatedValue = markRaw(new AnimatedValue(0));
-        // Inverted sticky headers stick to the BOTTOM, so they need the viewport height (RN reads it
-        // in _handleLayout). Tracked here and fed back into the wrapped headers on the next render.
+        // Inverted sticky headers stick to the BOTTOM, so they need the viewport height (RN's
+        // _handleLayout). Fed back into the wrapped headers on the next render.
         const viewportHeight = ref(undefined);
-        // Sticky-header cross-talk (RN ScrollView.js _headerLayoutYs, line 754): a child-index→measured-y
-        // map the parent keeps so each header can learn where the NEXT sticky header starts (its push-off
-        // collision point). The map is a setup-scope const mutated imperatively from each header's onLayout
-        // (like RN's _onStickyHeaderLayout); a reactive bump ref forces the re-render that feeds the
-        // freshly-recorded y forward into the previous header's nextHeaderLayoutY (via nextStickyHeaderY).
+        // Sticky-header cross-talk (RN ScrollView.js _headerLayoutYs): a child-index -> measured-y
+        // map so each header learns where the NEXT sticky header starts (its push-off collision
+        // point). Mutated imperatively from each header's onLayout; the bump ref forces the
+        // re-render that feeds the freshly-recorded y into the previous header's nextStickyHeaderY.
         const headerLayoutYs = new Map();
         const bumpHeaderLayout = ref(0);
         const onHeaderLayoutY = (index, y) => {
@@ -128,13 +99,11 @@ export function createScrollView(platform) {
             dlog(`Vue ScrollView sticky-header layoutY index=${index} y=${y}`);
             bumpHeaderLayout.value += 1;
         };
-        // Native sticky-scroll attach (RN attachNativeEvent / _updateAnimatedNodeAttachment): when the
-        // native module is available, the scroll value is driven on the UI thread so the interpolations
-        // ride scroll natively (no JS jitter). A plain flag set in render (like createAnimatedComponent's
-        // wantsNative: non-reactive so writing it in render triggers no effect); the post-commit watch
-        // reads it once the node commits. The JS path needs no attach: Animated.event drives the value
-        // each frame. flush:'post' so the engine has committed the node before attachStickyScroll reads
-        // its Fabric handle. Detached on unmount (and re-detached if the node identity changes).
+        // Native sticky-scroll attach (RN attachNativeEvent): when the native module is available,
+        // the scroll value is driven on the UI thread so interpolations ride scroll natively (no
+        // JS jitter). A plain non-reactive flag set in render; the post-commit watch reads it once
+        // the node commits. flush:'post' so the node has a Fabric handle before attachStickyScroll
+        // reads it. Detached on unmount and re-detached if the node identity changes.
         let nativeStickyWanted = false;
         let detachStickyScroll;
         watch(() => nodeRef.value, node => {
@@ -153,24 +122,17 @@ export function createScrollView(platform) {
         return () => {
             // Read the bump so a recorded header y re-runs render and feeds nextStickyHeaderY forward.
             void bumpHeaderLayout.value;
-            // Fold kebab template props (:content-container-style) to the RN camelCase contract; idiomatic
-            // Vue templates use kebab, but the prop surface (and HANDLED_ATTRS below) is camelCase.
+            // Fold kebab template props (:content-container-style) to the camelCase prop surface.
             const attrs = normalizeVueAttrs(rawAttrs);
             const isHorizontal = attrs.horizontal === true;
             const userStyle = isStyleProp(attrs.style) ? attrs.style : undefined;
-            // resolveClassName(undefined) is a cheap {} no-op, so this is safe with no class prop too.
             const classProp = isClassNameProp(attrs.class) ? attrs.class : undefined;
             const layoutSplitStyle = [resolveClassName(classProp), userStyle];
-            // A class-name string resolves through the same style registry as `class`/`style` above;
-            // an object/array is already style-shaped and passes through as-is.
             const contentContainerStyle = typeof attrs.contentContainerStyle === 'string'
                 ? resolveClassName(attrs.contentContainerStyle)
                 : isStyleProp(attrs.contentContainerStyle)
                     ? attrs.contentContainerStyle
                     : undefined;
-            // Sticky headers are a pure-JS layer; the native scroll view ignores
-            // stickyHeaderIndices, so we wrap the flagged children below and drive their translateY off
-            // the scroll offset. invertStickyHeaders narrows to the inverted (stick-to-bottom) branch.
             const stickyHeaderIndices = isNumberArray(attrs.stickyHeaderIndices)
                 ? attrs.stickyHeaderIndices
                 : undefined;
@@ -180,10 +142,8 @@ export function createScrollView(platform) {
                 ? attrs.StickyHeaderComponent
                 : undefined;
             const { scrollViewIntrinsic, contentIntrinsic, scrollViewBaseStyle, contentStyle } = selectScrollIntrinsics(isHorizontal, contentContainerStyle);
-            // Outer props: fold aria/role, then layer the lifecycle-managed values on top. RN defaults
-            // nested scrolling ON (ScrollView.js `nestedScrollEnabled ?? true`); horizontal forwards
-            // only when defined (load-bearing on iOS's RCTScrollView axis, ignored by Android's
-            // dedicated manager); decelerationRate is resolved per-platform.
+            // RN defaults nested scrolling ON (ScrollView.js `nestedScrollEnabled ?? true`);
+            // horizontal forwards only when defined (load-bearing on iOS's RCTScrollView axis).
             const outerProps = {
                 ...resolveAccessibilityProps(forwardAttrs(attrs)),
             };
@@ -194,10 +154,10 @@ export function createScrollView(platform) {
             const decel = asDecelerationRate(attrs.decelerationRate);
             if (decel !== undefined)
                 outerProps.decelerationRate = resolveDecelerationRate(decel);
-            // onScroll: when sticky headers are active, the offset must reach the AnimatedValue. RN does
-            // the same with _scrollAnimatedValueAttachment. forwardAttrs already put the user's onScroll /
-            // onLayout / scrollEventThrottle on outerProps; here we override them per the shared
-            // resolveScrollForwarding DECISIONS (which path, the 1/16 throttle defaults, inverted capture).
+            // When sticky headers are active, the offset must reach the AnimatedValue (RN's
+            // _scrollAnimatedValueAttachment). forwardAttrs already put the user's onScroll/onLayout/
+            // scrollEventThrottle on outerProps; here we override per resolveScrollForwarding's
+            // decisions (which path, throttle default, inverted capture).
             const nativeStickyAvailable = hasStickyHeaders && isNativeAnimatedAvailable();
             nativeStickyWanted = nativeStickyAvailable;
             const userThrottle = typeof attrs.scrollEventThrottle === 'number' ? attrs.scrollEventThrottle : undefined;
@@ -212,20 +172,19 @@ export function createScrollView(platform) {
             if (hasStickyHeaders) {
                 const userOnScroll = isHandler(attrs.onScroll) ? attrs.onScroll : undefined;
                 if (forwarding.mode === 'sticky-js') {
-                    // JS fallback (no native module): Animated.event drives the value each frame and forwards
-                    // the user's handler as the listener passthrough. Correct, but lags a frame under fast
-                    // scroll (the jitter), which the native path removes on a real host.
+                    // JS fallback (no native module): correct, but lags a frame under fast scroll, which
+                    // the native path removes on a real host.
                     outerProps.onScroll = animatedEvent([{ nativeEvent: { contentOffset: { y: scrollAnimatedValue } } }], userOnScroll === undefined
                         ? undefined
                         : { listener: (...args) => forwardScrollEvent(userOnScroll, args) });
                 }
-                // Native path: the value is driven on the UI thread by the post-commit watch above, so the
-                // user onScroll (already on outerProps via forwardAttrs) forwards untouched, zero JS/frame.
+                // Native path: the value is driven on the UI thread by the post-commit watch above, so
+                // onScroll forwards untouched.
                 if (forwarding.scrollEventThrottle !== undefined) {
                     outerProps.scrollEventThrottle = forwarding.scrollEventThrottle;
                 }
-                // onLayout on the scroll-view node: capture the viewport height for inverted sticky headers
-                // (RN _handleLayout), then call the user's handler. Non-inverted leaves onLayout as forwarded.
+                // Capture the viewport height for inverted sticky headers (RN _handleLayout), then call
+                // the user's handler.
                 if (forwarding.capturesViewportHeight) {
                     const userOnLayout = isHandler(attrs.onLayout) ? attrs.onLayout : undefined;
                     outerProps.onLayout = (event) => {
@@ -238,18 +197,15 @@ export function createScrollView(platform) {
                 }
             }
             dlog(`Vue ScrollView -> ${scrollViewIntrinsic} (horizontal=${isHorizontal} sticky=${hasStickyHeaders})`);
-            // Content props: `collapsable: false` keeps the layout-only content view as a real native
-            // view: Android Fabric view-flattens it away otherwise, hoisting the cells as direct
-            // children of the scroll view (which hosts exactly one), an addViewAt crash. collapsableChildren
-            // false also preserves the cell views maintainVisibleContentPosition / snapToAlignment
-            // anchor against (RN preserveChildren). iOS never flattens; both are no-ops there.
+            // `collapsable: false` keeps the layout-only content view as a real native view: Android
+            // Fabric view-flattens it away otherwise, hoisting the cells as direct children of the
+            // scroll view (which hosts exactly one) - an addViewAt crash. iOS never flattens.
             const contentProps = { style: contentStyle, collapsable: false };
             if (forwarding.collapsableChildren) {
                 contentProps.collapsableChildren = false;
             }
-            // contentSizeChange is synthesized from the content view's own onLayout (RN
-            // _handleContentOnLayout): read width/height and emit only on a real size change (dedupe via
-            // the setup-scope lastContentSize).
+            // Synthesized from the content view's own onLayout (RN _handleContentOnLayout); emit only
+            // on a real size change.
             contentProps.onLayout = (event) => {
                 const width = readLayoutDimension(event, 'width');
                 const height = readLayoutDimension(event, 'height');
@@ -261,23 +217,17 @@ export function createScrollView(platform) {
                 dlog(`Vue ScrollView contentSizeChange ${width}x${height}`);
                 emit('contentSizeChange', width, height);
             };
-            // Sticky headers are a pure-JS layer (the native scroll view ignores stickyHeaderIndices);
-            // wrap the flagged children so they pin to the scroll offset. No-op when none are flagged.
             const slotChildren = slots.default !== undefined ? slots.default() : [];
             const contentChildren = hasStickyHeaders
                 ? wrapStickyHeaders(slotChildren, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, viewportHeight.value, stickyHeaderComponent, headerLayoutYs, onHeaderLayoutY)
                 : slotChildren;
             const content = h(contentIntrinsic, contentProps, contentChildren);
-            // Base style UNDER user style so an explicit user value (height, flexDirection) still wins;
-            // the scroll node carries overflow:'scroll' (frame clipping) + the per-axis flexDirection.
+            // Base style UNDER user style so an explicit user value (height, flexDirection) still wins.
             const scrollProps = {
                 ...outerProps,
                 style: [scrollViewBaseStyle, userStyle],
                 ref: setNodeRef,
             };
-            // refreshControl arrives as a Vue VNode the app passes (h(RefreshControl, …)); narrow it
-            // with isVNode (no cast). Stripped from forwardAttrs (it is in HANDLED_ATTRS) so it never
-            // reaches the host as a prop: it is lifecycle-consumed by the platform assemble.
             const refreshControl = isVNode(attrs.refreshControl) ? attrs.refreshControl : undefined;
             return platform.assemble({
                 scrollViewIntrinsic,

package/build/components/scroll-view/sticky-header.js

@@ -1,16 +1,14 @@
 // Sticky headers: the Vue twin of adapters/react/src/scroll-view-sticky-header.tsx, the JS layer
 // RN implements in ScrollView.js / ScrollViewStickyHeader.js.
 //
-// Source-based: RN does stickiness PURELY IN JS. ScrollView.js (render, ~line 1690)
-// wraps each child whose index is in `stickyHeaderIndices` in a ScrollViewStickyHeader, fed by a
-// single `_scrollAnimatedValue` an Animated.event drives from `onScroll` (ScrollView.js ~line
-// 1095). The native Fabric scroll view does NOT honor the index array on its own, so forwarding
-// `stickyHeaderIndices` to native is a silent no-op. So we replicate the JS layer: subscribe each
-// flagged child to the scroll offset and translate it to stay pinned. The interpolation mirrors
-// ScrollViewStickyHeader.js (non-inverted + inverted branches) and lives, framework-agnostic, in
+// RN does stickiness PURELY IN JS: ScrollView.js wraps each flagged child in a
+// ScrollViewStickyHeader fed by a single _scrollAnimatedValue that Animated.event drives from
+// onScroll. The native scroll view does NOT honor the index array itself, so forwarding
+// stickyHeaderIndices to native is a silent no-op - we replicate the JS layer instead. The
+// interpolation math (non-inverted + inverted) lives framework-agnostic in
 // @symbiote-native/components (computeStickyInterpolation); this file holds the Vue component
-// shell, the layout state, and the child-wrapping. Render shared verbatim with React via the math.
-// Vue supplies only the reactive lifecycle (refs/watch instead of useState/useEffect).
+// shell, layout state, and child-wrapping. Vue supplies only the reactive lifecycle
+// (refs/watch instead of useState/useEffect).
 import { defineComponent, h, isVNode, onBeforeUnmount, ref, shallowRef, watchEffect, markRaw, } from '@vue/runtime-core';
 import { AnimatedValue, AnimatedInterpolation, Platform, dlog, } from '@symbiote-native/engine';
 import { createInitialStickyState, nextStickyHeaderY, readLayoutNumber, reduceSticky, STICKY_HEADER_Z_INDEX, } from '@symbiote-native/components';
@@ -24,46 +22,39 @@ function isRecord(value) {
 function isAnimatedValue(value) {
     return value instanceof AnimatedValue;
 }
-// Read this header's wrapped child's own onLayout off its VNode props, so the sticky wrapper can
-// forward layout to it (RN ScrollViewStickyHeader.js calls the child's onLayout after its own).
+// So the sticky wrapper can forward layout to the child (RN calls the child's onLayout after its own).
 function readChildOnLayout(child) {
     if (!isRecord(child.props))
         return undefined;
     const handler = child.props.onLayout;
     return isHandler(handler) ? handler : undefined;
 }
-// One sticky header. Measures its own y/height via onLayout, interpolates the shared scroll offset
-// into a translateY that keeps it pinned to the top (or bottom, inverted) until the next header
-// collides with it, and drives that translate through the native driver when available so the pin
-// tracks scroll on the UI thread (no JS jitter). Ported from ScrollViewStickyHeader.js,
-// including the Fabric ShadowTree debounce path. inheritAttrs:false so the IStickyHeaderProps
-// inputs (scrollAnimatedValue/nextHeaderLayoutY/…) never fall through onto Animated.View and reach
-// Fabric as props (scrollAnimatedValue on a host node would crash Android's folly::dynamic).
+// One sticky header. Measures its own y/height via onLayout, interpolates the shared scroll
+// offset into a translateY pinning it to the top (or bottom, inverted) until the next header
+// collides with it, driven through the native driver when available (no JS jitter). Ported from
+// ScrollViewStickyHeader.js, including the Fabric ShadowTree debounce path. inheritAttrs:false
+// so the IStickyHeaderProps inputs never fall through onto Animated.View and reach Fabric as
+// props (scrollAnimatedValue on a host node would crash Android's folly::dynamic).
 export const ScrollViewStickyHeader = defineComponent({
     name: 'ScrollViewStickyHeader',
     inheritAttrs: false,
     setup(_props, { attrs, slots }) {
-        // The scroll-offset value the parent shares, read once (it is stable across renders, the same
-        // markRaw'd AnimatedValue), held by IDENTITY in a const (never run through toReactive). A fresh
-        // fallback keeps working if the invariant (wrapStickyHeaders always supplies it) ever breaks.
+        // Read once - stable across renders (the same markRaw'd AnimatedValue). Held by IDENTITY, never
+        // run through toReactive. A fresh fallback keeps working if wrapStickyHeaders ever fails to supply it.
         const scrollAnimatedValue = isAnimatedValue(attrs.scrollAnimatedValue)
             ? attrs.scrollAnimatedValue
             : markRaw(new AnimatedValue(0));
-        // The one folded state cell, mutated in place by reduceSticky. A plain object (NOT a ref /
-        // reactive): the render reads it gated by the reactive `version` bump + `animatedTranslateY`
-        // shallowRef below, so it never needs Vue to proxy it. The DECISIONS — zero-swallow gate,
-        // debounce delay, rebuild ranges — all live in reduceSticky.
+        // Mutated in place by reduceSticky. A plain object, not a ref: render reads it gated by the
+        // reactive `version` bump + `animatedTranslateY` below. DECISIONS (zero-swallow gate,
+        // debounce delay, rebuild ranges) all live in reduceSticky.
         const state = createInitialStickyState();
-        // A reactive tick bumped when the reducer commits a new translateY, forcing the render to re-read
-        // state.translateY (the debounced committed value).
+        // Bumped when the reducer commits a new translateY, forcing render to re-read state.translateY.
         const version = ref(0);
-        // The animated node that drives the transform (RN's animatedTranslateY). Engine node →
-        // shallowRef (held by identity, the reactivity rule); the un-measured identity stub until the
+        // Engine node -> shallowRef (identity rule); the un-measured identity stub until the
         // rebuild-interpolation effect below replaces it.
         const animatedTranslateY = shallowRef(scrollAnimatedValue.interpolate({ inputRange: [-1, 0], outputRange: [0, 0] }));
         let debounceTimer;
-        // The current interpolation node + its listener id, held so the next rebuild detaches the old
-        // listener (an engine call the reducer does not own) and onBeforeUnmount cleans up.
+        // Held so the next rebuild detaches the old listener and onBeforeUnmount cleans up.
         let interpolation;
         let listenerId;
         const inputs = () => ({
@@ -76,8 +67,7 @@ export const ScrollViewStickyHeader = defineComponent({
             for (const effect of effects) {
                 switch (effect.kind) {
                     case 'rebuild-interpolation': {
-                        // Detach the old listener, build a fresh interpolation onto the shared scroll value, and
-                        // wire the settled-value listener (symbiote is always Fabric; RN attaches it only there).
+                        // Detach the old listener, build a fresh interpolation, and wire the settled-value listener.
                         if (interpolation !== undefined && listenerId !== undefined) {
                             interpolation.removeListener(listenerId);
                             listenerId = undefined;
@@ -95,8 +85,8 @@ export const ScrollViewStickyHeader = defineComponent({
                         break;
                     }
                     case 'schedule-debounce':
-                        // The animated value updates several times per frame; debounce the settled value into the
-                        // committed transform so hit detection stays current (a Fabric issue, worse on Android).
+                        // The animated value updates several times per frame; debounce the settled value so
+                        // hit detection stays current (a Fabric issue, worse on Android).
                         if (debounceTimer !== undefined)
                             clearTimeout(debounceTimer);
                         debounceTimer = setTimeout(() => {
@@ -108,8 +98,7 @@ export const ScrollViewStickyHeader = defineComponent({
                         version.value += 1;
                         break;
                     case 'record-header-y':
-                        // Vue records through attrs.onLayout (the wrapper closure), which honors the public
-                        // IStickyHeaderProps contract; the reducer emits no index for it.
+                        // Vue records through attrs.onLayout (the wrapper closure); the reducer emits no index for it.
                         break;
                 }
             }
@@ -117,9 +106,8 @@ export const ScrollViewStickyHeader = defineComponent({
         const dispatch = (action) => {
             runEffects(reduceSticky(state, action, inputs()).effects);
         };
-        // Rebuild whenever the collision/viewport inputs change (the Vue twin of React's inputs-changed
-        // effect, tracking [inverted, scrollViewHeight, nextHeaderLayoutY] via inputs()); also the initial
-        // build on mount. scrollAnimatedValue is the stable const (never changes for one ScrollView).
+        // Rebuild whenever the collision/viewport inputs change ([inverted, scrollViewHeight,
+        // nextHeaderLayoutY]); also runs once on mount.
         watchEffect(() => {
             dispatch({ kind: 'inputs-changed' });
         });
@@ -130,9 +118,8 @@ export const ScrollViewStickyHeader = defineComponent({
             if (debounceTimer !== undefined)
                 clearTimeout(debounceTimer);
         });
-        // Stable function ref (defined once, not re-created per render): dispatch the layout (record
-        // own y/height, mark measured, rebuild), fire the wrapper's recorder (onHeaderLayoutY, in
-        // attrs.onLayout), then the child's own onLayout. Matches RN ScrollViewStickyHeader.js._onLayout.
+        // Dispatch the layout, fire the wrapper's recorder (onHeaderLayoutY via attrs.onLayout), then
+        // the child's own onLayout. Matches RN ScrollViewStickyHeader.js._onLayout.
         const onLayout = (event) => {
             const y = readLayoutNumber(event, 'y');
             const height = readLayoutNumber(event, 'height');
@@ -151,13 +138,12 @@ export const ScrollViewStickyHeader = defineComponent({
             // Read the version bump so a committed translateY re-runs render.
             void version.value;
             // The EXPLICIT debounced translateY overrides the committed transform for hit-testing, while
-            // `animatedTranslateY` does the smooth (native-driven) pin. See RN ScrollViewStickyHeader.js.
+            // animatedTranslateY does the smooth (native-driven) pin.
             const passthroughAnimatedPropExplicitValues = state.translateY !== null
                 ? { style: { transform: [{ translateY: state.translateY }] } }
                 : null;
             // collapsable:false keeps the wrapper a real Yoga node; zIndex makes the pinned header paint
-            // OVER the rows scrolling under it. The interpolation node passes inside the transform; the
-            // Animated wrapper's reduceProps rasterizes it into a numeric translateY for the committed tree.
+            // OVER the rows scrolling under it.
             return h(Animated.View, {
                 style: {
                     transform: [{ translateY: animatedTranslateY.value }],
@@ -171,15 +157,13 @@ export const ScrollViewStickyHeader = defineComponent({
     },
 });
 // Wrap each child flagged by `stickyHeaderIndices` in the sticky header component, fed by the
-// shared scroll AnimatedValue. Mirrors ScrollView.js's render-time children.map (~line 1690) and
-// the React adapter's wrapStickyHeaders. Returns the children unchanged when no indices are flagged.
+// shared scroll AnimatedValue. Returns the children unchanged when no indices are flagged.
 //
-// Cross-talk plumbing (RN's _headerLayoutYs + _onStickyHeaderLayout, ScrollView.js:1115-1143):
-// `headerLayoutYs` is a child-index→measured-y map the parent keeps; each header reports its own y
-// through `onHeaderLayoutY` as it measures, and we feed every header the y of the NEXT flagged
-// header (the collision point past which it scrolls off) by looking up its successor's index in
-// `stickyHeaderIndices`. The LAST flagged header has no successor, so its `nextHeaderLayoutY` stays
-// undefined and it sticks indefinitely (correct).
+// Cross-talk plumbing (RN's _headerLayoutYs + _onStickyHeaderLayout): headerLayoutYs is a
+// child-index -> measured-y map; each header reports its own y through onHeaderLayoutY, and we
+// feed every header the y of the NEXT flagged header (the collision point past which it scrolls
+// off). The LAST flagged header has no successor, so its nextHeaderLayoutY stays undefined and
+// it sticks indefinitely (correct).
 export function wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, scrollViewHeight, StickyHeaderComponent, headerLayoutYs, onHeaderLayoutY) {
     if (stickyHeaderIndices === undefined || stickyHeaderIndices.length === 0)
         return children;
@@ -188,17 +172,15 @@ export function wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedV
         const indexOfIndex = stickyHeaderIndices.indexOf(index);
         if (indexOfIndex === -1 || !isVNode(child))
             return child;
-        // The next flagged header's measured y, by index order in stickyHeaderIndices (RN
-        // ScrollView.js:1695 nextIndex). undefined until that header has measured (or for the last).
+        // The next flagged header's measured y. undefined until that header has measured (or for the last).
         const nextIndex = stickyHeaderIndices[indexOfIndex + 1];
         const nextHeaderLayoutY = nextStickyHeaderY(stickyHeaderIndices, indexOfIndex, headerLayoutYs);
         dlog(`Vue ScrollView sticky-header wrap index=${index} next=${nextIndex} nextY=${nextHeaderLayoutY}`);
         const props = {
             key: child.key ?? `sticky-${index}`,
             nextHeaderLayoutY,
-            // RN _onStickyHeaderLayout: record this header's own y, then push it to the previous header as
-            // its nextHeaderLayoutY. We record into the parent map; the lookup above feeds it forward on
-            // the resulting re-render (the headerLayoutYs bump in scroll-view-shared).
+            // Record this header's own y into the parent map; the lookup above feeds it forward to the
+            // previous header on the resulting re-render (the headerLayoutYs bump in scroll-view-shared).
             onLayout: (event) => {
                 const y = readLayoutNumber(event, 'y');
                 if (y !== undefined)

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

@@ -1,21 +1,18 @@
 // SectionList, the Vue public list-of-sections component. A thin wrapper over
 // VirtualizedSectionList, mirroring RN's layering (SectionList -> VirtualizedSectionList ->
-// VirtualizedList). All section-flattening / windowing / imperative-scroll logic lives below;
-// this layer re-exposes the same surface under the SectionList name and re-exposes the handle
-// (Vue resolves a parent ref to the exposed object, so the wrapper delegates). The Vue twin of
-// the React adapter's SectionList.
+// VirtualizedList). All section-flattening/windowing/imperative-scroll logic lives below; this
+// layer re-exposes the same surface and re-exposes the handle (Vue resolves a parent ref to the
+// exposed object, so the wrapper delegates).
 //
-// Typed-emits generic component (mirrors FlatList / VirtualizedList): a GENERIC setup function
-// `<ItemT,>(props: ISectionListProps<ItemT>, ctx: ICtx<ISectionListEmits>)` so the section inputs
-// (sections/renderItem/…) infer ItemT at the call site. As a pure forwarder it consumes nothing
-// itself — every input rides through $attrs straight onto VirtualizedSectionList; only the three
-// synthesized events (endReached/startReached/refresh) are bridged, gated on listener presence so
-// the inner list keeps its RefreshControl / edge-reached gating.
+// Typed-emits generic component: a GENERIC setup function so section inputs infer ItemT at the
+// call site. As a pure forwarder it consumes nothing itself - every input rides through $attrs
+// straight onto VirtualizedSectionList; only the three synthesized events are bridged, gated on
+// listener presence so the inner list keeps its RefreshControl/edge-reached gating.
 import { defineComponent, getCurrentInstance, h, shallowRef, } from '@vue/runtime-core';
 import { VirtualizedSectionList, } from '../virtualized-section-list/index.js';
 import { normalizeVueAttrs } from '../../utils/normalize-attrs.js';
-// VirtualizedSectionList is a generic component (generic construct signature), which h()'s overloads
-// can't resolve. Drive it through a loose functional-component handle (generic-component h() limit).
+// VirtualizedSectionList's generic construct signature can't be resolved by h()'s overloads, so
+// drive it through a loose functional-component handle.
 const VirtualizedSectionListHost = VirtualizedSectionList;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -36,17 +33,15 @@ function buildDelegate(getInner) {
     };
 }
 export const SectionList = defineComponent(
-// _props is read only by the type system: ISectionListProps<ItemT> is what lets ItemT infer at
-// the call site. As a pure forwarder, SectionList consumes nothing at runtime — it spreads $attrs.
+// _props is read only by the type system, to let ItemT infer at the call site.
 (_props, { attrs, expose, emit, slots }) => {
     const inner = shallowRef(null);
     const setInner = (instance) => {
         inner.value = isSectionHandle(instance) ? instance : null;
     };
     expose(buildDelegate(() => inner.value));
-    // The three section-list events are emits, so Vue strips their onX listeners from $attrs. Detect
-    // listener presence off the instance's own vnode props and bridge each ONLY when listened, so
-    // the inner VirtualizedSectionList (and its inner VirtualizedList) keeps its on-demand gating.
+    // Emits are stripped from $attrs by Vue; detect listener presence off the instance's own
+    // vnode props and bridge each ONLY when listened.
     const instance = getCurrentInstance();
     const listens = (onName) => {
         const vnodeProps = instance?.vnode.props;
@@ -60,8 +55,6 @@ export const SectionList = defineComponent(
             ? (info) => emit('startReached', info)
             : undefined;
         const refresh = listens('onRefresh') ? () => emit('refresh') : undefined;
-        // Pure forwarder: spread $attrs as props and pass the consumer's scoped slots (#item /
-        // #sectionHeader / … ) straight down to VirtualizedSectionList untouched.
         return h(VirtualizedSectionListHost, {
             ...normalizeVueAttrs(attrs),
             ref: setInner,