@symbiote-native/angular 3.2.0 → 3.4.0

package/src/host-instance/index.ts

@@ -21,14 +21,14 @@ import {
 
 export type { IHostInstance } from '@symbiote-native/engine';
 
-function resolveHostNode(candidate: unknown): ISymbioteNode | null {
+export function hostNodeOf(candidate: unknown): ISymbioteNode | null {
   if (candidate === null || candidate === undefined) return null;
   if (isSymbioteNode(candidate)) return candidate;
   if (candidate instanceof ElementRef)
-    return resolveHostNode(candidate.nativeElement);
+    return hostNodeOf(candidate.nativeElement);
   const maybeHost = candidate as { nativeElement?: unknown };
   if (typeof maybeHost.nativeElement !== 'undefined') {
-    return resolveHostNode(maybeHost.nativeElement);
+    return hostNodeOf(maybeHost.nativeElement);
   }
   return null;
 }
@@ -37,6 +37,6 @@ export function findNodeHandle(componentOrHandle: unknown): number | null {
   if (componentOrHandle === null || componentOrHandle === undefined)
     return null;
   if (typeof componentOrHandle === 'number') return componentOrHandle;
-  const node = resolveHostNode(componentOrHandle);
+  const node = hostNodeOf(componentOrHandle);
   return node ? (getNativeTag(node) ?? null) : null;
 }

package/src/index.ts

@@ -36,24 +36,27 @@ export {
   Text,
   TouchableNativeFeedback,
   View,
+  injectVirtualizedListScope,
   VirtualizedList,
   VirtualizedSectionList,
+  VListCellDirective,
   VListEmptyDirective,
   VListFooterDirective,
   VListHeaderDirective,
   VListItemDirective,
+  VListOutletDirective,
   VListSeparatorDirective,
   VSectionFooterDirective,
   VSectionHeaderDirective,
   VSectionItemDirective,
   VSectionSeparatorDirective,
 } from './components';
+// What a list built on `FlatList` needs to keep its template and its accessibility gate
+export { FLAT_LIST_TEMPLATE } from './components/flat-list/flat-list-template';
+export { provideGateDemand } from './gate-demand';
 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.
+// Named top-level too, as the ngtsc static evaluator cannot trace `Animated.View` property access
+// A template tag like `<AnimatedView>` needs a direct import, only a real ngc run catches it
 export {
   AnimatedFlatList,
   AnimatedImage,
@@ -62,15 +65,9 @@ export {
   AnimatedText,
   AnimatedView,
 } from './modules/animated';
-// Exported even though Angular's version maps only the four primitives (View/Text/Image/
-// ScrollView) onto the pre-authored wrappers above and THROWS on anything else — there is no JIT
-// under AOT/Metro, so it cannot synthesize a wrapper at runtime the way the other four adapters
-// do. It ships anyway because portable code (`createAnimatedComponent(View)`) then compiles and
-// runs identically on all five adapters, and the one case Angular cannot serve fails with a
-// message naming the fix (author a standalone @Component over AnimatedComponentBase) instead of
-// failing as a missing export, which names nothing. Found by the barrel audit in
-// `.claude/rules/adapter-parity-audit.md`: it was implemented and tested here all along and simply
-// never reached this file, so `@symbiote-native/angular` consumers could not reach it at all.
+// Maps only View/Text/Image/ScrollView onto the wrappers above and throws on anything else (no JIT)
+// Portable `createAnimatedComponent(View)` still runs on all five adapters, and the error names
+// the fix: a standalone `@Component` over `AnimatedComponentBase`
 export { createAnimatedComponent } from './modules/animated';
 export type {
   IActivityIndicatorProps,
@@ -78,6 +75,7 @@ export type {
   IAngularImageBackgroundProps,
   IAngularInputAccessoryViewProps,
   IAngularKeyboardAvoidingViewProps,
+  IAngularLayoutConformanceProps,
   IAngularModalProps,
   IAngularPressableProps,
   IAngularRefreshControlProps,
@@ -89,6 +87,7 @@ export type {
   IAngularTouchableOpacityProps,
   IAngularTouchableWithoutFeedbackProps,
   IButtonProps,
+  ICheckboxProps,
   ICellLayout,
   IFlatListHandle,
   IFlatListProps,
@@ -100,6 +99,7 @@ export type {
   IImageSourceProp,
   IInputMode,
   IKeyboardAvoidingBehavior,
+  ILayoutConformanceMode,
   IModalAnimationType,
   IModalOrientation,
   IModalOrientationChangeEvent,
@@ -118,14 +118,17 @@ export type {
   IViewabilityConfigCallbackPair,
   IViewableItemsChangedInfo,
   IViewToken,
+  IListScope,
   IVirtualizedListHandle,
   IVirtualizedListProps,
   IVirtualizedSectionListHandle,
   IVirtualizedSectionListProps,
+  IVListCellContext,
   IVListItemContext,
   IVListSeparatorContext,
   IVSectionContext,
   IVSectionItemContext,
+  IVSectionSeparatorContext,
   ISection,
   ISwitchProps,
   ISwitchTrackColor,
@@ -144,6 +147,7 @@ export {
   ActivityIndicatorElement,
   ActivityIndicatorSpinnerElement,
   ButtonElement,
+  CheckboxElement,
   HorizontalScrollContentElement,
   HorizontalScrollViewElement,
   ImageBackgroundElement,
@@ -154,6 +158,7 @@ export {
   PressableElement,
   RefreshControlElement,
   SafeAreaViewElement,
+  LayoutConformanceElement,
   ScrollContentElement,
   ScrollViewElement,
   StickyHeaderElement,
@@ -187,12 +192,9 @@ export { mount, unmount } from './render';
 // @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 { DescriptorHost } from './descriptor-to-angular/descriptor-host';
+// Twins of the React/Vue portal and tunnel: same-surface portal, cross-surface tunnel
+// No JIT under Metro/Hermes, so both are pre-authored structural directives (`*portal`/`*tunnelIn`)
 export { PortalDirective, PortalOutletDirective } from './create-portal';
 export {
   createTunnel,
@@ -206,15 +208,20 @@ export { SymbioteRenderer, SymbioteRendererFactory } from './renderer';
 // 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 { findNodeHandle, hostNodeOf } 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 {
+  AppRegistry,
+  HeadlessJsTaskError,
+  setHostRegistrar,
+} from './modules/app-registry';
 export type {
   IComponentProvider,
+  IAppConfig,
   IAppParameters,
   IRunnable,
   IHostRegistrar,
@@ -230,9 +237,16 @@ export {
   WindowDimensionsService,
   createResourceHook,
   createEventValueHook,
+  injectEvent,
+  injectEventListener,
   connectWatchedSignal,
   PermissionsServiceBase,
 } from './services';
+export {
+  createAnimatedColor as injectAnimatedColor,
+  createAnimatedValue as injectAnimatedValue,
+  createAnimatedValueXY as injectAnimatedValueXY,
+} from '@symbiote-native/engine';
 export { AccessibilityInputsBase } from './accessibility-inputs';
 export { NativeViewBase } from './native-view-base';
 export { anchorStyleProp } from './primitives/shared';
@@ -253,6 +267,7 @@ export {
   AppState,
   Keyboard,
   KEYBOARD_EVENT,
+  TextInputState,
   BackHandler,
   PermissionsAndroid,
   PERMISSIONS,
@@ -328,7 +343,6 @@ export {
   Platform,
   processColor,
   setColorProcessor,
-  setDeviceEventSource,
   setNativeViewConfigSource,
   StyleSheet,
 } from '@symbiote-native/engine';
@@ -376,3 +390,44 @@ export {
   setAngularProfileDetail,
 } from './diagnostics';
 export type { IAngularProfile, IAngularProfileDetail } from './diagnostics';
+
+// The device event bus and the easing curves, shared verbatim from the engine
+export {
+  DeviceEventEmitter,
+  Easing,
+  EventEmitter,
+  NativeAppEventEmitter,
+  NativeEventEmitter,
+} from '@symbiote-native/engine';
+export type {
+  IEasing,
+  IEasingFunction,
+  IEmitterSubscription,
+  IEventEmitter,
+  IEventEmitterModule,
+  IEventSubscription,
+  INativeEventListener,
+} from '@symbiote-native/engine';
+
+// RN's dev and native-module utilities, shared verbatim from the engine. The ones RN owns forward
+// to its own module, which `registerApp` hands over
+export {
+  codegenNativeCommands,
+  codegenNativeComponent,
+  DevMenu,
+  DevSettings,
+  LogBox,
+  NativeComponentRegistry,
+  NativeModules,
+  Networking,
+  PushNotificationIOS,
+  ReactNativeVersion,
+  registerCallableModule,
+  requireNativeComponent,
+  Systrace,
+  Touchable,
+  TurboModuleRegistry,
+  UIManager,
+  UTFSequence,
+} from '@symbiote-native/engine';
+export type { IDevSettings } from '@symbiote-native/engine';

package/src/modules/animated/index.ts

@@ -6,29 +6,9 @@
 // `Animated.timing(new Animated.Value(0), …).start()`, works against the Angular-driven engine.
 
 import {
-  AnimatedValue,
-  AnimatedValueXY,
-  AnimatedColor,
+  AnimatedDrivers,
   AnimatedMock,
-  Easing,
   Platform,
-  timing,
-  spring,
-  decay,
-  parallel,
-  sequence,
-  stagger,
-  loop,
-  delay,
-  add,
-  subtract,
-  multiply,
-  divide,
-  modulo,
-  diffClamp,
-  event,
-  forkEvent,
-  unforkEvent,
 } from '@symbiote-native/engine';
 import {
   AnimatedFlatList,
@@ -61,37 +41,12 @@ export {
 // components exist. Angular still cannot synthesize arbitrary animated wrappers at runtime; custom
 // animated components remain explicit standalone components over AnimatedComponentBase.
 
-// The live, JS-driven driver namespace (real frames). RN's AnimatedImplementation.
-const liveDrivers = {
-  Value: AnimatedValue,
-  ValueXY: AnimatedValueXY,
-  Color: AnimatedColor,
-  Easing,
-  timing,
-  spring,
-  decay,
-  parallel,
-  sequence,
-  stagger,
-  loop,
-  delay,
-  add,
-  subtract,
-  multiply,
-  divide,
-  modulo,
-  diffClamp,
-  event,
-  forkEvent,
-  unforkEvent,
-};
-
 // RN swaps the WHOLE driver namespace for the mock when the host reports isDisableAnimations
 // (reduced motion / test env): the mock keeps the same surface but jumps each animation to its
 // final value synchronously, no frames. The animated COMPONENTS are live in both branches; only
 // the drivers/value/operators/events half is swapped, exactly like RN spreading `...Animated`
 // (impl or mock) over the same components.
-const drivers = Platform.isDisableAnimations ? AnimatedMock : liveDrivers;
+const drivers = Platform.isDisableAnimations ? AnimatedMock : AnimatedDrivers;
 
 export const Animated = {
   View: AnimatedView,

package/src/modules/app-registry/index.ts

@@ -10,6 +10,7 @@ import type { Type } from '@angular/core';
 import {
   createAppRegistry,
   dlog,
+  HeadlessJsTaskError,
   type IAppParameters,
   type IRunnable,
 } from '@symbiote-native/engine';
@@ -47,8 +48,9 @@ const { AppRegistry, setHostRegistrar } = createAppRegistry<
   IWrapperComponentProvider
 >(runnableFor);
 
-export { AppRegistry, setHostRegistrar };
+export { AppRegistry, HeadlessJsTaskError, setHostRegistrar };
 export type {
+  IAppConfig,
   IAppParameters,
   IRunnable,
   IHostRegistrar,

package/src/modules/status-bar/index.ts

@@ -1,21 +1,20 @@
-// StatusBar, the Angular lifecycle half. The native StatusBarManager driving, the imperative
-// statics, and the Android bar-height constant all live in @symbiote-native/engine, shared verbatim with
-// React and Vue; Metro selects the engine's platform variant. Angular supplies only the
-// declarative shape: a component that renders nothing and re-applies the props through
-// ngOnChanges on mount + every prop change. Imperative statics are attached to the component
-// object the same way RN does.
+// Angular half of StatusBar, the props stack, statics and Android bar-height constant live in
+// @symbiote-native/engine. It renders nothing, keeps one stack entry through `ngOnChanges` and
+// releases it in `ngOnDestroy`
 
 import {
   Component,
   Input,
   type OnChanges,
-  type SimpleChanges,
+  type OnDestroy,
+  type OnInit,
 } from '@angular/core';
 import {
-  applyStatusBarProps,
+  createStatusBarEntry,
   statusBarImperative,
   statusBarCurrentHeight,
   type IColorValue,
+  type IStatusBarAnimation,
   type IStatusBarProps,
   type IStatusBarStyle,
 } from '@symbiote-native/engine';
@@ -27,16 +26,29 @@ export type { IStatusBarProps, IStatusBarStyle } from '@symbiote-native/engine';
   standalone: true,
   template: '',
 })
-class StatusBarComponent implements OnChanges {
+class StatusBarComponent implements OnInit, OnChanges, OnDestroy {
   @Input() barStyle?: IStatusBarStyle;
   @Input() hidden?: boolean;
   @Input() animated?: boolean;
+  @Input() showHideTransition?: IStatusBarAnimation;
   @Input() networkActivityIndicatorVisible?: boolean;
   @Input() backgroundColor?: IColorValue;
   @Input() translucent?: boolean;
 
-  ngOnChanges(_changes: SimpleChanges): void {
-    applyStatusBarProps(this.buildProps());
+  private readonly entry = createStatusBarEntry();
+
+  // `ngOnChanges` never runs without bound inputs, the bar still takes its place in the stack
+  ngOnInit(): void {
+    this.entry.apply(this.buildProps());
+  }
+
+  ngOnChanges(): void {
+    this.entry.apply(this.buildProps());
+  }
+
+  // Popping restores what the stack held below this entry
+  ngOnDestroy(): void {
+    this.entry.release();
   }
 
   private buildProps(): IStatusBarProps {
@@ -44,6 +56,7 @@ class StatusBarComponent implements OnChanges {
       barStyle: this.barStyle,
       hidden: this.hidden,
       animated: this.animated,
+      showHideTransition: this.showHideTransition,
       networkActivityIndicatorVisible: this.networkActivityIndicatorVisible,
       backgroundColor: this.backgroundColor,
       translucent: this.translucent,

package/src/native-view-base.ts

@@ -1,18 +1,32 @@
-import { Directive, ElementRef, inject, Input } from '@angular/core';
+import {
+  ChangeDetectorRef,
+  Directive,
+  ElementRef,
+  inject,
+  Input,
+  ViewChild,
+} from '@angular/core';
+import type { OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 import { resolveAccessibilityProps } from '@symbiote-native/components';
 import type { IDescriptor } from '@symbiote-native/components';
 import type {
   IStyleProp,
   ISymbioteEvent,
+  ISymbioteNode,
   IViewStyle,
 } from '@symbiote-native/engine';
 import { AccessibilityInputsBase } from './accessibility-inputs';
+import { DescriptorOutlet } from './descriptor-to-angular';
+import { hostNodeOf } from './host-instance';
 import { anchorStyleProp } from './primitives/shared';
 
 // Shared shell of a component that paints one Expo native view: the common inputs, the anchor
 // host `class="..."` resolves onto, and a descriptor that recomputes on every OnPush check
 @Directive()
-export abstract class NativeViewBase extends AccessibilityInputsBase {
+export abstract class NativeViewBase
+  extends AccessibilityInputsBase
+  implements OnChanges, OnDestroy
+{
   @Input() style?: IStyleProp<IViewStyle>;
   @Input() testID?: string;
   @Input() nativeID?: string;
@@ -23,6 +37,27 @@ export abstract class NativeViewBase extends AccessibilityInputsBase {
 
   // This component's own `ElementRef`, the anchor a `class="..."` at the use site lands on
   private readonly elementRef = inject(ElementRef);
+  protected readonly changeDetector = inject(ChangeDetectorRef);
+
+  @ViewChild(DescriptorOutlet) private readonly nativeOutlet?: DescriptorOutlet;
+
+  // The committed host node of the native view, for a component that calls its view functions
+  protected hostNode(): ISymbioteNode | null {
+    return hostNodeOf(this.nativeOutlet?.rootNode);
+  }
+
+  // Hook for a component that holds more than its native node, runs once when it is destroyed
+  protected disposeView(): void {}
+
+  // A `[style]` binding reaches the `style` input without dirtying an OnPush view, a plain
+  // `[prop]` does. A subclass with its own `ngOnChanges` calls this one first
+  ngOnChanges(changes: SimpleChanges): void {
+    if ('style' in changes) this.changeDetector.markForCheck();
+  }
+
+  ngOnDestroy(): void {
+    this.disposeView();
+  }
 
   // Names of the component's own inputs that go to the native view, read off `this`
   protected abstract readonly propNames: readonly string[];

package/src/primitives/index.ts

@@ -103,6 +103,13 @@ export class ActivityIndicatorHost extends SymbiotePrimitiveHost {}
 })
 export class SafeAreaViewHost extends SymbiotePrimitiveHost {}
 
+@Component({
+  selector: 'layout-conformance',
+  standalone: true,
+  template: '<ng-content></ng-content>',
+})
+export class LayoutConformanceHost extends SymbiotePrimitiveHost {}
+
 @Component({
   selector: 'modal',
   standalone: true,

package/src/services/color-scheme.service.ts

@@ -11,7 +11,7 @@ import { Appearance, type IColorSchemeName } from '@symbiote-native/engine';
  */
 @Injectable({ providedIn: 'root' })
 export class ColorSchemeService {
-  readonly colorScheme = signal<IColorSchemeName | null>(
+  readonly colorScheme = signal<IColorSchemeName | null | undefined>(
     Appearance.getColorScheme(),
   );
 

package/src/services/index.ts

@@ -2,5 +2,6 @@ export { ColorSchemeService } from './color-scheme.service';
 export { WindowDimensionsService } from './window-dimensions.service';
 export { createResourceHook } from './create-resource-hook';
 export { createEventValueHook } from './create-event-value-hook';
+export { injectEvent, injectEventListener } from './inject-event';
 export { connectWatchedSignal } from './connect-watched-signal';
 export { PermissionsServiceBase } from './permissions-service-base';

package/src/services/inject-event.ts

@@ -0,0 +1,52 @@
+// Angular twins of `useEvent` and `useEventListener` of the `expo` package, for any emitter
+
+import { effect, signal, untracked } from '@angular/core';
+import type { Signal } from '@angular/core';
+import { bindEventListener } from '@symbiote-native/engine';
+import type {
+  IEventEmitterOf,
+  IEventName,
+  IEventPayload,
+  IEventsMap,
+} from '@symbiote-native/engine';
+
+/** Calls the listener for each event, the latest one, and stops with the injection context */
+export function injectEventListener<
+  TEventsMap extends IEventsMap,
+  TName extends IEventName<TEventsMap>,
+>(
+  emitter: () => IEventEmitterOf<TEventsMap>,
+  eventName: () => TName,
+  listener: () => TEventsMap[TName],
+): void {
+  effect(onCleanup => {
+    const source = emitter();
+    const name = eventName();
+    // The listener is read at each event, a new one is not a new subscription
+    onCleanup(bindEventListener(source, name, () => untracked(listener)));
+  });
+}
+
+/** The payload of the last event, `initialValue` (or `null`) until the first one */
+export function injectEvent<
+  TEventsMap extends IEventsMap,
+  TName extends IEventName<TEventsMap>,
+>(
+  emitter: () => IEventEmitterOf<TEventsMap>,
+  eventName: () => TName,
+  initialValue: IEventPayload<TEventsMap, TName> | null = null,
+): Signal<IEventPayload<TEventsMap, TName> | null> {
+  const event = signal<IEventPayload<TEventsMap, TName> | null>(initialValue);
+  effect(onCleanup => {
+    const source = emitter();
+    const name = eventName();
+    onCleanup(
+      bindEventListener(
+        source,
+        name,
+        () => (next: IEventPayload<TEventsMap, TName>) => event.set(next),
+      ),
+    );
+  });
+  return event.asReadonly();
+}