@almadar/ui 2.13.3 → 2.15.0

package/dist/providers/index.d.ts

@@ -1,465 +1,17 @@
-import React__default, { ReactNode } from 'react';
-import { b as ThemeDefinition } from '../ThemeContext-D9xUORq5.js';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { E as EventBusContextType } from '../event-bus-types-CjJduURa.js';
-import { U as UseOfflineExecutorResult, a as UseOfflineExecutorOptions } from '../offline-executor-CHr4uAhf.js';
-
 /**
- * Extended context type for backward compatibility.
- *
- * @deprecated getSelectedEntity and clearSelectedEntity are deprecated.
- * Use SelectionProvider and useSelection hook instead.
- */
-interface EventBusContextTypeExtended extends EventBusContextType {
-    /**
-     * @deprecated Use useSelection from SelectionProvider instead.
-     * This method now returns null - selection state moved to SelectionProvider.
-     */
-    getSelectedEntity: () => unknown | null;
-    /**
-     * @deprecated Use useSelection from SelectionProvider instead.
-     * This method is now a no-op - selection state moved to SelectionProvider.
-     */
-    clearSelectedEntity: () => void;
-}
-declare const EventBusContext: React__default.Context<EventBusContextTypeExtended | null>;
-interface EventBusProviderProps {
-    children: ReactNode;
-    /** Enable debug logging in development */
-    debug?: boolean;
-}
-/**
- * Provider component for the page event bus.
- *
- * This is a pure pub/sub event bus. For selection state,
- * use SelectionProvider which listens to events and maintains state.
- *
- * @example
- * ```tsx
- * function TaskDetailPage() {
- *   return (
- *     <EventBusProvider debug={process.env.NODE_ENV === 'development'}>
- *       <SelectionProvider>
- *         <TaskHeader />
- *         <TaskForm />
- *         <TaskActions />
- *       </SelectionProvider>
- *     </EventBusProvider>
- *   );
- * }
- * ```
- */
-declare function EventBusProvider({ children, debug }: EventBusProviderProps): react_jsx_runtime.JSX.Element;
-
-interface SelectionContextType<T = unknown> {
-    /** The currently selected entity */
-    selected: T | null;
-    /** Manually set the selected entity */
-    setSelected: (entity: T | null) => void;
-    /** Clear the selection */
-    clearSelection: () => void;
-    /** Check if an entity is selected */
-    isSelected: (entity: T) => boolean;
-}
-declare const SelectionContext: React__default.Context<SelectionContextType<unknown> | null>;
-interface SelectionProviderProps {
-    children: ReactNode;
-    /** Enable debug logging */
-    debug?: boolean;
-    /** Custom comparison function for isSelected */
-    compareEntities?: (a: unknown, b: unknown) => boolean;
-}
-/**
- * Provider component for selection state.
- *
- * Must be used within an EventBusProvider.
- *
- * @example
- * ```tsx
- * function OrderListPage() {
- *   return (
- *     <EventBusProvider>
- *       <SelectionProvider debug={process.env.NODE_ENV === 'development'}>
- *         <OrderTable />
- *         <OrderDetailDrawer />
- *       </SelectionProvider>
- *     </EventBusProvider>
- *   );
- * }
- * ```
- */
-declare function SelectionProvider({ children, debug, compareEntities, }: SelectionProviderProps): react_jsx_runtime.JSX.Element;
-/**
- * Hook to access selection state.
- *
- * @throws Error if used outside SelectionProvider
- *
- * @example
- * ```tsx
- * function OrderDetailDrawer() {
- *   const { selected, clearSelection } = useSelection<Order>();
- *
- *   if (!selected) return null;
- *
- *   return (
- *     <Drawer onClose={clearSelection}>
- *       <OrderDetail order={selected} />
- *     </Drawer>
- *   );
- * }
- * ```
- */
-declare function useSelection<T = unknown>(): SelectionContextType<T>;
-/**
- * Hook to access selection state with fallback for components
- * that may be used outside SelectionProvider.
- *
- * Returns null if no SelectionProvider is found.
- */
-declare function useSelectionOptional<T = unknown>(): SelectionContextType<T> | null;
-
-/**
- * FetchedDataProvider
- *
- * Provides server-fetched entity data to the client runtime.
- * This context stores data returned from compiled event handlers
- * via the `data` field in EventResponse.
- *
- * Data Flow:
- * 1. Client sends event to server
- * 2. Server executes compiled handler with fetch effects
- * 3. Server returns { data: { EntityName: [...records] }, clientEffects: [...] }
- * 4. Provider stores data in this context
- * 5. Pattern components access data via useFetchedData hook
- *
- * Used by both Builder preview and compiled shell.
- *
- * @packageDocumentation
- */
-
-interface EntityRecord {
-    id: string;
-    [key: string]: unknown;
-}
-interface FetchedDataState {
-    /** Entity data by entity name (e.g., { Task: [...], User: [...] }) */
-    data: Record<string, EntityRecord[]>;
-    /** Timestamp of last fetch per entity */
-    fetchedAt: Record<string, number>;
-    /** Whether data is currently being fetched */
-    loading: boolean;
-    /** Last error message */
-    error: string | null;
-}
-interface FetchedDataContextValue {
-    /** Get all records for an entity */
-    getData: (entityName: string) => EntityRecord[];
-    /** Get a single record by ID */
-    getById: (entityName: string, id: string) => EntityRecord | undefined;
-    /** Check if entity data exists */
-    hasData: (entityName: string) => boolean;
-    /** Get fetch timestamp for entity */
-    getFetchedAt: (entityName: string) => number | undefined;
-    /** Update data from server response */
-    setData: (data: Record<string, unknown[]>) => void;
-    /** Clear all fetched data */
-    clearData: () => void;
-    /** Clear data for specific entity */
-    clearEntity: (entityName: string) => void;
-    /** Current loading state */
-    loading: boolean;
-    /** Set loading state */
-    setLoading: (loading: boolean) => void;
-    /** Current error */
-    error: string | null;
-    /** Set error */
-    setError: (error: string | null) => void;
-}
-declare const FetchedDataContext: React__default.Context<FetchedDataContextValue | null>;
-interface FetchedDataProviderProps {
-    /** Initial data (optional) */
-    initialData?: Record<string, unknown[]>;
-    /** Children */
-    children: React__default.ReactNode;
-}
-/**
- * FetchedDataProvider - Provides server-fetched entity data
- *
- * @example
- * ```tsx
- * <FetchedDataProvider>
- *   <OrbitalProvider>
- *     <App />
- *   </OrbitalProvider>
- * </FetchedDataProvider>
- * ```
- */
-declare function FetchedDataProvider({ initialData, children, }: FetchedDataProviderProps): React__default.ReactElement;
-/**
- * Access the fetched data context.
- * Returns null if not within a FetchedDataProvider.
- */
-declare function useFetchedDataContext(): FetchedDataContextValue | null;
-/**
- * Access fetched data with fallback behavior.
- * If not in a provider, returns empty data.
- */
-declare function useFetchedData(): FetchedDataContextValue;
-/**
- * Access fetched data for a specific entity.
- * Provides a convenient API for entity-specific operations.
- */
-declare function useFetchedEntity(entityName: string): {
-    /** All fetched records for this entity */
-    records: EntityRecord[];
-    /** Get a record by ID */
-    getById: (id: string) => EntityRecord | undefined;
-    /** Whether data has been fetched for this entity */
-    hasData: boolean;
-    /** When data was last fetched */
-    fetchedAt: number | undefined;
-    /** Whether data is loading */
-    loading: boolean;
-    /** Current error */
-    error: string | null;
-};
-
-/**
- * OrbitalProvider
- *
- * Unified provider that combines all required contexts for Orbital applications.
- * Provides a single import for both Builder preview and compiled shell.
- *
- * Combines:
- * - ThemeProvider - Theme and color mode management
- * - EventBusProvider - Page-scoped event pub/sub
- * - SelectionProvider - Selected entity tracking
- * - FetchedDataProvider - Server-fetched entity data
- *
- * @packageDocumentation
- */
-
-interface OrbitalProviderProps {
-    children: ReactNode;
-    /** Custom themes (merged with built-in themes) */
-    themes?: ThemeDefinition[];
-    /** Default theme name */
-    defaultTheme?: string;
-    /** Default color mode */
-    defaultMode?: 'light' | 'dark' | 'system';
-    /** Optional target element ref for scoped theme application */
-    targetRef?: React__default.RefObject<HTMLElement>;
-    /** Skip ThemeProvider (use when already inside a themed container like shadow DOM) */
-    skipTheme?: boolean;
-    /** Enable debug logging for all providers */
-    debug?: boolean;
-    /** Initial fetched data */
-    initialData?: Record<string, unknown[]>;
-    /**
-     * Enable Suspense mode. When true, UISlotRenderer wraps each slot in
-     * `<ErrorBoundary><Suspense>` with Skeleton fallbacks.
-     * Opt-in — existing isLoading prop pattern still works when false/absent.
-     */
-    suspense?: boolean;
-    /**
-     * Enable verification wiring for visual testing.
-     * When true, lifecycle events are recorded and exposed via
-     * `window.__orbitalVerification` for Playwright/automation.
-     * Default: true in development, false in production.
-     */
-    verification?: boolean;
-}
-/**
- * OrbitalProvider - Unified context provider for Orbital applications
- *
- * Wraps your application with all required providers in the correct order.
- *
- * @example
- * ```tsx
- * // Basic usage
- * function App() {
- *   return (
- *     <OrbitalProvider>
- *       <Router>
- *         <Routes />
- *       </Router>
- *     </OrbitalProvider>
- *   );
- * }
- *
- * // With configuration
- * function App() {
- *   return (
- *     <OrbitalProvider
- *       defaultTheme="minimalist"
- *       defaultMode="dark"
- *       debug={process.env.NODE_ENV === 'development'}
- *     >
- *       <Router>
- *         <Routes />
- *       </Router>
- *     </OrbitalProvider>
- *   );
- * }
- *
- * // With custom themes from schema
- * import { THEMES } from './generated/theme-manifest';
- *
- * function App() {
- *   return (
- *     <OrbitalProvider themes={THEMES} defaultTheme="ocean">
- *       <Router>
- *         <Routes />
- *       </Router>
- *     </OrbitalProvider>
- *   );
- * }
- * ```
- */
-declare function OrbitalProvider({ children, themes, defaultTheme, defaultMode, targetRef, skipTheme, debug, initialData, suspense, verification, }: OrbitalProviderProps): React__default.ReactElement;
-declare namespace OrbitalProvider {
-    var displayName: string;
-}
-
-/**
- * VerificationProvider
- *
- * Wires the verification registry to both compiled and runtime execution paths.
- *
- * **Compiled apps**: Intercepts event bus lifecycle events
- *   (`{traitName}:DISPATCH`, `{traitName}:{event}:SUCCESS`, `{traitName}:{event}:ERROR`)
- *   emitted by `useOrbitalBridge` and records transitions via `recordTransition()`.
- *
- * **Runtime apps**: Accepts an optional `StateMachineManager` and wires its
- *   `TransitionObserver` to `recordTransition()`.
- *
- * **Both**: Calls `bindEventBus()` and `bindTraitStateGetter()` to populate
- *   `window.__orbitalVerification` for Playwright/automation.
- *
- * @packageDocumentation
- */
-
-/**
- * Observer interface compatible with `StateMachineManager.setObserver()`.
- * Defined locally to avoid hard dependency on `@almadar/runtime`.
- */
-interface TransitionObserver {
-    onTransition(trace: {
-        traitName: string;
-        from: string;
-        to: string;
-        event: string;
-        guardResult?: boolean;
-        effects: Array<{
-            type: string;
-            args: unknown[];
-            status: 'executed' | 'failed' | 'skipped';
-            error?: string;
-            durationMs?: number;
-        }>;
-    }): void;
-}
-/**
- * Minimal interface for StateMachineManager — avoids importing the full runtime.
- */
-interface StateMachineManagerLike {
-    setObserver(observer: TransitionObserver): void;
-    getState?(traitName: string): string | undefined;
-}
-interface VerificationProviderProps {
-    children: ReactNode;
-    /** Enable verification wiring (default: true in dev, false in prod) */
-    enabled?: boolean;
-    /** Optional runtime StateMachineManager for interpreted mode */
-    runtimeManager?: StateMachineManagerLike;
-    /** Optional trait state getter for compiled apps (maps traitName → currentState) */
-    traitStateGetter?: (traitName: string) => string | undefined;
-}
-/**
- * VerificationProvider — wires the verification registry to the event bus
- * and optional runtime manager. Renders children unchanged.
- */
-declare function VerificationProvider({ children, enabled, runtimeManager, traitStateGetter, }: VerificationProviderProps): React__default.ReactElement;
-declare namespace VerificationProvider {
-    var displayName: string;
-}
-
-/**
- * OfflineModeProvider
- *
- * Context provider that wraps useOfflineExecutor with force-offline toggle support.
- * Enables testing offline behavior without actually disconnecting.
- *
- * @packageDocumentation
- */
-
-interface OfflineModeContextValue extends UseOfflineExecutorResult {
-    /** Force offline mode for testing */
-    forceOffline: boolean;
-    /** Toggle force offline mode */
-    setForceOffline: (value: boolean) => void;
-    /** Whether effectively offline (real or forced) */
-    effectivelyOffline: boolean;
-}
-interface OfflineModeProviderProps extends UseOfflineExecutorOptions {
-    children: React__default.ReactNode;
-}
-/**
- * OfflineModeProvider - Wraps offline executor with force-offline support.
- *
- * @example
- * ```tsx
- * function App() {
- *   return (
- *     <OfflineModeProvider
- *       serverUrl="/api/orbitals"
- *       authToken={token}
- *       autoSync={true}
- *       renderToSlot={slotManager.render}
- *       navigate={router.push}
- *       notify={toast.show}
- *       eventBus={{ emit: bus.emit }}
- *     >
- *       <PreviewPage />
- *     </OfflineModeProvider>
- *   );
- * }
- * ```
- */
-declare function OfflineModeProvider({ children, ...executorOptions }: OfflineModeProviderProps): React__default.ReactElement;
-/**
- * Access offline mode context.
- *
- * @example
- * ```tsx
- * function OfflineToggle() {
- *   const {
- *     effectivelyOffline,
- *     forceOffline,
- *     setForceOffline,
- *     pendingCount,
- *     sync,
- *   } = useOfflineMode();
- *
- *   return (
- *     <div>
- *       <Toggle
- *         checked={forceOffline}
- *         onChange={setForceOffline}
- *       >
- *         Test Offline
- *       </Toggle>
- *       {pendingCount > 0 && <Badge>{pendingCount} pending</Badge>}
- *       <Button onClick={sync}>Sync Now</Button>
- *     </div>
- *   );
- * }
- * ```
- */
-declare function useOfflineMode(): OfflineModeContextValue;
-/**
- * Check if offline mode provider is available (optional usage).
- */
-declare function useOptionalOfflineMode(): OfflineModeContextValue | null;
-
-export { type EntityRecord, EventBusContext, EventBusProvider, FetchedDataContext, type FetchedDataContextValue, FetchedDataProvider, type FetchedDataProviderProps, type FetchedDataState, type OfflineModeContextValue, OfflineModeProvider, type OfflineModeProviderProps, OrbitalProvider, type OrbitalProviderProps, SelectionContext, type SelectionContextType, SelectionProvider, ThemeDefinition, VerificationProvider, type VerificationProviderProps, useFetchedData, useFetchedDataContext, useFetchedEntity, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional };
+ * Providers barrel export
+ *
+ * Unified providers for Orbital applications.
+ * Use OrbitalProvider for most cases - it combines all required providers.
+ */
+export { OrbitalProvider, type OrbitalProviderProps } from './OrbitalProvider';
+export type { ThemeDefinition } from '../context/ThemeContext';
+export { EventBusProvider, EventBusContext } from './EventBusProvider';
+export { SelectionProvider, SelectionContext, useSelection, useSelectionOptional } from './SelectionProvider';
+export type { SelectionContextType } from './SelectionProvider';
+export { FetchedDataProvider, FetchedDataContext, useFetchedDataContext, useFetchedData, useFetchedEntity, } from './FetchedDataProvider';
+export type { FetchedDataProviderProps, FetchedDataContextValue, FetchedDataState, EntityRecord, } from './FetchedDataProvider';
+export { VerificationProvider } from './VerificationProvider';
+export type { VerificationProviderProps } from './VerificationProvider';
+export { OfflineModeProvider, useOfflineMode, useOptionalOfflineMode, } from './OfflineModeProvider';
+export type { OfflineModeContextValue, OfflineModeProviderProps, } from './OfflineModeProvider';

package/dist/providers/index.js

@@ -1,10 +1,11 @@
-export { FetchedDataContext, FetchedDataProvider, OfflineModeProvider, OrbitalProvider, VerificationProvider, useFetchedData, useFetchedDataContext, useFetchedEntity, useOfflineMode, useOptionalOfflineMode } from '../chunk-UNDQO6DL.js';
-import '../chunk-MSLMORZK.js';
+export { FetchedDataContext, FetchedDataProvider, OfflineModeProvider, OrbitalProvider, VerificationProvider, useFetchedData, useFetchedDataContext, useFetchedEntity, useOfflineMode, useOptionalOfflineMode } from '../chunk-4KP6IZEQ.js';
+import '../chunk-YPY74G7F.js';
+import '../chunk-4N3BAPDB.js';
 import '../chunk-DKQN5FVU.js';
-export { SelectionContext, SelectionProvider, useSelection, useSelectionOptional } from '../chunk-Y7IHEYYE.js';
+export { SelectionContext, SelectionProvider, useSelection, useSelectionOptional } from '../chunk-QU2X55WH.js';
 export { EventBusContext, EventBusProvider } from '../chunk-YXZM3WCF.js';
 import '../chunk-3JGAROCW.js';
-import '../chunk-WCTZ7WZX.js';
+import '../chunk-XL7WB2O5.js';
 import '../chunk-2XXSUIOK.js';
 import '../chunk-K2D5D3WK.js';
 import '../chunk-PKBMQBKP.js';

package/dist/renderer/client-effect-executor.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Client Effect Executor
+ *
+ * Executes client effects returned from the server.
+ * This is the core of the dual execution model - the server processes
+ * events and returns client effects, which this module executes.
+ *
+ * Used by both Builder preview and compiled shells.
+ *
+ * @packageDocumentation
+ */
+import type { ClientEffect, ClientEffectExecutorConfig, PatternConfig, NotifyOptions } from './types';
+/**
+ * Execute an array of client effects.
+ *
+ * Effects are executed sequentially in order.
+ * Errors in one effect don't prevent subsequent effects from executing.
+ *
+ * @param effects - Array of client effects to execute
+ * @param config - Configuration providing implementations for each effect type
+ *
+ * @example
+ * ```typescript
+ * executeClientEffects(
+ *   [
+ *     ['render-ui', 'main', { type: 'entity-table', entity: 'Task' }],
+ *     ['notify', 'Tasks loaded!', { type: 'success' }]
+ *   ],
+ *   {
+ *     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) }
+ *   }
+ * );
+ * ```
+ */
+export declare function executeClientEffects(effects: ClientEffect[], config: ClientEffectExecutorConfig): void;
+/**
+ * Parse a raw effect array into a typed ClientEffect.
+ * Handles unknown effect formats gracefully.
+ */
+export declare function parseClientEffect(raw: unknown[]): ClientEffect | null;
+/**
+ * Parse an array of raw effects into typed ClientEffects.
+ * Filters out invalid effects.
+ */
+export declare function parseClientEffects(raw: unknown[] | undefined): ClientEffect[];
+/**
+ * Filter effects by type.
+ */
+export declare function filterEffectsByType<T extends ClientEffect[0]>(effects: ClientEffect[], type: T): Extract<ClientEffect, [T, ...unknown[]]>[];
+/**
+ * Get all render-ui effects.
+ */
+export declare function getRenderUIEffects(effects: ClientEffect[]): Array<['render-ui', string, PatternConfig | null]>;
+/**
+ * Get all navigate effects.
+ */
+export declare function getNavigateEffects(effects: ClientEffect[]): Array<['navigate', string, Record<string, unknown>?]>;
+/**
+ * Get all notify effects.
+ */
+export declare function getNotifyEffects(effects: ClientEffect[]): Array<['notify', string, NotifyOptions?]>;
+/**
+ * Get all emit effects.
+ */
+export declare function getEmitEffects(effects: ClientEffect[]): Array<['emit', string, unknown?]>;

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

@@ -0,0 +1,68 @@
+/**
+ * Data Resolver
+ *
+ * Resolves entity data for pattern rendering.
+ * Supports multiple data sources with priority:
+ * 1. Server-provided data (from EventResponse.data)
+ * 2. Entity store (Builder in-memory mock data)
+ * 3. Empty array (fallback)
+ *
+ * Used by both Builder's PatternRenderer and compiled shell's UISlotRenderer.
+ *
+ * @packageDocumentation
+ */
+import type { DataContext, DataResolution } from './types';
+/**
+ * Resolve entity data from available sources.
+ *
+ * Priority:
+ * 1. fetchedData (from server response) - highest priority
+ * 2. entityStore (Builder mock data)
+ * 3. Empty array (fallback)
+ *
+ * @param entityName - Name of the entity to resolve data for
+ * @param context - Data context with available sources
+ * @returns Resolved data with loading state
+ *
+ * @example
+ * ```typescript
+ * const { data, loading } = resolveEntityData('Task', {
+ *   fetchedData: response.data,
+ *   entityStore: mockStore
+ * });
+ * ```
+ */
+export declare function resolveEntityData(entityName: string, context: DataContext): DataResolution;
+/**
+ * Resolve entity data with query filtering.
+ *
+ * Applies query singleton filters if available.
+ *
+ * @param entityName - Name of the entity
+ * @param queryRef - Optional query reference for filtering
+ * @param context - Data context
+ * @returns Filtered resolved data
+ */
+export declare function resolveEntityDataWithQuery(entityName: string, queryRef: string | undefined, context: DataContext): DataResolution;
+/**
+ * Get a single entity record by ID.
+ */
+export declare function resolveEntityById(entityName: string, id: string | number, context: DataContext): unknown | null;
+/**
+ * Get the count of entities matching criteria.
+ */
+export declare function resolveEntityCount(entityName: string, context: DataContext, filters?: Record<string, unknown>): number;
+/**
+ * Check if any entities exist for a given entity name.
+ */
+export declare function hasEntities(entityName: string, context: DataContext): boolean;
+/**
+ * Create a data context from fetched data only.
+ * Convenience function for compiled shells.
+ */
+export declare function createFetchedDataContext(data: Record<string, unknown[]>): DataContext;
+/**
+ * Merge multiple data contexts.
+ * Later contexts take precedence.
+ */
+export declare function mergeDataContexts(...contexts: DataContext[]): DataContext;