@mmapp/react 0.1.0-alpha.18 → 0.1.0-alpha.20

package/dist/builtin-atoms-jt04b7Rw.d.ts

@@ -0,0 +1,643 @@
+import * as React$1 from 'react';
+import React__default from 'react';
+
+/**
+ * Player Runtime Types
+ *
+ * Core type system for the player IR interpreter.
+ * Covers experience nodes, data sources, resolvers, scopes, and actions.
+ *
+ * Backward compatible — original ComponentNode/ComponentTree/AtomRegistry still exported.
+ */
+interface ComponentNode {
+    type?: string;
+    component?: string;
+    props?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    id?: string;
+    className?: string;
+    children?: ComponentNode[] | string;
+    $if?: string;
+    $for?: {
+        each: string;
+        as: string;
+        key?: string;
+    };
+}
+type ComponentTree = ComponentNode | ComponentNode[];
+type AtomComponent = React.ComponentType<Record<string, unknown>>;
+type AtomRegistry = Record<string, AtomComponent>;
+interface WorkflowInstance {
+    id: string;
+    definition_id?: string;
+    definition_slug?: string;
+    current_state: string;
+    status?: string;
+    state_data: Record<string, unknown>;
+    memory?: Record<string, unknown>;
+    action_results?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+interface WorkflowDefinition {
+    id: string;
+    slug: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    category?: string;
+    fields?: FieldDefinition[];
+    states?: StateDefinition[];
+    transitions?: TransitionDefinition[];
+    roles?: RoleDefinition[];
+    experience?: ExperienceNode;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface FieldDefinition {
+    name: string;
+    field_type?: string;
+    type?: string;
+    required?: boolean;
+    default?: unknown;
+    label?: string;
+    description?: string;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    visible_when?: string;
+    editable_when?: string;
+    [key: string]: unknown;
+}
+interface StateDefinition {
+    name: string;
+    type?: string;
+    on_enter?: ActionDefinition[];
+    on_exit?: ActionDefinition[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface TransitionDefinition {
+    name: string;
+    from: string | string[];
+    to: string;
+    condition?: string;
+    required_roles?: string[];
+    required_fields?: string[];
+    actions?: ActionDefinition[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface RoleDefinition {
+    name: string;
+    description?: string;
+    assigned_when?: string;
+    permissions?: string[];
+    [key: string]: unknown;
+}
+interface ActionDefinition {
+    id?: string;
+    type?: string;
+    action_type?: string;
+    config?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface TransitionInfo {
+    name: string;
+    from: string | string[];
+    to: string;
+    condition?: string;
+    required_roles?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface DataSourceBase {
+    name: string;
+    fields?: FieldDefinition[];
+}
+interface WorkflowDataSource extends DataSourceBase {
+    type: 'workflow';
+    slug?: string;
+    query: 'latest' | 'list' | 'count';
+    instanceId?: string;
+    entity?: {
+        type: string;
+        id: string;
+    } | null;
+    paginated?: boolean;
+    pageSize?: number;
+    pageKey?: string;
+    filters?: Record<string, string | {
+        bind: string;
+    }>;
+    filter?: Record<string, string>;
+    filterKey?: string;
+    autoStart?: boolean;
+    initialData?: Record<string, unknown>;
+    includeDefinition?: boolean;
+    includeMemory?: boolean;
+    facets?: string[];
+    sort?: string;
+    search?: string;
+    searchFields?: string[];
+    range?: Record<string, {
+        min?: unknown;
+        max?: unknown;
+    }>;
+    aggregate?: string;
+    groupBy?: string;
+    parentInstanceId?: string;
+}
+interface ApiDataSource extends DataSourceBase {
+    type: 'api';
+    endpoint: string;
+    method?: 'GET' | 'POST';
+    body?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    mapping?: {
+        id?: string;
+        state?: string;
+        data?: string;
+        items?: string;
+        total?: string;
+    };
+    staleTime?: number;
+}
+interface StaticDataSource extends DataSourceBase {
+    type: 'static';
+    data: Record<string, unknown> | Record<string, unknown>[];
+}
+interface RefDataSource extends DataSourceBase {
+    type: 'ref';
+    expression: string;
+}
+type DataSource = WorkflowDataSource | ApiDataSource | StaticDataSource | RefDataSource;
+interface FacetEntry {
+    value: string | null;
+    count: number;
+}
+interface DataSourceResult {
+    instance?: InstanceData;
+    instances?: InstanceData[];
+    definition?: WorkflowDefinition;
+    pagination?: {
+        total: number;
+        page: number;
+        pageSize: number;
+    };
+    facets?: Record<string, FacetEntry[]>;
+    aggregates?: Record<string, Record<string, number>>;
+    grouped?: Array<Record<string, unknown>>;
+    loading: boolean;
+    error: Error | null;
+}
+/** Normalized instance shape used in scope */
+interface InstanceData {
+    id: string;
+    state: string;
+    fields: Record<string, unknown>;
+    slug?: string;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+interface ExperienceNode {
+    id: string;
+    displayName?: string;
+    experienceId?: string;
+    component?: string;
+    slot?: string;
+    dataSources?: DataSource[];
+    dataScope?: string;
+    children?: ExperienceNode[];
+    config?: Record<string, unknown>;
+    layout?: string;
+    className?: string;
+    style?: Record<string, unknown>;
+    overrides?: Record<string, unknown>;
+    bindings?: Record<string, string>;
+    visible_when?: string;
+    type?: string;
+    props?: Record<string, unknown>;
+    $if?: string;
+    $for?: {
+        each: string;
+        as: string;
+        key?: string;
+    };
+}
+interface QueryParams {
+    state?: string | string[];
+    status?: string;
+    filter?: Record<string, unknown>;
+    search?: string;
+    searchFields?: string[];
+    sort?: Array<{
+        field: string;
+        direction: 'asc' | 'desc';
+    }> | string;
+    limit?: number;
+    page?: number;
+    offset?: number;
+    facets?: string[];
+    aggregate?: {
+        fn: string;
+        field: string;
+        groupBy?: string;
+    };
+    includeDefinition?: boolean;
+    entity?: {
+        type: string;
+        id: string;
+    } | null;
+    parentInstanceId?: string;
+}
+interface QueryResult {
+    data: InstanceData[];
+    total: number;
+    page: number;
+    pageSize: number;
+    definition?: WorkflowDefinition;
+    facets?: Record<string, FacetEntry[]>;
+    aggregates?: Record<string, Record<string, number>>;
+    grouped?: Array<Record<string, unknown>>;
+}
+interface TransitionResult {
+    success: boolean;
+    instance?: WorkflowInstance;
+    from_state?: string;
+    to_state?: string;
+    error?: string;
+}
+interface PlayerResolver {
+    query(slug: string, params: QueryParams): Promise<QueryResult>;
+    getInstance(id: string): Promise<InstanceData>;
+    getDefinition(slug: string): Promise<WorkflowDefinition>;
+    create(slug: string, data?: Record<string, unknown>): Promise<string>;
+    update(id: string, fields: Record<string, unknown>): Promise<void>;
+    transition(id: string, name: string, data?: Record<string, unknown>): Promise<TransitionResult>;
+    remove(id: string): Promise<void>;
+    availableTransitions(id: string): Promise<TransitionInfo[]>;
+    fetch?(endpoint: string, config: {
+        method?: string;
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<unknown>;
+    subscribe?(channel: string, callback: (event: unknown) => void): () => void;
+}
+interface PlayerAuth {
+    userId?: string;
+    roles?: string[];
+    token?: string | (() => string | null);
+}
+interface PlayerRouter {
+    push(path: string): void;
+    replace?(path: string): void;
+    back?(): void;
+    pathname?: string;
+}
+interface ScopeData {
+    $instance?: InstanceData;
+    $instances?: InstanceData[];
+    $definition?: WorkflowDefinition;
+    $pagination?: {
+        total: number;
+        page: number;
+        pageSize: number;
+    };
+    $entity?: {
+        type: string;
+        id: string;
+    };
+    $local: Record<string, unknown>;
+    $user: {
+        id?: string;
+        roles: string[];
+    };
+    $fn: Record<string, (...args: unknown[]) => unknown>;
+    $action: ActionScope;
+    $item?: unknown;
+    $index?: number;
+    state_data?: Record<string, unknown>;
+    memory?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface ActionScope {
+    transition(name: string, instanceId?: string, data?: Record<string, unknown>): Promise<void>;
+    create(slug: string, data?: Record<string, unknown>): Promise<string>;
+    update(instanceId: string, fields: Record<string, unknown>): Promise<void>;
+    remove(instanceId: string): Promise<void>;
+    setLocal(key: string, value: unknown): void;
+    navigate(path: string): void;
+    toast(message: string, variant?: 'default' | 'success' | 'error' | 'warning'): void;
+    refreshQuery(dataSourceName?: string): void;
+    scrollTo(elementId: string): void;
+    openModal(modalId: string): void;
+    closeModal(modalId: string): void;
+    emit(event: string, payload?: unknown): void;
+    [key: string]: unknown;
+}
+interface AtomRegistryInterface {
+    register(name: string, loader: () => Promise<{
+        default: React.ComponentType<Record<string, unknown>>;
+    }>): void;
+    resolve(name: string): React.LazyExoticComponent<React.ComponentType<Record<string, unknown>>> | null;
+    has(name: string): boolean;
+    list(): string[];
+    merge(other: AtomRegistryInterface): AtomRegistryInterface;
+    /** Get as flat record for backward compat with ComponentTreeRenderer */
+    toRecord(): AtomRegistry;
+}
+type ExprClass$1 = 'literal' | 'path' | 'function' | 'action' | 'condition';
+interface BindingClass {
+    type: ExprClass$1;
+    value?: unknown;
+    root?: string;
+    rest?: string;
+    name?: string;
+    rawArgs?: string[];
+    expression?: string;
+}
+interface ExpressionEvaluator {
+    evaluate(expr: string, context: Record<string, unknown>): unknown;
+    classify(expr: string): ExprClass$1;
+}
+
+/**
+ * ExperienceRenderer — Full IR interpreter for compiled experience trees.
+ *
+ * Per-node pipeline:
+ * 1. Check visibility (visible_when expression)
+ * 2. Resolve dataSources (fetch via PlayerResolver)
+ * 3. Initialize $local state (from config.localDefaults)
+ * 4. Build scope chain ($instance, $local, $action, $user, $fn, $entity)
+ * 5. Evaluate bindings (classify + resolve each expression)
+ * 6. Merge props (config + resolved bindings)
+ * 7. Resolve atom (look up component name in registry)
+ * 8. Render with ErrorBoundary + Suspense
+ * 9. Recurse for children
+ */
+
+interface ExperienceRendererProps {
+    tree: ExperienceNode | ExperienceNode[];
+    initialScope?: Partial<ScopeData>;
+    entity?: {
+        type: string;
+        id: string;
+    };
+    fallback?: React__default.ReactNode;
+    className?: string;
+}
+declare const ExperienceRenderer: React__default.FC<ExperienceRendererProps>;
+
+/**
+ * PlayerProvider — Top-level context provider for the ExperienceRenderer.
+ *
+ * Bridges the player runtime with:
+ * - PlayerResolver (data fetching / mutations)
+ * - AtomRegistryInterface (component lookup)
+ * - Auth context ($user)
+ * - Router integration (navigate)
+ * - Toast/notification system
+ * - Event bus
+ *
+ * Also wires into the existing DI hooks (setQueryResolver, setMutationResolver)
+ * so that useQuery/useMutation work inside player-rendered components.
+ */
+
+interface PlayerContextValue {
+    resolver: PlayerResolver | null;
+    atomRegistry: AtomRegistryInterface;
+    auth?: PlayerAuth;
+    router?: PlayerRouter;
+    toast?: (message: string, variant?: 'default' | 'success' | 'error' | 'warning') => void;
+    onEvent?: (event: string, payload?: unknown) => void;
+}
+declare function usePlayerContext(): PlayerContextValue | null;
+interface PlayerProviderProps {
+    /** Backend resolver for data fetching and mutations */
+    resolver?: PlayerResolver;
+    /** Atom registry (defaults to core atoms) */
+    atomRegistry?: AtomRegistryInterface;
+    /** Auth context — populates $user in scope */
+    auth?: PlayerAuth;
+    /** Router integration for $action.navigate */
+    router?: PlayerRouter;
+    /** Toast handler for $action.toast */
+    toast?: (message: string, variant?: 'default' | 'success' | 'error' | 'warning') => void;
+    /** Event handler for $action.emit */
+    onEvent?: (event: string, payload?: unknown) => void;
+    /** Children */
+    children: React__default.ReactNode;
+}
+declare const PlayerProvider: React__default.FC<PlayerProviderProps>;
+
+/**
+ * Player Resolvers — Default backend implementations.
+ *
+ * Factory function for creating PlayerResolver instances:
+ * - createApiResolver: HTTP API backend (mm-api)
+ */
+
+interface ApiResolverConfig {
+    baseUrl: string;
+    token?: string | (() => string | null);
+    fetch?: typeof globalThis.fetch;
+    defaults?: {
+        limit?: number;
+        staleTime?: number;
+    };
+}
+declare function createApiResolver(config: ApiResolverConfig): PlayerResolver;
+
+/**
+ * Expression Engine — Three-tier evaluation strategy.
+ *
+ * Tier 1: Fast-path for literals and dot-paths (no compilation)
+ * Tier 2: WASM mm-compute evaluation (if available)
+ * Tier 3: JS Function compilation with LRU cache (fallback)
+ *
+ * Ported from packages/frontend/src/services/expression.service.ts
+ * with all frontend coupling removed.
+ */
+interface WasmModule {
+    evaluateExpressionSync(expr: string, contextJson: string): string;
+}
+declare function setWasmModule(module: WasmModule | null): void;
+type ExprClass = 'literal' | 'path' | 'function' | 'action' | 'condition';
+declare const builtinFunctions: Record<string, (...args: unknown[]) => unknown>;
+/**
+ * Evaluate an expression against a context object.
+ * Uses three-tier strategy: WASM → JS compiled → fast-path.
+ */
+declare function evaluateExpression(expr: string, context: Record<string, unknown>): unknown;
+
+/**
+ * Binding Resolver — Resolves $-prefix expression bindings to concrete values.
+ *
+ * Ported from packages/frontend/src/experiences/binding-resolver.ts
+ * with all frontend coupling removed (no @/ imports, no QueryClient, no React Router).
+ *
+ * Classification is cached per expression string (parse once, resolve fast).
+ * Literal/path bindings are fast-path (no Function compilation).
+ */
+
+interface BindingClassification {
+    type: ExprClass;
+    value?: unknown;
+    root?: string;
+    rest?: string;
+    name?: string;
+    rawArgs?: string[];
+    expression?: string;
+}
+declare function classifyBinding(expr: string): BindingClassification;
+/**
+ * Resolve a single binding expression against a scope.
+ */
+declare function resolveBinding(expr: string, scope: ScopeData): unknown;
+/**
+ * Resolve all bindings for a node, returning a props object.
+ */
+declare function resolveAllBindings(bindings: Record<string, string>, scope: ScopeData): Record<string, unknown>;
+/**
+ * Build a flat evaluation context from scoped data.
+ * Merges all scope namespaces into a single object for expression evaluation.
+ */
+declare function buildEvalContext(scope: ScopeData): Record<string, unknown>;
+interface BuildActionScopeOptions {
+    resolver: PlayerResolver;
+    instanceId?: string;
+    slug?: string;
+    setLocal: (key: string, value: unknown) => void;
+    router?: PlayerRouter;
+    toast?: (message: string, variant?: string) => void;
+    refreshQuery?: (dataSourceName?: string) => void;
+    onEvent?: (event: string, payload?: unknown) => void;
+}
+declare function buildActionScope(opts: BuildActionScopeOptions): ActionScope;
+
+declare const ScopeContext: React$1.Context<ScopeData>;
+declare function useScope(): ScopeData;
+interface BuildScopeOptions {
+    /** DataSource results keyed by name */
+    dataSources?: Record<string, DataSourceResult>;
+    /** Local state values */
+    localState?: Record<string, unknown>;
+    /** Auth context */
+    auth?: PlayerAuth;
+    /** Entity context */
+    entity?: {
+        type: string;
+        id: string;
+    };
+    /** Parent scope to inherit from */
+    parentScope?: ScopeData;
+    /** Action scope */
+    actionScope?: ActionScope;
+    /** Custom $fn additions */
+    functions?: Record<string, (...args: unknown[]) => unknown>;
+}
+declare function buildScope(opts: BuildScopeOptions): ScopeData;
+/**
+ * Merge a child scope into a parent scope.
+ * Child values override parent values.
+ */
+declare function mergeScope(parent: ScopeData, child: Partial<ScopeData>): ScopeData;
+/**
+ * Create a loop iteration scope with $item and $index.
+ * Also adds the item under the `as` variable name.
+ */
+declare function buildLoopScope(parent: ScopeData, item: unknown, index: number, as: string): ScopeData;
+
+/**
+ * Atom Registry — Lazy-loaded component resolution.
+ *
+ * Instance-based (not module-singleton) so multiple PlayerProvider
+ * instances don't conflict. Each registry maintains its own lazy cache.
+ */
+
+type ComponentLoader = () => Promise<{
+    default: React__default.ComponentType<Record<string, unknown>>;
+}>;
+declare class AtomRegistryImpl implements AtomRegistryInterface {
+    private loaders;
+    private lazyCache;
+    private eagerCache;
+    register(name: string, loader: ComponentLoader): void;
+    registerEager(name: string, component: React__default.ComponentType<Record<string, unknown>>): void;
+    resolve(name: string): React__default.LazyExoticComponent<React__default.ComponentType<Record<string, unknown>>> | null;
+    resolveSync(name: string): React__default.ComponentType<Record<string, unknown>> | null;
+    has(name: string): boolean;
+    list(): string[];
+    merge(other: AtomRegistryInterface): AtomRegistryInterface;
+    toRecord(): AtomRegistry;
+}
+declare function createCoreAtomRegistry(): AtomRegistryImpl;
+declare function mergeRegistries(...registries: AtomRegistryInterface[]): AtomRegistryInterface;
+
+/**
+ * Standalone ComponentTreeRenderer for the dev player.
+ *
+ * Renders a JSON component tree (IR experience nodes) to React elements.
+ * Uses the minimal evaluator and accepts an AtomRegistry for component resolution.
+ */
+
+interface ComponentTreeRendererProps {
+    /** The component tree to render */
+    tree: ComponentTree;
+    /** Data scopes for expression evaluation */
+    scopes: Partial<ScopeData>;
+    /** Runtime atom registry — maps type names to React components */
+    atoms?: AtomRegistry;
+    /** Event handlers */
+    onEvent?: (eventName: string, payload?: unknown) => void;
+    /** Error boundary fallback */
+    fallback?: React__default.ReactNode;
+}
+declare const ComponentTreeRenderer: React__default.FC<ComponentTreeRendererProps>;
+
+/**
+ * DevPlayer — Development shell for previewing workflow component trees.
+ *
+ * Provides:
+ * - ComponentTreeRenderer with built-in atoms
+ * - Scope inspector panel (collapsible)
+ * - Event log
+ * - HMR integration (listens to __mm_dev WebSocket for live reload)
+ * - Error boundary with dev-friendly error display
+ */
+
+interface DevPlayerProps {
+    /** The component tree to render */
+    tree: ComponentTree;
+    /** Data scopes for expression evaluation */
+    scopes?: Partial<ScopeData>;
+    /** Additional atoms (merged with built-ins; overrides win) */
+    atoms?: AtomRegistry;
+    /** Title shown in the dev chrome */
+    title?: string;
+    /** Hide the dev toolbar (render tree only) */
+    bare?: boolean;
+    /** WebSocket URL for HMR (default: auto-detect from window.location) */
+    wsUrl?: string;
+    /** Called when the tree is reloaded via HMR */
+    onReload?: () => void;
+    /** Called on every atom event */
+    onEvent?: (eventName: string, payload?: unknown) => void;
+}
+declare const DevPlayer: React__default.FC<DevPlayerProps>;
+
+/**
+ * Built-in atom components for the standalone player.
+ *
+ * These are minimal HTML-based implementations of the core layout and
+ * display atoms. Projects can override any of these via the AtomRegistry.
+ */
+
+declare const builtinAtoms: AtomRegistry;
+
+export { type StateDefinition as $, type ApiResolverConfig as A, type PlayerResolver as B, ComponentTreeRenderer as C, DevPlayer as D, ExperienceRenderer as E, type PlayerAuth as F, type PlayerRouter as G, type ScopeData as H, type InstanceData as I, type ActionScope as J, type AtomRegistryInterface as K, type ExprClass$1 as L, type BindingClass as M, setWasmModule as N, classifyBinding as O, PlayerProvider as P, type BuildScopeOptions as Q, type DataSource as R, ScopeContext as S, type DataSourceResult as T, type ApiDataSource as U, type StaticDataSource as V, type WorkflowDataSource as W, type RefDataSource as X, type WorkflowDefinition as Y, type WorkflowInstance as Z, type FieldDefinition as _, type ExperienceRendererProps as a, type TransitionDefinition as a0, type RoleDefinition as a1, type ActionDefinition as a2, type TransitionInfo as a3, type TransitionResult as a4, type QueryParams as a5, type QueryResult as a6, type ExpressionEvaluator as a7, type FacetEntry as a8, type PlayerProviderProps as b, type PlayerContextValue as c, createApiResolver as d, evaluateExpression as e, builtinFunctions as f, resolveAllBindings as g, buildActionScope as h, buildEvalContext as i, useScope as j, buildScope as k, buildLoopScope as l, mergeScope as m, AtomRegistryImpl as n, createCoreAtomRegistry as o, mergeRegistries as p, type ComponentTreeRendererProps as q, resolveBinding as r, type DevPlayerProps as s, builtinAtoms as t, usePlayerContext as u, type ComponentNode as v, type ComponentTree as w, type AtomComponent as x, type AtomRegistry as y, type ExperienceNode as z };