@almadar/ui 1.0.0 → 1.0.10

package/dist/renderer/index.d.ts

@@ -1,6 +1,8 @@
 import { P as PatternConfig, R as ResolvedPattern, C as ClientEffect, b as ClientEffectExecutorConfig, N as NotifyOptions, D as DataContext, c as DataResolution, d as UISlot, S as SlotDefinition, e as SlotType } from '../offline-executor-CHr4uAhf.js';
 export { E as EventResponse, O as OfflineExecutor, f as OfflineExecutorConfig, g as OfflineExecutorState, h as PendingSyncEffect, a as UseOfflineExecutorOptions, U as UseOfflineExecutorResult, i as createOfflineExecutor, u as useOfflineExecutor } from '../offline-executor-CHr4uAhf.js';
 import * as React from 'react';
+import React__default from 'react';
+import { OrbitalSchema, OrbitalPage } from '@almadar/core';
 
 /**
  * Pattern Resolver
@@ -364,6 +366,147 @@ declare function getPortalSlots(): UISlot[];
  */
 declare const ALL_SLOTS: UISlot[];
 
+/**
+ * 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
+ */
+
+/**
+ * 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
+ */
+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.
+ */
+declare function extractRouteParams(pattern: string, path: string): Record<string, string>;
+/**
+ * Check if a path matches a pattern.
+ */
+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.
+ */
+declare function findPageByPath(schema: OrbitalSchema, path: string): {
+    page: OrbitalPage;
+    params: Record<string, string>;
+    orbitalName: string;
+} | null;
+/**
+ * Find a page by name.
+ */
+declare function findPageByName(schema: OrbitalSchema, pageName: string): {
+    page: OrbitalPage;
+    orbitalName: string;
+} | null;
+/**
+ * Get the first page in the schema (default page).
+ */
+declare function getDefaultPage(schema: OrbitalSchema): {
+    page: OrbitalPage;
+    orbitalName: string;
+} | null;
+/**
+ * Get all pages from the schema.
+ */
+declare function getAllPages(schema: OrbitalSchema): Array<{
+    page: OrbitalPage;
+    orbitalName: string;
+}>;
+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;
+}
+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;
+}
+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__default.ReactNode;
+}
+/**
+ * NavigationProvider - Provides schema-driven navigation context
+ *
+ * @example
+ * ```tsx
+ * <NavigationProvider schema={mySchema}>
+ *   <OrbitalRuntimeContent />
+ * </NavigationProvider>
+ * ```
+ */
+declare function NavigationProvider({ schema, initialPage, updateUrl, onNavigate, children, }: NavigationProviderProps): React__default.ReactElement;
+/**
+ * Hook to access navigation context.
+ * Returns null if not within NavigationProvider.
+ */
+declare function useNavigation(): NavigationContextValue | null;
+/**
+ * Hook to get the navigateTo function.
+ * Returns a no-op function if not within NavigationProvider.
+ */
+declare function useNavigateTo(): (path: string, payload?: Record<string, unknown>) => void;
+/**
+ * Hook to get current navigation state.
+ */
+declare function useNavigationState(): NavigationState | null;
+/**
+ * Hook to get the current INIT payload (for passing to trait INIT events).
+ */
+declare function useInitPayload(): Record<string, unknown>;
+/**
+ * Hook to get current active page name.
+ */
+declare function useActivePage(): string | null;
+/**
+ * Hook to get navigation ID (changes on each navigation, useful for triggering effects).
+ */
+declare function useNavigationId(): number;
+
 /**
  * Pattern Resolver Initialization
  *
@@ -379,4 +522,4 @@ declare const ALL_SLOTS: UISlot[];
  */
 declare function initializePatterns(): number;
 
-export { ALL_SLOTS, ClientEffect, ClientEffectConfigContext, ClientEffectConfigProvider, ClientEffectExecutorConfig, DataContext, DataResolution, NotifyOptions, PatternConfig, ResolvedPattern, SLOT_DEFINITIONS, SlotDefinition, SlotType, UISlot, type UseClientEffectsOptions, type UseClientEffectsResult, createFetchedDataContext, executeClientEffects, filterEffectsByType, getEmitEffects, getInlineSlots, getKnownPatterns, getNavigateEffects, getNotifyEffects, getPatternDefinition, getPatternMapping, getPatternsByCategory, getPortalSlots, getRenderUIEffects, getSlotDefinition, getSlotsByType, hasEntities, initializePatternResolver, initializePatterns, isInlineSlot, isKnownPattern, isPortalSlot, mergeDataContexts, parseClientEffect, parseClientEffects, resolveEntityById, resolveEntityCount, resolveEntityData, resolveEntityDataWithQuery, resolvePattern, setComponentMapping, setPatternRegistry, useClientEffectConfig, useClientEffectConfigOptional, useClientEffects };
+export { ALL_SLOTS, ClientEffect, ClientEffectConfigContext, ClientEffectConfigProvider, ClientEffectExecutorConfig, DataContext, DataResolution, type NavigationContextValue, NavigationProvider, type NavigationProviderProps, type NavigationState, NotifyOptions, PatternConfig, ResolvedPattern, SLOT_DEFINITIONS, SlotDefinition, SlotType, UISlot, type UseClientEffectsOptions, type UseClientEffectsResult, createFetchedDataContext, executeClientEffects, extractRouteParams, filterEffectsByType, findPageByName, findPageByPath, getAllPages, getDefaultPage, getEmitEffects, getInlineSlots, getKnownPatterns, getNavigateEffects, getNotifyEffects, getPatternDefinition, getPatternMapping, getPatternsByCategory, getPortalSlots, getRenderUIEffects, getSlotDefinition, getSlotsByType, hasEntities, initializePatternResolver, initializePatterns, isInlineSlot, isKnownPattern, isPortalSlot, matchPath, mergeDataContexts, parseClientEffect, parseClientEffects, pathMatches, resolveEntityById, resolveEntityCount, resolveEntityData, resolveEntityDataWithQuery, resolvePattern, setComponentMapping, setPatternRegistry, useActivePage, useClientEffectConfig, useClientEffectConfigOptional, useClientEffects, useInitPayload, useNavigateTo, useNavigation, useNavigationId, useNavigationState };