@symbiote-native/angular 3.1.3 → 3.3.0

package/src/finalization-registry.ts

@@ -0,0 +1,18 @@
+// Hermes has no `FinalizationRegistry`, and `@angular/core` >=22.2 builds one at module load
+// Cleanup callbacks never fire, which only costs Angular's signal debug bookkeeping
+
+class InertFinalizationRegistry {
+  register(): void {}
+
+  unregister(): boolean {
+    return false;
+  }
+}
+
+if (typeof globalThis.FinalizationRegistry === 'undefined') {
+  Object.defineProperty(globalThis, 'FinalizationRegistry', {
+    value: InertFinalizationRegistry,
+    configurable: true,
+    writable: true,
+  });
+}

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

@@ -17,6 +17,7 @@
 // template dependencies to importable names (NG3004, the same rule that put the element directives
 // back below). Retiring them means retiring them from those nine components first.
 
+import './finalization-registry';
 import './register';
 
 export {
@@ -88,6 +89,7 @@ export type {
   IAngularTouchableOpacityProps,
   IAngularTouchableWithoutFeedbackProps,
   IButtonProps,
+  ICheckboxProps,
   ICellLayout,
   IFlatListHandle,
   IFlatListProps,
@@ -143,6 +145,7 @@ export {
   ActivityIndicatorElement,
   ActivityIndicatorSpinnerElement,
   ButtonElement,
+  CheckboxElement,
   HorizontalScrollContentElement,
   HorizontalScrollViewElement,
   ImageBackgroundElement,
@@ -186,6 +189,7 @@ 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';
+export { DescriptorHost } from './descriptor-to-angular/descriptor-host';
 // 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
@@ -205,7 +209,7 @@ 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';
@@ -224,7 +228,19 @@ export type {
   ITaskCanceller,
   ITaskCancelProvider,
 } from './modules/app-registry';
-export { ColorSchemeService, WindowDimensionsService } from './services';
+export {
+  ColorSchemeService,
+  WindowDimensionsService,
+  createResourceHook,
+  createEventValueHook,
+  injectEvent,
+  injectEventListener,
+  connectWatchedSignal,
+  PermissionsServiceBase,
+} from './services';
+export { AccessibilityInputsBase } from './accessibility-inputs';
+export { NativeViewBase } from './native-view-base';
+export { anchorStyleProp } from './primitives/shared';
 
 // Framework-agnostic runtime modules from @symbiote-native/engine. Every adapter re-exports them so
 // app code names only @symbiote-native/angular.

package/src/native-view-base.ts

@@ -0,0 +1,86 @@
+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
+  implements OnChanges, OnDestroy
+{
+  @Input() style?: IStyleProp<IViewStyle>;
+  @Input() testID?: string;
+  @Input() nativeID?: string;
+  @Input() onLayout?: (event: ISymbioteEvent) => void;
+  @Input() onAccessibilityTap?: (event: ISymbioteEvent) => void;
+  @Input() onMagicTap?: (event: ISymbioteEvent) => void;
+  @Input() onAccessibilityEscape?: (event: ISymbioteEvent) => void;
+
+  // 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[];
+
+  // The core render fn, `null` when the view has nothing to paint on this platform
+  protected abstract renderView(props: object): IDescriptor | null;
+
+  get descriptor(): IDescriptor | null {
+    return this.renderView(
+      resolveAccessibilityProps({
+        ...this.accessibilityInputProps(),
+        ...Object.fromEntries(
+          this.propNames.map(name => [name, Reflect.get(this, name)]),
+        ),
+        // Ambient class style first, so an explicit `style` input wins
+        style: [anchorStyleProp<IViewStyle>(this.elementRef), this.style],
+        testID: this.testID,
+        nativeID: this.nativeID,
+        onLayout: this.onLayout,
+        onAccessibilityTap: this.onAccessibilityTap,
+        onMagicTap: this.onMagicTap,
+        onAccessibilityEscape: this.onAccessibilityEscape,
+      }),
+    );
+  }
+}

package/src/render/index.ts

@@ -29,6 +29,8 @@ import {
   ɵprovideZonelessChangeDetectionInternal as provideZonelessChangeDetectionInternal,
   type ComponentRef,
   type EnvironmentInjector,
+  type EnvironmentProviders,
+  type Provider,
   type Type,
 } from '@angular/core';
 import { SymbioteRendererFactory } from '../renderer';
@@ -119,6 +121,15 @@ export interface IMountOptions {
   wrapperComponent?: Type<unknown>;
 }
 
+// App-level providers (`provideHttpClient()` and the like), set once at bootstrap
+let rootProviders: (Provider | EnvironmentProviders)[] = [];
+
+export function setRootProviders(
+  providers: (Provider | EnvironmentProviders)[],
+): void {
+  rootProviders = providers;
+}
+
 function applyInputs(
   cmpRef: ComponentRef<unknown>,
   initialProps: object | undefined,
@@ -189,32 +200,17 @@ function settleAngularDevMode(): void {
   enableProdMode();
 }
 
-export function mount(
-  rootTag: IRootTag,
-  rootComponent: Type<unknown>,
-  options?: IMountOptions,
-): SymbioteSurface {
-  settleAngularDevMode();
-  // A re-mount on a live rootTag starts clean; otherwise the stale app double-drives the surface.
-  teardown(rootTag);
-
-  const surface = createSurface(rootTag);
-  const rendererFactory = new SymbioteRendererFactory(surface);
-  const injector = createEnvironmentInjector(
+// Kept apart from `mount` so the provider list reads as one block
+function createRootInjector(
+  surface: SymbioteSurface,
+  rendererFactory: SymbioteRendererFactory,
+): EnvironmentInjector {
+  return createEnvironmentInjector(
     [
-      {
-        provide: RendererFactory2,
-        useValue: rendererFactory,
-      },
-      // `getElementById` is not decoration: `resource()` resolves TransferState, whose root
-      // factory runs `retrieveTransferredState(doc, appId)` ->
-      // `doc.getElementById(appId + '-state')` (core/src/transfer_state.ts:156) to pick up
-      // server-rendered state. A stub without it makes that a TypeError, and because the throw
-      // happens while the component is being constructed, the ENTIRE screen renders nothing —
-      // white body under a native header that navigation drew anyway, no error surfaced. The
-      // `optional: true` on the injector lookup does not help: the token resolves, its factory
-      // is what throws. Returning null is the honest client answer — there is no server here, so
-      // `script?.tagName` short-circuits and the caller gets `{}`.
+      ...rootProviders,
+      { provide: RendererFactory2, useValue: rendererFactory },
+      // `resource()` resolves TransferState, which calls `doc.getElementById`
+      // a stub without it throws mid-construction and the whole screen renders nothing
       {
         provide: DOCUMENT,
         useValue: {
@@ -223,72 +219,75 @@ export function mount(
           getElementById: (): null => null,
         },
       },
-      // createEnvironmentInjector with a null parent scopes this injector to {'environment'}
-      // only (see EnvironmentNgModuleRefAdapter), so providedIn:'root' tokens — ApplicationRef
-      // included — never resolve (R3Injector.get walks up for a `scopes` containing 'root', and
-      // a null parent always dead-ends in NullInjector). platform-browser solves this the same
-      // way for real DOM apps via BROWSER_MODULE_PROVIDERS: hand { provide: INJECTOR_SCOPE,
-      // useValue: 'root' } to the app-level providers, which R3Injector's constructor reads to
-      // self-tag this.scopes with 'root'. Same trick here, no PlatformRef, no DOM.
+      // A null-parent injector is not root-scoped, so `providedIn: 'root'` tokens never resolve
       { provide: INJECTOR_SCOPE, useValue: 'root' },
-      // Supplies the real ChangeDetectionSchedulerImpl (microtask-batched via
-      // ApplicationRef.afterTick) + NoopNgZone + ZONELESS_ENABLED: true — the exact bundle
-      // internalCreateApplication() uses. Replaces the old unconditional
-      // `rootView.detectChanges(); cmpView.detectChanges()` (force-ran both root views on every
-      // tick) with Angular's own tick(), which only enters a view something actually marked
-      // dirty. This does NOT stop the root's own template from re-running on a plain press or
-      // `markForCheck()` anywhere in the tree — `markViewDirty` unconditionally sets RefreshView
-      // on every ancestor up to the root; that's fundamental Angular zoneless behavior, not
-      // something this swap changes. A genuine child `@Component` boundary still protects a
-      // sibling branch from an unrelated press.
+      // Real microtask-batched scheduler plus a noop zone, so `appRef.tick()` drives the views
       ...provideZonelessChangeDetectionInternal(),
-      // Angular's INTERNAL_APPLICATION_ERROR_HANDLER reports a tick() exception via
-      // `injector.get(ErrorHandler)`; a normal `bootstrapApplication` registers that token by
-      // default, but our from-scratch environment injector never did, so the lookup itself threw
-      // NG0201 and replaced the real error with "No provider found for ErrorHandler" — any async
-      // tick() exception crashed hard, uncaught, instead of being reported. The token still has to
-      // be provided for exactly that reason; what it resolves to is now SymbioteErrorHandler
-      // (see above), which reports through the engine instead of Angular's `console.error('ERROR',
-      // e)` and, like the default, returns rather than rethrows so the app keeps running.
+      // Angular's `tick()` looks up `ErrorHandler`, and a from-scratch injector has none (NG0201)
       { provide: ErrorHandler, useClass: SymbioteErrorHandler },
       ColorSchemeService,
       WindowDimensionsService,
     ],
     rootInjectorParent(),
   );
+}
 
-  // hostElement = the surface: the component's template content commits straight into the
-  // surface with no wrapper view, the engine wrapping surface.children in its synthetic flex
-  // root — the Angular equivalent of Vue's `app.mount(surface)`.
-  let cmpRef: ComponentRef<unknown>;
-  let rootRef: ComponentRef<unknown> | undefined;
-  if (options?.wrapperComponent === undefined) {
-    cmpRef = createComponent<unknown>(rootComponent, {
-      environmentInjector: injector,
-      hostElement: asAngularHost(surface),
-    });
-    applyInputs(cmpRef, options?.initialProps);
-  } else {
-    // The root gets its own host node from the renderer (createComponent without a
-    // hostElement) but is not attached to the surface directly; it is handed to the
-    // wrapper as projectable content instead, so only the wrapper needs a real host.
-    const rootHost = asAngularHost(createDetachedViewHost());
-    rootRef = createComponent<unknown>(rootComponent, {
-      environmentInjector: injector,
-      hostElement: rootHost,
-    });
-    applyInputs(rootRef, options.initialProps);
-    cmpRef = createComponent<unknown>(options.wrapperComponent, {
+interface IRoots {
+  cmpRef: ComponentRef<unknown>;
+  rootRef: ComponentRef<unknown> | undefined;
+}
+
+function createRoots(
+  injector: EnvironmentInjector,
+  surface: SymbioteSurface,
+  rootComponent: Type<unknown>,
+  options: IMountOptions | undefined,
+): IRoots {
+  const { wrapperComponent, initialProps } = options ?? {};
+  // `hostElement` is the surface, content commits straight into it with no wrapper view
+  if (wrapperComponent === undefined) {
+    const cmpRef = createComponent<unknown>(rootComponent, {
       environmentInjector: injector,
       hostElement: asAngularHost(surface),
-      projectableNodes: [[rootHost]],
     });
+    applyInputs(cmpRef, initialProps);
+    return { cmpRef, rootRef: undefined };
   }
+  // The root gets its own host and reaches the wrapper as projected content
+  const rootHost = asAngularHost(createDetachedViewHost());
+  const rootRef = createComponent<unknown>(rootComponent, {
+    environmentInjector: injector,
+    hostElement: rootHost,
+  });
+  applyInputs(rootRef, initialProps);
+  const cmpRef = createComponent<unknown>(wrapperComponent, {
+    environmentInjector: injector,
+    hostElement: asAngularHost(surface),
+    projectableNodes: [[rootHost]],
+  });
+  return { cmpRef, rootRef };
+}
+
+export function mount(
+  rootTag: IRootTag,
+  rootComponent: Type<unknown>,
+  options?: IMountOptions,
+): SymbioteSurface {
+  settleAngularDevMode();
+  // A re-mount on a live rootTag starts clean; otherwise the stale app double-drives the surface.
+  teardown(rootTag);
+
+  const surface = createSurface(rootTag);
+  const rendererFactory = new SymbioteRendererFactory(surface);
+  const injector = createRootInjector(surface, rendererFactory);
+  const { cmpRef, rootRef } = createRoots(
+    injector,
+    surface,
+    rootComponent,
+    options,
+  );
 
-  // Attach both root views to ApplicationRef so its own tick() (via the real
-  // ChangeDetectionSchedulerImpl provided above) drives them from here on — no manual
-  // ChangeDetectorRef juggling needed. markForCheck anywhere in the tree now notifies
-  // the real scheduler, which batches a microtask and calls appRef.tick() itself.
+  // `tick()` then drives both root views through the real scheduler
   const appRef = injector.get(ApplicationRef);
   appRef.attachView(cmpRef.hostView);
   if (rootRef !== undefined) {

package/src/services/connect-watched-signal.ts

@@ -0,0 +1,15 @@
+// A signal fed by a `watch` subscription that lives as long as the injector's owner
+
+import { effect, signal, type Injector, type Signal } from '@angular/core';
+
+export function connectWatchedSignal<T>(
+  injector: Injector,
+  initial: T,
+  watch: (set: (value: T) => void) => () => void,
+): Signal<T> {
+  const value = signal(initial);
+
+  effect(onCleanup => onCleanup(watch(next => value.set(next))), { injector });
+
+  return value.asReadonly();
+}

package/src/services/create-event-value-hook.ts

@@ -0,0 +1,24 @@
+// Every `useXStatus`-style `injectX` (`injectAudioPlayerStatus`, ...) binds this to its own
+// event name + initial-value getter instead of repeating the signal/effect wiring
+
+import { effect, signal, type Signal } from '@angular/core';
+import type { IEventValueSource } from '@symbiote-native/engine';
+
+export function createEventValueHook<
+  TSource extends IEventValueSource<TValue, TEvent>,
+  TValue,
+  TEvent extends string = string,
+>(event: TEvent, getValue: (source: TSource) => TValue) {
+  return function injectValue(getSource: () => TSource): Signal<TValue> {
+    const value = signal(getValue(getSource()));
+
+    effect(onCleanup => {
+      const source = getSource();
+      value.set(getValue(source));
+      const subscription = source.addListener(event, next => value.set(next));
+      onCleanup(() => subscription.remove());
+    });
+
+    return value.asReadonly();
+  };
+}

package/src/services/create-resource-hook.ts

@@ -0,0 +1,32 @@
+// Every `useReleasingSharedObject`-style `injectX` (`injectAudioPlayer`, `injectImageManipulator`,
+// ...) binds this to its own `createXController()` factory instead of repeating the wiring
+
+import { DestroyRef, effect, inject, signal, type Signal } from '@angular/core';
+
+export type IResourceHookController<TArgs extends unknown[], TResource> = {
+  resolve: (...args: TArgs) => TResource;
+  flushDispose: () => void;
+  dispose: () => void;
+};
+
+export function createResourceHook<TArgs extends unknown[], TResource>(
+  createController: () => IResourceHookController<TArgs, TResource>,
+) {
+  return function injectResource(getArgs: () => TArgs): Signal<TResource> {
+    const controller = createController();
+    const resource = signal(controller.resolve(...getArgs()));
+
+    effect(() => {
+      resource.set(controller.resolve(...getArgs()));
+    });
+
+    effect(() => {
+      resource();
+      controller.flushDispose();
+    });
+
+    inject(DestroyRef).onDestroy(() => controller.dispose());
+
+    return resource.asReadonly();
+  };
+}

package/src/services/index.ts

@@ -1,2 +1,7 @@
 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();
+}

package/src/services/permissions-service-base.ts

@@ -0,0 +1,46 @@
+import { signal, type Signal } from '@angular/core';
+
+// Общая часть сервисов разрешений всех Expo-пакетов, наследник передаёт пару методов
+// Сбой автозапроса попадает в `error`, а не в unhandled rejection: null-статус с непустым `error`
+// значит "запрос упал", а не "ещё не было"
+export abstract class PermissionsServiceBase<TPermission, TOptions = void> {
+  private readonly status = signal<TPermission | null>(null);
+  private readonly fetchError = signal<Error | null>(null);
+  private isAutoFetchStarted = false;
+
+  readonly error: Signal<Error | null> = this.fetchError.asReadonly();
+
+  protected constructor(
+    private readonly getMethod: (options?: TOptions) => Promise<TPermission>,
+    private readonly requestMethod: (
+      options?: TOptions,
+    ) => Promise<TPermission>,
+  ) {}
+
+  // Защёлка, а не проверка `status() === null`: упавший запрос оставляет null навсегда
+  connect(): Signal<TPermission | null> {
+    if (!this.isAutoFetchStarted) {
+      this.isAutoFetchStarted = true;
+      this.get().catch((cause: unknown) => {
+        this.fetchError.set(
+          cause instanceof Error ? cause : new Error(String(cause)),
+        );
+      });
+    }
+    return this.status.asReadonly();
+  }
+
+  async get(options?: TOptions): Promise<TPermission> {
+    return this.store(await this.getMethod(options));
+  }
+
+  async request(options?: TOptions): Promise<TPermission> {
+    return this.store(await this.requestMethod(options));
+  }
+
+  private store(response: TPermission): TPermission {
+    this.status.set(response);
+    this.fetchError.set(null);
+    return response;
+  }
+}