@symbiote-native/angular 0.1.0

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. This mirrors wolf-tui's
+// WNodeOutlet, but patches same type/key nodes instead of clearing and recreating the subtree so
+// Symbiote 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 (ADR 0025), 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,257 @@
+// @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 — see the
+// `angular-adapter` skill (§6 descriptorToAngular, the layered milestones).
+
+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 (real AOT, see angular-adapter skill §4) 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 (§6 of the angular-adapter skill), 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 — see the react-adapter-portal / angular-adapter skills.
+export { PortalDirective, PortalOutletDirective } from './create-portal';
+export { createTunnel, TunnelInDirective, TunnelOut, type ITunnelStore } from './create-tunnel';
+export { SymbioteRenderer, SymbioteRendererFactory } from './renderer';
+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-scroll-view.test.ts

@@ -0,0 +1,85 @@
+// 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']);
+  });
+
+  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);
+  });
+});