@almadar/ui 2.0.0 → 2.0.1

package/dist/renderer/offline-executor.d.ts

@@ -0,0 +1,238 @@
+/**
+ * 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
+ */
+import type { ClientEffect, ClientEffectExecutorConfig, EventResponse } from './types';
+/**
+ * Effect that needs to be synced to server when online
+ */
+export 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: unknown;
+    /** Number of retry attempts */
+    retries: number;
+    /** Maximum retries before giving up */
+    maxRetries: number;
+}
+/**
+ * Configuration for offline executor
+ */
+export interface OfflineExecutorConfig extends ClientEffectExecutorConfig {
+    /**
+     * Mock data provider for simulating fetch responses.
+     * Returns data for a given entity name.
+     */
+    mockDataProvider?: (entityName: string) => unknown[];
+    /**
+     * 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
+ */
+export 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);
+ * ```
+ */
+export 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, unknown>, effects?: Array<unknown[]>): 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),
+ * });
+ * ```
+ */
+export declare function createOfflineExecutor(config: OfflineExecutorConfig): OfflineExecutor;
+/**
+ * Options for useOfflineExecutor hook
+ */
+export 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
+ */
+export 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, unknown>, effects?: Array<unknown[]>) => 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>
+ *   );
+ * }
+ * ```
+ */
+export declare function useOfflineExecutor(options: UseOfflineExecutorOptions): UseOfflineExecutorResult;

package/dist/renderer/pattern-resolver.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Pattern Resolver
+ *
+ * Resolves pattern configurations to component information.
+ * Uses the central pattern registry and component mapping from orbital-shared/patterns/.
+ *
+ * This is the shared logic used by both Builder's PatternRenderer and
+ * the compiled shell's UISlotRenderer.
+ *
+ * @packageDocumentation
+ */
+import type { PatternConfig, ResolvedPattern } from './types';
+/**
+ * Component mapping entry from component-mapping.json
+ */
+interface ComponentMappingEntry {
+    component: string;
+    importPath: string;
+    category: string;
+    deprecated?: boolean;
+    replacedBy?: string;
+}
+/**
+ * Pattern definition from registry.json
+ */
+interface PatternDefinition {
+    type: string;
+    category: string;
+    description: string;
+    propsSchema?: Record<string, {
+        required?: boolean;
+        types?: string[];
+        description?: string;
+    }>;
+}
+/**
+ * Initialize the pattern resolver with mappings.
+ * Called at app startup with data from JSON files.
+ */
+export declare function initializePatternResolver(config: {
+    componentMapping: Record<string, ComponentMappingEntry>;
+    patternRegistry: Record<string, PatternDefinition>;
+}): void;
+/**
+ * Set component mapping (alternative to full initialization).
+ */
+export declare function setComponentMapping(mapping: Record<string, ComponentMappingEntry>): void;
+/**
+ * Set pattern registry (alternative to full initialization).
+ */
+export declare function setPatternRegistry(registry: Record<string, PatternDefinition>): void;
+/**
+ * Resolve a pattern configuration to component information.
+ *
+ * @param config - Pattern configuration from render-ui effect
+ * @returns Resolved pattern with component name, import path, and validated props
+ * @throws Error if pattern type is unknown
+ *
+ * @example
+ * ```typescript
+ * const resolved = resolvePattern({
+ *   type: 'entity-table',
+ *   entity: 'Task',
+ *   columns: ['title', 'status']
+ * });
+ * // resolved.component === 'DataTable'
+ * // resolved.importPath === '@/components/organisms/DataTable'
+ * ```
+ */
+export declare function resolvePattern(config: PatternConfig): ResolvedPattern;
+/**
+ * Check if a pattern type is known.
+ */
+export declare function isKnownPattern(type: string): boolean;
+/**
+ * Get all known pattern types.
+ */
+export declare function getKnownPatterns(): string[];
+/**
+ * Get patterns by category.
+ */
+export declare function getPatternsByCategory(category: string): string[];
+/**
+ * Get the component mapping for a pattern type.
+ */
+export declare function getPatternMapping(type: string): ComponentMappingEntry | undefined;
+/**
+ * Get the pattern definition from the registry.
+ */
+export declare function getPatternDefinition(type: string): PatternDefinition | undefined;
+export {};

package/dist/renderer/slot-definitions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Slot Definitions
+ *
+ * Defines the available UI slots and their rendering behavior.
+ * Slots are either inline (rendered in the component tree) or
+ * portal (rendered to document.body via React Portal).
+ *
+ * @packageDocumentation
+ */
+import type { UISlot, SlotDefinition, SlotType } from './types';
+/**
+ * Definitions for all available UI slots.
+ *
+ * Inline slots render within the component hierarchy.
+ * Portal slots render to document.body, breaking out of overflow containers.
+ */
+export declare const SLOT_DEFINITIONS: Record<UISlot, SlotDefinition>;
+/**
+ * Get the slot definition for a slot name.
+ */
+export declare function getSlotDefinition(slot: UISlot): SlotDefinition;
+/**
+ * Check if a slot is a portal slot.
+ */
+export declare function isPortalSlot(slot: UISlot): boolean;
+/**
+ * Check if a slot is an inline slot.
+ */
+export declare function isInlineSlot(slot: UISlot): boolean;
+/**
+ * Get all slots of a specific type.
+ */
+export declare function getSlotsByType(type: SlotType): UISlot[];
+/**
+ * Get all inline slots.
+ */
+export declare function getInlineSlots(): UISlot[];
+/**
+ * Get all portal slots.
+ */
+export declare function getPortalSlots(): UISlot[];
+/**
+ * All valid slot names.
+ */
+export declare const ALL_SLOTS: UISlot[];

package/dist/renderer/types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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
+ */
+/**
+ * A client effect is a tuple where the first element is the effect type
+ * and the remaining elements are the arguments.
+ *
+ * @example
+ * ['render-ui', 'main', { type: 'entity-table', ... }]
+ * ['navigate', '/tasks/123']
+ * ['notify', 'Task created!', { type: 'success' }]
+ * ['emit', 'TASK_CREATED', { id: '123' }]
+ */
+export type ClientEffect = ['render-ui', string, PatternConfig | null] | ['navigate', string, Record<string, unknown>?] | ['notify', string, NotifyOptions?] | ['emit', string, unknown?];
+/**
+ * Options for notify effect
+ */
+export interface NotifyOptions {
+    type?: 'success' | 'error' | 'info' | 'warning';
+    duration?: number;
+}
+/**
+ * Configuration for a pattern to render in a slot.
+ * This is what render-ui effects carry as their payload.
+ */
+export interface PatternConfig {
+    /** Pattern type from registry (e.g., 'entity-table', 'form-section') */
+    type: string;
+    /** Entity name for data binding */
+    entity?: string;
+    /** Additional props for the pattern component */
+    [key: string]: unknown;
+}
+/**
+ * Resolved pattern with component information from component-mapping.json
+ */
+export interface ResolvedPattern {
+    /** 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, unknown>;
+}
+/**
+ * Response from server after processing an event.
+ * This is the unified response format for both Builder and compiled shells.
+ */
+export 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, unknown[]>;
+    /** 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?: unknown;
+        error?: string;
+    }>;
+    /** Error message if success is false */
+    error?: string;
+}
+/**
+ * Configuration for the client effect executor.
+ * Provides implementations for each effect type.
+ */
+export 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, unknown>) => 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?: unknown) => void;
+    };
+    /**
+     * Optional: Data from server response for render-ui.
+     * Components can use this to access fetched entity data.
+     */
+    data?: Record<string, unknown[]>;
+    /**
+     * Optional: Callback when all effects have been executed.
+     */
+    onComplete?: () => void;
+}
+/**
+ * Valid UI slot names
+ */
+export type UISlot = 'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'center' | 'toast' | 'hud-top' | 'hud-bottom' | 'floating';
+/**
+ * Slot type classification
+ */
+export type SlotType = 'inline' | 'portal';
+/**
+ * Definition of a slot including its rendering behavior
+ */
+export 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.
+ */
+export interface DataContext {
+    /** Server-provided data (highest priority) */
+    fetchedData?: Record<string, unknown[]>;
+    /** In-memory mock data (for Builder preview) */
+    entityStore?: {
+        getRecords: (entityName: string) => unknown[];
+    };
+    /** Query singleton for filtering */
+    querySingleton?: {
+        getFilters: (queryRef: string) => Record<string, unknown>;
+    };
+}
+/**
+ * Result of data resolution
+ */
+export interface DataResolution {
+    /** Resolved data array */
+    data: unknown[];
+    /** Whether data is still loading */
+    loading: boolean;
+    /** Error if resolution failed */
+    error?: Error;
+}

package/dist/renderer/useClientEffects.d.ts

@@ -0,0 +1,88 @@
+import type { ClientEffect, ClientEffectExecutorConfig } from './types';
+/**
+ * Options for the useClientEffects hook
+ */
+export interface UseClientEffectsOptions extends ClientEffectExecutorConfig {
+    /**
+     * Whether to execute effects. Defaults to true.
+     * Set to false to temporarily disable effect execution.
+     */
+    enabled?: boolean;
+    /**
+     * Debug mode - logs effect execution details.
+     */
+    debug?: boolean;
+}
+/**
+ * Result of useClientEffects hook
+ */
+export interface UseClientEffectsResult {
+    /**
+     * Number of effects executed in the last batch.
+     */
+    executedCount: number;
+    /**
+     * Whether effects are currently being executed.
+     */
+    executing: boolean;
+    /**
+     * Manually trigger effect execution.
+     * Useful for imperative control.
+     */
+    execute: (effects: ClientEffect[]) => void;
+}
+/**
+ * Execute client effects from server response.
+ *
+ * This hook automatically executes effects when they change,
+ * tracking which effects have been executed to prevent duplicates.
+ *
+ * @param effects - Array of client effects to execute (from server response)
+ * @param options - Configuration including effect implementations
+ * @returns Hook result with execution state and manual trigger
+ *
+ * @example
+ * ```typescript
+ * function useMyTrait() {
+ *   const [state, setState] = useState({ pendingEffects: [] });
+ *   const effectConfig = useClientEffectConfig();
+ *
+ *   useClientEffects(state.pendingEffects, {
+ *     ...effectConfig,
+ *     onComplete: () => setState(s => ({ ...s, pendingEffects: [] }))
+ *   });
+ *
+ *   // ...
+ * }
+ * ```
+ */
+export declare function useClientEffects(effects: ClientEffect[] | undefined, options: UseClientEffectsOptions): UseClientEffectsResult;
+declare const ClientEffectConfigContext: import("react").Context<ClientEffectExecutorConfig | null>;
+/**
+ * Provider for client effect configuration.
+ */
+export declare const ClientEffectConfigProvider: import("react").Provider<ClientEffectExecutorConfig | null>;
+/**
+ * Hook to get the client effect configuration from context.
+ *
+ * @throws Error if used outside of ClientEffectConfigProvider
+ *
+ * @example
+ * ```typescript
+ * function MyTraitHook() {
+ *   const effectConfig = useClientEffectConfig();
+ *
+ *   useClientEffects(pendingEffects, {
+ *     ...effectConfig,
+ *     onComplete: () => clearPendingEffects()
+ *   });
+ * }
+ * ```
+ */
+export declare function useClientEffectConfig(): ClientEffectExecutorConfig;
+/**
+ * Hook to get client effect configuration, returning null if not available.
+ * Use this for optional integration where effects may not be configured.
+ */
+export declare function useClientEffectConfigOptional(): ClientEffectExecutorConfig | null;
+export { ClientEffectConfigContext };