@almadar/ui 5.111.0 → 5.113.0

package/dist/offline-executor-aRuNznZx.d.cts

@@ -0,0 +1,520 @@
+import React__default from 'react';
+import { FieldValue, OrbitalSchema, OrbitalPage, PatternConfig, EntityRow, UISlot } from '@almadar/core';
+
+/**
+ * NavigationContext - Schema-Driven Navigation for Orbital Runtime
+ *
+ * Provides navigation within the orbital schema without react-router dependency.
+ * Navigation works by:
+ * 1. Matching path to a page in the schema
+ * 2. Extracting route params (e.g., /inspection/:id → { id: "123" })
+ * 3. Switching active page
+ * 4. Triggering INIT with merged payload
+ *
+ * This approach works whether OrbitalRuntime is standalone or embedded in another app.
+ *
+ * Used by both:
+ * - Builder runtime (interpreted execution)
+ * - Compiled shells (generated applications)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Match a concrete path against a pattern with :param placeholders.
+ * Returns null if no match, or the extracted params if match.
+ *
+ * @example
+ * matchPath('/inspection/:id', '/inspection/123') // { id: '123' }
+ * matchPath('/users/:userId/posts/:postId', '/users/42/posts/7') // { userId: '42', postId: '7' }
+ * matchPath('/about', '/about') // {}
+ * matchPath('/about', '/contact') // null
+ */
+declare function matchPath(pattern: string, path: string): Record<string, string> | null;
+/**
+ * Extract route params from a path given its pattern.
+ * Wrapper around matchPath for explicit use.
+ */
+declare function extractRouteParams(pattern: string, path: string): Record<string, string>;
+/**
+ * Check if a path matches a pattern.
+ */
+declare function pathMatches(pattern: string, path: string): boolean;
+/**
+ * Find a page in the schema by matching its path pattern against a concrete path.
+ * Returns the page and extracted route params.
+ */
+declare function findPageByPath(schema: OrbitalSchema, path: string): {
+    page: OrbitalPage;
+    params: Record<string, string>;
+    orbitalName: string;
+} | null;
+/**
+ * Find a page by name.
+ */
+declare function findPageByName(schema: OrbitalSchema, pageName: string): {
+    page: OrbitalPage;
+    orbitalName: string;
+} | null;
+/**
+ * Get the first page in the schema (default page).
+ */
+declare function getDefaultPage(schema: OrbitalSchema): {
+    page: OrbitalPage;
+    orbitalName: string;
+} | null;
+/**
+ * Get all pages from the schema.
+ */
+declare function getAllPages(schema: OrbitalSchema): Array<{
+    page: OrbitalPage;
+    orbitalName: string;
+}>;
+interface NavigationState {
+    /** Current active page name */
+    activePage: string;
+    /** Current path (for URL sync) */
+    currentPath: string;
+    /** Payload to pass to INIT when page loads */
+    initPayload: Record<string, FieldValue>;
+    /** Navigation counter (increments on each navigation) */
+    navigationId: number;
+}
+interface NavigationContextValue {
+    /** Current navigation state */
+    state: NavigationState;
+    /** Navigate to a path with optional payload */
+    navigateTo: (path: string, payload?: Record<string, FieldValue>) => void;
+    /** Navigate to a page by name with optional payload */
+    navigateToPage: (pageName: string, payload?: Record<string, FieldValue>) => void;
+    /** The schema being navigated */
+    schema: OrbitalSchema;
+    /** Whether navigation is ready (schema loaded) */
+    isReady: boolean;
+}
+interface NavigationProviderProps {
+    /** The schema to navigate within */
+    schema: OrbitalSchema;
+    /** Initial page name (optional, defaults to first page) */
+    initialPage?: string;
+    /** Whether to update browser URL on navigation (default: true) */
+    updateUrl?: boolean;
+    /** Callback when navigation occurs */
+    onNavigate?: (pageName: string, path: string, payload: Record<string, FieldValue>) => void;
+    /** Children */
+    children: React__default.ReactNode;
+}
+/**
+ * NavigationProvider - Provides schema-driven navigation context
+ *
+ * @example
+ * ```tsx
+ * <NavigationProvider schema={mySchema}>
+ *   <OrbitalRuntimeContent />
+ * </NavigationProvider>
+ * ```
+ */
+declare function NavigationProvider({ schema, initialPage, updateUrl, onNavigate, children, }: NavigationProviderProps): React__default.ReactElement;
+/**
+ * Hook to access navigation context.
+ * Returns null if not within NavigationProvider.
+ */
+declare function useNavigation(): NavigationContextValue | null;
+/**
+ * Hook to get the navigateTo function.
+ * Returns a no-op function if not within NavigationProvider.
+ */
+declare function useNavigateTo(): (path: string, payload?: Record<string, FieldValue>) => void;
+/**
+ * Hook to get current navigation state.
+ */
+declare function useNavigationState(): NavigationState | null;
+/**
+ * Hook to get the current INIT payload (for passing to trait INIT events).
+ */
+declare function useInitPayload(): Record<string, FieldValue>;
+/**
+ * Hook to get current active page name.
+ */
+declare function useActivePage(): string | null;
+/**
+ * Hook to get navigation ID (changes on each navigation, useful for triggering effects).
+ */
+declare function useNavigationId(): number;
+
+/**
+ * Shared Renderer Types
+ *
+ * Type definitions used by both Builder and compiled shells for
+ * the dual execution model. These types define the contract between
+ * server and client for effect execution.
+ *
+ * @packageDocumentation
+ */
+
+type ClientEffect = ['render-ui', string, PatternConfig | null] | ['navigate', string, Record<string, FieldValue>?] | ['notify', string, NotifyOptions?] | ['emit', string, FieldValue?];
+/**
+ * Options for notify effect
+ */
+interface NotifyOptions {
+    type?: 'success' | 'error' | 'info' | 'warning';
+    duration?: number;
+}
+/**
+ * Resolved pattern with component information from component-mapping.json
+ */
+interface MappedPattern {
+    /** Component name (e.g., 'DataTable') */
+    component: string;
+    /** Import path for the component */
+    importPath: string;
+    /** Pattern category (e.g., 'display', 'form') */
+    category: string;
+    /** Validated and normalized props */
+    validatedProps: Record<string, FieldValue>;
+}
+/**
+ * Response from server after processing an event.
+ * This is the unified response format for both Builder and compiled shells.
+ */
+interface EventResponse {
+    /** Whether the event was processed successfully */
+    success: boolean;
+    /** New state after transition (if transition occurred) */
+    newState?: string;
+    /** Data fetched by server effects (e.g., { Task: [...] }) */
+    data?: Record<string, EntityRow[]>;
+    /** Client effects to execute (render-ui, navigate, notify, emit) */
+    clientEffects?: ClientEffect[];
+    /** Results of individual effect executions (for debugging) */
+    effectResults?: Array<{
+        effect: string;
+        success: boolean;
+        data?: FieldValue;
+        error?: string;
+    }>;
+    /** Error message if success is false */
+    error?: string;
+}
+/**
+ * Configuration for the client effect executor.
+ * Provides implementations for each effect type.
+ */
+interface ClientEffectExecutorConfig {
+    /**
+     * Render a pattern to a slot.
+     * Called for 'render-ui' effects.
+     */
+    renderToSlot: (slot: string, pattern: PatternConfig | null) => void;
+    /**
+     * Navigate to a route.
+     * Called for 'navigate' effects.
+     */
+    navigate: (path: string, params?: Record<string, FieldValue>) => void;
+    /**
+     * Show a notification.
+     * Called for 'notify' effects.
+     */
+    notify: (message: string, options?: NotifyOptions) => void;
+    /**
+     * Emit an event to the event bus.
+     * Called for 'emit' effects.
+     */
+    eventBus: {
+        emit: (event: string, payload?: FieldValue) => void;
+    };
+    /**
+     * Optional: Data from server response for render-ui.
+     * Components can use this to access fetched entity data.
+     */
+    data?: Record<string, EntityRow[]>;
+    /**
+     * Optional: Callback when all effects have been executed.
+     */
+    onComplete?: () => void;
+}
+/**
+ * Slot type classification
+ */
+type SlotType = 'inline' | 'portal';
+/**
+ * Definition of a slot including its rendering behavior
+ */
+interface SlotDefinition {
+    /** Slot name */
+    name: UISlot;
+    /** Whether to render inline or via portal */
+    type: SlotType;
+    /** For portal slots: where to render (default: document.body) */
+    portalTarget?: string;
+    /** Z-index for portal slots */
+    zIndex?: number;
+}
+/**
+ * Context for resolving entity data.
+ * Supports multiple data sources with priority.
+ */
+interface DataContext {
+    /** Server-provided data (highest priority) */
+    fetchedData?: Record<string, EntityRow[]>;
+    /** In-memory mock data (for Builder preview) */
+    entityStore?: {
+        getRecords: (entityName: string) => EntityRow[];
+    };
+    /** Query singleton for filtering */
+    querySingleton?: {
+        getFilters: (queryRef: string) => Record<string, FieldValue>;
+    };
+}
+/**
+ * Result of data resolution
+ */
+interface DataResolution {
+    /** Resolved data array */
+    data: EntityRow[];
+    /** Whether data is still loading */
+    loading: boolean;
+    /** Error if resolution failed */
+    error?: Error;
+}
+
+/**
+ * Offline Effect Executor
+ *
+ * Enables client-only mode for applications that need to work without
+ * server connectivity. Provides:
+ * - Mock data providers for simulating server responses
+ * - Local effect execution without server round-trip
+ * - Sync queue for effects that need server persistence when back online
+ *
+ * Used by both Builder preview (offline mode) and compiled shells (PWA mode).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Effect that needs to be synced to server when online
+ */
+interface PendingSyncEffect {
+    /** Unique ID for this effect */
+    id: string;
+    /** Timestamp when effect was queued */
+    timestamp: number;
+    /** Effect type (persist, call-service, etc.) */
+    type: string;
+    /** Effect payload */
+    payload: Record<string, FieldValue>;
+    /** Number of retry attempts */
+    retries: number;
+    /** Maximum retries before giving up */
+    maxRetries: number;
+}
+/**
+ * Configuration for offline executor
+ */
+interface OfflineExecutorConfig extends ClientEffectExecutorConfig {
+    /**
+     * Mock data provider for simulating fetch responses.
+     * Returns data for a given entity name.
+     */
+    mockDataProvider?: (entityName: string) => EntityRow[];
+    /**
+     * Whether to queue server effects for sync when online.
+     * Default: true
+     */
+    enableSyncQueue?: boolean;
+    /**
+     * Maximum number of effects to queue before dropping oldest.
+     * Default: 100
+     */
+    maxQueueSize?: number;
+    /**
+     * Callback when an effect is added to sync queue.
+     */
+    onEffectQueued?: (effect: PendingSyncEffect) => void;
+    /**
+     * Callback when sync queue changes.
+     */
+    onQueueChange?: (queue: PendingSyncEffect[]) => void;
+}
+/**
+ * Offline executor state
+ */
+interface OfflineExecutorState {
+    /** Whether we're in offline mode */
+    isOffline: boolean;
+    /** Pending effects waiting for sync */
+    syncQueue: PendingSyncEffect[];
+    /** Number of effects processed locally */
+    localEffectsProcessed: number;
+    /** Number of effects synced to server */
+    effectsSynced: number;
+    /** Last sync attempt timestamp */
+    lastSyncAttempt?: number;
+    /** Last successful sync timestamp */
+    lastSuccessfulSync?: number;
+}
+/**
+ * OfflineExecutor - Handles effects in offline/client-only mode.
+ *
+ * Features:
+ * - Executes client effects immediately (render-ui, navigate, notify, emit)
+ * - Queues server effects (persist, fetch, call-service) for later sync
+ * - Provides mock data for fetch effects when offline
+ * - Syncs queued effects when connection is restored
+ *
+ * @example
+ * ```typescript
+ * const executor = new OfflineExecutor({
+ *   renderToSlot: (slot, pattern) => slotManager.render(slot, pattern),
+ *   navigate: (path) => router.push(path),
+ *   notify: (message, opts) => toast.show(message, opts),
+ *   eventBus: { emit: (event, payload) => bus.emit(event, payload) },
+ *   mockDataProvider: (entityName) => mockStore.getAll(entityName),
+ * });
+ *
+ * // Process effects locally
+ * const response = executor.processEventOffline('LOAD', { id: '123' });
+ *
+ * // When back online
+ * await executor.syncPendingEffects(serverUrl);
+ * ```
+ */
+declare class OfflineExecutor {
+    private config;
+    private state;
+    private storage;
+    constructor(config: OfflineExecutorConfig);
+    /**
+     * Check if we're online (browser API)
+     */
+    private checkOnline;
+    /**
+     * Handle going online
+     */
+    private handleOnline;
+    /**
+     * Handle going offline
+     */
+    private handleOffline;
+    /**
+     * Load sync queue from localStorage
+     */
+    private loadSyncQueue;
+    /**
+     * Save sync queue to localStorage
+     */
+    private saveSyncQueue;
+    /**
+     * Add an effect to the sync queue
+     */
+    private queueForSync;
+    /**
+     * Execute client effects immediately.
+     */
+    executeClientEffects(effects: ClientEffect[]): void;
+    /**
+     * Process an event in offline mode.
+     *
+     * Returns a simulated EventResponse with mock data.
+     * Client effects are executed immediately.
+     * Server effects are queued for sync.
+     */
+    processEventOffline(event: string, payload?: Record<string, FieldValue>, effects?: Array<FieldValue[]>): EventResponse;
+    /**
+     * Sync pending effects to server.
+     *
+     * @param serverUrl - Base URL for the orbital server
+     * @param authToken - Optional auth token for requests
+     * @returns Number of successfully synced effects
+     */
+    syncPendingEffects(serverUrl: string, authToken?: string): Promise<number>;
+    /**
+     * Get current executor state
+     */
+    getState(): OfflineExecutorState;
+    /**
+     * Get number of pending effects
+     */
+    getPendingCount(): number;
+    /**
+     * Clear the sync queue
+     */
+    clearQueue(): void;
+    /**
+     * Dispose the executor and clean up listeners
+     */
+    dispose(): void;
+}
+/**
+ * Create an offline executor with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * const executor = createOfflineExecutor({
+ *   renderToSlot: slotManager.render,
+ *   navigate: router.push,
+ *   notify: toast.show,
+ *   eventBus: { emit: bus.emit },
+ *   mockDataProvider: (entity) => store.getAll(entity),
+ * });
+ * ```
+ */
+declare function createOfflineExecutor(config: OfflineExecutorConfig): OfflineExecutor;
+/**
+ * Options for useOfflineExecutor hook
+ */
+interface UseOfflineExecutorOptions extends OfflineExecutorConfig {
+    /** Server URL for syncing */
+    serverUrl?: string;
+    /** Auth token for server requests */
+    authToken?: string;
+    /** Auto-sync when coming back online */
+    autoSync?: boolean;
+}
+/**
+ * Result of useOfflineExecutor hook
+ */
+interface UseOfflineExecutorResult {
+    /** Current executor state */
+    state: OfflineExecutorState;
+    /** Whether we're offline */
+    isOffline: boolean;
+    /** Number of pending effects */
+    pendingCount: number;
+    /** Execute client effects */
+    executeClientEffects: (effects: ClientEffect[]) => void;
+    /** Process event offline */
+    processEventOffline: (event: string, payload?: Record<string, FieldValue>, effects?: Array<FieldValue[]>) => EventResponse;
+    /** Manually trigger sync */
+    sync: () => Promise<number>;
+    /** Clear the queue */
+    clearQueue: () => void;
+}
+/**
+ * React hook for offline effect execution.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { isOffline, pendingCount, processEventOffline, sync } = useOfflineExecutor({
+ *     renderToSlot: slotManager.render,
+ *     navigate: router.push,
+ *     notify: toast.show,
+ *     eventBus: { emit: bus.emit },
+ *     serverUrl: '/api/orbitals',
+ *     autoSync: true,
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {isOffline && <Banner>Offline - {pendingCount} changes pending</Banner>}
+ *       <button onClick={() => processEventOffline('SAVE', data)}>Save</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useOfflineExecutor(options: UseOfflineExecutorOptions): UseOfflineExecutorResult;
+
+export { type ClientEffect as C, type DataContext as D, type EventResponse as E, type MappedPattern as M, type NavigationContextValue as N, OfflineExecutor as O, type PendingSyncEffect as P, type SlotDefinition as S, type UseOfflineExecutorResult as U, type UseOfflineExecutorOptions as a, NavigationProvider as b, type NavigationProviderProps as c, type NavigationState as d, extractRouteParams as e, findPageByName as f, findPageByPath as g, getAllPages as h, getDefaultPage as i, useInitPayload as j, useNavigateTo as k, useNavigation as l, matchPath as m, useNavigationId as n, useNavigationState as o, pathMatches as p, type ClientEffectExecutorConfig as q, type NotifyOptions as r, type DataResolution as s, type OfflineExecutorConfig as t, useActivePage as u, type OfflineExecutorState as v, type SlotType as w, createOfflineExecutor as x, useOfflineExecutor as y };