@almadar/ui 5.111.0 → 5.113.0

package/dist/providers/ServerBridge.d.ts

@@ -1,102 +0,0 @@
-import type { ReactNode } from 'react';
-import type { BusEventSource, EntityRow, EventPayload, OrbitalSchema, SExpr } from '@almadar/core';
-import type { AnyPatternConfig } from '@almadar/patterns';
-/** Wire-format client effect tuple from the server response. */
-type ClientEffectTuple = ['render-ui', string, AnyPatternConfig | null, ...SExpr[]] | ['navigate', string, ...SExpr[]] | ['notify', string, ...SExpr[]];
-interface OrbitalEventResponse {
-    success: boolean;
-    transitioned: boolean;
-    states: Record<string, string>;
-    /**
-     * Server-cascade events carried back in the response. Each entry has a
-     * `source: BusEventSource` stamped by the compiled handler (`emit ...
-     * { source: __ORBITAL_SOURCE }`) so the client can re-broadcast on the
-     * qualified `UI:Orbital.Trait.EVENT` bus key (gap #13).
-     */
-    emittedEvents?: Array<{
-        event: string;
-        payload?: EventPayload;
-        source?: BusEventSource;
-    }>;
-    data?: Record<string, EntityRow[]>;
-    clientEffects?: ClientEffectTuple[];
-    /**
-     * Same effects as `clientEffects`, paired with the trait that produced
-     * each one. When present, prefer this for trait attribution. Falls back
-     * to legacy `clientEffects` parsing on older servers.
-     */
-    clientEffectsByTrait?: Array<{
-        traitName: string;
-        effect: ClientEffectTuple;
-    }>;
-    error?: string;
-}
-export interface ServerClientEffect {
-    type: 'render-ui' | 'navigate' | 'notify';
-    slot?: string;
-    pattern?: AnyPatternConfig;
-    route?: string;
-    params?: EventPayload;
-    message?: string;
-    /**
-     * Trait that emitted this effect. Used by `<TraitFrame>` to resolve
-     * `@trait.X` bindings. Undefined when the server didn't tag the effect
-     * (older servers that pre-date the per-trait sidecar).
-     */
-    traitName?: string;
-}
-/** Metadata about what the server returned, for debugger logging */
-export interface ServerResponseMeta {
-    success: boolean;
-    clientEffects: number;
-    dataEntities: Record<string, number>;
-    /** Raw entity data from server response (for EntityStore advancement) */
-    data?: Record<string, EntityRow[]>;
-    emittedEvents: string[];
-    error?: string;
-}
-export interface SendEventResult {
-    effects: ServerClientEffect[];
-    meta: ServerResponseMeta;
-}
-export interface ServerBridgeContextValue {
-    connected: boolean;
-    sendEvent: (orbitalName: string, event: string, payload?: EventPayload) => Promise<SendEventResult>;
-}
-/**
- * Transport adapter for ServerBridgeProvider. Decouples the bridge's
- * cascade-rebroadcast / effect-parsing logic from its wire format.
- *
- * - The `serverUrl` mode (default) uses an HTTP transport that POSTs to
- *   `/register`, `/unregister`, `/:orbital/events`. This is what canonical
- *   playground-runtime (`tools/runtime-verify`) and apps/builder-server
- *   speak.
- * - The `transport` mode lets a consumer plug in a direct function-call
- *   adapter — used by `<BrowserPlayground>` to invoke
- *   `OrbitalServerRuntime.processOrbitalEvent` in-process, no HTTP, no
- *   server. Both modes return the same `OrbitalEventResponse` shape so the
- *   cascade-rebroadcast logic is identical downstream.
- */
-export interface ServerBridgeTransport {
-    register: (schema: OrbitalSchema) => Promise<boolean>;
-    unregister: () => Promise<void>;
-    sendEvent: (orbitalName: string, event: string, payload?: EventPayload) => Promise<OrbitalEventResponse>;
-}
-/**
- * Access the server bridge. Returns a no-op stub when outside the provider.
- */
-export declare function useServerBridge(): ServerBridgeContextValue;
-export interface ServerBridgeProviderProps {
-    schema: OrbitalSchema;
-    /** HTTP server URL (canonical playground-runtime / apps/builder-server). */
-    serverUrl?: string;
-    /**
-     * Custom transport adapter. Use this for in-process execution (e.g.
-     * `<BrowserPlayground>` invokes `OrbitalServerRuntime.processOrbitalEvent`
-     * directly). Mutually exclusive with `serverUrl`.
-     */
-    transport?: ServerBridgeTransport;
-    children: ReactNode;
-}
-export declare function ServerBridgeProvider({ schema, serverUrl, transport: customTransport, children, }: ServerBridgeProviderProps): import("react").JSX.Element;
-export {};

package/dist/providers/ThemeContext.d.ts

@@ -1,104 +0,0 @@
-/**
- * Unified ThemeContext - Single provider for theme and color mode
- *
- * Combines design theme selection (ocean, wireframe, etc.) with
- * color mode (light/dark) into a single, simple system.
- *
- * Uses a single data attribute: data-theme="ocean-light" or data-theme="ocean-dark"
- *
- * @packageDocumentation
- */
-import React from "react";
-/** Color mode preference */
-export type ColorMode = "light" | "dark" | "system";
-/** Resolved color mode (what's actually applied) */
-export type ResolvedMode = "light" | "dark";
-/** Theme definition */
-export interface UIThemeDefinition {
-    /** Theme identifier (e.g., "ocean", "wireframe") */
-    name: string;
-    /** Display name for UI (e.g., "Ocean Blue") */
-    displayName?: string;
-    /** Whether this theme has light mode styles */
-    hasLightMode?: boolean;
-    /** Whether this theme has dark mode styles */
-    hasDarkMode?: boolean;
-}
-/** Built-in themes available in the design system */
-export declare const BUILT_IN_THEMES: UIThemeDefinition[];
-/** Theme context value */
-interface ThemeContextValue {
-    /** Current theme name */
-    theme: string;
-    /** Current color mode setting (may be 'system') */
-    mode: ColorMode;
-    /** Resolved color mode (always 'light' or 'dark') */
-    resolvedMode: ResolvedMode;
-    /** Set the theme */
-    setTheme: (theme: string) => void;
-    /** Set the color mode */
-    setMode: (mode: ColorMode) => void;
-    /** Toggle between light and dark modes */
-    toggleMode: () => void;
-    /** Available themes */
-    availableThemes: UIThemeDefinition[];
-    /** The full theme string applied to data-theme (e.g., "ocean-light") */
-    appliedTheme: string;
-}
-declare const ThemeContext: React.Context<ThemeContextValue | undefined>;
-export interface ThemeProviderProps {
-    children: React.ReactNode;
-    /** Available themes (will be merged with built-in themes) */
-    themes?: readonly UIThemeDefinition[] | UIThemeDefinition[];
-    /** Default theme name */
-    defaultTheme?: string;
-    /** Default color mode */
-    defaultMode?: ColorMode;
-    /** Optional target element ref — when provided, theme attributes are applied to this element instead of document.documentElement */
-    targetRef?: React.RefObject<HTMLElement>;
-}
-/**
- * Unified ThemeProvider component
- *
- * @example
- * ```tsx
- * // Basic usage with built-in themes
- * <ThemeProvider defaultTheme="wireframe" defaultMode="light">
- *   <App />
- * </ThemeProvider>
- *
- * // With custom themes from orbital schema
- * import { THEMES } from './generated/theme-manifest';
- * <ThemeProvider themes={THEMES} defaultTheme="ocean" defaultMode="system">
- *   <App />
- * </ThemeProvider>
- * ```
- */
-export declare const ThemeProvider: React.FC<ThemeProviderProps>;
-/**
- * Hook for accessing theme context
- *
- * @returns Theme context value
- *
- * @example
- * ```tsx
- * const { theme, resolvedMode, toggleMode, setTheme } = useTheme();
- *
- * // Toggle dark mode
- * <button onClick={toggleMode}>
- *   {resolvedMode === 'dark' ? 'Light' : 'Dark'}
- * </button>
- *
- * // Change theme
- * <select value={theme} onChange={(e) => setTheme(e.target.value)}>
- *   {availableThemes.map(t => (
- *     <option key={t.name} value={t.name}>{t.displayName || t.name}</option>
- *   ))}
- * </select>
- * ```
- */
-export declare function useTheme(): ThemeContextValue;
-export type Theme = ColorMode;
-export type ResolvedTheme = ResolvedMode;
-export type DesignTheme = UIThemeDefinition;
-export default ThemeContext;

package/dist/providers/TraitProvider.d.ts

@@ -1,53 +0,0 @@
-/**
- * TraitProvider Component
- *
- * Provides trait state machines to child components via React context.
- *
- * @packageDocumentation
- */
-import React from 'react';
-import type { EventPayload } from '@almadar/core';
-import type { ResolvedTrait, ResolvedTraitBinding, ResolvedEntity } from '../types/runtime-types';
-export interface TraitInstance {
-    /** Trait name */
-    name: string;
-    /** Current state */
-    currentState: string;
-    /** Available events (can be triggered) */
-    availableEvents: string[];
-    /** Dispatch an event to the state machine */
-    dispatch: (eventKey: string, payload?: EventPayload) => void;
-    /** Check if an event can be dispatched */
-    canDispatch: (eventKey: string) => boolean;
-    /** Get the full trait definition */
-    trait: ResolvedTrait;
-}
-export interface TraitContextValue {
-    /** All trait instances on this page */
-    traits: Map<string, TraitInstance>;
-    /** Get a trait instance by name */
-    getTrait: (name: string) => TraitInstance | undefined;
-    /** Dispatch an event to a specific trait */
-    dispatchToTrait: (traitName: string, eventKey: string, payload?: EventPayload) => void;
-    /** Check if an event can be dispatched to a trait */
-    canDispatch: (traitName: string, eventKey: string) => boolean;
-}
-export declare const TraitContext: React.Context<TraitContextValue | null>;
-export interface TraitProviderProps {
-    /** Trait bindings for this page */
-    traits: ResolvedTraitBinding[];
-    /** Entity map for context */
-    entities: Map<string, ResolvedEntity>;
-    /** Children to render */
-    children: React.ReactNode;
-}
-export declare function TraitProvider({ traits: traitBindings, children, }: TraitProviderProps): React.ReactElement;
-/**
- * Access the trait context from within the TraitProvider.
- */
-export declare function useTraitContext(): TraitContextValue;
-/**
- * Access a specific trait instance.
- */
-export declare function useTrait(traitName: string): TraitInstance | undefined;
-export default TraitProvider;

package/dist/providers/TraitScopeProvider.d.ts

@@ -1,43 +0,0 @@
-/**
- * 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
- */
-import React from 'react';
-export interface TraitScope {
-    /** Owning orbital name (e.g. `"ContactOrbital"`). */
-    orbital: string;
-    /** Trait name within the orbital (e.g. `"ContactBrowse"`). */
-    trait: string;
-}
-export interface TraitScopeProviderProps {
-    orbital: string;
-    trait: string;
-    children: React.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).
- */
-export declare function TraitScopeProvider({ orbital, trait, children, }: TraitScopeProviderProps): React.ReactElement;
-/**
- * Read the current trait scope. Returns `null` when called outside
- * any `TraitScopeProvider` (e.g. Storybook, design-system catalog).
- */
-export declare function useTraitScope(): TraitScope | null;
-export default TraitScopeProvider;

package/dist/providers/UserContext.d.ts

@@ -1,112 +0,0 @@
-/**
- * UserContext
- *
- * React context for providing user data throughout the application.
- * Enables @user bindings in S-expressions for role-based UI and permissions.
- *
- * Usage:
- * ```tsx
- * // In App.tsx or layout
- * <UserProvider user={{ id: '123', role: 'admin', permissions: ['read', 'write'] }}>
- *   <App />
- * </UserProvider>
- *
- * // In components - access via hook
- * const { user, hasRole, hasPermission } = useUser();
- * if (hasRole('admin')) { ... }
- * if (hasPermission('delete')) { ... }
- * ```
- *
- * @packageDocumentation
- */
-import React from 'react';
-import type { FieldValue } from '@almadar/core';
-/**
- * User data for @user bindings.
- * Matches UserContext type from evaluator/context.ts
- */
-export interface UserData {
-    /** User's unique ID */
-    id: string;
-    /** User's email */
-    email?: string;
-    /** User's display name */
-    name?: string;
-    /** User's role (for RBAC) */
-    role?: string;
-    /** User's permissions */
-    permissions?: string[];
-    /** Additional custom profile fields */
-    [key: string]: FieldValue | undefined;
-}
-/**
- * User context value.
- */
-export interface UserContextValue {
-    /** Current user data (null if not logged in) */
-    user: UserData | null;
-    /** Check if user is logged in */
-    isLoggedIn: boolean;
-    /** Check if user has a specific role */
-    hasRole: (role: string) => boolean;
-    /** Check if user has a specific permission */
-    hasPermission: (permission: string) => boolean;
-    /** Check if user has any of the specified roles */
-    hasAnyRole: (roles: string[]) => boolean;
-    /** Check if user has all of the specified permissions */
-    hasAllPermissions: (permissions: string[]) => boolean;
-    /** Get a user field by path (for @user.field bindings) */
-    getUserField: (path: string) => FieldValue | undefined;
-}
-/**
- * Anonymous user for when no user is logged in.
- */
-declare const ANONYMOUS_USER: UserData;
-declare const UserContext: React.Context<UserContextValue | null>;
-export interface UserProviderProps {
-    /** User data (null if not logged in) */
-    user?: UserData | null;
-    /** Children to render */
-    children: React.ReactNode;
-}
-/**
- * Provider component that provides user context to the application.
- *
- * Provides RBAC helpers and field access for @user bindings.
- */
-export declare function UserProvider({ user, children, }: UserProviderProps): React.ReactElement;
-/**
- * Hook to access the user context.
- *
- * Returns default values if used outside of UserProvider (for resilience).
- *
- * @example
- * ```tsx
- * function AdminPanel() {
- *   const { user, hasRole, hasPermission } = useUser();
- *
- *   if (!hasRole('admin') && !hasPermission('admin:access')) {
- *     return <AccessDenied />;
- *   }
- *
- *   return <div>Welcome, {user?.name}</div>;
- * }
- * ```
- */
-export declare function useUser(): UserContextValue;
-/**
- * Hook to check if user has a specific role.
- * Convenience wrapper around useUser().hasRole().
- */
-export declare function useHasRole(role: string): boolean;
-/**
- * Hook to check if user has a specific permission.
- * Convenience wrapper around useUser().hasPermission().
- */
-export declare function useHasPermission(permission: string): boolean;
-/**
- * Hook to get user data for @user bindings in S-expressions.
- * Returns the user data object compatible with EvaluationContext.user
- */
-export declare function useUserForEvaluation(): UserData | undefined;
-export { UserContext, ANONYMOUS_USER };

package/dist/providers/VerificationProvider.d.ts

@@ -1,64 +0,0 @@
-/**
- * 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';
-import type { FieldValue } from '@almadar/core';
-/**
- * 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;
-}
-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 {};

package/dist/providers/navigation.d.ts

@@ -1,142 +0,0 @@
-/**
- * NavigationContext - Schema-Driven Navigation for Orbital Runtime
- *
- * Provides navigation within the orbital schema without react-router dependency.
- * Navigation works by:
- * 1. Matching path to a page in the schema
- * 2. Extracting route params (e.g., /inspection/:id → { id: "123" })
- * 3. Switching active page
- * 4. Triggering INIT with merged payload
- *
- * This approach works whether OrbitalRuntime is standalone or embedded in another app.
- *
- * Used by both:
- * - Builder runtime (interpreted execution)
- * - Compiled shells (generated applications)
- *
- * @packageDocumentation
- */
-import React from 'react';
-import type { OrbitalSchema, OrbitalPage, FieldValue } from '@almadar/core';
-/**
- * Match a concrete path against a pattern with :param placeholders.
- * Returns null if no match, or the extracted params if match.
- *
- * @example
- * matchPath('/inspection/:id', '/inspection/123') // { id: '123' }
- * matchPath('/users/:userId/posts/:postId', '/users/42/posts/7') // { userId: '42', postId: '7' }
- * matchPath('/about', '/about') // {}
- * matchPath('/about', '/contact') // null
- */
-export declare function matchPath(pattern: string, path: string): Record<string, string> | null;
-/**
- * Extract route params from a path given its pattern.
- * Wrapper around matchPath for explicit use.
- */
-export declare function extractRouteParams(pattern: string, path: string): Record<string, string>;
-/**
- * Check if a path matches a pattern.
- */
-export declare function pathMatches(pattern: string, path: string): boolean;
-/**
- * Find a page in the schema by matching its path pattern against a concrete path.
- * Returns the page and extracted route params.
- */
-export declare function findPageByPath(schema: OrbitalSchema, path: string): {
-    page: OrbitalPage;
-    params: Record<string, string>;
-    orbitalName: string;
-} | null;
-/**
- * Find a page by name.
- */
-export declare function findPageByName(schema: OrbitalSchema, pageName: string): {
-    page: OrbitalPage;
-    orbitalName: string;
-} | null;
-/**
- * Get the first page in the schema (default page).
- */
-export declare function getDefaultPage(schema: OrbitalSchema): {
-    page: OrbitalPage;
-    orbitalName: string;
-} | null;
-/**
- * Get all pages from the schema.
- */
-export declare function getAllPages(schema: OrbitalSchema): Array<{
-    page: OrbitalPage;
-    orbitalName: string;
-}>;
-export interface NavigationState {
-    /** Current active page name */
-    activePage: string;
-    /** Current path (for URL sync) */
-    currentPath: string;
-    /** Payload to pass to INIT when page loads */
-    initPayload: Record<string, FieldValue>;
-    /** Navigation counter (increments on each navigation) */
-    navigationId: number;
-}
-export interface NavigationContextValue {
-    /** Current navigation state */
-    state: NavigationState;
-    /** Navigate to a path with optional payload */
-    navigateTo: (path: string, payload?: Record<string, FieldValue>) => void;
-    /** Navigate to a page by name with optional payload */
-    navigateToPage: (pageName: string, payload?: Record<string, FieldValue>) => void;
-    /** The schema being navigated */
-    schema: OrbitalSchema;
-    /** Whether navigation is ready (schema loaded) */
-    isReady: boolean;
-}
-export interface NavigationProviderProps {
-    /** The schema to navigate within */
-    schema: OrbitalSchema;
-    /** Initial page name (optional, defaults to first page) */
-    initialPage?: string;
-    /** Whether to update browser URL on navigation (default: true) */
-    updateUrl?: boolean;
-    /** Callback when navigation occurs */
-    onNavigate?: (pageName: string, path: string, payload: Record<string, FieldValue>) => void;
-    /** Children */
-    children: React.ReactNode;
-}
-/**
- * NavigationProvider - Provides schema-driven navigation context
- *
- * @example
- * ```tsx
- * <NavigationProvider schema={mySchema}>
- *   <OrbitalRuntimeContent />
- * </NavigationProvider>
- * ```
- */
-export declare function NavigationProvider({ schema, initialPage, updateUrl, onNavigate, children, }: NavigationProviderProps): React.ReactElement;
-/**
- * Hook to access navigation context.
- * Returns null if not within NavigationProvider.
- */
-export declare function useNavigation(): NavigationContextValue | null;
-/**
- * Hook to get the navigateTo function.
- * Returns a no-op function if not within NavigationProvider.
- */
-export declare function useNavigateTo(): (path: string, payload?: Record<string, FieldValue>) => void;
-/**
- * Hook to get current navigation state.
- */
-export declare function useNavigationState(): NavigationState | null;
-/**
- * Hook to get the current INIT payload (for passing to trait INIT events).
- */
-export declare function useInitPayload(): Record<string, FieldValue>;
-/**
- * Hook to get current active page name.
- */
-export declare function useActivePage(): string | null;
-/**
- * Hook to get navigation ID (changes on each navigation, useful for triggering effects).
- */
-export declare function useNavigationId(): number;
-export default NavigationProvider;

package/dist/runtime/BrowserPlayground.d.ts

@@ -1,34 +0,0 @@
-/**
- * BrowserPlayground — in-browser Almadar runtime mount.
- *
- * Runs `OrbitalServerRuntime` (mock mode) in-process and threads it through
- * `<OrbPreview>` via the `ServerBridgeTransport` adapter. Equivalent to
- * canonical playground-runtime's server-mode mount, but without Express,
- * fork, or HTTP — invokes `runtime.processOrbitalEvent` directly.
- *
- * Same React tree as `runtime-verify` (and apps/builder server-mode) speak,
- * so any `@almadar/runtime` fix flows in through one bump cycle.
- *
- * @example
- * ```tsx
- * <BrowserPlayground schema={schema} mode="mock" height="100%" />
- * ```
- *
- * @packageDocumentation
- */
-import React from 'react';
-import type { OrbitalSchema } from '@almadar/core';
-export interface BrowserPlaygroundProps {
-    /** OrbitalSchema to render. */
-    schema: OrbitalSchema;
-    /** Persistence mode for the in-process runtime. Default: 'mock' (Faker-seeded MockPersistenceAdapter). */
-    mode?: 'mock';
-    /** Initial page path to render (forwarded to OrbPreview). */
-    initialPagePath?: string;
-    /** Preview container height. Default: '400px'. */
-    height?: string;
-    /** CSS class for the outer container. */
-    className?: string;
-}
-export declare function BrowserPlayground({ schema, mode, initialPagePath, height, className, }: BrowserPlaygroundProps): React.ReactElement;
-export default BrowserPlayground;