@symbiote-native/vue 0.3.7 → 0.4.0

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

@@ -1,48 +1,34 @@
-// 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, selectScrollIntrinsics, } from '@symbiote-native/components';
+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';
 import { wrapStickyHeaders } from './sticky-header.js';
 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,33 +154,38 @@ 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 for the sticky branch.
+            // 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;
+            const forwarding = resolveScrollForwarding({
+                hasStickyHeaders,
+                nativeStickyAvailable,
+                invertStickyHeaders,
+                scrollEventThrottle: userThrottle,
+                maintainVisibleContentPosition: attrs.maintainVisibleContentPosition,
+                snapToAlignment: attrs.snapToAlignment,
+            });
             if (hasStickyHeaders) {
                 const userOnScroll = isHandler(attrs.onScroll) ? attrs.onScroll : undefined;
-                const userThrottle = typeof attrs.scrollEventThrottle === 'number' ? attrs.scrollEventThrottle : undefined;
-                if (nativeStickyAvailable) {
-                    // Native path (RN attachNativeEvent): the scroll value is driven on the UI thread by the
-                    // post-commit watch above, so onScroll only forwards to the user: zero JS per frame. RN
-                    // uses throttle 1 when sticky (ScrollView.js:1798); the native driver can afford it. The
-                    // user onScroll is already on outerProps via forwardAttrs.
-                    outerProps.scrollEventThrottle = userThrottle ?? 1;
-                }
-                else {
-                    // 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 above removes on a real host.
+                if (forwarding.mode === 'sticky-js') {
+                    // 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) });
-                    outerProps.scrollEventThrottle = userThrottle ?? 16;
                 }
-                // 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.
-                if (invertStickyHeaders === true) {
+                // 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;
+                }
+                // 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) => {
                         const height = readLayoutDimension(event, 'height');
@@ -232,19 +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 (attrs.maintainVisibleContentPosition !== undefined ||
-                attrs.snapToAlignment !== undefined) {
+            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');
@@ -256,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,