@symbiote-native/angular 3.1.3 → 3.2.0

package/src/components/virtualized-section-list/section-list-template.ts

@@ -0,0 +1,108 @@
+// One synthesized `vListItem` template switches on the flattened entry kind and stamps the matching
+// app template, since the inner list renders every cell through a single one
+
+import { LIST_ACCESSIBILITY_FORWARD } from '../virtualized-list/list-a11y-forward';
+
+export const VIRTUALIZED_SECTION_LIST_TEMPLATE = `
+  <VirtualizedList
+    [data]="flatEntries"
+    [getItem]="getEntry"
+    [getItemCount]="getEntryCount"
+    [keyExtractor]="entryKeyExtractor"
+    [getItemLayout]="entryItemLayout"
+    [stickyHeaderIndices]="stickyHeaderIndices"
+    [extraData]="extraData"
+    [inverted]="inverted"
+    [refreshing]="refreshing"
+    [progressViewOffset]="progressViewOffset"
+    [refreshRequested]="refreshRequested ?? refresh.observed"
+    (refresh)="resolvedOnRefresh?.()"
+    (endReached)="resolvedOnEndReached?.($event)"
+    [onEndReachedThreshold]="onEndReachedThreshold"
+    (startReached)="resolvedOnStartReached?.($event)"
+    [onStartReachedThreshold]="onStartReachedThreshold"
+    [initialNumToRender]="initialNumToRender"
+    [initialScrollIndex]="initialScrollIndex"
+    [maxToRenderPerBatch]="maxToRenderPerBatch"
+    [updateCellsBatchingPeriod]="updateCellsBatchingPeriod"
+    [windowSize]="windowSize"
+    [maintainVisibleContentPosition]="maintainVisibleContentPosition"
+    [onScroll]="onScroll"
+    [onScrollBeginDrag]="onScrollBeginDrag"
+    [onScrollEndDrag]="onScrollEndDrag"
+    [onMomentumScrollBegin]="onMomentumScrollBegin"
+    [onMomentumScrollEnd]="onMomentumScrollEnd"
+    [scrollEventThrottle]="scrollEventThrottle"
+    [keyboardShouldPersistTaps]="keyboardShouldPersistTaps"
+    [keyboardDismissMode]="keyboardDismissMode"
+    [removeClippedSubviews]="removeClippedSubviews"
+    [nestedScrollEnabled]="nestedScrollEnabled"
+    [style]="resolvedStyle"
+    [contentContainerStyle]="contentContainerStyle"
+    [testID]="testID"
+    [nativeID]="nativeID"
+    ${LIST_ACCESSIBILITY_FORWARD}
+  >
+    <!-- The single synthesized cell template: dispatch per flattened entry tag -->
+    <ng-template vListItem let-entry let-separators="separators">
+      @switch (entryKind(entry)) {
+        @case ('header') {
+          <ng-container
+            [vListOutlet]="sectionHeaderDir?.templateRef"
+            [vListOutletContext]="sectionContextOf(entry)"
+          ></ng-container>
+        }
+        @case ('footer') {
+          <ng-container
+            [vListOutlet]="sectionFooterDir?.templateRef"
+            [vListOutletContext]="sectionContextOf(entry)"
+          ></ng-container>
+        }
+        @case ('section-separator') {
+          <ng-container
+            [vListOutlet]="sectionSeparatorDir?.templateRef"
+          ></ng-container>
+        }
+        @case ('item') {
+          <ng-container
+            [vListOutlet]="sectionItemDir?.templateRef"
+            [vListOutletContext]="itemContextOf(entry, separators)"
+          ></ng-container>
+        }
+      }
+    </ng-template>
+
+    <!-- List-level slots: forward the app's directives to the inner list -->
+    @if (listHeaderDir !== undefined) {
+      <ng-template vListHeader>
+        <ng-container [vListOutlet]="listHeaderDir.templateRef"></ng-container>
+      </ng-template>
+    }
+    @if (listFooterDir !== undefined) {
+      <ng-template vListFooter>
+        <ng-container [vListOutlet]="listFooterDir.templateRef"></ng-container>
+      </ng-template>
+    }
+    @if (listEmptyDir !== undefined) {
+      <ng-template vListEmpty>
+        <ng-container [vListOutlet]="listEmptyDir.templateRef"></ng-container>
+      </ng-template>
+    }
+    <!-- Item separator: unwrap each flattened entry back to its item -->
+    @if (itemSeparatorDir !== undefined) {
+      <ng-template
+        vListSeparator
+        let-highlighted
+        let-leadingItem="leadingItem"
+        let-trailingItem="trailingItem"
+      >
+        <ng-container
+          [vListOutlet]="itemSeparatorDir.templateRef"
+          [vListOutletContext]="
+            itemSeparatorContextOf(highlighted, leadingItem, trailingItem)
+          "
+        ></ng-container>
+      </ng-template>
+    }
+  </VirtualizedList>
+`;

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/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 {
@@ -224,7 +225,17 @@ export type {
   ITaskCanceller,
   ITaskCancelProvider,
 } from './modules/app-registry';
-export { ColorSchemeService, WindowDimensionsService } from './services';
+export {
+  ColorSchemeService,
+  WindowDimensionsService,
+  createResourceHook,
+  createEventValueHook,
+  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,51 @@
+import { Directive, ElementRef, inject, Input } from '@angular/core';
+import { resolveAccessibilityProps } from '@symbiote-native/components';
+import type { IDescriptor } from '@symbiote-native/components';
+import type {
+  IStyleProp,
+  ISymbioteEvent,
+  IViewStyle,
+} from '@symbiote-native/engine';
+import { AccessibilityInputsBase } from './accessibility-inputs';
+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 {
+  @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);
+
+  // 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,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 { connectWatchedSignal } from './connect-watched-signal';
+export { PermissionsServiceBase } from './permissions-service-base';

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;
+  }
+}