@endge/nova 0.13.6 → 0.13.14

package/dist/model/runtime/scene/nova-scene-components.d.ts

@@ -0,0 +1,87 @@
+import { EventList } from '@endge/utils';
+import { NovaComponentDescriptor } from '../../../domain/types/component.types';
+import { NovaApp } from '../app/NovaApp';
+import { NovaSchemaRegistry } from '../components/NovaSchemaRegistry';
+import { NovaTemplateChildSchema } from '../template/NovaTemplateRuntime';
+import { NovaSurface } from '../tree/NovaSurface';
+import { NovaComponentNode } from '../components/NovaComponentNode';
+export declare const NOVA_SCENES_SCHEMA_TYPE = "nova.scenes";
+export declare const NOVA_SCENE_SCHEMA_TYPE = "nova.scene";
+export type NovaScenesStrategy = 'keep-alive';
+export interface NovaScenesProps {
+    active?: string | number | null;
+    strategy?: NovaScenesStrategy;
+}
+export interface NovaScenesResolvedProps {
+    active: string | number | null;
+    strategy: NovaScenesStrategy;
+}
+export interface NovaSceneDefinitionProps {
+    id?: string | number;
+}
+export interface NovaScenesApi {
+    setChildren: (children: Array<NovaTemplateChildSchema>) => void;
+    getActiveSceneId: () => string | null;
+    getCachedSceneIds: () => Array<string>;
+}
+type NovaScenesDescriptor = NovaComponentDescriptor<NovaScenesResolvedProps, NovaScenesApi, Record<string, never>, NovaScenesProps>;
+type NovaSceneDefinitionDescriptor = NovaComponentDescriptor<NovaSceneDefinitionProps, unknown, Record<string, never>, NovaSceneDefinitionProps>;
+/** Runtime-компонент, который управляет cached NovaScene из DSL-разметки. */
+export declare class NovaScenesNode<E extends EventList = Record<string, any>> extends NovaComponentNode<NovaScenesResolvedProps, NovaScenesApi, Record<string, never>, NovaScenesProps, E> {
+    private readonly _api;
+    private readonly _definitions;
+    private readonly _scenes;
+    private _activeSceneId;
+    private _ready;
+    /**
+     * Создает manager независимых NovaScene внутри текущего template subtree.
+     */
+    constructor(app: NovaApp<E>, surface: NovaSurface<E>, props?: NovaScenesProps, options?: {
+        componentId?: string;
+        children?: Array<NovaTemplateChildSchema>;
+    }, descriptor?: NovaScenesDescriptor);
+    /** Возвращает public API компонента. */
+    getApi(): NovaScenesApi;
+    /** Обновляет props и синхронизирует активную сцену. */
+    setProps(patch: NovaScenesProps): this;
+    /** Принимает декларации Scene и обновляет cached runtime-сцены. */
+    setChildren(children: Array<NovaTemplateChildSchema>): void;
+    /** Синхронизирует active Scene после mount самой manager-ноды. */
+    protected onMount(): void;
+    /** Освобождает cached scenes вместе с manager node. */
+    dispose(): void;
+    /**
+     * Синхронизирует состояние между слоями NovaScenesNode.
+     */
+    private _syncActiveSceneIfReady;
+    /**
+     * Синхронизирует состояние между слоями NovaScenesNode.
+     */
+    private _syncActiveScene;
+    /**
+     * Выполняет внутренний шаг ensureActiveSceneMounted для NovaScenesNode.
+     */
+    private _ensureActiveSceneMounted;
+    /**
+     * Нормализует и возвращает итоговое значение NovaScenesNode.
+     */
+    private _resolveScene;
+}
+export declare const NOVA_SCENES_DESCRIPTOR: NovaScenesDescriptor;
+export declare class NovaSceneDefinitionNode<E extends EventList = Record<string, any>> extends NovaComponentNode<NovaSceneDefinitionProps, unknown, Record<string, never>, NovaSceneDefinitionProps, E> {
+    /**
+     * Создает declaration node без render-поведения.
+     */
+    constructor(app: NovaApp<E>, surface: NovaSurface<E>, props?: NovaSceneDefinitionProps, options?: {
+        componentId?: string;
+    }, descriptor?: NovaSceneDefinitionDescriptor);
+}
+export declare const NOVA_SCENE_DESCRIPTOR: NovaSceneDefinitionDescriptor;
+/** Группировка core DSL schema types для compiler output и публичных интеграций. */
+export declare const NovaCoreDSL: {
+    readonly Scenes: "nova.scenes";
+    readonly Scene: "nova.scene";
+};
+/** Регистрирует core DSL-компоненты сцен. */
+export declare function registerNovaSceneComponents(registry: NovaSchemaRegistry): void;
+export {};

package/dist/model/runtime/state/NovaStore.d.ts

@@ -0,0 +1,27 @@
+import { ClassConstructor } from 'class-transformer';
+/**
+ * Хранит shared runtime-state, который используется сценами и surfaces.
+ */
+export declare class NovaStore {
+    private _dataMap;
+    /**
+     * Выполняет внутреннюю операцию set.
+     */
+    set<T>(key: string, data: T): void;
+    /**
+     * Выполняет внутреннюю операцию get.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Возвращает by type.
+     */
+    getByType<T>(type: ClassConstructor<T>): Array<T>;
+    /**
+     * Выполняет внутреннюю операцию remove.
+     */
+    remove(key: string): void;
+    /**
+     * Выполняет внутреннюю операцию update.
+     */
+    update<T>(key: string, newData: T): void;
+}

package/dist/model/runtime/state/nova-store-decorators.d.ts

@@ -0,0 +1,40 @@
+import { NovaPhaseName } from '../../../domain/constants/nova-phase';
+export type NovaStorePhase = 'update' | 'matrix' | 'render';
+export type NovaStorePhaseInput = NovaStorePhase | Array<NovaStorePhase>;
+export interface NovaReactiveOptions<TStore extends object = object> {
+    path?: string | ((store: TStore) => string);
+    phase?: NovaStorePhaseInput;
+}
+export interface NovaStoreOptions {
+    scope?: string;
+}
+export interface NovaReactiveFieldMetadata {
+    key: string | symbol;
+    options: NovaReactiveOptions;
+}
+export interface NovaStoreMetadata {
+    reactiveFields: Array<NovaReactiveFieldMetadata>;
+}
+type NovaStoreConstructor = abstract new (...args: Array<any>) => object;
+/**
+ * Помечает class как business store, поля которого могут быть привязаны к Raph data graph.
+ */
+export declare function Store(options?: NovaStoreOptions): <T extends new (...args: Array<any>) => object>(target: T) => T;
+/**
+ * Помечает поле store как reactive data path.
+ */
+export declare function Reactive<TStore extends object = object>(options?: NovaReactiveOptions<TStore>): (...args: Array<any>) => any;
+/**
+ * Возвращает store metadata конструктора.
+ */
+export declare function readNovaStoreMetadata(target: NovaStoreConstructor): NovaStoreMetadata | undefined;
+/**
+ * Проверяет, что объект помечен как Nova store или содержит reactive fields.
+ */
+export declare function isNovaStoreObject(value: unknown): value is object;
+/**
+ * Возвращает store options конструктора.
+ */
+export declare function readNovaStoreOptions(target: NovaStoreConstructor): NovaStoreOptions;
+export declare function normalizeNovaStorePhases(input?: NovaStorePhaseInput, fallback?: NovaPhaseName | string): Array<NovaStorePhase>;
+export {};

package/dist/model/runtime/state/nova-store-runtime.d.ts

@@ -0,0 +1,23 @@
+import { NovaApp } from '../app/NovaApp';
+export interface NovaCreateStoreOptions {
+    app?: NovaApp<any>;
+    scope?: string;
+}
+export interface NovaStoreRuntime {
+    app?: NovaApp<any>;
+    scope: string;
+    path: string;
+    root: object;
+}
+/**
+ * Создает reactive business store и подключает его к Raph data graph.
+ */
+export declare function createNovaStore<T extends object>(instance: T, options?: NovaCreateStoreOptions): T;
+/**
+ * Выполняет несколько store mutations в одной Raph transaction.
+ */
+export declare function batchNovaStore<T>(store: object, callback: () => T): T;
+/**
+ * Возвращает runtime metadata store instance.
+ */
+export declare function findNovaStoreRuntime(store: object): NovaStoreRuntime | undefined;

package/dist/model/runtime/state/nova-store-tracking.d.ts

@@ -0,0 +1,17 @@
+import { DataPathDef } from '@endge/raph';
+import { NovaStorePhaseInput } from './nova-store-decorators';
+import { NovaNode } from '../tree/NovaNode';
+export type NovaStoreTrackingPhase = 'update' | 'matrix' | 'render';
+export type NovaStoreReadMap = Map<NovaStoreTrackingPhase, Set<string>>;
+/**
+ * Начинает сбор reactive store reads для lifecycle phase.
+ */
+export declare function beginNovaStoreTracking(node: NovaNode<any>, defaultPhase: NovaStoreTrackingPhase): void;
+/**
+ * Завершает сбор reads и синхронизирует Raph data observers ноды.
+ */
+export declare function endNovaStoreTracking(): void;
+/**
+ * Регистрирует чтение store data path в текущем tracking context.
+ */
+export declare function trackNovaStoreRead(path: DataPathDef, phaseInput?: NovaStorePhaseInput): void;

package/dist/model/runtime/sync/NovaSyncScope.d.ts

@@ -0,0 +1,93 @@
+import { NovaSyncEndpointInput, NovaSyncLink, NovaSyncLinkConfig, NovaSyncPort, NovaSyncPortMap, NovaSyncSchedule, NovaSyncScopeOptions, NovaSyncTransaction } from './nova-sync.types';
+import { NovaNode } from '../tree/NovaNode';
+/**
+ * Описывает ответственность NovaSyncScope в архитектуре проекта.
+ */
+export declare class NovaSyncScope {
+    readonly id: string;
+    readonly scheduler: NovaSyncSchedule;
+    private readonly _ports;
+    private readonly _nodeEndpoints;
+    private readonly _links;
+    private readonly _microtaskQueue;
+    private readonly _frameQueue;
+    private _microtaskScheduled;
+    private _frameScheduled;
+    private _applyDepth;
+    /**
+     * Создает экземпляр NovaSyncScope и подготавливает базовое состояние.
+     */
+    constructor(options?: NovaSyncScopeOptions);
+    /**
+     * Регистрирует сущность в runtime-слое NovaSyncScope.
+     */
+    registerNode(node: NovaNode<any>, ports: NovaSyncPortMap): () => void;
+    /**
+     * Удаляет регистрацию сущности из runtime-слоя NovaSyncScope.
+     */
+    unregisterNode(node: NovaNode<any>): void;
+    /**
+     * Выполняет действие link в рамках ответственности NovaSyncScope.
+     */
+    link(config: NovaSyncLinkConfig): NovaSyncLink;
+    /**
+     * Выполняет действие unlink в рамках ответственности NovaSyncScope.
+     */
+    unlink(id: string): void;
+    /**
+     * Нормализует и возвращает итоговое значение NovaSyncScope.
+     */
+    resolvePort<T = unknown>(endpoint: NovaSyncEndpointInput): NovaSyncPort<T>;
+    /**
+     * Выполняет действие notify в рамках ответственности NovaSyncScope.
+     */
+    notify(endpoint: NovaSyncEndpointInput, value?: unknown, transaction?: NovaSyncTransaction): void;
+    /**
+     * Выполняет действие notifyPortChanged в рамках ответственности NovaSyncScope.
+     */
+    notifyPortChanged(node: NovaNode<any>, name: string, value?: unknown): void;
+    /**
+     * Освобождает runtime-ресурсы и подписки NovaSyncScope.
+     */
+    dispose(): void;
+    /**
+     * Выполняет внутренний шаг propagate для NovaSyncScope.
+     */
+    private _propagate;
+    /**
+     * Добавляет действие в очередь выполнения NovaSyncScope.
+     */
+    private _queueLinkedWrite;
+    /**
+     * Применяет подготовленное состояние NovaSyncScope.
+     */
+    private _applyQueuedWrite;
+    /**
+     * Планирует отложенное выполнение NovaSyncScope.
+     */
+    private _scheduleMicrotaskFlush;
+    /**
+     * Планирует отложенное выполнение NovaSyncScope.
+     */
+    private _scheduleFrameFlush;
+    /**
+     * Принудительно завершает накопленные изменения NovaSyncScope.
+     */
+    private _flushQueue;
+    /**
+     * Создает runtime-сущность NovaSyncScope.
+     */
+    private _createTransaction;
+    /**
+     * Выполняет внутренний шаг requirePort для NovaSyncScope.
+     */
+    private _requirePort;
+    /**
+     * Нормализует и возвращает итоговое значение NovaSyncScope.
+     */
+    private _resolveEndpoint;
+    /**
+     * Выполняет внутренний шаг endpointFor для NovaSyncScope.
+     */
+    private _endpointFor;
+}

package/dist/model/runtime/sync/nova-sync-context.d.ts

@@ -0,0 +1,2 @@
+import { NovaSyncScope } from './NovaSyncScope';
+export declare const NovaSyncScopeToken: import('../../..').NovaContextToken<NovaSyncScope>;

package/dist/model/runtime/sync/nova-sync-ports.d.ts

@@ -0,0 +1,5 @@
+import { EventList } from '@endge/utils';
+import { NovaComponentNode } from '../components/NovaComponentNode';
+import { NovaSyncPort, NovaSyncPortMap } from './nova-sync.types';
+export declare function createNovaSyncPort<T>(input: Omit<NovaSyncPort<T>, 'id' | 'owner'>): NovaSyncPort<T>;
+export declare function createNovaComponentPropSyncPorts<TProps extends Record<string, any>, E extends EventList>(node: NovaComponentNode<TProps, unknown, Record<string, unknown>, TProps, E>): NovaSyncPortMap;

package/dist/model/runtime/sync/nova-sync.types.d.ts

@@ -0,0 +1,48 @@
+import { NovaNode } from '../tree/NovaNode';
+export type NovaSyncSchedule = 'immediate' | 'microtask' | 'frame';
+export type NovaSyncPortMap = Record<string, NovaSyncPort<any>>;
+export type NovaSyncEndpointInput = string | NovaSyncPort<any>;
+export interface NovaSyncTransaction {
+    id: number;
+    origin: string;
+    path: Set<string>;
+}
+export interface NovaSyncPort<T = unknown> {
+    id?: string;
+    owner?: NovaNode<any>;
+    type?: string;
+    writable?: boolean;
+    schedule?: NovaSyncSchedule;
+    meta?: Record<string, unknown>;
+    read: () => T;
+    write: (value: T, transaction: NovaSyncTransaction) => void;
+    equals?: (left: T, right: T) => boolean;
+}
+export interface NovaSyncLinkConfig<TFrom = unknown, TTo = TFrom> {
+    id?: string;
+    from: NovaSyncEndpointInput;
+    to: NovaSyncEndpointInput;
+    schedule?: NovaSyncSchedule;
+    bidirectional?: boolean;
+    transform?: (value: TFrom, transaction: NovaSyncTransaction) => TTo;
+    filter?: (value: TFrom, transaction: NovaSyncTransaction) => boolean;
+    equals?: (left: TTo, right: TTo) => boolean;
+}
+export interface NovaSyncLink {
+    id: string;
+    from: string;
+    to: string;
+    schedule: NovaSyncSchedule;
+    bidirectional: boolean;
+    dispose: () => void;
+}
+export interface NovaSyncRegisteredPort {
+    endpoint: string;
+    name: string;
+    node: NovaNode<any>;
+    port: NovaSyncPort<any>;
+}
+export interface NovaSyncScopeOptions {
+    id?: string;
+    scheduler?: NovaSyncSchedule;
+}

package/dist/model/runtime/template/NovaTemplateRuntime.d.ts

@@ -0,0 +1,79 @@
+import { EventList } from '@endge/utils';
+import { NovaElementSchema, NovaElementSlotFactory, NovaElementSlots, NovaElementType } from '../../../domain/types/component.types';
+import { NovaNodeEventHandlers } from '../../../domain/types/events.types';
+import { NovaApp } from '../app/NovaApp';
+import { NovaScope } from '../refs/nova-ref';
+import { NovaNode } from '../tree/NovaNode';
+import { NovaSurface } from '../tree/NovaSurface';
+/** Constructor скомпилированного `.nova` компонента. */
+export type NovaCompiledNodeConstructor<E extends EventList = Record<string, any>> = new (app: NovaApp<E>, surface: NovaSurface<E>, props?: Record<string, any>, listeners?: Record<string, (...args: Array<any>) => void>, slots?: NovaTemplateSlots) => NovaNode<E>;
+/** Тип компонента в compiled template schema. */
+export type NovaTemplateComponentType<E extends EventList = Record<string, any>> = NovaElementType<E>;
+/** Фабрика compiled slot, которая возвращает schema snapshot по публичному scope. */
+export type NovaTemplateSlotFactory<TScope = Record<string, any>> = NovaElementSlotFactory<TScope>;
+/** Набор named slots в compiled template schema. */
+export type NovaTemplateSlots = NovaElementSlots;
+export interface NovaTemplateChildSchema<TProps = Record<string, any>> extends Omit<NovaElementSchema<TProps>, 'type'> {
+    type: NovaTemplateComponentType;
+    key?: string | number;
+    ref?: string;
+    refKey?: string | number;
+    context?: unknown;
+    children?: Array<NovaTemplateChildSchema>;
+    events?: Partial<NovaNodeEventHandlers>;
+    slots?: NovaTemplateSlots;
+}
+export interface NovaTemplateReconcileResult<E extends EventList = Record<string, any>> {
+    nodes: Array<NovaNode<E>>;
+    created: number;
+    reused: number;
+    removed: number;
+    patched: number;
+}
+export type NovaTemplateParentRenderDirtyMode = 'always' | 'structural' | 'never';
+export interface NovaTemplateRuntimeOptions {
+    parentRenderDirty?: NovaTemplateParentRenderDirtyMode;
+}
+/**
+ * Runtime для сгенерированных Nova SFC, который сохраняет identity keyed children.
+ */
+export declare class NovaTemplateRuntime<E extends EventList = Record<string, any>> {
+    private readonly _parent;
+    private _scope;
+    private readonly _options;
+    private _managedChildren;
+    private _stats;
+    private _reconciling;
+    /**
+     * Создает runtime для конкретного generated root node.
+     */
+    constructor(_parent: NovaNode<E>, _scope?: NovaScope, _options?: NovaTemplateRuntimeOptions);
+    /**
+     * Обновляет scope refs для следующих reconcile-проходов.
+     */
+    setScope(scope: NovaScope): void;
+    /**
+     * Применяет новый template snapshot к managed children.
+     */
+    reconcile(children: Array<NovaTemplateChildSchema>): NovaTemplateReconcileResult<E>;
+    /**
+     * Возвращает последние counters reconcile-прохода.
+     */
+    getStats(): Readonly<NovaTemplateReconcileResult<E>>;
+    /**
+     * Удаляет все managed children.
+     */
+    dispose(): void;
+}
+/**
+ * Сверяет children по key/id/type и обновляет существующие component nodes без пересоздания.
+ */
+export declare function reconcileNovaTemplateChildren<E extends EventList>(parent: NovaNode<E>, previousNodes: ReadonlyArray<NovaNode<E>>, nextSchemas: ReadonlyArray<NovaTemplateChildSchema>, scope?: NovaScope, options?: NovaTemplateRuntimeOptions): NovaTemplateReconcileResult<E>;
+/**
+ * Обновляет props, события, context и вложенные children существующей node.
+ */
+export declare function patchNovaTemplateNode<E extends EventList>(node: NovaNode<E>, schema: NovaTemplateChildSchema): void;
+/**
+ * Проверяет, может ли node быть обновлена без пересоздания.
+ */
+export declare function canPatchTemplateNode(node: NovaNode<any>, schema: NovaTemplateChildSchema): boolean;

package/dist/model/runtime/tree/NovaContainer.d.ts

@@ -0,0 +1,78 @@
+import { EventList } from '@endge/utils';
+import { NovaBounds } from '../../../domain/types/renderer.types';
+import { NovaApp } from '../app/NovaApp';
+import { NovaSurface } from './NovaSurface';
+import { NovaNode } from './NovaNode';
+/**
+ * Описывает контейнерный node для группировки дочерних Nova nodes.
+ */
+export declare class NovaContainer<E extends EventList> extends NovaNode<E> {
+    /**
+     * Создает instance и подготавливает внутреннее состояние.
+     */
+    constructor(app: NovaApp<E>, surface?: NovaSurface<E>);
+    /**
+     * Добавляет дочернюю Nova-ноду в контейнер.
+     */
+    add<T extends NovaNode<E>>(node: T): T;
+    /**
+     * Добавляет набор дочерних Nova-нод и делает один render-dirty проход.
+     */
+    addMany<T extends NovaNode<E>>(nodes: Array<T>): Array<T>;
+    /**
+     * Удаляет дочернюю Nova-ноду из контейнера и уничтожает ее.
+     */
+    remove(): void;
+    /**
+     * Выполняет внутреннюю операцию remove.
+     */
+    remove(node: NovaNode<E>): boolean;
+    /**
+     * Уничтожает всех дочерних Nova-потомков контейнера.
+     */
+    clear(): void;
+    /**
+     * Быстро переключает видимость всей группы через состояние контейнера.
+     */
+    setGroupVisible(visible: boolean): this;
+    /**
+     * Выполняет внутреннюю операцию show.
+     */
+    show(): this;
+    /**
+     * Выполняет внутреннюю операцию hide.
+     */
+    hide(): this;
+    /**
+     * Быстро переключает активность всей группы через состояние контейнера.
+     */
+    setGroupActive(active: boolean): this;
+    /**
+     * Выполняет внутреннюю операцию activate.
+     */
+    activate(): this;
+    /**
+     * Выполняет внутреннюю операцию deactivate.
+     */
+    deactivate(): this;
+    /**
+     * Переключает локальную видимость всех прямых Nova-детей.
+     */
+    setChildrenVisible(visible: boolean): this;
+    /**
+     * Переключает локальную активность всех прямых Nova-детей.
+     */
+    setChildrenActive(active: boolean): this;
+    /**
+     * Возвращает child count.
+     */
+    get childCount(): number;
+    /**
+     * Возвращает local bounds.
+     */
+    getLocalBounds(): NovaBounds;
+    /**
+     * Возвращает nova children.
+     */
+    get novaChildren(): Array<NovaNode<E>>;
+}