@almadar/ui 2.7.0 → 2.9.0

package/dist/runtime/index.d.ts

@@ -0,0 +1,280 @@
+import { TraitState, EffectHandlers } from '@almadar/runtime';
+import { PatternConfig, ResolvedTrait, ResolvedTraitBinding, ResolvedPage, ResolvedEntity, ResolvedIR, OrbitalSchema } from '@almadar/core';
+export { ResolvedEntity, ResolvedIR, ResolvedPage, ResolvedTrait, ResolvedTraitBinding } from '@almadar/core';
+import React__default from 'react';
+
+/**
+ * SlotsContext - React state-based UI slot management
+ *
+ * Replaces the UIEnvironment observable store with plain React state.
+ * No stacking logic, no priority system, no source tracking for arbitration.
+ *
+ * A transition's effects produce the COMPLETE content for each slot.
+ * The runtime collects all render-ui effects from a transition, groups by slot,
+ * and sets each slot's patterns array in one atomic operation.
+ *
+ * @packageDocumentation
+ */
+
+/** A single pattern entry in a slot */
+interface SlotPatternEntry {
+    pattern: PatternConfig;
+    props: Record<string, unknown>;
+}
+/**
+ * Source metadata for a rendered slot.
+ * Used by the Slot Inspector to show debug info.
+ */
+interface SlotSource {
+    trait: string;
+    state: string;
+    transition: string;
+    effects?: unknown[];
+    /** Full trait definition for inspector */
+    traitDefinition?: ResolvedTrait;
+}
+/** Full state of a single slot */
+interface SlotState {
+    patterns: SlotPatternEntry[];
+    source?: SlotSource;
+}
+/** All slots state */
+type SlotsState = Record<string, SlotState>;
+/** Mutation functions for slots (stable references, won't trigger re-renders) */
+interface SlotsActions {
+    /** Set all patterns for a slot atomically (replaces previous content) */
+    setSlotPatterns: (slot: string, patterns: SlotPatternEntry[], source?: SlotSource) => void;
+    /** Clear a single slot */
+    clearSlot: (slot: string) => void;
+    /** Clear all slots */
+    clearAllSlots: () => void;
+}
+interface SlotsProviderProps {
+    children: React__default.ReactNode;
+}
+/**
+ * SlotsProvider - Manages UI slot state via React useState.
+ *
+ * Replaces UIEnvironmentProvider. No observable store, no stacking logic.
+ * Slots are set atomically per transition — React diffs and re-renders.
+ */
+declare function SlotsProvider({ children }: SlotsProviderProps): React__default.ReactElement;
+/**
+ * Get the full slots state. Triggers re-render on ANY slot change.
+ * Prefer useSlotContent(name) for individual slot subscriptions.
+ */
+declare function useSlots(): SlotsState;
+/**
+ * Get content for a specific slot. Returns null if slot is empty.
+ */
+declare function useSlotContent(slotName: string): SlotState | null;
+/**
+ * Get slot mutation actions. Stable reference — never triggers re-renders.
+ */
+declare function useSlotsActions(): SlotsActions;
+
+/**
+ * useTraitStateMachine Hook
+ *
+ * Manages trait state machines with event-driven transitions.
+ * Subscribes to eventBus events and executes effects when transitions occur.
+ *
+ * CONSOLIDATED RUNTIME:
+ * - Uses StateMachineManager from @almadar/runtime for state management
+ * - Uses the same state machine logic as the server runtime (OrbitalServerRuntime)
+ * - Ensures consistent behavior between client preview and server execution
+ *
+ * SLOT MANAGEMENT:
+ * - Collects all render-ui effects from a transition, groups by slot
+ * - Sets each slot's patterns array atomically via SlotsActions
+ * - No stacking logic, no priority system — transition produces complete slot content
+ *
+ * @packageDocumentation
+ */
+
+interface TraitStateMachineResult {
+    /** Current state for each trait */
+    traitStates: Map<string, TraitState>;
+    /** Send an event to trigger a transition */
+    sendEvent: (eventKey: string, payload?: Record<string, unknown>) => void;
+    /** Get current state for a specific trait */
+    getTraitState: (traitName: string) => TraitState | undefined;
+    /** Check if a trait can handle an event from its current state */
+    canHandleEvent: (traitName: string, eventKey: string) => boolean;
+}
+interface UseTraitStateMachineOptions {
+    /** Callback invoked after each event is processed (for server forwarding) */
+    onEventProcessed?: (eventKey: string, payload?: Record<string, unknown>) => void;
+    /** Router navigate function for navigate effects */
+    navigate?: (path: string, params?: Record<string, unknown>) => void;
+    /** Notification function for notify effects */
+    notify?: (message: string, type?: 'success' | 'error' | 'warning' | 'info') => void;
+}
+/**
+ * useTraitStateMachine - Manages state machines for multiple traits
+ *
+ * Uses the shared StateMachineManager for consistent behavior with server runtime.
+ * Collects render-ui effects per transition and sets slot content atomically.
+ */
+declare function useTraitStateMachine(traitBindings: ResolvedTraitBinding[], slotsActions: SlotsActions, options?: UseTraitStateMachineOptions): TraitStateMachineResult;
+
+/**
+ * useResolvedSchema Hook
+ *
+ * Resolves OrbitalSchema to IR for the OrbitalRuntime.
+ * Uses the shared resolver to ensure consistency with the compiler.
+ *
+ * TRAIT-DRIVEN ARCHITECTURE:
+ * - Pages have traits, NOT sections
+ * - UI is produced by trait effects (render_ui)
+ * - No backwards compatibility with legacy formats
+ *
+ * @packageDocumentation
+ */
+
+interface ResolvedSchemaResult {
+    /** The resolved page (or undefined if not found) */
+    page: ResolvedPage | undefined;
+    /** Trait bindings for this page */
+    traits: ResolvedTraitBinding[];
+    /** Entities used by this page */
+    entities: Map<string, ResolvedEntity>;
+    /** All entities from schema */
+    allEntities: Map<string, ResolvedEntity>;
+    /** All resolved traits */
+    allTraits: Map<string, ResolvedTrait>;
+    /** Loading state */
+    loading: boolean;
+    /** Error message if resolution failed */
+    error: string | null;
+    /** Full IR (for debugging) */
+    ir: ResolvedIR | null;
+}
+/**
+ * Hook to resolve an OrbitalSchema to IR.
+ *
+ * @param schema - The OrbitalSchema to resolve
+ * @param pageName - Optional page name (defaults to first page or initial page)
+ * @returns Resolved schema data including page, traits, and entities
+ */
+declare function useResolvedSchema(schema: OrbitalSchema | null | undefined, pageName?: string): ResolvedSchemaResult;
+/**
+ * Clear the schema resolution cache
+ */
+declare function clearSchemaCache(): void;
+
+/**
+ * EntitySchemaContext
+ *
+ * Minimal context providing entity schema definitions (field metadata).
+ * This is NOT a data store - data comes from FetchedDataContext via server.
+ *
+ * Replaces EntityStore's schema functionality without the mock data generation.
+ *
+ * @packageDocumentation
+ */
+
+interface EntitySchemaContextValue {
+    /** Entity definitions (schema metadata only) */
+    entities: Map<string, ResolvedEntity>;
+}
+interface EntitySchemaProviderProps {
+    /** Entity definitions from resolved schema */
+    entities: ResolvedEntity[];
+    /** Children */
+    children: React__default.ReactNode;
+}
+/**
+ * Provides entity schema definitions to the component tree.
+ *
+ * This is a lightweight provider that only holds schema metadata (field definitions).
+ * Actual entity data comes from FetchedDataContext via server responses.
+ */
+declare function EntitySchemaProvider({ entities, children, }: EntitySchemaProviderProps): React__default.ReactElement;
+/**
+ * Access entity schema definitions.
+ * Use this for field metadata (form building, filter enrichment).
+ * For actual data, use useFetchedDataContext.
+ */
+declare function useEntitySchema(): EntitySchemaContextValue;
+/**
+ * Get a specific entity's schema definition.
+ */
+declare function useEntityDefinition(entityName: string): ResolvedEntity | undefined;
+
+/**
+ * TraitProvider Component
+ *
+ * Provides trait state machines to child components via React context.
+ *
+ * @packageDocumentation
+ */
+
+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?: Record<string, unknown>) => void;
+    /** Check if an event can be dispatched */
+    canDispatch: (eventKey: string) => boolean;
+    /** Get the full trait definition */
+    trait: ResolvedTrait;
+}
+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?: Record<string, unknown>) => void;
+    /** Check if an event can be dispatched to a trait */
+    canDispatch: (traitName: string, eventKey: string) => boolean;
+}
+declare const TraitContext: React__default.Context<TraitContextValue | null>;
+interface TraitProviderProps {
+    /** Trait bindings for this page */
+    traits: ResolvedTraitBinding[];
+    /** Entity map for context */
+    entities: Map<string, ResolvedEntity>;
+    /** Children to render */
+    children: React__default.ReactNode;
+}
+declare function TraitProvider({ traits: traitBindings, children, }: TraitProviderProps): React__default.ReactElement;
+/**
+ * Access the trait context from within the TraitProvider.
+ */
+declare function useTraitContext(): TraitContextValue;
+/**
+ * Access a specific trait instance.
+ */
+declare function useTrait(traitName: string): TraitInstance | undefined;
+
+/**
+ * Client Effect Handlers Factory
+ *
+ * Creates the standard effect handler set for client-side trait execution.
+ *
+ * @packageDocumentation
+ */
+
+interface ClientEventBus {
+    emit: (type: string, payload?: Record<string, unknown>) => void;
+}
+interface SlotSetter {
+    addPattern: (slot: string, pattern: unknown, props?: Record<string, unknown>) => void;
+    clearSlot: (slot: string) => void;
+}
+interface CreateClientEffectHandlersOptions {
+    eventBus: ClientEventBus;
+    slotSetter: SlotSetter;
+    navigate?: (path: string, params?: Record<string, unknown>) => void;
+    notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;
+    enrichPattern?: (pattern: unknown) => unknown;
+}
+declare function createClientEffectHandlers(options: CreateClientEffectHandlersOptions): EffectHandlers;
+
+export { type ClientEventBus, type CreateClientEffectHandlersOptions, type EntitySchemaContextValue, EntitySchemaProvider, type EntitySchemaProviderProps, type ResolvedSchemaResult, type SlotPatternEntry, type SlotSetter, type SlotSource, type SlotState, type SlotsActions, SlotsProvider, type SlotsProviderProps, type SlotsState, TraitContext, type TraitContextValue, type TraitInstance, TraitProvider, type TraitProviderProps, type TraitStateMachineResult, type UseTraitStateMachineOptions, clearSchemaCache, createClientEffectHandlers, useEntityDefinition, useEntitySchema, useResolvedSchema, useSlotContent, useSlots, useSlotsActions, useTrait, useTraitContext, useTraitStateMachine };