@almadar/ui 2.13.3 → 2.14.0

package/dist/runtime/index.d.ts

@@ -1,280 +0,0 @@
-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 };

package/dist/stores/index.d.ts

@@ -1,151 +0,0 @@
-/**
- * Entity Filtering Utilities
- *
- * Provides filter types and utility functions for filtering entity records.
- * Used by EntityStore and can be imported by runtime preview.
- */
-/** Filter value for a single field (entity filtering) */
-interface EntityFilterValue {
-    /** The field key (may include suffix like _from, _to for date ranges) */
-    field: string;
-    /** The actual record field to compare against (defaults to field if not specified) */
-    targetField?: string;
-    value: unknown;
-    /** Comparison operator for filtering
-     * - eq: exact match (default)
-     * - contains: substring match for strings
-     * - in: value is in array
-     * - date_eq: same date (ignoring time)
-     * - date_gte: on or after date
-     * - date_lte: on or before date
-     */
-    operator?: FilterOperator;
-}
-/** Operator type for filter */
-type FilterOperator = 'eq' | 'contains' | 'in' | 'date_eq' | 'date_gte' | 'date_lte' | 'search';
-/** Filter state for an entity - Map of field key to filter value */
-type EntityFilters = Map<string, EntityFilterValue>;
-/** Record type that can be filtered */
-interface FilterableRecord {
-    id: string;
-    [key: string]: unknown;
-}
-/**
- * Extract date part from ISO string or Date object.
- * Returns format: "YYYY-MM-DD"
- */
-declare function getDateString(value: unknown): string | null;
-/**
- * Apply a single filter to check if a record matches.
- * Returns true if the record passes the filter.
- */
-declare function matchesFilter(record: FilterableRecord, filter: EntityFilterValue): boolean;
-/**
- * Apply all filters to a list of records.
- * Returns only records that match ALL filters.
- */
-declare function applyFilters<T extends FilterableRecord>(records: T[], entityFilters: EntityFilters): T[];
-/**
- * Create a filter value with proper defaults.
- */
-declare function createFilter(field: string, value: unknown, operator?: FilterOperator, targetField?: string): EntityFilterValue;
-
-/**
- * Entity Store
- *
- * Simple module-level store for runtime entities.
- * No providers needed - hooks import and use directly.
- *
- * NOTE: Mutations create new Map instances to trigger React rerenders
- * when using useSyncExternalStore.
- */
-
-interface Entity {
-    id: string;
-    type: string;
-    [key: string]: unknown;
-}
-type Listener = () => void;
-/**
- * Subscribe to store changes
- */
-declare function subscribe(listener: Listener): () => void;
-/**
- * Get all entities
- */
-declare function getEntities(): Map<string, Entity>;
-/**
- * Get entity by ID
- */
-declare function getEntity(id: string): Entity | undefined;
-/**
- * Get entities by type
- */
-declare function getByType(type: string | string[]): Entity[];
-/**
- * Get all entities as array
- */
-declare function getAllEntities(): Entity[];
-/**
- * Get singleton entity by type (first of that type)
- */
-declare function getSingleton(type: string): Entity | undefined;
-/**
- * Spawn a new entity
- */
-declare function spawnEntity(config: {
-    type: string;
-    id?: string;
-    [key: string]: unknown;
-}): string;
-/**
- * Update an entity
- */
-declare function updateEntity(id: string, updates: Partial<Entity>): void;
-/**
- * Update singleton entity by type
- */
-declare function updateSingleton(type: string, updates: Partial<Entity>): void;
-/**
- * Remove an entity
- */
-declare function removeEntity(id: string): void;
-/**
- * Clear all entities
- */
-declare function clearEntities(): void;
-/**
- * Set a filter for an entity type
- * @param entityType - The entity type to filter (e.g., "Player", "Enemy")
- * @param field - The filter key (e.g., 'status' or 'date_from')
- * @param value - The filter value
- * @param operator - The comparison operator
- * @param targetField - The actual record field to compare (defaults to field)
- */
-declare function setFilter(entityType: string, field: string, value: unknown, operator?: FilterOperator, targetField?: string): void;
-/**
- * Clear a specific filter
- */
-declare function clearFilter(entityType: string, field: string): void;
-/**
- * Clear all filters for an entity type
- */
-declare function clearAllFilters(entityType: string): void;
-/**
- * Get active filters for an entity type
- */
-declare function getFilters(entityType: string): EntityFilters;
-/**
- * Get entities by type with optional filtering
- */
-declare function getByTypeFiltered(type: string | string[]): Entity[];
-/**
- * Get snapshot for React useSyncExternalStore
- */
-declare function getSnapshot(): Map<string, Entity>;
-/**
- * Get filter snapshot for React useSyncExternalStore
- */
-declare function getFilterSnapshot(): Map<string, EntityFilters>;
-
-export { type Entity, type EntityFilterValue, type EntityFilters, type FilterOperator, type FilterableRecord, applyFilters, clearAllFilters, clearEntities, clearFilter, createFilter, getAllEntities, getByType, getByTypeFiltered, getDateString, getEntities, getEntity, getFilterSnapshot, getFilters, getSingleton, getSnapshot, matchesFilter, removeEntity, setFilter, spawnEntity, subscribe, updateEntity, updateSingleton };

package/dist/useUISlots-BBjNvQtb.d.ts

@@ -1,85 +0,0 @@
-/**
- * Valid UI slot names
- */
-type UISlot = 'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'center' | 'toast' | 'hud-top' | 'hud-bottom' | 'hud-left' | 'hud-right' | 'floating';
-/**
- * Animation types for slot transitions
- */
-type SlotAnimation = 'fade' | 'slide' | 'scale' | 'none';
-/**
- * Content rendered in a slot
- */
-interface SlotContent {
-    /** Unique ID for this content */
-    id: string;
-    /** Pattern/component type to render */
-    pattern: string;
-    /** Props to pass to the pattern component */
-    props: Record<string, unknown>;
-    /** Priority for conflict resolution (higher wins) */
-    priority: number;
-    /** Animation for showing/hiding */
-    animation?: SlotAnimation;
-    /** Auto-dismiss timestamp (for toasts) */
-    autoDismissAt?: number;
-    /** Callback when dismissed */
-    onDismiss?: () => void;
-    /** Source trait that rendered this content */
-    sourceTrait?: string;
-}
-/**
- * Configuration for render_ui effect
- */
-interface RenderUIConfig {
-    /** Target slot */
-    target: UISlot;
-    /** Pattern/component to render */
-    pattern: string;
-    /** Props for the pattern */
-    props?: Record<string, unknown>;
-    /** Priority (default: 0) */
-    priority?: number;
-    /** Animation type */
-    animation?: SlotAnimation;
-    /** Auto-dismiss after ms (for toasts) */
-    autoDismissMs?: number;
-    /** Callback on dismiss */
-    onDismiss?: () => void;
-    /** Source trait name */
-    sourceTrait?: string;
-}
-/**
- * Callback for slot changes
- */
-type SlotChangeCallback = (slot: UISlot, content: SlotContent | null) => void;
-/**
- * UI Slot Manager interface
- */
-interface UISlotManager {
-    /** Current content for each slot */
-    slots: Record<UISlot, SlotContent | null>;
-    /** Render content to a slot */
-    render: (config: RenderUIConfig) => string;
-    /** Clear a specific slot */
-    clear: (slot: UISlot) => void;
-    /** Clear content by ID */
-    clearById: (id: string) => void;
-    /** Clear all slots */
-    clearAll: () => void;
-    /** Subscribe to slot changes */
-    subscribe: (callback: SlotChangeCallback) => () => void;
-    /** Check if a slot has content */
-    hasContent: (slot: UISlot) => boolean;
-    /** Get content for a slot */
-    getContent: (slot: UISlot) => SlotContent | null;
-}
-declare const DEFAULT_SLOTS: Record<UISlot, SlotContent | null>;
-/**
- * Create a UI Slot Manager instance.
- *
- * This is the internal hook that creates the manager.
- * Use `useUISlots()` from context in components.
- */
-declare function useUISlotManager(): UISlotManager;
-
-export { DEFAULT_SLOTS as D, type RenderUIConfig as R, type SlotContent as S, type UISlotManager as U, type UISlot as a, type SlotAnimation as b, type SlotChangeCallback as c, useUISlotManager as u };