@almadar/ui 2.0.1 → 2.0.2

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

@@ -1,238 +0,0 @@
-/**
- * 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

@@ -1,91 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-/**
- * 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

@@ -1,160 +0,0 @@
-/**
- * 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

@@ -1,88 +0,0 @@
-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 };