@almadar/ui 2.13.3 → 2.15.0

package/dist/runtime/index.d.ts

@@ -1,280 +1,15 @@
-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
+ * @almadar/ui Runtime
  *
- * 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.
+ * Client-side runtime components for rendering Orbital schemas.
+ * Provides trait state machines, slot management, and pattern rendering.
  *
  * @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 };
+export { useTraitStateMachine, type UseTraitStateMachineOptions, type TraitStateMachineResult } from './useTraitStateMachine';
+export { useResolvedSchema, type ResolvedSchemaResult, clearSchemaCache } from './useResolvedSchema';
+export { EntitySchemaProvider, useEntitySchema, useEntityDefinition, type EntitySchemaContextValue, type EntitySchemaProviderProps, } from './EntitySchemaContext';
+export { TraitProvider, TraitContext, useTraitContext, useTrait, type TraitContextValue, type TraitInstance, type TraitProviderProps, } from './TraitProvider';
+export { SlotsProvider, useSlots, useSlotContent, useSlotsActions, type SlotsState, type SlotState, type SlotPatternEntry, type SlotSource, type SlotsActions, type SlotsProviderProps, } from './ui/SlotsContext';
+export { createClientEffectHandlers, type ClientEventBus, type SlotSetter, type CreateClientEffectHandlersOptions, } from './createClientEffectHandlers';
+export type { ResolvedTraitBinding, ResolvedTrait, ResolvedEntity, ResolvedPage, ResolvedIR, } from './types';

package/dist/runtime/index.js

@@ -1,14 +1,14 @@
-import '../chunk-PERGHHON.js';
+import '../chunk-IRIGCHP4.js';
 import '../chunk-N7MVUW4R.js';
-import { registerTrait, unregisterTrait, updateTraitState } from '../chunk-42YQ6JVR.js';
 import '../chunk-3HJHHULT.js';
-import { useFetchedDataContext } from '../chunk-UNDQO6DL.js';
-import '../chunk-MSLMORZK.js';
+import { useFetchedDataContext } from '../chunk-4KP6IZEQ.js';
+import '../chunk-YPY74G7F.js';
+import '../chunk-4N3BAPDB.js';
 import '../chunk-DKQN5FVU.js';
-import '../chunk-Y7IHEYYE.js';
+import '../chunk-QU2X55WH.js';
 import { useEventBus } from '../chunk-YXZM3WCF.js';
 import '../chunk-3JGAROCW.js';
-import { recordTransition } from '../chunk-WCTZ7WZX.js';
+import { registerTrait, unregisterTrait, updateTraitState, recordTransition } from '../chunk-XL7WB2O5.js';
 import '../chunk-2XXSUIOK.js';
 import '../chunk-K2D5D3WK.js';
 import '../chunk-PKBMQBKP.js';

package/dist/runtime/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * OrbitalRuntime Types
+ *
+ * Re-exports IR types from @almadar/core.
+ * This ensures runtime uses the same types as the compiler.
+ *
+ * @packageDocumentation
+ */
+export type { TransitionFrom, ResolvedField, ResolvedEntity, ResolvedEntityBinding, ResolvedTraitState, ResolvedTraitEvent, ResolvedTraitTransition, ResolvedTraitGuard, ResolvedTraitTick, ResolvedTraitListener, ResolvedTraitDataEntity, ResolvedTraitUIBinding, ResolvedTrait, ResolvedTraitBinding, ResolvedPattern, ResolvedSectionEvent, ResolvedSection, ResolvedNavigation, ResolvedPage, ResolvedIR, } from '@almadar/core';
+export { createEmptyResolvedTrait, createEmptyResolvedPage, createResolvedField, inferTsType, isResolvedIR, } from '@almadar/core';

package/dist/runtime/ui/SlotsContext.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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
+ */
+import React from 'react';
+import type { PatternConfig } from '@almadar/core';
+import type { ResolvedTrait } from '@almadar/core';
+/** A single pattern entry in a slot */
+export interface SlotPatternEntry {
+    pattern: PatternConfig;
+    props: Record<string, unknown>;
+}
+/**
+ * Source metadata for a rendered slot.
+ * Used by the Slot Inspector to show debug info.
+ */
+export interface SlotSource {
+    trait: string;
+    state: string;
+    transition: string;
+    effects?: unknown[];
+    /** Full trait definition for inspector */
+    traitDefinition?: ResolvedTrait;
+}
+/** Full state of a single slot */
+export interface SlotState {
+    patterns: SlotPatternEntry[];
+    source?: SlotSource;
+}
+/** All slots state */
+export type SlotsState = Record<string, SlotState>;
+/** Mutation functions for slots (stable references, won't trigger re-renders) */
+export 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;
+}
+export interface SlotsProviderProps {
+    children: React.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.
+ */
+export declare function SlotsProvider({ children }: SlotsProviderProps): React.ReactElement;
+/**
+ * Get the full slots state. Triggers re-render on ANY slot change.
+ * Prefer useSlotContent(name) for individual slot subscriptions.
+ */
+export declare function useSlots(): SlotsState;
+/**
+ * Get content for a specific slot. Returns null if slot is empty.
+ */
+export declare function useSlotContent(slotName: string): SlotState | null;
+/**
+ * Get slot mutation actions. Stable reference — never triggers re-renders.
+ */
+export declare function useSlotsActions(): SlotsActions;

package/dist/runtime/useResolvedSchema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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
+ */
+import type { OrbitalSchema } from '@almadar/core';
+import type { ResolvedIR, ResolvedPage, ResolvedTrait, ResolvedEntity, ResolvedTraitBinding } from './types';
+export 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
+ */
+export declare function useResolvedSchema(schema: OrbitalSchema | null | undefined, pageName?: string): ResolvedSchemaResult;
+/**
+ * Clear the schema resolution cache
+ */
+export declare function clearSchemaCache(): void;

package/dist/runtime/useTraitStateMachine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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
+ */
+import { type TraitState } from '@almadar/runtime';
+import type { ResolvedTraitBinding } from './types';
+import type { SlotsActions } from './ui/SlotsContext';
+export type { TraitState };
+export 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;
+}
+export 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.
+ */
+export declare function useTraitStateMachine(traitBindings: ResolvedTraitBinding[], slotsActions: SlotsActions, options?: UseTraitStateMachineOptions): TraitStateMachineResult;
+export default useTraitStateMachine;

package/dist/scripts/generate-design-system.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Unified Design System Generator
+ *
+ * Generates a complete client-specific design system from an .orb schema:
+ * 1. Generates custom theme CSS
+ * 2. Suggests domain-specific components
+ * 3. Generates component stubs
+ * 4. Builds Storybook documentation
+ * 5. Exports static design system package
+ */
+interface GeneratorOptions {
+    schemaPath: string;
+    outputDir: string;
+    clientName?: string;
+    buildStorybook?: boolean;
+    generateComponents?: boolean;
+    clientOnly?: boolean;
+}
+interface GeneratorResult {
+    themePath: string;
+    suggestedComponents: number;
+    generatedComponents: number;
+    storybookPath?: string;
+}
+/**
+ * Main generator function
+ */
+export declare function generateDesignSystem(options: GeneratorOptions): Promise<GeneratorResult>;
+export {};

package/dist/scripts/generate-theme-from-schema.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Theme Generator from OrbitalSchema
+ *
+ * Analyzes an .orb schema file and generates a client-specific theme CSS file.
+ * The theme is derived from the domain, entity names, and any explicit style hints.
+ */
+/**
+ * Main function to generate theme from schema
+ */
+export declare function generateThemeFromSchema(schemaPath: string, outputPath?: string): string;

package/dist/scripts/generate.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env npx tsx
+/**
+ * Design System Generator
+ *
+ * Reads a config file from a project folder and outputs a customized
+ * design system to that project.
+ *
+ * Usage:
+ *   npx tsx generate.ts --config <path-to-config>
+ *   npm run generate -- --config ../../projects/winning-11/design-system.config.ts
+ */
+export {};

package/dist/scripts/suggest-components.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Component Suggester
+ *
+ * Analyzes an .orb schema and suggests domain-specific components
+ * that should be added to the design system for this client.
+ */
+interface ComponentSuggestion {
+    name: string;
+    description: string;
+    category: 'atoms' | 'molecules' | 'organisms' | 'templates';
+    props: Array<{
+        name: string;
+        type: string;
+        description: string;
+    }>;
+    reasoning: string;
+    priority: 'high' | 'medium' | 'low';
+    codeSketch: string;
+}
+/**
+ * Suggest components based on schema analysis
+ */
+export declare function suggestComponents(schemaPath: string): {
+    domains: string[];
+    suggestions: ComponentSuggestion[];
+};
+/**
+ * Generate component stubs from suggestions
+ */
+export declare function generateComponentStubs(suggestions: ComponentSuggestion[], outputDir: string): void;
+export {};