@symbiote-native/angular 0.0.0-canary-20260724081123

package/src/modules/animated/animated-leaf-binder/index.ts

@@ -0,0 +1,101 @@
+// Pure Fabrication (GRASP): the leaf-lifecycle orchestration shared by every Animated*
+// wrapper, extracted out of AnimatedComponentBase so AnimatedImage — which cannot extend
+// AnimatedComponentBase, since it must extend ImageBase for TS's-native image handling —
+// gets the SAME logic via composition instead of copy-pasting it. Framework-thin on
+// purpose: it knows nothing about Angular (@ViewChild, DI, change detection), only the
+// engine's Animated leaf + commit primitives, so it stays testable without any Angular
+// bootstrap. NOTE: react/vue drive this same dance through their own runtime HOC
+// (createAnimatedComponent) rather than a class, so there is no cross-adapter dedup
+// opportunity here yet — this Pure Fabrication is local to the angular adapter.
+import {
+  AnimatedProps,
+  attachNativeEventHandler,
+  dlog,
+  whenCommitted,
+  type ISymbioteNode,
+} from '@symbiote-native/engine';
+
+export class AnimatedLeafBinder {
+  // The leaf currently wired into the value graph. Null until the first reconcile.
+  private attached: AnimatedProps | null = null;
+  // The whenCommitted waiter for the current leaf's node binding, cancelled before the next.
+  private cancelBind: (() => void) | undefined;
+  // Detachers for any Animated.event prop bound natively to the committed node (JS path: none).
+  private eventDetachers: Array<() => void> = [];
+
+  // `resolveNode` stays a caller-supplied resolver (not a constructor-captured node) so this
+  // class never needs to know HOW the host node is found — AnimatedComponentBase and
+  // AnimatedImage both resolve it the same way (resolveHostNode + isSymbioteNode over their
+  // own @ViewChild), but that's Angular DI state this binder has no business touching.
+  // `label` is purely diagnostic (dlog), mirroring the constructor.name the pre-extraction
+  // dlog call used.
+  constructor(
+    private readonly resolveNode: () => ISymbioteNode | null,
+    private readonly label: string,
+  ) {}
+
+  // Build a fresh AnimatedProps leaf from the current props (the React/Vue per-render
+  // useMemo(rest)), wire it into the graph, and swap the previous one out. Attach the NEW leaf
+  // BEFORE detaching the OLD one: a shared Value self-detaches (dropping its native node) the
+  // instant its child count hits zero, so detaching first would kill a running native animation
+  // on any unrelated re-render (mirrors RN's AnimatedComponent._attachProps). Then bind the
+  // committed node, go native if wanted, and rebind native events.
+  reconcile(props: Record<string, unknown>, wantsNative: boolean): void {
+    dlog(`${this.label} reconcile`);
+    const newLeaf = new AnimatedProps(props);
+    newLeaf.__attach();
+    if (this.attached !== null && this.attached !== newLeaf) this.attached.__detach();
+    this.attached = newLeaf;
+
+    this.bindNode(newLeaf, props, wantsNative);
+  }
+
+  // Bind the leaf to the host's Fabric node THROUGH whenCommitted: under Angular's zoneless
+  // batched change detection the inner host's tag does not exist yet at ngAfterViewInit time
+  // (the same async-commit gotcha Vue documents), so binding eagerly would no-op. whenCommitted
+  // runs the action now if already committed, else after the commit that assigns the tag.
+  private bindNode(
+    leaf: AnimatedProps,
+    props: Record<string, unknown>,
+    wantsNative: boolean,
+  ): void {
+    this.cancelBind?.();
+    this.cancelBind = undefined;
+    const node = this.resolveNode();
+    if (node === null) return;
+    this.cancelBind = whenCommitted(node, () => {
+      leaf.setNativeView(node);
+      if (wantsNative) leaf.__makeNative();
+      this.attachEvents(node, props);
+    });
+  }
+
+  // Native-attach any Animated.event prop (e.g. onScroll={Animated.event(…,{useNativeDriver:true})})
+  // to the committed node. attachNativeEventHandler no-ops (returns undefined) unless the prop is a
+  // native event handler with a committed tag, so the JS path stays the fallback. Rebound each
+  // reconcile so a new inline event re-attaches; detached first to avoid leaking the prior binding.
+  private attachEvents(node: ISymbioteNode, props: Record<string, unknown>): void {
+    this.detachEvents();
+    for (const key of Object.keys(props)) {
+      const attachment = attachNativeEventHandler(node, key, props[key]);
+      if (attachment !== undefined) this.eventDetachers.push(attachment.detach);
+    }
+  }
+
+  private detachEvents(): void {
+    for (const detach of this.eventDetachers) detach();
+    this.eventDetachers = [];
+  }
+
+  // Tear down everything: cancel a still-pending bind, drop native event listeners, detach the
+  // current leaf from the value graph. Safe to call even if reconcile() was never called.
+  destroy(): void {
+    this.cancelBind?.();
+    this.cancelBind = undefined;
+    this.detachEvents();
+    if (this.attached !== null) {
+      this.attached.__detach();
+      this.attached = null;
+    }
+  }
+}

package/src/modules/animated/animated-leaf-binder.test.ts

@@ -0,0 +1,116 @@
+// Unit tests for AnimatedLeafBinder in isolation — no Angular involved. Both
+// AnimatedComponentBase and AnimatedImage delegate their leaf-lifecycle (build a leaf,
+// bind it to the committed Fabric node, swap leaves on re-render, tear down) to this Pure
+// Fabrication; these tests exercise the binder directly against a real engine node
+// (SymbioteSurface + the fake Fabric backend), so a break here isolates to the shared
+// orchestration rather than either owning component.
+import { beforeEach, describe, expect, it } from 'vitest';
+import { installFabric } from '@symbiote-native/test-utils';
+import {
+  AnimatedValue,
+  createElement,
+  createSurface,
+  type ISymbioteNode,
+} from '@symbiote-native/engine';
+import { AnimatedLeafBinder } from './animated-leaf-binder';
+
+const fabric = installFabric();
+let nextRootTag = 9001;
+
+beforeEach(() => fabric.reset());
+
+// A node that has already gone through a commit — whenCommitted fires synchronously.
+function committedNode(): ISymbioteNode {
+  const surface = createSurface(nextRootTag++);
+  const node = createElement('RCTView');
+  surface.appendChild(node);
+  surface.commit();
+  return node;
+}
+
+// A node that is attached to a surface but has NOT been committed yet — whenCommitted
+// must defer until the caller commits the surface.
+function uncommittedNode(): { node: ISymbioteNode; commit: () => void } {
+  const surface = createSurface(nextRootTag++);
+  const node = createElement('RCTView');
+  surface.appendChild(node);
+  return { node, commit: () => surface.commit() };
+}
+
+// `appRoot()` unwraps RN's synthetic box-none AppContainer, which is ALSO an RCTView, so a
+// plain `fabric.find(viewName === 'RCTView')` would match it instead of the node under test.
+// Each test appends exactly one child, so the container's first (only) child is the real node.
+function fakeView(): ReturnType<typeof fabric.find> {
+  return fabric.appRoot().children[0];
+}
+
+describe('AnimatedLeafBinder', () => {
+  it('creates and attaches an AnimatedProps leaf, wiring value changes onto the host node', () => {
+    const node = committedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const opacity = new AnimatedValue(1);
+
+    // The leaf itself never pushes the INITIAL value — that first paint comes from the
+    // owning component's own reduceProps template binding (out of scope here). The leaf
+    // only drives value CHANGES after it is bound.
+    binder.reconcile({ style: { opacity } }, false);
+
+    opacity.setValue(0.4);
+    expect(fakeView()?.props.opacity).toBe(0.4);
+  });
+
+  it('binds to the host node via whenCommitted, deferring until the node is actually committed', () => {
+    const { node, commit } = uncommittedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const opacity = new AnimatedValue(1);
+
+    binder.reconcile({ style: { opacity } }, false);
+    // Not committed yet: the value graph exists, but no Fabric node to flush onto.
+    opacity.setValue(0.5);
+    expect(fabric.created).toHaveLength(0);
+
+    commit();
+    // whenCommitted's post-commit retry binds the leaf now; a subsequent change flushes.
+    opacity.setValue(0.7);
+    expect(fakeView()?.props.opacity).toBe(0.7);
+  });
+
+  it('attaches the new leaf before detaching the old one on a second reconcile', () => {
+    const node = committedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const shared = new AnimatedValue(1);
+    const order: string[] = [];
+    const originalAddChild = shared.__addChild.bind(shared);
+    const originalRemoveChild = shared.__removeChild.bind(shared);
+    shared.__addChild = child => {
+      order.push('add');
+      originalAddChild(child);
+    };
+    shared.__removeChild = child => {
+      order.push('remove');
+      originalRemoveChild(child);
+    };
+
+    binder.reconcile({ style: { opacity: shared } }, false);
+    order.length = 0; // only care about the SECOND reconcile's swap order
+
+    binder.reconcile({ style: { opacity: shared } }, false);
+
+    expect(order).toEqual(['add', 'remove']);
+  });
+
+  it('detaches the leaf and cancels any pending bind on destroy', () => {
+    const { node, commit } = uncommittedNode();
+    const binder = new AnimatedLeafBinder(() => node, 'test');
+    const opacity = new AnimatedValue(1);
+
+    binder.reconcile({ style: { opacity } }, false);
+    binder.destroy();
+    commit();
+
+    // The pending whenCommitted bind was cancelled by destroy, so committing afterward
+    // must not retroactively bind the (already-detached) leaf.
+    opacity.setValue(0.9);
+    expect(fakeView()?.props.opacity).toBeUndefined();
+  });
+});

package/src/modules/animated/animated-leaf-binder.ts

@@ -0,0 +1,101 @@
+// Pure Fabrication (GRASP): the leaf-lifecycle orchestration shared by every Animated*
+// wrapper, extracted out of AnimatedComponentBase so AnimatedImage — which cannot extend
+// AnimatedComponentBase, since it must extend ImageBase for TS's-native image handling —
+// gets the SAME logic via composition instead of copy-pasting it. Framework-thin on
+// purpose: it knows nothing about Angular (@ViewChild, DI, change detection), only the
+// engine's Animated leaf + commit primitives, so it stays testable without any Angular
+// bootstrap. NOTE: react/vue drive this same dance through their own runtime HOC
+// (createAnimatedComponent) rather than a class, so there is no cross-adapter dedup
+// opportunity here yet — this Pure Fabrication is local to the angular adapter.
+import {
+  AnimatedProps,
+  attachNativeEventHandler,
+  dlog,
+  whenCommitted,
+  type ISymbioteNode,
+} from '@symbiote-native/engine';
+
+export class AnimatedLeafBinder {
+  // The leaf currently wired into the value graph. Null until the first reconcile.
+  private attached: AnimatedProps | null = null;
+  // The whenCommitted waiter for the current leaf's node binding, cancelled before the next.
+  private cancelBind: (() => void) | undefined;
+  // Detachers for any Animated.event prop bound natively to the committed node (JS path: none).
+  private eventDetachers: Array<() => void> = [];
+
+  // `resolveNode` stays a caller-supplied resolver (not a constructor-captured node) so this
+  // class never needs to know HOW the host node is found — AnimatedComponentBase and
+  // AnimatedImage both resolve it the same way (resolveHostNode + isSymbioteNode over their
+  // own @ViewChild), but that's Angular DI state this binder has no business touching.
+  // `label` is purely diagnostic (dlog), mirroring the constructor.name the pre-extraction
+  // dlog call used.
+  constructor(
+    private readonly resolveNode: () => ISymbioteNode | null,
+    private readonly label: string,
+  ) {}
+
+  // Build a fresh AnimatedProps leaf from the current props (the React/Vue per-render
+  // useMemo(rest)), wire it into the graph, and swap the previous one out. Attach the NEW leaf
+  // BEFORE detaching the OLD one: a shared Value self-detaches (dropping its native node) the
+  // instant its child count hits zero, so detaching first would kill a running native animation
+  // on any unrelated re-render (mirrors RN's AnimatedComponent._attachProps). Then bind the
+  // committed node, go native if wanted, and rebind native events.
+  reconcile(props: Record<string, unknown>, wantsNative: boolean): void {
+    dlog(`${this.label} reconcile`);
+    const newLeaf = new AnimatedProps(props);
+    newLeaf.__attach();
+    if (this.attached !== null && this.attached !== newLeaf) this.attached.__detach();
+    this.attached = newLeaf;
+
+    this.bindNode(newLeaf, props, wantsNative);
+  }
+
+  // Bind the leaf to the host's Fabric node THROUGH whenCommitted: under Angular's zoneless
+  // batched change detection the inner host's tag does not exist yet at ngAfterViewInit time
+  // (the same async-commit gotcha Vue documents), so binding eagerly would no-op. whenCommitted
+  // runs the action now if already committed, else after the commit that assigns the tag.
+  private bindNode(
+    leaf: AnimatedProps,
+    props: Record<string, unknown>,
+    wantsNative: boolean,
+  ): void {
+    this.cancelBind?.();
+    this.cancelBind = undefined;
+    const node = this.resolveNode();
+    if (node === null) return;
+    this.cancelBind = whenCommitted(node, () => {
+      leaf.setNativeView(node);
+      if (wantsNative) leaf.__makeNative();
+      this.attachEvents(node, props);
+    });
+  }
+
+  // Native-attach any Animated.event prop (e.g. onScroll={Animated.event(…,{useNativeDriver:true})})
+  // to the committed node. attachNativeEventHandler no-ops (returns undefined) unless the prop is a
+  // native event handler with a committed tag, so the JS path stays the fallback. Rebound each
+  // reconcile so a new inline event re-attaches; detached first to avoid leaking the prior binding.
+  private attachEvents(node: ISymbioteNode, props: Record<string, unknown>): void {
+    this.detachEvents();
+    for (const key of Object.keys(props)) {
+      const attachment = attachNativeEventHandler(node, key, props[key]);
+      if (attachment !== undefined) this.eventDetachers.push(attachment.detach);
+    }
+  }
+
+  private detachEvents(): void {
+    for (const detach of this.eventDetachers) detach();
+    this.eventDetachers = [];
+  }
+
+  // Tear down everything: cancel a still-pending bind, drop native event listeners, detach the
+  // current leaf from the value graph. Safe to call even if reconcile() was never called.
+  destroy(): void {
+    this.cancelBind?.();
+    this.cancelBind = undefined;
+    this.detachEvents();
+    if (this.attached !== null) {
+      this.attached.__detach();
+      this.attached = null;
+    }
+  }
+}

package/src/modules/animated/animated-scroll-view.test.ts

@@ -0,0 +1,102 @@
+// Regression tests for two Android-only bugs AnimatedScrollView's bespoke template hit because
+// it talks to the raw symbiote-scroll-view primitive directly instead of reusing the real
+// ScrollView component (which already has both fixes — see scroll-view/shared.ts):
+//
+// 1. It projected <ng-content> straight into symbiote-scroll-view with no content wrapper. On
+//    Android, symbiote-scroll-content resolves to a plain RCTView, which Fabric view-flattens
+//    away unless collapsable:false pins it — so multiple projected children were hoisted up as
+//    direct children of the scroll view, which natively hosts exactly one ("ScrollView can
+//    host only one direct child" -> addViewAt crash).
+// 2. It never defaulted nestedScrollEnabled. RN defaults nested scrolling ON (ScrollView.js
+//    `nestedScrollEnabled ?? true`), but Android needs it explicit or a ScrollView nested
+//    inside another scrollable container (this canary's own nested demo) never receives touch
+//    — it renders fine but is static, the outer ScrollView swallows the gesture.
+//
+// The fake Fabric harness doesn't simulate Android's real view-flattening or touch dispatch, so
+// these tests only prove the structural/prop invariants that prevent both bugs, not the
+// on-device symptoms themselves — those still need a real Android host.
+import '@angular/compiler';
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { installFabric } from '@symbiote-native/test-utils';
+import { mount, unmount } from '../../render';
+import { AnimatedScrollView } from './create-animated-component';
+
+const ROOT_TAG = 927;
+const OVERRIDE_ROOT_TAG = 928;
+const fabric = installFabric();
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+class AnimatedScrollViewApp {}
+Component({
+  selector: 'animated-scroll-view-test',
+  standalone: true,
+  imports: [AnimatedScrollView],
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <AnimatedScrollView>
+      <symbiote-view testID="a"></symbiote-view>
+      <symbiote-view testID="b"></symbiote-view>
+    </AnimatedScrollView>
+  `,
+})(AnimatedScrollViewApp);
+
+class AnimatedScrollViewOverrideApp {}
+Component({
+  selector: 'animated-scroll-view-override-test',
+  standalone: true,
+  imports: [AnimatedScrollView],
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <AnimatedScrollView [animatedProps]="{ nestedScrollEnabled: false }">
+      <symbiote-view testID="a"></symbiote-view>
+    </AnimatedScrollView>
+  `,
+})(AnimatedScrollViewOverrideApp);
+
+beforeEach(() => fabric.reset());
+afterEach(() => {
+  unmount(ROOT_TAG);
+  unmount(OVERRIDE_ROOT_TAG);
+});
+
+describe('AnimatedScrollView', () => {
+  it('wraps multiple projected children in a single non-collapsable content view', async () => {
+    mount(ROOT_TAG, AnimatedScrollViewApp);
+    await tick();
+
+    const scrollView = fabric.find(node => node.viewName === 'RCTScrollView');
+    expect(scrollView?.children).toHaveLength(1);
+    expect(scrollView?.props.nestedScrollEnabled).toBe(true);
+
+    const content = scrollView?.children[0];
+    expect(content?.viewName).toBe('RCTScrollContentView');
+    expect(content?.props.collapsable).toBe(false);
+    expect(content?.children.map(child => child.props.testID)).toEqual(['a', 'b']);
+  });
+
+  // Regression test for a THIRD bug in this same bespoke-template class, this one iOS-only (the
+  // inverse of the two Android bugs above): AnimatedScrollView never applied
+  // selectScrollIntrinsics' scrollViewBaseStyle (overflow: 'scroll') to its host node, unlike the
+  // real ScrollView component. On iOS Fabric a scroll view only clips its content to its own
+  // frame when `overflow: 'scroll'` is set; without it, content taller than the frame bleeds out
+  // over sibling views instead of scrolling clipped (Android's native ViewGroup clips regardless
+  // of the style prop, which is why this was invisible there). See
+  // core/components/src/view/render-scroll-view.ts's SCROLL_VIEW_BASE_VERTICAL comment.
+  it('applies the scroll-view base style (overflow: scroll) so content clips to the frame', async () => {
+    mount(ROOT_TAG, AnimatedScrollViewApp);
+    await tick();
+
+    const scrollView = fabric.find(node => node.viewName === 'RCTScrollView');
+    expect(scrollView?.props.overflow).toBe('scroll');
+    expect(scrollView?.props.flexDirection).toBe('column');
+  });
+
+  it('lets an explicit nestedScrollEnabled in animatedProps override the default', async () => {
+    mount(OVERRIDE_ROOT_TAG, AnimatedScrollViewOverrideApp);
+    await tick();
+
+    const scrollView = fabric.find(node => node.viewName === 'RCTScrollView');
+    expect(scrollView?.props.nestedScrollEnabled).toBe(false);
+  });
+});