@almadar/shell-web 0.0.0-stage → 1.0.0

package/dist/renderer/index.d.ts

@@ -0,0 +1,465 @@
+import { PatternConfig, FieldValue, EntityRow, UISlot } from '@almadar/core';
+export { PatternConfig, UISlot } from '@almadar/core';
+import { PatternPropDef } from '@almadar/core/patterns';
+import * as React from 'react';
+
+/**
+ * Shared Renderer Types
+ *
+ * Type definitions used by both Builder and compiled shells for
+ * the dual execution model. These types define the contract between
+ * server and client for effect execution.
+ *
+ * @packageDocumentation
+ */
+
+type ClientEffect = ['render-ui', string, PatternConfig | null] | ['navigate', string, Record<string, FieldValue>?] | ['emit', string, FieldValue?];
+/**
+ * Resolved pattern with component information from component-mapping.json
+ */
+interface MappedPattern {
+    /** Component name (e.g., 'DataTable') */
+    component: string;
+    /** Import path for the component */
+    importPath: string;
+    /** Pattern category (e.g., 'display', 'form') */
+    category: string;
+    /** Validated and normalized props */
+    validatedProps: Record<string, FieldValue>;
+}
+/**
+ * Response from server after processing an event.
+ * This is the unified response format for both Builder and compiled shells.
+ */
+interface EventResponse {
+    /** Whether the event was processed successfully */
+    success: boolean;
+    /** New state after transition (if transition occurred) */
+    newState?: string;
+    /** Data fetched by server effects (e.g., { Task: [...] }) */
+    data?: Record<string, EntityRow[]>;
+    /** Results of individual effect executions (for debugging) */
+    effectResults?: Array<{
+        effect: string;
+        success: boolean;
+        data?: FieldValue;
+        error?: string;
+    }>;
+    /** Error message if success is false */
+    error?: string;
+}
+/**
+ * Configuration for the client effect executor.
+ * Provides implementations for each effect type.
+ */
+interface ClientEffectExecutorConfig {
+    /**
+     * Render a pattern to a slot.
+     * Called for 'render-ui' effects.
+     */
+    renderToSlot: (slot: string, pattern: PatternConfig | null) => void;
+    /**
+     * Navigate to a route.
+     * Called for 'navigate' effects.
+     */
+    navigate: (path: string, params?: Record<string, FieldValue>) => void;
+    /**
+     * Emit an event to the event bus.
+     * Called for 'emit' effects.
+     */
+    eventBus: {
+        emit: (event: string, payload?: FieldValue) => void;
+    };
+    /**
+     * Optional: Data from server response for render-ui.
+     * Components can use this to access fetched entity data.
+     */
+    data?: Record<string, EntityRow[]>;
+    /**
+     * Optional: Callback when all effects have been executed.
+     */
+    onComplete?: () => void;
+}
+/**
+ * Slot type classification
+ */
+type SlotType = 'inline' | 'portal';
+/**
+ * Definition of a slot including its rendering behavior
+ */
+interface SlotDefinition {
+    /** Slot name */
+    name: UISlot;
+    /** Whether to render inline or via portal */
+    type: SlotType;
+    /** For portal slots: where to render (default: document.body) */
+    portalTarget?: string;
+    /** Z-index for portal slots */
+    zIndex?: number;
+    /**
+     * A notification surface (toast): an embedded trait's render here shows in
+     * the slot itself, never as its host frame's content. Every other slot's
+     * render of an embedded trait IS its frame content.
+     */
+    notification?: boolean;
+}
+/**
+ * Context for resolving entity data.
+ * Supports multiple data sources with priority.
+ */
+interface DataContext {
+    /** Server-provided data (highest priority) */
+    fetchedData?: Record<string, EntityRow[]>;
+    /** In-memory mock data (for Builder preview) */
+    entityStore?: {
+        getRecords: (entityName: string) => EntityRow[];
+    };
+    /** Query singleton for filtering */
+    querySingleton?: {
+        getFilters: (queryRef: string) => Record<string, FieldValue>;
+    };
+}
+/**
+ * Result of data resolution
+ */
+interface DataResolution {
+    /** Resolved data array */
+    data: EntityRow[];
+    /** Whether data is still loading */
+    loading: boolean;
+    /** Error if resolution failed */
+    error?: Error;
+}
+
+/**
+ * Pattern Resolver
+ *
+ * Resolves pattern configurations to component information.
+ * Uses the central pattern registry and component mapping from orbital-shared/patterns/.
+ *
+ * This is the shared logic used by both Builder's PatternRenderer and
+ * the compiled shell's UISlotRenderer.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Component mapping entry from component-mapping.json
+ */
+interface ComponentMappingEntry {
+    component: string;
+    importPath: string;
+    category: string;
+    deprecated?: boolean;
+    replacedBy?: string;
+}
+/**
+ * Pattern definition from registry.json
+ */
+interface PatternDefinition {
+    type: string;
+    category: string;
+    description: string;
+    propsSchema?: Record<string, PatternPropDef>;
+}
+/**
+ * Initialize the pattern resolver with mappings.
+ * Called at app startup with data from JSON files.
+ */
+declare function initializePatternResolver(config: {
+    componentMapping: Record<string, ComponentMappingEntry>;
+    patternRegistry: Record<string, PatternDefinition>;
+}): void;
+/**
+ * Set component mapping (alternative to full initialization).
+ */
+declare function setComponentMapping(mapping: Record<string, ComponentMappingEntry>): void;
+/**
+ * Set pattern registry (alternative to full initialization).
+ */
+declare function setPatternRegistry(registry: Record<string, PatternDefinition>): void;
+/**
+ * Resolve a pattern configuration to component information.
+ *
+ * @param config - Pattern configuration from render-ui effect
+ * @returns Resolved pattern with component name, import path, and validated props
+ * @throws Error if pattern type is unknown
+ *
+ * @example
+ * ```typescript
+ * const resolved = resolvePattern({
+ *   type: 'entity-table',
+ *   entity: 'Task',
+ *   columns: ['title', 'status']
+ * });
+ * // resolved.component === 'DataTable'
+ * // resolved.importPath === '@/components/organisms/DataTable'
+ * ```
+ */
+declare function resolvePattern(config: PatternConfig): MappedPattern;
+/**
+ * Check if a pattern type is known.
+ */
+declare function isKnownPattern(type: string): boolean;
+/**
+ * Get all known pattern types.
+ */
+declare function getKnownPatterns(): string[];
+/**
+ * Get patterns by category.
+ */
+declare function getPatternsByCategory(category: string): string[];
+/**
+ * Get the component mapping for a pattern type.
+ */
+declare function getPatternMapping(type: string): ComponentMappingEntry | undefined;
+/**
+ * Get the pattern definition from the registry.
+ */
+declare function getPatternDefinition(type: string): PatternDefinition | undefined;
+
+/**
+ * Client Effect Executor
+ *
+ * Executes client effects returned from the server.
+ * This is the core of the dual execution model - the server processes
+ * events and returns client effects, which this module executes.
+ *
+ * Used by both Builder preview and compiled shells.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Execute an array of client effects.
+ *
+ * Effects are executed sequentially in order.
+ * Errors in one effect don't prevent subsequent effects from executing.
+ *
+ * @param effects - Array of client effects to execute
+ * @param config - Configuration providing implementations for each effect type
+ *
+ * @example
+ * ```typescript
+ * executeClientEffects(
+ *   [
+ *     ['render-ui', 'main', { type: 'entity-table', entity: 'Task' }],
+ *     ['emit', 'TASKS_LOADED']
+ *   ],
+ *   {
+ *     renderToSlot: (slot, pattern) => slotManager.render(slot, pattern),
+ *     navigate: (path) => router.push(path),
+ *     eventBus: { emit: (event, payload) => bus.emit(event, payload) }
+ *   }
+ * );
+ * ```
+ */
+declare function executeClientEffects(effects: ClientEffect[], config: ClientEffectExecutorConfig): void;
+/**
+ * Parse a raw effect array into a typed ClientEffect.
+ * Handles unknown effect formats gracefully.
+ */
+declare function parseClientEffect(raw: FieldValue[]): ClientEffect | null;
+/**
+ * Parse an array of raw effects into typed ClientEffects.
+ * Filters out invalid effects.
+ */
+declare function parseClientEffects(raw: FieldValue[] | undefined): ClientEffect[];
+/**
+ * Get all render-ui effects.
+ */
+declare function getRenderUIEffects(effects: ClientEffect[]): Array<['render-ui', string, PatternConfig | null]>;
+
+/**
+ * Options for the useClientEffects hook
+ */
+interface UseClientEffectsOptions extends ClientEffectExecutorConfig {
+    /**
+     * Whether to execute effects. Defaults to true.
+     * Set to false to temporarily disable effect execution.
+     */
+    enabled?: boolean;
+    /**
+     * Debug mode - logs effect execution details.
+     */
+    debug?: boolean;
+}
+/**
+ * Result of useClientEffects hook
+ */
+interface UseClientEffectsResult {
+    /**
+     * Number of effects executed in the last batch.
+     */
+    executedCount: number;
+    /**
+     * Whether effects are currently being executed.
+     */
+    executing: boolean;
+    /**
+     * Manually trigger effect execution.
+     * Useful for imperative control.
+     */
+    execute: (effects: ClientEffect[]) => void;
+}
+/**
+ * Execute client effects from server response.
+ *
+ * This hook automatically executes effects when they change,
+ * tracking which effects have been executed to prevent duplicates.
+ *
+ * @param effects - Array of client effects to execute (from server response)
+ * @param options - Configuration including effect implementations
+ * @returns Hook result with execution state and manual trigger
+ *
+ * @example
+ * ```typescript
+ * function useMyTrait() {
+ *   const [state, setState] = useState({ pendingEffects: [] });
+ *   const effectConfig = useClientEffectConfig();
+ *
+ *   useClientEffects(state.pendingEffects, {
+ *     ...effectConfig,
+ *     onComplete: () => setState(s => ({ ...s, pendingEffects: [] }))
+ *   });
+ *
+ *   // ...
+ * }
+ * ```
+ */
+declare function useClientEffects(effects: ClientEffect[] | undefined, options: UseClientEffectsOptions): UseClientEffectsResult;
+declare const ClientEffectConfigContext: React.Context<ClientEffectExecutorConfig | null>;
+/**
+ * Provider for client effect configuration.
+ */
+declare const ClientEffectConfigProvider: React.Provider<ClientEffectExecutorConfig | null>;
+/**
+ * Hook to get the client effect configuration from context.
+ *
+ * @throws Error if used outside of ClientEffectConfigProvider
+ *
+ * @example
+ * ```typescript
+ * function MyTraitHook() {
+ *   const effectConfig = useClientEffectConfig();
+ *
+ *   useClientEffects(pendingEffects, {
+ *     ...effectConfig,
+ *     onComplete: () => clearPendingEffects()
+ *   });
+ * }
+ * ```
+ */
+declare function useClientEffectConfig(): ClientEffectExecutorConfig;
+/**
+ * Hook to get client effect configuration, returning null if not available.
+ * Use this for optional integration where effects may not be configured.
+ */
+declare function useClientEffectConfigOptional(): ClientEffectExecutorConfig | null;
+
+/**
+ * Data Resolver
+ *
+ * Resolves entity data for pattern rendering.
+ * Supports multiple data sources with priority:
+ * 1. Server-provided data (from EventResponse.data)
+ * 2. Entity store (Builder in-memory mock data)
+ * 3. Empty array (fallback)
+ *
+ * Used by both Builder's PatternRenderer and compiled shell's UISlotRenderer.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Resolve entity data from available sources.
+ *
+ * Priority:
+ * 1. fetchedData (from server response) - highest priority
+ * 2. entityStore (Builder mock data)
+ * 3. Empty array (fallback)
+ *
+ * @param entityName - Name of the entity to resolve data for
+ * @param context - Data context with available sources
+ * @returns Resolved data with loading state
+ *
+ * @example
+ * ```typescript
+ * const { data, loading } = resolveEntityData('Task', {
+ *   fetchedData: response.data,
+ *   entityStore: mockStore
+ * });
+ * ```
+ */
+declare function resolveEntityData(entityName: string, context: DataContext): DataResolution;
+/**
+ * Resolve entity data with query filtering.
+ *
+ * Applies query singleton filters if available.
+ *
+ * @param entityName - Name of the entity
+ * @param queryRef - Optional query reference for filtering
+ * @param context - Data context
+ * @returns Filtered resolved data
+ */
+declare function resolveEntityDataWithQuery(entityName: string, queryRef: string | undefined, context: DataContext): DataResolution;
+/**
+ * Get a single entity record by ID.
+ */
+declare function resolveEntityById(entityName: string, id: string | number, context: DataContext): EntityRow | null;
+/**
+ * Check if any entities exist for a given entity name.
+ */
+declare function hasEntities(entityName: string, context: DataContext): boolean;
+
+/**
+ * Slot Definitions
+ *
+ * Defines the available UI slots and their rendering behavior.
+ * Slots are either inline (rendered in the component tree) or
+ * portal (rendered to document.body via React Portal).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Definitions for all available UI slots.
+ *
+ * Inline slots render within the component hierarchy.
+ * Portal slots render to document.body, breaking out of overflow containers.
+ */
+declare const SLOT_DEFINITIONS: Partial<Record<UISlot, SlotDefinition>> & Record<'main' | 'sidebar' | 'dock' | 'modal' | 'drawer' | 'overlay' | 'center' | 'toast' | 'hud-top' | 'hud-bottom' | 'floating', SlotDefinition>;
+/**
+ * Get the slot definition for a slot name.
+ */
+declare function getSlotDefinition(slot: UISlot): SlotDefinition | undefined;
+/**
+ * Check if a slot is a portal slot.
+ */
+declare function isPortalSlot(slot: string): boolean;
+/**
+ * Get all inline slots.
+ */
+declare function getInlineSlots(): UISlot[];
+/**
+ * All valid slot names.
+ */
+declare const ALL_SLOTS: UISlot[];
+
+/**
+ * Pattern Resolver Initialization
+ *
+ * Loads pattern registry and component mapping from @almadar/core/patterns
+ * and initializes the pattern resolver at app startup.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Initialize the pattern resolver with shared pattern data.
+ * Must be called once at app startup before any pattern rendering.
+ * @returns The number of patterns initialized
+ */
+declare function initializePatterns(): number;
+
+export { ALL_SLOTS, ClientEffectConfigContext, ClientEffectConfigProvider, SLOT_DEFINITIONS, executeClientEffects, getInlineSlots, getKnownPatterns, getPatternDefinition, getPatternMapping, getPatternsByCategory, getRenderUIEffects, getSlotDefinition, hasEntities, initializePatternResolver, initializePatterns, isKnownPattern, isPortalSlot, parseClientEffect, parseClientEffects, resolveEntityById, resolveEntityData, resolveEntityDataWithQuery, resolvePattern, setComponentMapping, setPatternRegistry, useClientEffectConfig, useClientEffectConfigOptional, useClientEffects };
+export type { ClientEffect, ClientEffectExecutorConfig, DataContext, DataResolution, EventResponse, MappedPattern, SlotDefinition, SlotType, UseClientEffectsOptions, UseClientEffectsResult };

package/dist/renderer/index.js

@@ -0,0 +1,4 @@
+"use client";
+export { ClientEffectConfigContext, ClientEffectConfigProvider, executeClientEffects, getKnownPatterns, getPatternDefinition, getPatternMapping, getPatternsByCategory, getRenderUIEffects, hasEntities, initializePatternResolver, initializePatterns, isKnownPattern, parseClientEffect, parseClientEffects, resolveEntityById, resolveEntityData, resolveEntityDataWithQuery, resolvePattern, setComponentMapping, setPatternRegistry, useClientEffectConfig, useClientEffectConfigOptional, useClientEffects } from '../chunk-A2LR6VQQ.js';
+export { ALL_SLOTS, SLOT_DEFINITIONS, getInlineSlots, getSlotDefinition, isPortalSlot } from '../chunk-P4ZFUQFF.js';
+import '../chunk-G7DCAZ22.js';