@almadar/ui 2.13.3 → 2.15.0

package/dist/providers/FetchedDataProvider.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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
+ */
+import React from 'react';
+export interface EntityRecord {
+    id: string;
+    [key: string]: unknown;
+}
+export 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;
+}
+export 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;
+}
+export declare const FetchedDataContext: React.Context<FetchedDataContextValue | null>;
+export interface FetchedDataProviderProps {
+    /** Initial data (optional) */
+    initialData?: Record<string, unknown[]>;
+    /** Children */
+    children: React.ReactNode;
+}
+/**
+ * FetchedDataProvider - Provides server-fetched entity data
+ *
+ * @example
+ * ```tsx
+ * <FetchedDataProvider>
+ *   <OrbitalProvider>
+ *     <App />
+ *   </OrbitalProvider>
+ * </FetchedDataProvider>
+ * ```
+ */
+export declare function FetchedDataProvider({ initialData, children, }: FetchedDataProviderProps): React.ReactElement;
+/**
+ * Access the fetched data context.
+ * Returns null if not within a FetchedDataProvider.
+ */
+export declare function useFetchedDataContext(): FetchedDataContextValue | null;
+/**
+ * Access fetched data with fallback behavior.
+ * If not in a provider, returns empty data.
+ */
+export declare function useFetchedData(): FetchedDataContextValue;
+/**
+ * Access fetched data for a specific entity.
+ * Provides a convenient API for entity-specific operations.
+ */
+export 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;
+};

package/dist/providers/OfflineModeProvider.d.ts

@@ -0,0 +1,79 @@
+/**
+ * OfflineModeProvider
+ *
+ * Context provider that wraps useOfflineExecutor with force-offline toggle support.
+ * Enables testing offline behavior without actually disconnecting.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type UseOfflineExecutorOptions, type UseOfflineExecutorResult } from '../renderer/offline-executor';
+export 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;
+}
+export interface OfflineModeProviderProps extends UseOfflineExecutorOptions {
+    children: React.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>
+ *   );
+ * }
+ * ```
+ */
+export declare function OfflineModeProvider({ children, ...executorOptions }: OfflineModeProviderProps): React.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>
+ *   );
+ * }
+ * ```
+ */
+export declare function useOfflineMode(): OfflineModeContextValue;
+/**
+ * Check if offline mode provider is available (optional usage).
+ */
+export declare function useOptionalOfflineMode(): OfflineModeContextValue | null;
+export default OfflineModeProvider;

package/dist/providers/OrbitalProvider.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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
+ */
+import React, { type ReactNode } from 'react';
+import { type ThemeDefinition } from '../context/ThemeContext';
+export 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.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>
+ *   );
+ * }
+ * ```
+ */
+export declare function OrbitalProvider({ children, themes, defaultTheme, defaultMode, targetRef, skipTheme, debug, initialData, suspense, verification, }: OrbitalProviderProps): React.ReactElement;
+export declare namespace OrbitalProvider {
+    var displayName: string;
+}
+export { ThemeProvider } from '../context/ThemeContext';
+export { EventBusProvider } from './EventBusProvider';
+export { SelectionProvider } from './SelectionProvider';
+export { FetchedDataProvider } from './FetchedDataProvider';

package/dist/providers/SelectionProvider.d.ts

@@ -0,0 +1,81 @@
+/**
+ * SelectionProvider - Manages selected entity state
+ *
+ * Separates selection state from the EventBusProvider to maintain
+ * clean architecture (event bus stays pure pub/sub).
+ *
+ * This provider:
+ * - Listens to UI:VIEW and UI:SELECT events to track selected entity
+ * - Listens to UI:CLOSE, UI:DESELECT, UI:CANCEL to clear selection
+ * - Provides the selected entity to any component that needs it
+ *
+ * @packageDocumentation
+ */
+import React, { type ReactNode } from 'react';
+export 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.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>
+ *   );
+ * }
+ * ```
+ */
+export declare function SelectionProvider({ children, debug, compareEntities, }: SelectionProviderProps): import("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>
+ *   );
+ * }
+ * ```
+ */
+export 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.
+ */
+export declare function useSelectionOptional<T = unknown>(): SelectionContextType<T> | null;
+export { SelectionContext };

package/dist/providers/VerificationProvider.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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
+ */
+import React, { type ReactNode } from 'react';
+/**
+ * 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;
+}
+export 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.
+ */
+export declare function VerificationProvider({ children, enabled, runtimeManager, traitStateGetter, }: VerificationProviderProps): React.ReactElement;
+export declare namespace VerificationProvider {
+    var displayName: string;
+}
+export {};