@almadar/ui 5.111.0 → 5.113.0

package/dist/renderer/index.d.ts

@@ -1,28 +1,343 @@
+import { M as MappedPattern, C as ClientEffect, q as ClientEffectExecutorConfig, r as NotifyOptions, D as DataContext, s as DataResolution, S as SlotDefinition } from '../offline-executor-aRuNznZx.js';
+export { E as EventResponse, N as NavigationContextValue, b as NavigationProvider, c as NavigationProviderProps, d as NavigationState, O as OfflineExecutor, t as OfflineExecutorConfig, v as OfflineExecutorState, P as PendingSyncEffect, w as SlotType, a as UseOfflineExecutorOptions, U as UseOfflineExecutorResult, x as createOfflineExecutor, e as extractRouteParams, f as findPageByName, g as findPageByPath, h as getAllPages, i as getDefaultPage, m as matchPath, p as pathMatches, u as useActivePage, j as useInitPayload, k as useNavigateTo, l as useNavigation, n as useNavigationId, o as useNavigationState, y as useOfflineExecutor } from '../offline-executor-aRuNznZx.js';
+import { PatternPropDef } from '@almadar/core/patterns';
+import { PatternConfig, FieldValue, EntityRow, UISlot } from '@almadar/core';
+export { PatternConfig, UISlot } from '@almadar/core';
+import * as React from 'react';
+
 /**
- * Shared Renderer Module
+ * Pattern Resolver
  *
- * Provides unified rendering logic for both Builder preview and compiled shells.
- * This is the core of the runtime unification - both systems use this same code.
+ * Resolves pattern configurations to component information.
+ * Uses the central pattern registry and component mapping from orbital-shared/patterns/.
  *
- * Key components:
- * - Types: Shared type definitions for effects, patterns, responses
- * - Pattern Resolver: Pattern → Component resolution
- * - Client Effect Executor: Execute clientEffects from server
- * - useClientEffects: React hook for effect execution
- * - Data Resolver: Entity data resolution with filtering
- * - Slot Definitions: Inline vs portal slot configuration
+ * This is the shared logic used by both Builder's PatternRenderer and
+ * the compiled shell's UISlotRenderer.
  *
  * @packageDocumentation
  */
-export type { ClientEffect, NotifyOptions, ClientEffectExecutorConfig, PatternConfig, MappedPattern, EventResponse, UISlot, SlotType, SlotDefinition, DataContext, DataResolution, } from '../types/renderer-types';
-export { resolvePattern, isKnownPattern, getKnownPatterns, getPatternsByCategory, getPatternMapping, getPatternDefinition, initializePatternResolver, setComponentMapping, setPatternRegistry, } from '../lib/pattern-resolver';
-export { executeClientEffects, parseClientEffect, parseClientEffects, getRenderUIEffects, getNotifyEffects, } from '../lib/client-effect-executor';
-export { useClientEffects, useClientEffectConfig, useClientEffectConfigOptional, ClientEffectConfigProvider, ClientEffectConfigContext, } from '../hooks/useClientEffects';
-export type { UseClientEffectsOptions, UseClientEffectsResult, } from '../hooks/useClientEffects';
-export { resolveEntityData, resolveEntityDataWithQuery, resolveEntityById, hasEntities, } from '../lib/data-resolver';
-export { SLOT_DEFINITIONS, getSlotDefinition, isPortalSlot, getInlineSlots, ALL_SLOTS, } from '../lib/slot-definitions';
-export { OfflineExecutor, createOfflineExecutor, useOfflineExecutor, } from '../lib/offline-executor';
-export type { PendingSyncEffect, OfflineExecutorConfig, OfflineExecutorState, UseOfflineExecutorOptions, UseOfflineExecutorResult, } from '../lib/offline-executor';
-export { NavigationProvider, useNavigation, useNavigateTo, useNavigationState, useInitPayload, useActivePage, useNavigationId, matchPath, extractRouteParams, pathMatches, findPageByPath, findPageByName, getDefaultPage, getAllPages, } from '../providers/navigation';
-export type { NavigationState, NavigationContextValue, NavigationProviderProps, } from '../providers/navigation';
-export { initializePatterns } from '../lib/init';
+
+/**
+ * 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' }],
+ *     ['notify', 'Tasks loaded!', { type: 'success' }]
+ *   ],
+ *   {
+ *     renderToSlot: (slot, pattern) => slotManager.render(slot, pattern),
+ *     navigate: (path) => router.push(path),
+ *     notify: (message, opts) => toast.show(message, opts),
+ *     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]>;
+/**
+ * Get all notify effects.
+ */
+declare function getNotifyEffects(effects: ClientEffect[]): Array<['notify', string, NotifyOptions?]>;
+
+/**
+ * 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' | '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, ClientEffect, ClientEffectConfigContext, ClientEffectConfigProvider, ClientEffectExecutorConfig, DataContext, DataResolution, MappedPattern, NotifyOptions, SLOT_DEFINITIONS, SlotDefinition, type UseClientEffectsOptions, type UseClientEffectsResult, executeClientEffects, getInlineSlots, getKnownPatterns, getNotifyEffects, getPatternDefinition, getPatternMapping, getPatternsByCategory, getRenderUIEffects, getSlotDefinition, hasEntities, initializePatternResolver, initializePatterns, isKnownPattern, isPortalSlot, parseClientEffect, parseClientEffects, resolveEntityById, resolveEntityData, resolveEntityDataWithQuery, resolvePattern, setComponentMapping, setPatternRegistry, useClientEffectConfig, useClientEffectConfigOptional, useClientEffects };

package/dist/renderer/index.js

@@ -1,7 +1,7 @@
 import { createLogger } from '@almadar/logger';
 import { createContext, useRef, useCallback, useEffect, useContext, useState } from 'react';
 export { NavigationProvider, extractRouteParams, findPageByName, findPageByPath, getAllPages, getDefaultPage, matchPath, pathMatches, useActivePage, useInitPayload, useNavigateTo, useNavigation, useNavigationId, useNavigationState } from '@almadar/ui/providers';
-import { componentMapping as componentMapping$1, patternsRegistry } from '@almadar/patterns';
+import { componentMapping as componentMapping$1, patternsRegistry } from '@almadar/core/patterns';
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;