@almadar/ui 5.111.0 → 5.113.0

package/dist/providers/index.d.cts

@@ -0,0 +1,428 @@
+import React__default, { ReactNode } from 'react';
+import { EntityRow, FieldValue } from '@almadar/core';
+import { U as UIThemeDefinition } from '../UserContext-bziZwgFL.cjs';
+export { A as ANONYMOUS_USER, a as CurrentPagePathContext, b as CurrentPagePathProvider, c as CurrentPagePathProviderProps, d as DesignThemeProvider, O as OrbitalThemeProvider, e as OrbitalThemeProviderProps, h as UserContext, i as UserContextValue, j as UserData, k as UserProvider, l as UserProviderProps, u as useCurrentPagePath, m as useDesignTheme, n as useHasPermission, o as useHasRole, q as useUser, r as useUserForEvaluation } from '../UserContext-bziZwgFL.cjs';
+export { E as EntitySchemaContextValue, a as EntitySchemaProvider, b as EntitySchemaProviderProps, S as SendEventResult, c as ServerBridgeContextValue, d as ServerBridgeProvider, e as ServerBridgeProviderProps, f as ServerBridgeTransport, g as ServerClientEffect, h as ServerResponseMeta, T as TraitContext, i as TraitContextValue, j as TraitInstance, k as TraitProvider, l as TraitProviderProps, u as useEntitySchema, m as useEntitySchemaOptional, n as useServerBridge, o as useTrait, p as useTraitContext } from '../TraitProvider-YkK6tXDw.cjs';
+import { U as UseOfflineExecutorResult, a as UseOfflineExecutorOptions } from '../offline-executor-aRuNznZx.cjs';
+export { N as NavigationContextValue, b as NavigationProvider, c as NavigationProviderProps, d as NavigationState, e as extractRouteParams, f as findPageByName, g as findPageByPath, h as getAllPages, i as getDefaultPage, m as matchPath, p as pathMatches, u as useActivePage, j as useInitPayload, k as useNavigateTo, l as useNavigation, n as useNavigationId, o as useNavigationState } from '../offline-executor-aRuNznZx.cjs';
+import { E as EventBusContextType } from '../event-bus-types-Bl78kokd.cjs';
+export { G as GameAudioContext, a as GameAudioContextValue, b as GameAudioProvider, c as GameAudioProviderProps, u as useGameAudioContext, d as useGameAudioContextOptional } from '../GameAudioProvider-CPGwD49P.cjs';
+import '@almadar/core/patterns';
+
+/**
+ * EventBusProvider - React context provider for the event bus
+ *
+ * Provides a page-scoped event bus for trait communication.
+ * Each page has its own event bus instance.
+ *
+ * NOTE: Selection state has been moved to SelectionProvider.
+ * Use SelectionProvider for tracking selected entities.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 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. */
+    getSelectedEntity: () => EntityRow | null;
+    /** @deprecated Use useSelection from SelectionProvider instead. */
+    clearSelectedEntity: () => void;
+}
+declare const EventBusContext: React__default.Context<EventBusContextTypeExtended | null>;
+interface EventBusProviderProps {
+    children: ReactNode;
+    /**
+     * @deprecated No-op. Logging is now gated by `@almadar/logger` —
+     * use `setLogLevel('DEBUG')` or `setNamespaceLevel('almadar:eventbus', 'DEBUG')`
+     * from `@almadar/logger` to control verbosity. Kept for API compatibility.
+     */
+    debug?: boolean;
+    /**
+     * When true, this provider does NOT register itself as the global event bus
+     * (`window.__kflowEventBus`). Use for SANDBOXED subtrees — e.g. a studio
+     * preview (`BrowserPlayground`) embedded inside a host app — whose internal
+     * events must stay context-local and must NOT clobber the host's global bus.
+     * Children still get this bus via React context; only the global bridge is
+     * skipped. Default false (root/standalone providers own the global bridge).
+     */
+    isolated?: boolean;
+}
+declare function EventBusProvider({ children, isolated }: EventBusProviderProps): React__default.JSX.Element;
+
+/**
+ * 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
+ */
+
+interface SelectionContextType<T = EntityRow> {
+    /** 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<EntityRow> | null>;
+interface SelectionProviderProps {
+    children: ReactNode;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom comparison function for isSelected */
+    compareEntities?: (a: EntityRow, b: EntityRow) => 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__default.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 = EntityRow>(): 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 = EntityRow>(): SelectionContextType<T> | 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
+ *
+ * Entity data flows through props (via enrichFromResponse in ServerBridge),
+ * not through context. FetchedDataProvider has been removed.
+ *
+ * @packageDocumentation
+ */
+
+interface OrbitalProviderProps {
+    children: ReactNode;
+    /** Custom themes (merged with built-in themes) */
+    themes?: UIThemeDefinition[];
+    /** 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 */
+    /** @deprecated No longer used. Entity data flows through server response props. */
+    initialData?: Record<string, EntityRow[]>;
+    /**
+     * 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;
+    /**
+     * Sandbox mode: the event bus stays context-local and does NOT register as
+     * the global bus. Set for studio previews embedded in a host app (so the
+     * preview's events don't clobber the host's global bus). Default false.
+     */
+    isolated?: 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, isolated, }: OrbitalProviderProps): React__default.ReactElement;
+declare namespace OrbitalProvider {
+    var displayName: string;
+}
+
+/**
+ * TraitScopeProvider
+ *
+ * Wraps a trait's rendered subtree with its owning `{ orbital, trait }`
+ * pair. Pure components inside the subtree (Button, Form, etc.) keep
+ * calling `useEventBus().emit('UI:X', ...)` exactly as today; the
+ * scoped wrapper that `useEventBus` returns inside this provider
+ * rewrites bare `UI:X` keys into the qualified
+ * `UI:Orbital.Trait.X` form that `useTraitStateMachine` (and the rest
+ * of the post-Phase 4 subscriber side) listens on.
+ *
+ * Producer-side fix for the gap where Button-emitted bare keys never
+ * reached the trait state machine in the runtime path. The compiled
+ * path's codegen wraps each trait view with the same provider so both
+ * paths share the qualification contract.
+ *
+ * @packageDocumentation
+ */
+
+interface TraitScope {
+    /** Owning orbital name (e.g. `"ContactOrbital"`). */
+    orbital: string;
+    /** Trait name within the orbital (e.g. `"ContactBrowse"`). */
+    trait: string;
+}
+interface TraitScopeProviderProps {
+    orbital: string;
+    trait: string;
+    children: React__default.ReactNode;
+}
+/**
+ * Wrap a trait's rendered subtree to qualify bare `UI:*` emits with the
+ * trait's scope. Mount this at the slot-content boundary in runtime
+ * mode (UISlotRenderer) and at each generated trait view's outermost
+ * element in compiled mode (orbital-shell-typescript codegen).
+ */
+declare function TraitScopeProvider({ orbital, trait, children, }: TraitScopeProviderProps): React__default.ReactElement;
+/**
+ * Read the current trait scope. Returns `null` when called outside
+ * any `TraitScopeProvider` (e.g. Storybook, design-system catalog).
+ */
+declare function useTraitScope(): TraitScope | null;
+
+/**
+ * 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: FieldValue[];
+            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 { EventBusContext, EventBusProvider, type OfflineModeContextValue, OfflineModeProvider, type OfflineModeProviderProps, OrbitalProvider, type OrbitalProviderProps, SelectionContext, type SelectionContextType, SelectionProvider, type TraitScope, TraitScopeProvider, type TraitScopeProviderProps, UIThemeDefinition, VerificationProvider, type VerificationProviderProps, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional, useTraitScope };