@symbiote-native/angular 0.0.0-canary-20260724081123

package/src/descriptor-to-angular/index.ts

@@ -0,0 +1,190 @@
+// Angular descriptor outlet. The React/Vue bridges can return framework elements directly
+// (`descriptorToReact` / `descriptorToVue`); Angular needs a tiny standalone component that
+// consumes a Descriptor tree and drives Renderer2 imperatively, patching same type/key nodes
+// instead of clearing and recreating the subtree so it keeps retained-node identity and Fabric
+// stays on the clone-on-write path.
+
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  inject,
+  Input,
+  Renderer2,
+  type OnChanges,
+  type OnDestroy,
+  type SimpleChanges,
+} from '@angular/core';
+import type { IDescriptor, IDescriptorChild } from '@symbiote-native/components';
+
+type IRenderedChild = IRenderedElement | IRenderedText;
+
+type IRenderedElement = {
+  kind: 'element';
+  node: unknown;
+  descriptor: IDescriptor;
+  props: Record<string, unknown>;
+  children: IRenderedChild[];
+};
+
+type IRenderedText = {
+  kind: 'text';
+  node: unknown;
+  value: string;
+};
+
+@Component({
+  selector: 'symbiote-descriptor-outlet',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class DescriptorOutlet implements OnChanges, OnDestroy {
+  @Input({ required: true }) node!: IDescriptor;
+
+  private readonly renderer = inject(Renderer2);
+  private readonly hostNode = inject<ElementRef<unknown>>(ElementRef).nativeElement;
+  private rendered: IRenderedElement | undefined;
+
+  ngOnChanges(changes: SimpleChanges): void {
+    if (!('node' in changes) || this.node === undefined) return;
+    this.rendered = this.patchRoot(this.rendered, this.node);
+  }
+
+  ngOnDestroy(): void {
+    if (this.rendered === undefined) return;
+    this.renderer.removeChild(this.hostNode, this.rendered.node);
+    this.rendered = undefined;
+  }
+
+  private patchRoot(rendered: IRenderedElement | undefined, next: IDescriptor): IRenderedElement {
+    if (rendered === undefined) {
+      const created = this.createElement(next);
+      this.renderer.appendChild(this.hostNode, created.node);
+      return created;
+    }
+    return this.patchElement(this.hostNode, rendered, next);
+  }
+
+  private createChild(child: IDescriptorChild): IRenderedChild {
+    return typeof child === 'string' ? this.createText(child) : this.createElement(child);
+  }
+
+  private createText(value: string): IRenderedText {
+    return { kind: 'text', node: this.renderer.createText(value), value };
+  }
+
+  private createElement(descriptor: IDescriptor): IRenderedElement {
+    const node = this.renderer.createElement(descriptor.type);
+    const props = { ...descriptor.props };
+    for (const [key, value] of Object.entries(props)) {
+      this.renderer.setProperty(node, key, value);
+    }
+
+    const children = descriptor.children.map(child => this.createChild(child));
+    for (const child of children) {
+      this.renderer.appendChild(node, child.node);
+    }
+
+    return { kind: 'element', node, descriptor, props, children };
+  }
+
+  private patchChild(
+    parent: unknown,
+    rendered: IRenderedChild,
+    next: IDescriptorChild,
+  ): IRenderedChild {
+    if (typeof next === 'string') {
+      if (rendered.kind === 'text') {
+        if (rendered.value !== next) {
+          this.renderer.setValue(rendered.node, next);
+          rendered.value = next;
+        }
+        return rendered;
+      }
+      const replacement = this.createText(next);
+      this.replaceChild(parent, rendered.node, replacement.node);
+      return replacement;
+    }
+
+    if (rendered.kind === 'element') {
+      return this.patchElement(parent, rendered, next);
+    }
+    const replacement = this.createElement(next);
+    this.replaceChild(parent, rendered.node, replacement.node);
+    return replacement;
+  }
+
+  private patchElement(
+    parent: unknown,
+    rendered: IRenderedElement,
+    next: IDescriptor,
+  ): IRenderedElement {
+    if (!sameElement(rendered.descriptor, next)) {
+      const replacement = this.createElement(next);
+      this.replaceChild(parent, rendered.node, replacement.node);
+      return replacement;
+    }
+
+    this.patchProps(rendered, next.props);
+    rendered.children = this.patchChildren(rendered.node, rendered.children, next.children);
+    rendered.descriptor = next;
+    return rendered;
+  }
+
+  private patchProps(rendered: IRenderedElement, nextProps: Record<string, unknown>): void {
+    const prevProps = rendered.props;
+    for (const key of Object.keys(prevProps)) {
+      if (!(key in nextProps)) {
+        this.renderer.setProperty(rendered.node, key, undefined);
+      }
+    }
+    for (const [key, value] of Object.entries(nextProps)) {
+      if (!Object.is(prevProps[key], value)) {
+        this.renderer.setProperty(rendered.node, key, value);
+      }
+    }
+    rendered.props = { ...nextProps };
+  }
+
+  private patchChildren(
+    parent: unknown,
+    renderedChildren: IRenderedChild[],
+    nextChildren: IDescriptorChild[],
+  ): IRenderedChild[] {
+    const nextRendered: IRenderedChild[] = [];
+    const common = Math.min(renderedChildren.length, nextChildren.length);
+
+    for (let i = 0; i < common; i++) {
+      const rendered = renderedChildren[i];
+      const next = nextChildren[i];
+      if (rendered !== undefined && next !== undefined) {
+        nextRendered.push(this.patchChild(parent, rendered, next));
+      }
+    }
+
+    for (let i = common; i < nextChildren.length; i++) {
+      const next = nextChildren[i];
+      if (next === undefined) continue;
+      const child = this.createChild(next);
+      this.renderer.appendChild(parent, child.node);
+      nextRendered.push(child);
+    }
+
+    for (let i = common; i < renderedChildren.length; i++) {
+      const rendered = renderedChildren[i];
+      if (rendered !== undefined) this.renderer.removeChild(parent, rendered.node);
+    }
+
+    return nextRendered;
+  }
+
+  private replaceChild(parent: unknown, oldChild: unknown, newChild: unknown): void {
+    this.renderer.insertBefore(parent, newChild, oldChild);
+    this.renderer.removeChild(parent, oldChild);
+  }
+}
+
+function sameElement(prev: IDescriptor, next: IDescriptor): boolean {
+  return prev.type === next.type && prev.key === next.key;
+}

package/src/host-instance/host-instance.test.ts

@@ -0,0 +1,49 @@
+// Co-located test for findNodeHandle, the Angular twin of adapters/vue/src/host-instance/host-instance.test.ts.
+// Proves the Angular adapter can resolve a raw engine node, an engine public instance, a bare
+// reactTag, and null/undefined to a native tag using the engine's getNativeTag.
+
+import { describe, expect, it } from 'vitest';
+import { createElement, createSurface, getNativeTag } from '@symbiote-native/engine';
+import { installFabric } from '@symbiote-native/test-utils';
+import { findNodeHandle } from './index';
+
+installFabric();
+const ROOT_TAG = 708;
+
+describe('Angular findNodeHandle on the engine', () => {
+  it('returns the committed tag for a raw engine node', async () => {
+    const surface = createSurface(ROOT_TAG);
+    const node = createElement('RCTView');
+    surface.appendChild(node);
+    surface.commit();
+    await new Promise<void>(resolve => setTimeout(resolve, 0));
+
+    const tag = getNativeTag(node);
+    expect(tag).toBeGreaterThan(0);
+    expect(findNodeHandle(node)).toBe(tag);
+  });
+
+  it('returns the committed tag for a public instance (toPublicInstance graft)', async () => {
+    const surface = createSurface(ROOT_TAG + 1);
+    const node = createElement('RCTView');
+    surface.appendChild(node);
+    surface.commit();
+    await new Promise<void>(resolve => setTimeout(resolve, 0));
+
+    const tag = getNativeTag(node);
+    // The public instance is the same identity as the engine node; findNodeHandle accepts it.
+    const publicInstance = node;
+    expect(findNodeHandle(publicInstance)).toBe(tag);
+  });
+
+  it('passes a bare number through idempotently', () => {
+    expect(findNodeHandle(42)).toBe(42);
+  });
+
+  it('returns null for null, undefined, and unknown inputs', () => {
+    expect(findNodeHandle(null)).toBeNull();
+    expect(findNodeHandle(undefined)).toBeNull();
+    expect(findNodeHandle('not-a-node' as any)).toBeNull();
+    expect(findNodeHandle({} as any)).toBeNull();
+  });
+});

package/src/host-instance/index.ts

@@ -0,0 +1,36 @@
+// findNodeHandle, the Angular twin of adapters/react/src/host-instance.ts and
+// adapters/vue/src/host-instance/index.ts. RN's "ref/instance -> native reactTag" lookup,
+// the seam imperative-interop libraries reach through.
+//
+// Angular template refs on a primitive host (`<View #myView>`) receive the component instance,
+// not the raw engine node. SymbiotePrimitiveHost exposes `nativeElement`, which holds the
+// engine host node that `getNativeTag` is keyed on. This adapter accepts:
+//   - a bare number (idempotent)
+//   - an engine host node / public instance
+//   - an Angular ElementRef wrapping the host node
+//   - a SymbiotePrimitiveHost component instance (via its public `nativeElement` getter)
+//   - null/undefined -> null
+// An uncommitted or unknown input surfaces as null.
+
+import { ElementRef } from '@angular/core';
+import { getNativeTag, isSymbioteNode, type ISymbioteNode } from '@symbiote-native/engine';
+
+export type { IHostInstance } from '@symbiote-native/engine';
+
+function resolveHostNode(candidate: unknown): ISymbioteNode | null {
+  if (candidate === null || candidate === undefined) return null;
+  if (isSymbioteNode(candidate)) return candidate;
+  if (candidate instanceof ElementRef) return resolveHostNode(candidate.nativeElement);
+  const maybeHost = candidate as { nativeElement?: unknown };
+  if (typeof maybeHost.nativeElement !== 'undefined') {
+    return resolveHostNode(maybeHost.nativeElement);
+  }
+  return null;
+}
+
+export function findNodeHandle(componentOrHandle: unknown): number | null {
+  if (componentOrHandle === null || componentOrHandle === undefined) return null;
+  if (typeof componentOrHandle === 'number') return componentOrHandle;
+  const node = resolveHostNode(componentOrHandle);
+  return node ? (getNativeTag(node) ?? null) : null;
+}

package/src/index.ts

@@ -0,0 +1,261 @@
+// @symbiote-native/angular: a thin Angular reconciler over @symbiote-native/engine. A custom Renderer2 +
+// RendererFactory2 map each node op onto the engine's mutation API; all Fabric clone-on-write
+// lives in the engine, shared with every other adapter. App code names only @symbiote-native/angular.
+//
+// SEAM SCAFFOLD: mount/unmount + the renderer seam + host intrinsic selectors. Full RN-like
+// composed components still flow through the shared @symbiote-native/components bridge.
+
+export {
+  ActivityIndicator,
+  anchorHostStyle,
+  Button,
+  FlatList,
+  HorizontalScrollContentView,
+  HorizontalScrollView,
+  Image,
+  ImageBackground,
+  InputAccessoryView,
+  KeyboardAvoidingView,
+  Modal,
+  Pressable,
+  RefreshControl,
+  SafeAreaView,
+  ScrollContentView,
+  ScrollView,
+  ScrollViewStickyHeader,
+  SectionList,
+  stableAnchorStyle,
+  Switch,
+  SymbioteHostPropsDirective,
+  Text,
+  TextInput,
+  TouchableHighlight,
+  TouchableNativeFeedback,
+  TouchableOpacity,
+  TouchableWithoutFeedback,
+  View,
+  VirtualizedList,
+  VirtualizedSectionList,
+  VListEmptyDirective,
+  VListFooterDirective,
+  VListHeaderDirective,
+  VListItemDirective,
+  VListSeparatorDirective,
+  VSectionFooterDirective,
+  VSectionHeaderDirective,
+  VSectionItemDirective,
+  VSectionSeparatorDirective,
+} from './components';
+export { Animated } from './modules/animated';
+// Also exposed as named top-level symbols (not just Animated.View/.Text/...): ngtsc's partial-mode
+// static evaluator can't trace a component class through property access on an external
+// namespace object, only through a direct named import binding —
+// so `<AnimatedView>` in a template requires `import { AnimatedView } from '@symbiote-native/angular'`,
+// not `const AnimatedView = Animated.View`. Plain tsc/vitest don't catch this; only a real ngc run does.
+export {
+  AnimatedFlatList,
+  AnimatedImage,
+  AnimatedScrollView,
+  AnimatedSectionList,
+  AnimatedText,
+  AnimatedView,
+} from './modules/animated';
+export type {
+  IActivityIndicatorProps,
+  IAngularImageBackgroundProps,
+  IAngularInputAccessoryViewProps,
+  IAngularKeyboardAvoidingViewProps,
+  IAngularModalProps,
+  IAngularPressableProps,
+  IAngularRefreshControlProps,
+  IAngularSafeAreaViewProps,
+  IAngularScrollViewProps,
+  IAngularTextInputProps,
+  IAngularTouchableHighlightProps,
+  IAngularTouchableNativeFeedbackProps,
+  IAngularTouchableOpacityProps,
+  IAngularTouchableWithoutFeedbackProps,
+  IButtonProps,
+  ICellLayout,
+  IFlatListHandle,
+  IFlatListProps,
+  IEnterKeyHint,
+  IImageCacheStatus,
+  IImageProps,
+  IImageSize,
+  IImageSource,
+  IImageSourceProp,
+  IInputMode,
+  IKeyboardAvoidingBehavior,
+  IModalAnimationType,
+  IModalOrientation,
+  IModalOrientationChangeEvent,
+  IModalPresentationStyle,
+  INativeFeedbackBackground,
+  IResizeMode,
+  IRippleBackground,
+  IScrollViewHandle,
+  ISectionListHandle,
+  ISectionListProps,
+  ISeparatorProps,
+  ISeparators,
+  IStickyHeaderComponentType,
+  ISubmitBehavior,
+  IThemeAttrBackground,
+  IViewabilityConfig,
+  IViewabilityConfigCallbackPair,
+  IViewableItemsChangedInfo,
+  IViewToken,
+  IVirtualizedListHandle,
+  IVirtualizedListProps,
+  IVirtualizedSectionListHandle,
+  IVirtualizedSectionListProps,
+  IVListItemContext,
+  IVListSeparatorContext,
+  IVSectionContext,
+  IVSectionItemContext,
+  ISection,
+  ISwitchProps,
+  ISwitchTrackColor,
+  ITextInputHandle,
+  ITextInputSelection,
+} from './components';
+export { setImageSourceResolver } from './components';
+export { mount, unmount } from './render';
+// The generic Descriptor→Angular bridge, the twin of descriptorToReact/descriptorToVue.
+// Exported so a component defined OUTSIDE this package (e.g.
+// @symbiote-native/slider) can render a shared @symbiote-native/components/@symbiote-native/slider Descriptor tree
+// without hand-writing its own Renderer2 walker.
+export { DescriptorOutlet } from './descriptor-to-angular';
+// createPortal (same-surface only — see the file header) and createTunnel (cross-surface,
+// see its file header) are the Angular twins of the React/Vue portal/tunnel primitives.
+// Angular can't synthesize components at runtime (no JIT under Metro/Hermes), so both are
+// static, pre-authored structural directives (`*portal`/`*tunnelIn`, the `*ngIf`/`*ngFor`
+// idiom) parameterized by an `@Input()`, rather than a factory returning fresh components per
+// call.
+export { PortalDirective, PortalOutletDirective } from './create-portal';
+export { createTunnel, TunnelInDirective, TunnelOut, type ITunnelStore } from './create-tunnel';
+export { SymbioteRenderer, SymbioteRendererFactory } from './renderer';
+// registerComposedComponent lives in the dependency-free leaf ./anchor-host-registry, NOT in the
+// require-cyclic ./renderer — see the leaf header. The babel-register-composed plugin injects the
+// import straight from that subpath so app-screen registration never routes through this cyclic
+// barrel.
+export { registerComposedComponent } from './anchor-host-registry';
+export { findNodeHandle } from './host-instance';
+export type { IHostInstance } from './host-instance';
+export { StatusBar } from './modules/status-bar';
+export type { IStatusBarProps, IStatusBarStyle } from './modules/status-bar';
+// AppRegistry: RN's app entry point over `mount`. setHostRegistrar wires RN's own
+// registrar so the native Fabric host finds our runnable by app key.
+export { AppRegistry, setHostRegistrar } from './modules/app-registry';
+export type {
+  IComponentProvider,
+  IAppParameters,
+  IRunnable,
+  IHostRegistrar,
+  IWrapperComponentProvider,
+  IRegistry,
+  IHeadlessTask,
+  ITaskProvider,
+  ITaskCanceller,
+  ITaskCancelProvider,
+} from './modules/app-registry';
+export { ColorSchemeService, WindowDimensionsService } from './services';
+
+// Framework-agnostic runtime modules from @symbiote-native/engine. Every adapter re-exports them so
+// app code names only @symbiote-native/angular.
+export {
+  Alert,
+  Share,
+  ActionSheetIOS,
+  Linking,
+  Vibration,
+  ToastAndroid,
+  Settings,
+  I18nManager,
+  Dimensions,
+  Appearance,
+  AppState,
+  Keyboard,
+  KEYBOARD_EVENT,
+  BackHandler,
+  PermissionsAndroid,
+  PERMISSIONS,
+  RESULTS,
+  AccessibilityInfo,
+  LayoutAnimation,
+  InteractionManager,
+  PanResponder,
+  PixelRatio,
+  PlatformColor,
+  DynamicColorIOS,
+} from '@symbiote-native/engine';
+export type {
+  IAlertType,
+  IAlertButtonStyle,
+  IAlertButton,
+  IAlertButtons,
+  IAlertOptions,
+  IShareContent,
+  IShareOptions,
+  IShareAction,
+  IActionSheetIOSOptions,
+  IShareActionSheetIOSOptions,
+  IShareActionSheetError,
+  IUrlEvent,
+  II18nManagerConstants,
+  IDisplayMetrics,
+  IDisplayMetricsAndroid,
+  IDimensionsPayload,
+  IDimensionsSet,
+  IDimensionsKey,
+  IDimensionsChangeListener,
+  IDimensionsStatic,
+  IColorSchemeName,
+  IColorSchemePreference,
+  IAppStateStatus,
+  IAppStateEvent,
+  IKeyboardEventName,
+  IKeyboardEvent,
+  IKeyboardMetrics,
+  IBackPressEventName,
+  IBackPressHandler,
+  IPermission,
+  IPermissionStatus,
+  IRationale,
+  IAccessibilityChangeEvent,
+  IAccessibilityChangeEventName,
+  IAccessibilityChangeEventHandler,
+  IAccessibilityAnnouncementFinishedEvent,
+  IAnnounceForAccessibilityOptions,
+  IAccessibilityEventType,
+  ILayoutAnimationType,
+  ILayoutAnimationProperty,
+  ILayoutAnimationConfig,
+  ILayoutAnimationAnim,
+  IInteractionEvent,
+  ISimpleTask,
+  IPromiseTask,
+  ITask,
+  IHandle,
+  IPanResponderGestureState,
+  IPanResponderCallbacks,
+  IGestureResponderHandlers,
+  IPanResponderInstance,
+  IPixelRatioStatic,
+  IColorValue,
+  IOpaqueColorValue,
+  IDynamicColorIOSTuple,
+} from '@symbiote-native/engine';
+export {
+  dlog,
+  flattenStyle,
+  isDebug,
+  Platform,
+  processColor,
+  setColorProcessor,
+  setDeviceEventSource,
+  setNativeViewConfigSource,
+  StyleSheet,
+} from '@symbiote-native/engine';
+export type { IRootTag, ISymbioteEvent, ISymbioteNode } from '@symbiote-native/engine';

package/src/modules/animated/animated-leaf-binder/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 './index';
+
+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();
+  });
+});