@almadar/ui 1.0.34 → 2.0.1

package/dist/renderer/init.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pattern Resolver Initialization
+ *
+ * Loads pattern registry and component mapping from orbital-shared/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
+ */
+export declare function initializePatterns(): number;

package/dist/renderer/navigation.d.ts

@@ -0,0 +1,142 @@
+/**
+ * NavigationContext - Schema-Driven Navigation for Orbital Runtime
+ *
+ * Provides navigation within the orbital schema without react-router dependency.
+ * Navigation works by:
+ * 1. Matching path to a page in the schema
+ * 2. Extracting route params (e.g., /inspection/:id → { id: "123" })
+ * 3. Switching active page
+ * 4. Triggering INIT with merged payload
+ *
+ * This approach works whether OrbitalRuntime is standalone or embedded in another app.
+ *
+ * Used by both:
+ * - Builder runtime (interpreted execution)
+ * - Compiled shells (generated applications)
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { OrbitalSchema, OrbitalPage } from '@almadar/core';
+/**
+ * Match a concrete path against a pattern with :param placeholders.
+ * Returns null if no match, or the extracted params if match.
+ *
+ * @example
+ * matchPath('/inspection/:id', '/inspection/123') // { id: '123' }
+ * matchPath('/users/:userId/posts/:postId', '/users/42/posts/7') // { userId: '42', postId: '7' }
+ * matchPath('/about', '/about') // {}
+ * matchPath('/about', '/contact') // null
+ */
+export declare function matchPath(pattern: string, path: string): Record<string, string> | null;
+/**
+ * Extract route params from a path given its pattern.
+ * Wrapper around matchPath for explicit use.
+ */
+export declare function extractRouteParams(pattern: string, path: string): Record<string, string>;
+/**
+ * Check if a path matches a pattern.
+ */
+export declare function pathMatches(pattern: string, path: string): boolean;
+/**
+ * Find a page in the schema by matching its path pattern against a concrete path.
+ * Returns the page and extracted route params.
+ */
+export declare function findPageByPath(schema: OrbitalSchema, path: string): {
+    page: OrbitalPage;
+    params: Record<string, string>;
+    orbitalName: string;
+} | null;
+/**
+ * Find a page by name.
+ */
+export declare function findPageByName(schema: OrbitalSchema, pageName: string): {
+    page: OrbitalPage;
+    orbitalName: string;
+} | null;
+/**
+ * Get the first page in the schema (default page).
+ */
+export declare function getDefaultPage(schema: OrbitalSchema): {
+    page: OrbitalPage;
+    orbitalName: string;
+} | null;
+/**
+ * Get all pages from the schema.
+ */
+export declare function getAllPages(schema: OrbitalSchema): Array<{
+    page: OrbitalPage;
+    orbitalName: string;
+}>;
+export interface NavigationState {
+    /** Current active page name */
+    activePage: string;
+    /** Current path (for URL sync) */
+    currentPath: string;
+    /** Payload to pass to INIT when page loads */
+    initPayload: Record<string, unknown>;
+    /** Navigation counter (increments on each navigation) */
+    navigationId: number;
+}
+export interface NavigationContextValue {
+    /** Current navigation state */
+    state: NavigationState;
+    /** Navigate to a path with optional payload */
+    navigateTo: (path: string, payload?: Record<string, unknown>) => void;
+    /** Navigate to a page by name with optional payload */
+    navigateToPage: (pageName: string, payload?: Record<string, unknown>) => void;
+    /** The schema being navigated */
+    schema: OrbitalSchema;
+    /** Whether navigation is ready (schema loaded) */
+    isReady: boolean;
+}
+export interface NavigationProviderProps {
+    /** The schema to navigate within */
+    schema: OrbitalSchema;
+    /** Initial page name (optional, defaults to first page) */
+    initialPage?: string;
+    /** Whether to update browser URL on navigation (default: true) */
+    updateUrl?: boolean;
+    /** Callback when navigation occurs */
+    onNavigate?: (pageName: string, path: string, payload: Record<string, unknown>) => void;
+    /** Children */
+    children: React.ReactNode;
+}
+/**
+ * NavigationProvider - Provides schema-driven navigation context
+ *
+ * @example
+ * ```tsx
+ * <NavigationProvider schema={mySchema}>
+ *   <OrbitalRuntimeContent />
+ * </NavigationProvider>
+ * ```
+ */
+export declare function NavigationProvider({ schema, initialPage, updateUrl, onNavigate, children, }: NavigationProviderProps): React.ReactElement;
+/**
+ * Hook to access navigation context.
+ * Returns null if not within NavigationProvider.
+ */
+export declare function useNavigation(): NavigationContextValue | null;
+/**
+ * Hook to get the navigateTo function.
+ * Returns a no-op function if not within NavigationProvider.
+ */
+export declare function useNavigateTo(): (path: string, payload?: Record<string, unknown>) => void;
+/**
+ * Hook to get current navigation state.
+ */
+export declare function useNavigationState(): NavigationState | null;
+/**
+ * Hook to get the current INIT payload (for passing to trait INIT events).
+ */
+export declare function useInitPayload(): Record<string, unknown>;
+/**
+ * Hook to get current active page name.
+ */
+export declare function useActivePage(): string | null;
+/**
+ * Hook to get navigation ID (changes on each navigation, useful for triggering effects).
+ */
+export declare function useNavigationId(): number;
+export default NavigationProvider;

package/dist/{offline-executor-CHr4uAhf.d.ts → renderer/offline-executor.d.ts}

@@ -1,164 +1,3 @@
-/**
- * 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
- */
-/**
- * A client effect is a tuple where the first element is the effect type
- * and the remaining elements are the arguments.
- *
- * @example
- * ['render-ui', 'main', { type: 'entity-table', ... }]
- * ['navigate', '/tasks/123']
- * ['notify', 'Task created!', { type: 'success' }]
- * ['emit', 'TASK_CREATED', { id: '123' }]
- */
-type ClientEffect = ['render-ui', string, PatternConfig | null] | ['navigate', string, Record<string, unknown>?] | ['notify', string, NotifyOptions?] | ['emit', string, unknown?];
-/**
- * Options for notify effect
- */
-interface NotifyOptions {
-    type?: 'success' | 'error' | 'info' | 'warning';
-    duration?: number;
-}
-/**
- * Configuration for a pattern to render in a slot.
- * This is what render-ui effects carry as their payload.
- */
-interface PatternConfig {
-    /** Pattern type from registry (e.g., 'entity-table', 'form-section') */
-    type: string;
-    /** Entity name for data binding */
-    entity?: string;
-    /** Additional props for the pattern component */
-    [key: string]: unknown;
-}
-/**
- * Resolved pattern with component information from component-mapping.json
- */
-interface ResolvedPattern {
-    /** 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, unknown>;
-}
-/**
- * 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, unknown[]>;
-    /** Client effects to execute (render-ui, navigate, notify, emit) */
-    clientEffects?: ClientEffect[];
-    /** Results of individual effect executions (for debugging) */
-    effectResults?: Array<{
-        effect: string;
-        success: boolean;
-        data?: unknown;
-        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, unknown>) => void;
-    /**
-     * Show a notification.
-     * Called for 'notify' effects.
-     */
-    notify: (message: string, options?: NotifyOptions) => void;
-    /**
-     * Emit an event to the event bus.
-     * Called for 'emit' effects.
-     */
-    eventBus: {
-        emit: (event: string, payload?: unknown) => void;
-    };
-    /**
-     * Optional: Data from server response for render-ui.
-     * Components can use this to access fetched entity data.
-     */
-    data?: Record<string, unknown[]>;
-    /**
-     * Optional: Callback when all effects have been executed.
-     */
-    onComplete?: () => void;
-}
-/**
- * Valid UI slot names
- */
-type UISlot = 'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'center' | 'toast' | 'hud-top' | 'hud-bottom' | 'floating';
-/**
- * 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;
-}
-/**
- * Context for resolving entity data.
- * Supports multiple data sources with priority.
- */
-interface DataContext {
-    /** Server-provided data (highest priority) */
-    fetchedData?: Record<string, unknown[]>;
-    /** In-memory mock data (for Builder preview) */
-    entityStore?: {
-        getRecords: (entityName: string) => unknown[];
-    };
-    /** Query singleton for filtering */
-    querySingleton?: {
-        getFilters: (queryRef: string) => Record<string, unknown>;
-    };
-}
-/**
- * Result of data resolution
- */
-interface DataResolution {
-    /** Resolved data array */
-    data: unknown[];
-    /** Whether data is still loading */
-    loading: boolean;
-    /** Error if resolution failed */
-    error?: Error;
-}
-
 /**
  * Offline Effect Executor
  *
@@ -172,11 +11,11 @@ interface DataResolution {
  *
  * @packageDocumentation
  */
-
+import type { ClientEffect, ClientEffectExecutorConfig, EventResponse } from './types';
 /**
  * Effect that needs to be synced to server when online
  */
-interface PendingSyncEffect {
+export interface PendingSyncEffect {
     /** Unique ID for this effect */
     id: string;
     /** Timestamp when effect was queued */
@@ -193,7 +32,7 @@ interface PendingSyncEffect {
 /**
  * Configuration for offline executor
  */
-interface OfflineExecutorConfig extends ClientEffectExecutorConfig {
+export interface OfflineExecutorConfig extends ClientEffectExecutorConfig {
     /**
      * Mock data provider for simulating fetch responses.
      * Returns data for a given entity name.
@@ -221,7 +60,7 @@ interface OfflineExecutorConfig extends ClientEffectExecutorConfig {
 /**
  * Offline executor state
  */
-interface OfflineExecutorState {
+export interface OfflineExecutorState {
     /** Whether we're in offline mode */
     isOffline: boolean;
     /** Pending effects waiting for sync */
@@ -261,7 +100,7 @@ interface OfflineExecutorState {
  * await executor.syncPendingEffects(serverUrl);
  * ```
  */
-declare class OfflineExecutor {
+export declare class OfflineExecutor {
     private config;
     private state;
     private storage;
@@ -341,11 +180,11 @@ declare class OfflineExecutor {
  * });
  * ```
  */
-declare function createOfflineExecutor(config: OfflineExecutorConfig): OfflineExecutor;
+export declare function createOfflineExecutor(config: OfflineExecutorConfig): OfflineExecutor;
 /**
  * Options for useOfflineExecutor hook
  */
-interface UseOfflineExecutorOptions extends OfflineExecutorConfig {
+export interface UseOfflineExecutorOptions extends OfflineExecutorConfig {
     /** Server URL for syncing */
     serverUrl?: string;
     /** Auth token for server requests */
@@ -356,7 +195,7 @@ interface UseOfflineExecutorOptions extends OfflineExecutorConfig {
 /**
  * Result of useOfflineExecutor hook
  */
-interface UseOfflineExecutorResult {
+export interface UseOfflineExecutorResult {
     /** Current executor state */
     state: OfflineExecutorState;
     /** Whether we're offline */
@@ -396,6 +235,4 @@ interface UseOfflineExecutorResult {
  * }
  * ```
  */
-declare function useOfflineExecutor(options: UseOfflineExecutorOptions): UseOfflineExecutorResult;
-
-export { type ClientEffect as C, type DataContext as D, type EventResponse as E, type NotifyOptions as N, OfflineExecutor as O, type PatternConfig as P, type ResolvedPattern as R, type SlotDefinition as S, type UseOfflineExecutorResult as U, type UseOfflineExecutorOptions as a, type ClientEffectExecutorConfig as b, type DataResolution as c, type UISlot as d, type SlotType as e, type OfflineExecutorConfig as f, type OfflineExecutorState as g, type PendingSyncEffect as h, createOfflineExecutor as i, useOfflineExecutor as u };
+export declare function useOfflineExecutor(options: UseOfflineExecutorOptions): UseOfflineExecutorResult;

package/dist/renderer/pattern-resolver.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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
+ */
+import type { PatternConfig, ResolvedPattern } from './types';
+/**
+ * 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, {
+        required?: boolean;
+        types?: string[];
+        description?: string;
+    }>;
+}
+/**
+ * Initialize the pattern resolver with mappings.
+ * Called at app startup with data from JSON files.
+ */
+export declare function initializePatternResolver(config: {
+    componentMapping: Record<string, ComponentMappingEntry>;
+    patternRegistry: Record<string, PatternDefinition>;
+}): void;
+/**
+ * Set component mapping (alternative to full initialization).
+ */
+export declare function setComponentMapping(mapping: Record<string, ComponentMappingEntry>): void;
+/**
+ * Set pattern registry (alternative to full initialization).
+ */
+export 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'
+ * ```
+ */
+export declare function resolvePattern(config: PatternConfig): ResolvedPattern;
+/**
+ * Check if a pattern type is known.
+ */
+export declare function isKnownPattern(type: string): boolean;
+/**
+ * Get all known pattern types.
+ */
+export declare function getKnownPatterns(): string[];
+/**
+ * Get patterns by category.
+ */
+export declare function getPatternsByCategory(category: string): string[];
+/**
+ * Get the component mapping for a pattern type.
+ */
+export declare function getPatternMapping(type: string): ComponentMappingEntry | undefined;
+/**
+ * Get the pattern definition from the registry.
+ */
+export declare function getPatternDefinition(type: string): PatternDefinition | undefined;
+export {};

package/dist/renderer/slot-definitions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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
+ */
+import type { UISlot, SlotDefinition, SlotType } from './types';
+/**
+ * Definitions for all available UI slots.
+ *
+ * Inline slots render within the component hierarchy.
+ * Portal slots render to document.body, breaking out of overflow containers.
+ */
+export declare const SLOT_DEFINITIONS: Record<UISlot, SlotDefinition>;
+/**
+ * Get the slot definition for a slot name.
+ */
+export declare function getSlotDefinition(slot: UISlot): SlotDefinition;
+/**
+ * Check if a slot is a portal slot.
+ */
+export declare function isPortalSlot(slot: UISlot): boolean;
+/**
+ * Check if a slot is an inline slot.
+ */
+export declare function isInlineSlot(slot: UISlot): boolean;
+/**
+ * Get all slots of a specific type.
+ */
+export declare function getSlotsByType(type: SlotType): UISlot[];
+/**
+ * Get all inline slots.
+ */
+export declare function getInlineSlots(): UISlot[];
+/**
+ * Get all portal slots.
+ */
+export declare function getPortalSlots(): UISlot[];
+/**
+ * All valid slot names.
+ */
+export declare const ALL_SLOTS: UISlot[];

package/dist/renderer/types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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
+ */
+/**
+ * A client effect is a tuple where the first element is the effect type
+ * and the remaining elements are the arguments.
+ *
+ * @example
+ * ['render-ui', 'main', { type: 'entity-table', ... }]
+ * ['navigate', '/tasks/123']
+ * ['notify', 'Task created!', { type: 'success' }]
+ * ['emit', 'TASK_CREATED', { id: '123' }]
+ */
+export type ClientEffect = ['render-ui', string, PatternConfig | null] | ['navigate', string, Record<string, unknown>?] | ['notify', string, NotifyOptions?] | ['emit', string, unknown?];
+/**
+ * Options for notify effect
+ */
+export interface NotifyOptions {
+    type?: 'success' | 'error' | 'info' | 'warning';
+    duration?: number;
+}
+/**
+ * Configuration for a pattern to render in a slot.
+ * This is what render-ui effects carry as their payload.
+ */
+export interface PatternConfig {
+    /** Pattern type from registry (e.g., 'entity-table', 'form-section') */
+    type: string;
+    /** Entity name for data binding */
+    entity?: string;
+    /** Additional props for the pattern component */
+    [key: string]: unknown;
+}
+/**
+ * Resolved pattern with component information from component-mapping.json
+ */
+export interface ResolvedPattern {
+    /** 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, unknown>;
+}
+/**
+ * Response from server after processing an event.
+ * This is the unified response format for both Builder and compiled shells.
+ */
+export 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, unknown[]>;
+    /** Client effects to execute (render-ui, navigate, notify, emit) */
+    clientEffects?: ClientEffect[];
+    /** Results of individual effect executions (for debugging) */
+    effectResults?: Array<{
+        effect: string;
+        success: boolean;
+        data?: unknown;
+        error?: string;
+    }>;
+    /** Error message if success is false */
+    error?: string;
+}
+/**
+ * Configuration for the client effect executor.
+ * Provides implementations for each effect type.
+ */
+export 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, unknown>) => void;
+    /**
+     * Show a notification.
+     * Called for 'notify' effects.
+     */
+    notify: (message: string, options?: NotifyOptions) => void;
+    /**
+     * Emit an event to the event bus.
+     * Called for 'emit' effects.
+     */
+    eventBus: {
+        emit: (event: string, payload?: unknown) => void;
+    };
+    /**
+     * Optional: Data from server response for render-ui.
+     * Components can use this to access fetched entity data.
+     */
+    data?: Record<string, unknown[]>;
+    /**
+     * Optional: Callback when all effects have been executed.
+     */
+    onComplete?: () => void;
+}
+/**
+ * Valid UI slot names
+ */
+export type UISlot = 'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'center' | 'toast' | 'hud-top' | 'hud-bottom' | 'floating';
+/**
+ * Slot type classification
+ */
+export type SlotType = 'inline' | 'portal';
+/**
+ * Definition of a slot including its rendering behavior
+ */
+export 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;
+}
+/**
+ * Context for resolving entity data.
+ * Supports multiple data sources with priority.
+ */
+export interface DataContext {
+    /** Server-provided data (highest priority) */
+    fetchedData?: Record<string, unknown[]>;
+    /** In-memory mock data (for Builder preview) */
+    entityStore?: {
+        getRecords: (entityName: string) => unknown[];
+    };
+    /** Query singleton for filtering */
+    querySingleton?: {
+        getFilters: (queryRef: string) => Record<string, unknown>;
+    };
+}
+/**
+ * Result of data resolution
+ */
+export interface DataResolution {
+    /** Resolved data array */
+    data: unknown[];
+    /** Whether data is still loading */
+    loading: boolean;
+    /** Error if resolution failed */
+    error?: Error;
+}