@almadar/ui 1.0.34 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (241) hide show
  1. package/LICENSE +21 -72
  2. package/dist/components/atoms/Avatar.d.ts +58 -0
  3. package/dist/components/atoms/Badge.d.ts +8 -0
  4. package/dist/components/atoms/Box.d.ts +57 -0
  5. package/dist/components/atoms/Button.d.ts +24 -0
  6. package/dist/components/atoms/Card.d.ts +18 -0
  7. package/dist/components/atoms/Center.d.ts +33 -0
  8. package/dist/components/atoms/Checkbox.d.ts +5 -0
  9. package/dist/components/atoms/ConditionalWrapper.d.ts +68 -0
  10. package/dist/components/atoms/Divider.d.ts +29 -0
  11. package/dist/components/atoms/Icon.d.ts +38 -0
  12. package/dist/components/atoms/Input.d.ts +26 -0
  13. package/dist/components/atoms/Label.d.ts +5 -0
  14. package/dist/components/atoms/LawReferenceTooltip.d.ts +48 -0
  15. package/dist/components/atoms/Overlay.d.ts +16 -0
  16. package/dist/components/atoms/ProgressBar.d.ts +63 -0
  17. package/dist/components/atoms/Radio.d.ts +26 -0
  18. package/dist/components/atoms/Select.d.ts +12 -0
  19. package/dist/components/atoms/Spacer.d.ts +25 -0
  20. package/dist/components/atoms/Spinner.d.ts +6 -0
  21. package/dist/components/atoms/Stack.d.ts +64 -0
  22. package/dist/components/atoms/Switch.d.ts +12 -0
  23. package/dist/components/atoms/TextHighlight.d.ts +53 -0
  24. package/dist/components/atoms/Textarea.d.ts +5 -0
  25. package/dist/components/atoms/ThemeSelector.d.ts +21 -0
  26. package/dist/components/atoms/ThemeToggle.d.ts +33 -0
  27. package/dist/components/atoms/Typography.d.ts +57 -0
  28. package/dist/components/atoms/game/ControlButton.d.ts +31 -0
  29. package/dist/components/atoms/game/HealthBar.d.ts +18 -0
  30. package/dist/components/atoms/game/ScoreDisplay.d.ts +21 -0
  31. package/dist/components/atoms/game/Sprite.d.ts +63 -0
  32. package/dist/components/atoms/game/StateIndicator.d.ts +31 -0
  33. package/dist/components/atoms/game/index.d.ts +12 -0
  34. package/dist/components/atoms/index.d.ts +27 -0
  35. package/dist/components/index.css +11 -9
  36. package/dist/components/index.d.ts +6 -6951
  37. package/dist/components/index.js +5 -5
  38. package/dist/components/molecules/Accordion.d.ts +67 -0
  39. package/dist/components/molecules/Alert.d.ts +24 -0
  40. package/dist/components/molecules/Breadcrumb.d.ts +55 -0
  41. package/dist/components/molecules/ButtonGroup.d.ts +67 -0
  42. package/dist/components/molecules/Card.d.ts +44 -0
  43. package/dist/components/molecules/Container.d.ts +30 -0
  44. package/dist/components/molecules/Drawer.d.ts +46 -0
  45. package/dist/components/molecules/EmptyState.d.ts +25 -0
  46. package/dist/components/molecules/ErrorBoundary.d.ts +55 -0
  47. package/dist/components/molecules/ErrorState.d.ts +13 -0
  48. package/dist/components/molecules/FilterGroup.d.ts +54 -0
  49. package/dist/components/molecules/Flex.d.ts +43 -0
  50. package/dist/components/molecules/FloatingActionButton.d.ts +69 -0
  51. package/dist/components/molecules/FormField.d.ts +16 -0
  52. package/dist/components/molecules/FormSectionHeader.d.ts +30 -0
  53. package/dist/components/molecules/Grid.d.ts +54 -0
  54. package/dist/components/molecules/InputGroup.d.ts +24 -0
  55. package/dist/components/molecules/LoadingState.d.ts +7 -0
  56. package/dist/components/molecules/Menu.d.ts +40 -0
  57. package/dist/components/molecules/Modal.d.ts +26 -0
  58. package/dist/components/molecules/Pagination.d.ts +66 -0
  59. package/dist/components/molecules/Popover.d.ts +39 -0
  60. package/dist/components/molecules/QuizBlock.d.ts +20 -0
  61. package/dist/components/molecules/RelationSelect.d.ts +48 -0
  62. package/dist/components/molecules/RepeatableFormSection.d.ts +58 -0
  63. package/dist/components/molecules/ScaledDiagram.d.ts +20 -0
  64. package/dist/components/molecules/SearchInput.d.ts +60 -0
  65. package/dist/components/molecules/SidePanel.d.ts +47 -0
  66. package/dist/components/molecules/SimpleGrid.d.ts +27 -0
  67. package/dist/components/molecules/Skeleton.d.ts +35 -0
  68. package/dist/components/molecules/Tabs.d.ts +45 -0
  69. package/dist/components/molecules/Toast.d.ts +35 -0
  70. package/dist/components/molecules/Tooltip.d.ts +25 -0
  71. package/dist/components/molecules/ViolationAlert.d.ts +49 -0
  72. package/dist/components/molecules/WizardNavigation.d.ts +51 -0
  73. package/dist/components/molecules/WizardProgress.d.ts +42 -0
  74. package/dist/components/molecules/game/StatBadge.d.ts +27 -0
  75. package/dist/components/molecules/index.d.ts +38 -0
  76. package/dist/components/molecules/markdown/CodeBlock.d.ts +25 -0
  77. package/dist/components/molecules/markdown/MarkdownContent.d.ts +26 -0
  78. package/dist/components/organisms/CardGrid.d.ts +72 -0
  79. package/dist/components/organisms/Chart.d.ts +59 -0
  80. package/dist/components/organisms/CodeViewer.d.ts +67 -0
  81. package/dist/components/organisms/ComponentPatterns.d.ts +441 -0
  82. package/dist/components/organisms/ConfirmDialog.d.ts +50 -0
  83. package/dist/components/organisms/ContentRenderer.d.ts +23 -0
  84. package/dist/components/organisms/CustomPattern.d.ts +104 -0
  85. package/dist/components/organisms/DataTable.d.ts +63 -0
  86. package/dist/components/organisms/DetailPanel.d.ts +71 -0
  87. package/dist/components/organisms/DocumentViewer.d.ts +60 -0
  88. package/dist/components/organisms/DrawerSlot.d.ts +39 -0
  89. package/dist/components/organisms/Form.d.ts +203 -0
  90. package/dist/components/organisms/FormSection.d.ts +59 -0
  91. package/dist/components/organisms/GraphCanvas.d.ts +69 -0
  92. package/dist/components/organisms/Header.d.ts +110 -0
  93. package/dist/components/organisms/JazariStateMachine.d.ts +60 -0
  94. package/dist/components/organisms/LayoutPatterns.d.ts +181 -0
  95. package/dist/components/organisms/List.d.ts +76 -0
  96. package/dist/components/organisms/MasterDetail.d.ts +43 -0
  97. package/dist/components/organisms/MediaGallery.d.ts +66 -0
  98. package/dist/components/organisms/Meter.d.ts +58 -0
  99. package/dist/components/organisms/ModalSlot.d.ts +35 -0
  100. package/dist/components/organisms/Navigation.d.ts +68 -0
  101. package/dist/components/organisms/OrbitalVisualization.d.ts +48 -0
  102. package/dist/components/organisms/PageHeader.d.ts +59 -0
  103. package/dist/components/organisms/Section.d.ts +44 -0
  104. package/dist/components/organisms/Sidebar.d.ts +65 -0
  105. package/dist/components/organisms/SignaturePad.d.ts +44 -0
  106. package/dist/components/organisms/Split.d.ts +42 -0
  107. package/dist/components/organisms/StatCard.d.ts +66 -0
  108. package/dist/components/organisms/StateMachineView.d.ts +36 -0
  109. package/dist/components/organisms/Table.d.ts +99 -0
  110. package/dist/components/organisms/Timeline.d.ts +58 -0
  111. package/dist/components/organisms/ToastSlot.d.ts +38 -0
  112. package/dist/components/organisms/UISlotRenderer.d.ts +112 -0
  113. package/dist/components/organisms/WizardContainer.d.ts +160 -0
  114. package/dist/components/organisms/book/BookChapterView.d.ts +17 -0
  115. package/dist/components/organisms/book/BookCoverPage.d.ts +19 -0
  116. package/dist/components/organisms/book/BookNavBar.d.ts +18 -0
  117. package/dist/components/organisms/book/BookTableOfContents.d.ts +18 -0
  118. package/dist/components/organisms/book/BookViewer.d.ts +28 -0
  119. package/dist/components/organisms/book/index.d.ts +7 -0
  120. package/dist/components/organisms/book/types.d.ts +77 -0
  121. package/dist/components/organisms/game/BattleBoard.d.ts +167 -0
  122. package/dist/components/organisms/game/CanvasEffect.d.ts +68 -0
  123. package/dist/components/organisms/game/CastleBoard.d.ts +85 -0
  124. package/dist/components/organisms/game/DialogueBox.d.ts +73 -0
  125. package/dist/components/organisms/game/GameAudioProvider.d.ts +47 -0
  126. package/dist/components/organisms/game/GameAudioToggle.d.ts +28 -0
  127. package/dist/components/organisms/game/GameHud.d.ts +40 -0
  128. package/dist/components/organisms/game/GameMenu.d.ts +43 -0
  129. package/dist/components/organisms/game/GameOverScreen.d.ts +56 -0
  130. package/dist/components/organisms/game/InventoryPanel.d.ts +67 -0
  131. package/dist/components/organisms/game/IsometricCanvas.d.ts +123 -0
  132. package/dist/components/organisms/game/TraitSlot.d.ts +86 -0
  133. package/dist/components/organisms/game/TraitStateViewer.d.ts +53 -0
  134. package/dist/components/organisms/game/UncontrolledBattleBoard.d.ts +26 -0
  135. package/dist/components/organisms/game/WorldMapBoard.d.ts +147 -0
  136. package/dist/components/organisms/game/editor/editorUtils.d.ts +109 -0
  137. package/dist/components/organisms/game/editor/index.d.ts +9 -0
  138. package/dist/components/organisms/game/hooks/useBattleState.d.ts +35 -0
  139. package/dist/components/organisms/game/hooks/useCamera.d.ts +41 -0
  140. package/dist/components/organisms/game/hooks/useGameAudio.d.ts +47 -0
  141. package/dist/components/organisms/game/hooks/useImageCache.d.ts +16 -0
  142. package/dist/components/organisms/game/hooks/usePhysics2D.d.ts +45 -0
  143. package/dist/components/organisms/game/hooks/useSpriteAnimations.d.ts +43 -0
  144. package/dist/components/organisms/game/index.d.ts +36 -0
  145. package/dist/components/organisms/game/managers/PhysicsManager.d.ts +103 -0
  146. package/dist/components/organisms/game/types/effects.d.ts +253 -0
  147. package/dist/{isometric-ynNHVPZx.d.ts → components/organisms/game/types/isometric.d.ts} +4 -6
  148. package/dist/components/organisms/game/types/spriteAnimation.d.ts +73 -0
  149. package/dist/components/organisms/game/utils/canvasEffects.d.ts +50 -0
  150. package/dist/components/organisms/game/utils/combatPresets.d.ts +15 -0
  151. package/dist/components/organisms/game/utils/isometric.d.ts +61 -0
  152. package/dist/components/organisms/game/utils/spriteAnimation.d.ts +57 -0
  153. package/dist/components/organisms/game/utils/spriteSheetConstants.d.ts +16 -0
  154. package/dist/components/organisms/index.d.ts +37 -0
  155. package/dist/components/organisms/layout/DashboardGrid.d.ts +34 -0
  156. package/dist/components/organisms/layout/MasterDetail.d.ts +32 -0
  157. package/dist/components/organisms/layout/SplitPane.d.ts +34 -0
  158. package/dist/components/organisms/layout/TabbedContainer.d.ts +42 -0
  159. package/dist/components/organisms/layout/index.d.ts +9 -0
  160. package/dist/components/organisms/types.d.ts +65 -0
  161. package/dist/components/templates/AuthLayout.d.ts +14 -0
  162. package/dist/components/templates/BattleTemplate.d.ts +25 -0
  163. package/dist/components/templates/CastleTemplate.d.ts +23 -0
  164. package/dist/components/templates/CounterTemplate.d.ts +44 -0
  165. package/dist/components/templates/DashboardLayout.d.ts +32 -0
  166. package/dist/components/templates/GameShell.d.ts +33 -0
  167. package/dist/components/templates/GameTemplate.d.ts +36 -0
  168. package/dist/components/templates/GenericAppTemplate.d.ts +30 -0
  169. package/dist/components/templates/WorldMapTemplate.d.ts +29 -0
  170. package/dist/components/templates/index.d.ts +10 -0
  171. package/dist/components/templates/types.d.ts +17 -0
  172. package/dist/context/DesignThemeContext.d.ts +21 -0
  173. package/dist/{ThemeContext-D9xUORq5.d.ts → context/ThemeContext.d.ts} +15 -16
  174. package/dist/context/UISlotContext.d.ts +75 -0
  175. package/dist/context/UserContext.d.ts +111 -0
  176. package/dist/context/index.d.ts +6 -206
  177. package/dist/{event-bus-types-CjJduURa.d.ts → hooks/event-bus-types.d.ts} +4 -6
  178. package/dist/hooks/index.d.ts +24 -1090
  179. package/dist/hooks/useAgentChat.d.ts +104 -0
  180. package/dist/hooks/useAuthContext.d.ts +25 -0
  181. package/dist/hooks/useCompile.d.ts +22 -0
  182. package/dist/hooks/useDeepAgentGeneration.d.ts +46 -0
  183. package/dist/hooks/useEntities.d.ts +52 -0
  184. package/dist/hooks/useEntityData.d.ts +155 -0
  185. package/dist/hooks/useEntityMutations.d.ts +80 -0
  186. package/dist/hooks/useEventBus.d.ts +96 -0
  187. package/dist/hooks/useExtensions.d.ts +32 -0
  188. package/dist/hooks/useFileEditor.d.ts +32 -0
  189. package/dist/hooks/useFileSystem.d.ts +40 -0
  190. package/dist/hooks/useGitHub.d.ts +58 -0
  191. package/dist/hooks/useOrbitalHistory.d.ts +39 -0
  192. package/dist/hooks/useOrbitalMutations.d.ts +95 -0
  193. package/dist/hooks/usePreview.d.ts +57 -0
  194. package/dist/hooks/useQuerySingleton.d.ts +78 -0
  195. package/dist/hooks/useResolvedEntity.d.ts +32 -0
  196. package/dist/hooks/useTranslate.d.ts +35 -0
  197. package/dist/hooks/useUIEvents.d.ts +35 -0
  198. package/dist/{useUISlots-D0mttBSP.d.ts → hooks/useUISlots.d.ts} +8 -9
  199. package/dist/hooks/useValidation.d.ts +46 -0
  200. package/dist/lib/api-client.d.ts +42 -0
  201. package/dist/lib/cn.d.ts +6 -0
  202. package/dist/lib/debug.d.ts +43 -0
  203. package/dist/lib/debugRegistry.d.ts +29 -0
  204. package/dist/lib/debugUtils.d.ts +27 -0
  205. package/dist/lib/entityDebug.d.ts +38 -0
  206. package/dist/lib/getNestedValue.d.ts +33 -0
  207. package/dist/lib/guardRegistry.d.ts +32 -0
  208. package/dist/lib/index.d.ts +17 -426
  209. package/dist/lib/jazari/svg-paths.d.ts +61 -0
  210. package/dist/lib/parseContentSegments.d.ts +41 -0
  211. package/dist/lib/tickRegistry.d.ts +40 -0
  212. package/dist/lib/traitRegistry.d.ts +34 -0
  213. package/dist/lib/verificationRegistry.d.ts +107 -0
  214. package/dist/{cn-BoBXsxuX.d.ts → lib/visualizer/index.d.ts} +18 -69
  215. package/dist/locales/index.d.ts +5 -7
  216. package/dist/providers/EventBusProvider.d.ts +60 -0
  217. package/dist/providers/FetchedDataProvider.d.ts +105 -0
  218. package/dist/providers/OfflineModeProvider.d.ts +79 -0
  219. package/dist/providers/OrbitalProvider.d.ts +101 -0
  220. package/dist/providers/SelectionProvider.d.ts +81 -0
  221. package/dist/providers/VerificationProvider.d.ts +63 -0
  222. package/dist/providers/index.css +11 -9
  223. package/dist/providers/index.d.ts +16 -464
  224. package/dist/providers/index.js +3 -3
  225. package/dist/renderer/client-effect-executor.d.ts +68 -0
  226. package/dist/renderer/data-resolver.d.ts +68 -0
  227. package/dist/renderer/index.d.ts +22 -519
  228. package/dist/renderer/index.js +1 -1
  229. package/dist/renderer/init.d.ts +14 -0
  230. package/dist/renderer/navigation.d.ts +142 -0
  231. package/dist/{offline-executor-CHr4uAhf.d.ts → renderer/offline-executor.d.ts} +9 -172
  232. package/dist/renderer/pattern-resolver.d.ts +91 -0
  233. package/dist/renderer/slot-definitions.d.ts +45 -0
  234. package/dist/renderer/types.d.ts +160 -0
  235. package/dist/renderer/useClientEffects.d.ts +88 -0
  236. package/dist/stores/entityStore.d.ts +99 -0
  237. package/dist/stores/filtering.d.ts +51 -0
  238. package/dist/stores/index.d.ts +4 -148
  239. package/package.json +12 -10
  240. package/dist/components/organisms/game/three/index.d.ts +0 -1162
  241. package/dist/{chunk-FZJ73RDM.js → chunk-RIZ76XRF.js} +1 -1
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Client Effect Executor
3
+ *
4
+ * Executes client effects returned from the server.
5
+ * This is the core of the dual execution model - the server processes
6
+ * events and returns client effects, which this module executes.
7
+ *
8
+ * Used by both Builder preview and compiled shells.
9
+ *
10
+ * @packageDocumentation
11
+ */
12
+ import type { ClientEffect, ClientEffectExecutorConfig, PatternConfig, NotifyOptions } from './types';
13
+ /**
14
+ * Execute an array of client effects.
15
+ *
16
+ * Effects are executed sequentially in order.
17
+ * Errors in one effect don't prevent subsequent effects from executing.
18
+ *
19
+ * @param effects - Array of client effects to execute
20
+ * @param config - Configuration providing implementations for each effect type
21
+ *
22
+ * @example
23
+ * ```typescript
24
+ * executeClientEffects(
25
+ * [
26
+ * ['render-ui', 'main', { type: 'entity-table', entity: 'Task' }],
27
+ * ['notify', 'Tasks loaded!', { type: 'success' }]
28
+ * ],
29
+ * {
30
+ * renderToSlot: (slot, pattern) => slotManager.render(slot, pattern),
31
+ * navigate: (path) => router.push(path),
32
+ * notify: (message, opts) => toast.show(message, opts),
33
+ * eventBus: { emit: (event, payload) => bus.emit(event, payload) }
34
+ * }
35
+ * );
36
+ * ```
37
+ */
38
+ export declare function executeClientEffects(effects: ClientEffect[], config: ClientEffectExecutorConfig): void;
39
+ /**
40
+ * Parse a raw effect array into a typed ClientEffect.
41
+ * Handles unknown effect formats gracefully.
42
+ */
43
+ export declare function parseClientEffect(raw: unknown[]): ClientEffect | null;
44
+ /**
45
+ * Parse an array of raw effects into typed ClientEffects.
46
+ * Filters out invalid effects.
47
+ */
48
+ export declare function parseClientEffects(raw: unknown[] | undefined): ClientEffect[];
49
+ /**
50
+ * Filter effects by type.
51
+ */
52
+ export declare function filterEffectsByType<T extends ClientEffect[0]>(effects: ClientEffect[], type: T): Extract<ClientEffect, [T, ...unknown[]]>[];
53
+ /**
54
+ * Get all render-ui effects.
55
+ */
56
+ export declare function getRenderUIEffects(effects: ClientEffect[]): Array<['render-ui', string, PatternConfig | null]>;
57
+ /**
58
+ * Get all navigate effects.
59
+ */
60
+ export declare function getNavigateEffects(effects: ClientEffect[]): Array<['navigate', string, Record<string, unknown>?]>;
61
+ /**
62
+ * Get all notify effects.
63
+ */
64
+ export declare function getNotifyEffects(effects: ClientEffect[]): Array<['notify', string, NotifyOptions?]>;
65
+ /**
66
+ * Get all emit effects.
67
+ */
68
+ export declare function getEmitEffects(effects: ClientEffect[]): Array<['emit', string, unknown?]>;
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Data Resolver
3
+ *
4
+ * Resolves entity data for pattern rendering.
5
+ * Supports multiple data sources with priority:
6
+ * 1. Server-provided data (from EventResponse.data)
7
+ * 2. Entity store (Builder in-memory mock data)
8
+ * 3. Empty array (fallback)
9
+ *
10
+ * Used by both Builder's PatternRenderer and compiled shell's UISlotRenderer.
11
+ *
12
+ * @packageDocumentation
13
+ */
14
+ import type { DataContext, DataResolution } from './types';
15
+ /**
16
+ * Resolve entity data from available sources.
17
+ *
18
+ * Priority:
19
+ * 1. fetchedData (from server response) - highest priority
20
+ * 2. entityStore (Builder mock data)
21
+ * 3. Empty array (fallback)
22
+ *
23
+ * @param entityName - Name of the entity to resolve data for
24
+ * @param context - Data context with available sources
25
+ * @returns Resolved data with loading state
26
+ *
27
+ * @example
28
+ * ```typescript
29
+ * const { data, loading } = resolveEntityData('Task', {
30
+ * fetchedData: response.data,
31
+ * entityStore: mockStore
32
+ * });
33
+ * ```
34
+ */
35
+ export declare function resolveEntityData(entityName: string, context: DataContext): DataResolution;
36
+ /**
37
+ * Resolve entity data with query filtering.
38
+ *
39
+ * Applies query singleton filters if available.
40
+ *
41
+ * @param entityName - Name of the entity
42
+ * @param queryRef - Optional query reference for filtering
43
+ * @param context - Data context
44
+ * @returns Filtered resolved data
45
+ */
46
+ export declare function resolveEntityDataWithQuery(entityName: string, queryRef: string | undefined, context: DataContext): DataResolution;
47
+ /**
48
+ * Get a single entity record by ID.
49
+ */
50
+ export declare function resolveEntityById(entityName: string, id: string | number, context: DataContext): unknown | null;
51
+ /**
52
+ * Get the count of entities matching criteria.
53
+ */
54
+ export declare function resolveEntityCount(entityName: string, context: DataContext, filters?: Record<string, unknown>): number;
55
+ /**
56
+ * Check if any entities exist for a given entity name.
57
+ */
58
+ export declare function hasEntities(entityName: string, context: DataContext): boolean;
59
+ /**
60
+ * Create a data context from fetched data only.
61
+ * Convenience function for compiled shells.
62
+ */
63
+ export declare function createFetchedDataContext(data: Record<string, unknown[]>): DataContext;
64
+ /**
65
+ * Merge multiple data contexts.
66
+ * Later contexts take precedence.
67
+ */
68
+ export declare function mergeDataContexts(...contexts: DataContext[]): DataContext;
@@ -1,525 +1,28 @@
1
- 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';
2
- 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';
3
- import * as React from 'react';
4
- import React__default from 'react';
5
- import { OrbitalSchema, OrbitalPage } from '@almadar/core';
6
-
7
1
  /**
8
- * Pattern Resolver
2
+ * Shared Renderer Module
9
3
  *
10
- * Resolves pattern configurations to component information.
11
- * Uses the central pattern registry and component mapping from orbital-shared/patterns/.
4
+ * Provides unified rendering logic for both Builder preview and compiled shells.
5
+ * This is the core of the runtime unification - both systems use this same code.
12
6
  *
13
- * This is the shared logic used by both Builder's PatternRenderer and
14
- * the compiled shell's UISlotRenderer.
7
+ * Key components:
8
+ * - Types: Shared type definitions for effects, patterns, responses
9
+ * - Pattern Resolver: Pattern → Component resolution
10
+ * - Client Effect Executor: Execute clientEffects from server
11
+ * - useClientEffects: React hook for effect execution
12
+ * - Data Resolver: Entity data resolution with filtering
13
+ * - Slot Definitions: Inline vs portal slot configuration
15
14
  *
16
15
  * @packageDocumentation
17
16
  */
18
-
19
- /**
20
- * Component mapping entry from component-mapping.json
21
- */
22
- interface ComponentMappingEntry {
23
- component: string;
24
- importPath: string;
25
- category: string;
26
- deprecated?: boolean;
27
- replacedBy?: string;
28
- }
29
- /**
30
- * Pattern definition from registry.json
31
- */
32
- interface PatternDefinition {
33
- type: string;
34
- category: string;
35
- description: string;
36
- propsSchema?: Record<string, {
37
- required?: boolean;
38
- types?: string[];
39
- description?: string;
40
- }>;
41
- }
42
- /**
43
- * Initialize the pattern resolver with mappings.
44
- * Called at app startup with data from JSON files.
45
- */
46
- declare function initializePatternResolver(config: {
47
- componentMapping: Record<string, ComponentMappingEntry>;
48
- patternRegistry: Record<string, PatternDefinition>;
49
- }): void;
50
- /**
51
- * Set component mapping (alternative to full initialization).
52
- */
53
- declare function setComponentMapping(mapping: Record<string, ComponentMappingEntry>): void;
54
- /**
55
- * Set pattern registry (alternative to full initialization).
56
- */
57
- declare function setPatternRegistry(registry: Record<string, PatternDefinition>): void;
58
- /**
59
- * Resolve a pattern configuration to component information.
60
- *
61
- * @param config - Pattern configuration from render-ui effect
62
- * @returns Resolved pattern with component name, import path, and validated props
63
- * @throws Error if pattern type is unknown
64
- *
65
- * @example
66
- * ```typescript
67
- * const resolved = resolvePattern({
68
- * type: 'entity-table',
69
- * entity: 'Task',
70
- * columns: ['title', 'status']
71
- * });
72
- * // resolved.component === 'DataTable'
73
- * // resolved.importPath === '@/components/organisms/DataTable'
74
- * ```
75
- */
76
- declare function resolvePattern(config: PatternConfig): ResolvedPattern;
77
- /**
78
- * Check if a pattern type is known.
79
- */
80
- declare function isKnownPattern(type: string): boolean;
81
- /**
82
- * Get all known pattern types.
83
- */
84
- declare function getKnownPatterns(): string[];
85
- /**
86
- * Get patterns by category.
87
- */
88
- declare function getPatternsByCategory(category: string): string[];
89
- /**
90
- * Get the component mapping for a pattern type.
91
- */
92
- declare function getPatternMapping(type: string): ComponentMappingEntry | undefined;
93
- /**
94
- * Get the pattern definition from the registry.
95
- */
96
- declare function getPatternDefinition(type: string): PatternDefinition | undefined;
97
-
98
- /**
99
- * Client Effect Executor
100
- *
101
- * Executes client effects returned from the server.
102
- * This is the core of the dual execution model - the server processes
103
- * events and returns client effects, which this module executes.
104
- *
105
- * Used by both Builder preview and compiled shells.
106
- *
107
- * @packageDocumentation
108
- */
109
-
110
- /**
111
- * Execute an array of client effects.
112
- *
113
- * Effects are executed sequentially in order.
114
- * Errors in one effect don't prevent subsequent effects from executing.
115
- *
116
- * @param effects - Array of client effects to execute
117
- * @param config - Configuration providing implementations for each effect type
118
- *
119
- * @example
120
- * ```typescript
121
- * executeClientEffects(
122
- * [
123
- * ['render-ui', 'main', { type: 'entity-table', entity: 'Task' }],
124
- * ['notify', 'Tasks loaded!', { type: 'success' }]
125
- * ],
126
- * {
127
- * renderToSlot: (slot, pattern) => slotManager.render(slot, pattern),
128
- * navigate: (path) => router.push(path),
129
- * notify: (message, opts) => toast.show(message, opts),
130
- * eventBus: { emit: (event, payload) => bus.emit(event, payload) }
131
- * }
132
- * );
133
- * ```
134
- */
135
- declare function executeClientEffects(effects: ClientEffect[], config: ClientEffectExecutorConfig): void;
136
- /**
137
- * Parse a raw effect array into a typed ClientEffect.
138
- * Handles unknown effect formats gracefully.
139
- */
140
- declare function parseClientEffect(raw: unknown[]): ClientEffect | null;
141
- /**
142
- * Parse an array of raw effects into typed ClientEffects.
143
- * Filters out invalid effects.
144
- */
145
- declare function parseClientEffects(raw: unknown[] | undefined): ClientEffect[];
146
- /**
147
- * Filter effects by type.
148
- */
149
- declare function filterEffectsByType<T extends ClientEffect[0]>(effects: ClientEffect[], type: T): Extract<ClientEffect, [T, ...unknown[]]>[];
150
- /**
151
- * Get all render-ui effects.
152
- */
153
- declare function getRenderUIEffects(effects: ClientEffect[]): Array<['render-ui', string, PatternConfig | null]>;
154
- /**
155
- * Get all navigate effects.
156
- */
157
- declare function getNavigateEffects(effects: ClientEffect[]): Array<['navigate', string, Record<string, unknown>?]>;
158
- /**
159
- * Get all notify effects.
160
- */
161
- declare function getNotifyEffects(effects: ClientEffect[]): Array<['notify', string, NotifyOptions?]>;
162
- /**
163
- * Get all emit effects.
164
- */
165
- declare function getEmitEffects(effects: ClientEffect[]): Array<['emit', string, unknown?]>;
166
-
167
- /**
168
- * Options for the useClientEffects hook
169
- */
170
- interface UseClientEffectsOptions extends ClientEffectExecutorConfig {
171
- /**
172
- * Whether to execute effects. Defaults to true.
173
- * Set to false to temporarily disable effect execution.
174
- */
175
- enabled?: boolean;
176
- /**
177
- * Debug mode - logs effect execution details.
178
- */
179
- debug?: boolean;
180
- }
181
- /**
182
- * Result of useClientEffects hook
183
- */
184
- interface UseClientEffectsResult {
185
- /**
186
- * Number of effects executed in the last batch.
187
- */
188
- executedCount: number;
189
- /**
190
- * Whether effects are currently being executed.
191
- */
192
- executing: boolean;
193
- /**
194
- * Manually trigger effect execution.
195
- * Useful for imperative control.
196
- */
197
- execute: (effects: ClientEffect[]) => void;
198
- }
199
- /**
200
- * Execute client effects from server response.
201
- *
202
- * This hook automatically executes effects when they change,
203
- * tracking which effects have been executed to prevent duplicates.
204
- *
205
- * @param effects - Array of client effects to execute (from server response)
206
- * @param options - Configuration including effect implementations
207
- * @returns Hook result with execution state and manual trigger
208
- *
209
- * @example
210
- * ```typescript
211
- * function useMyTrait() {
212
- * const [state, setState] = useState({ pendingEffects: [] });
213
- * const effectConfig = useClientEffectConfig();
214
- *
215
- * useClientEffects(state.pendingEffects, {
216
- * ...effectConfig,
217
- * onComplete: () => setState(s => ({ ...s, pendingEffects: [] }))
218
- * });
219
- *
220
- * // ...
221
- * }
222
- * ```
223
- */
224
- declare function useClientEffects(effects: ClientEffect[] | undefined, options: UseClientEffectsOptions): UseClientEffectsResult;
225
- declare const ClientEffectConfigContext: React.Context<ClientEffectExecutorConfig | null>;
226
- /**
227
- * Provider for client effect configuration.
228
- */
229
- declare const ClientEffectConfigProvider: React.Provider<ClientEffectExecutorConfig | null>;
230
- /**
231
- * Hook to get the client effect configuration from context.
232
- *
233
- * @throws Error if used outside of ClientEffectConfigProvider
234
- *
235
- * @example
236
- * ```typescript
237
- * function MyTraitHook() {
238
- * const effectConfig = useClientEffectConfig();
239
- *
240
- * useClientEffects(pendingEffects, {
241
- * ...effectConfig,
242
- * onComplete: () => clearPendingEffects()
243
- * });
244
- * }
245
- * ```
246
- */
247
- declare function useClientEffectConfig(): ClientEffectExecutorConfig;
248
- /**
249
- * Hook to get client effect configuration, returning null if not available.
250
- * Use this for optional integration where effects may not be configured.
251
- */
252
- declare function useClientEffectConfigOptional(): ClientEffectExecutorConfig | null;
253
-
254
- /**
255
- * Data Resolver
256
- *
257
- * Resolves entity data for pattern rendering.
258
- * Supports multiple data sources with priority:
259
- * 1. Server-provided data (from EventResponse.data)
260
- * 2. Entity store (Builder in-memory mock data)
261
- * 3. Empty array (fallback)
262
- *
263
- * Used by both Builder's PatternRenderer and compiled shell's UISlotRenderer.
264
- *
265
- * @packageDocumentation
266
- */
267
-
268
- /**
269
- * Resolve entity data from available sources.
270
- *
271
- * Priority:
272
- * 1. fetchedData (from server response) - highest priority
273
- * 2. entityStore (Builder mock data)
274
- * 3. Empty array (fallback)
275
- *
276
- * @param entityName - Name of the entity to resolve data for
277
- * @param context - Data context with available sources
278
- * @returns Resolved data with loading state
279
- *
280
- * @example
281
- * ```typescript
282
- * const { data, loading } = resolveEntityData('Task', {
283
- * fetchedData: response.data,
284
- * entityStore: mockStore
285
- * });
286
- * ```
287
- */
288
- declare function resolveEntityData(entityName: string, context: DataContext): DataResolution;
289
- /**
290
- * Resolve entity data with query filtering.
291
- *
292
- * Applies query singleton filters if available.
293
- *
294
- * @param entityName - Name of the entity
295
- * @param queryRef - Optional query reference for filtering
296
- * @param context - Data context
297
- * @returns Filtered resolved data
298
- */
299
- declare function resolveEntityDataWithQuery(entityName: string, queryRef: string | undefined, context: DataContext): DataResolution;
300
- /**
301
- * Get a single entity record by ID.
302
- */
303
- declare function resolveEntityById(entityName: string, id: string | number, context: DataContext): unknown | null;
304
- /**
305
- * Get the count of entities matching criteria.
306
- */
307
- declare function resolveEntityCount(entityName: string, context: DataContext, filters?: Record<string, unknown>): number;
308
- /**
309
- * Check if any entities exist for a given entity name.
310
- */
311
- declare function hasEntities(entityName: string, context: DataContext): boolean;
312
- /**
313
- * Create a data context from fetched data only.
314
- * Convenience function for compiled shells.
315
- */
316
- declare function createFetchedDataContext(data: Record<string, unknown[]>): DataContext;
317
- /**
318
- * Merge multiple data contexts.
319
- * Later contexts take precedence.
320
- */
321
- declare function mergeDataContexts(...contexts: DataContext[]): DataContext;
322
-
323
- /**
324
- * Slot Definitions
325
- *
326
- * Defines the available UI slots and their rendering behavior.
327
- * Slots are either inline (rendered in the component tree) or
328
- * portal (rendered to document.body via React Portal).
329
- *
330
- * @packageDocumentation
331
- */
332
-
333
- /**
334
- * Definitions for all available UI slots.
335
- *
336
- * Inline slots render within the component hierarchy.
337
- * Portal slots render to document.body, breaking out of overflow containers.
338
- */
339
- declare const SLOT_DEFINITIONS: Record<UISlot, SlotDefinition>;
340
- /**
341
- * Get the slot definition for a slot name.
342
- */
343
- declare function getSlotDefinition(slot: UISlot): SlotDefinition;
344
- /**
345
- * Check if a slot is a portal slot.
346
- */
347
- declare function isPortalSlot(slot: UISlot): boolean;
348
- /**
349
- * Check if a slot is an inline slot.
350
- */
351
- declare function isInlineSlot(slot: UISlot): boolean;
352
- /**
353
- * Get all slots of a specific type.
354
- */
355
- declare function getSlotsByType(type: SlotType): UISlot[];
356
- /**
357
- * Get all inline slots.
358
- */
359
- declare function getInlineSlots(): UISlot[];
360
- /**
361
- * Get all portal slots.
362
- */
363
- declare function getPortalSlots(): UISlot[];
364
- /**
365
- * All valid slot names.
366
- */
367
- declare const ALL_SLOTS: UISlot[];
368
-
369
- /**
370
- * NavigationContext - Schema-Driven Navigation for Orbital Runtime
371
- *
372
- * Provides navigation within the orbital schema without react-router dependency.
373
- * Navigation works by:
374
- * 1. Matching path to a page in the schema
375
- * 2. Extracting route params (e.g., /inspection/:id → { id: "123" })
376
- * 3. Switching active page
377
- * 4. Triggering INIT with merged payload
378
- *
379
- * This approach works whether OrbitalRuntime is standalone or embedded in another app.
380
- *
381
- * Used by both:
382
- * - Builder runtime (interpreted execution)
383
- * - Compiled shells (generated applications)
384
- *
385
- * @packageDocumentation
386
- */
387
-
388
- /**
389
- * Match a concrete path against a pattern with :param placeholders.
390
- * Returns null if no match, or the extracted params if match.
391
- *
392
- * @example
393
- * matchPath('/inspection/:id', '/inspection/123') // { id: '123' }
394
- * matchPath('/users/:userId/posts/:postId', '/users/42/posts/7') // { userId: '42', postId: '7' }
395
- * matchPath('/about', '/about') // {}
396
- * matchPath('/about', '/contact') // null
397
- */
398
- declare function matchPath(pattern: string, path: string): Record<string, string> | null;
399
- /**
400
- * Extract route params from a path given its pattern.
401
- * Wrapper around matchPath for explicit use.
402
- */
403
- declare function extractRouteParams(pattern: string, path: string): Record<string, string>;
404
- /**
405
- * Check if a path matches a pattern.
406
- */
407
- declare function pathMatches(pattern: string, path: string): boolean;
408
- /**
409
- * Find a page in the schema by matching its path pattern against a concrete path.
410
- * Returns the page and extracted route params.
411
- */
412
- declare function findPageByPath(schema: OrbitalSchema, path: string): {
413
- page: OrbitalPage;
414
- params: Record<string, string>;
415
- orbitalName: string;
416
- } | null;
417
- /**
418
- * Find a page by name.
419
- */
420
- declare function findPageByName(schema: OrbitalSchema, pageName: string): {
421
- page: OrbitalPage;
422
- orbitalName: string;
423
- } | null;
424
- /**
425
- * Get the first page in the schema (default page).
426
- */
427
- declare function getDefaultPage(schema: OrbitalSchema): {
428
- page: OrbitalPage;
429
- orbitalName: string;
430
- } | null;
431
- /**
432
- * Get all pages from the schema.
433
- */
434
- declare function getAllPages(schema: OrbitalSchema): Array<{
435
- page: OrbitalPage;
436
- orbitalName: string;
437
- }>;
438
- interface NavigationState {
439
- /** Current active page name */
440
- activePage: string;
441
- /** Current path (for URL sync) */
442
- currentPath: string;
443
- /** Payload to pass to INIT when page loads */
444
- initPayload: Record<string, unknown>;
445
- /** Navigation counter (increments on each navigation) */
446
- navigationId: number;
447
- }
448
- interface NavigationContextValue {
449
- /** Current navigation state */
450
- state: NavigationState;
451
- /** Navigate to a path with optional payload */
452
- navigateTo: (path: string, payload?: Record<string, unknown>) => void;
453
- /** Navigate to a page by name with optional payload */
454
- navigateToPage: (pageName: string, payload?: Record<string, unknown>) => void;
455
- /** The schema being navigated */
456
- schema: OrbitalSchema;
457
- /** Whether navigation is ready (schema loaded) */
458
- isReady: boolean;
459
- }
460
- interface NavigationProviderProps {
461
- /** The schema to navigate within */
462
- schema: OrbitalSchema;
463
- /** Initial page name (optional, defaults to first page) */
464
- initialPage?: string;
465
- /** Whether to update browser URL on navigation (default: true) */
466
- updateUrl?: boolean;
467
- /** Callback when navigation occurs */
468
- onNavigate?: (pageName: string, path: string, payload: Record<string, unknown>) => void;
469
- /** Children */
470
- children: React__default.ReactNode;
471
- }
472
- /**
473
- * NavigationProvider - Provides schema-driven navigation context
474
- *
475
- * @example
476
- * ```tsx
477
- * <NavigationProvider schema={mySchema}>
478
- * <OrbitalRuntimeContent />
479
- * </NavigationProvider>
480
- * ```
481
- */
482
- declare function NavigationProvider({ schema, initialPage, updateUrl, onNavigate, children, }: NavigationProviderProps): React__default.ReactElement;
483
- /**
484
- * Hook to access navigation context.
485
- * Returns null if not within NavigationProvider.
486
- */
487
- declare function useNavigation(): NavigationContextValue | null;
488
- /**
489
- * Hook to get the navigateTo function.
490
- * Returns a no-op function if not within NavigationProvider.
491
- */
492
- declare function useNavigateTo(): (path: string, payload?: Record<string, unknown>) => void;
493
- /**
494
- * Hook to get current navigation state.
495
- */
496
- declare function useNavigationState(): NavigationState | null;
497
- /**
498
- * Hook to get the current INIT payload (for passing to trait INIT events).
499
- */
500
- declare function useInitPayload(): Record<string, unknown>;
501
- /**
502
- * Hook to get current active page name.
503
- */
504
- declare function useActivePage(): string | null;
505
- /**
506
- * Hook to get navigation ID (changes on each navigation, useful for triggering effects).
507
- */
508
- declare function useNavigationId(): number;
509
-
510
- /**
511
- * Pattern Resolver Initialization
512
- *
513
- * Loads pattern registry and component mapping from orbital-shared/patterns/
514
- * and initializes the pattern resolver at app startup.
515
- *
516
- * @packageDocumentation
517
- */
518
- /**
519
- * Initialize the pattern resolver with shared pattern data.
520
- * Must be called once at app startup before any pattern rendering.
521
- * @returns The number of patterns initialized
522
- */
523
- declare function initializePatterns(): number;
524
-
525
- 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 };
17
+ export type { ClientEffect, NotifyOptions, ClientEffectExecutorConfig, PatternConfig, ResolvedPattern, EventResponse, UISlot, SlotType, SlotDefinition, DataContext, DataResolution, } from './types';
18
+ export { resolvePattern, isKnownPattern, getKnownPatterns, getPatternsByCategory, getPatternMapping, getPatternDefinition, initializePatternResolver, setComponentMapping, setPatternRegistry, } from './pattern-resolver';
19
+ export { executeClientEffects, parseClientEffect, parseClientEffects, filterEffectsByType, getRenderUIEffects, getNavigateEffects, getNotifyEffects, getEmitEffects, } from './client-effect-executor';
20
+ export { useClientEffects, useClientEffectConfig, useClientEffectConfigOptional, ClientEffectConfigProvider, ClientEffectConfigContext, } from './useClientEffects';
21
+ export type { UseClientEffectsOptions, UseClientEffectsResult, } from './useClientEffects';
22
+ export { resolveEntityData, resolveEntityDataWithQuery, resolveEntityById, resolveEntityCount, hasEntities, createFetchedDataContext, mergeDataContexts, } from './data-resolver';
23
+ export { SLOT_DEFINITIONS, getSlotDefinition, isPortalSlot, isInlineSlot, getSlotsByType, getInlineSlots, getPortalSlots, ALL_SLOTS, } from './slot-definitions';
24
+ export { OfflineExecutor, createOfflineExecutor, useOfflineExecutor, } from './offline-executor';
25
+ export type { PendingSyncEffect, OfflineExecutorConfig, OfflineExecutorState, UseOfflineExecutorOptions, UseOfflineExecutorResult, } from './offline-executor';
26
+ export { NavigationProvider, useNavigation, useNavigateTo, useNavigationState, useInitPayload, useActivePage, useNavigationId, matchPath, extractRouteParams, pathMatches, findPageByPath, findPageByName, getDefaultPage, getAllPages, } from './navigation';
27
+ export type { NavigationState, NavigationContextValue, NavigationProviderProps, } from './navigation';
28
+ export { initializePatterns } from './init';
@@ -126,7 +126,7 @@ function useClientEffects(effects, options) {
126
126
  }
127
127
  execute(effects);
128
128
  }, [effects, enabled, execute]);
129
- const prevEffectsRef = useRef();
129
+ const prevEffectsRef = useRef(void 0);
130
130
  useEffect(() => {
131
131
  if (effects !== prevEffectsRef.current) {
132
132
  prevEffectsRef.current = effects;