@link-foundation/ui-components 0.0.0-stage → 0.0.0

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 (402) hide show
  1. package/CONFIGURATIONS.md +74 -0
  2. package/ICONS.md +76 -0
  3. package/LICENSE +24 -0
  4. package/README.md +1499 -2
  5. package/bin/lino-network.mjs +71 -0
  6. package/dist/icons/ATTRIBUTION.md +602 -0
  7. package/dist/icons/NOTICE.lino +1261 -0
  8. package/dist/icons/brand.js +31 -0
  9. package/dist/icons/brand.svg +3 -0
  10. package/dist/icons/licenses/brand/DISCLAIMER.md +51 -0
  11. package/dist/icons/licenses/brand/LICENSE.md +30 -0
  12. package/dist/icons/licenses/lucide/LICENSE +43 -0
  13. package/dist/icons/licenses/material-symbols/LICENSE +202 -0
  14. package/dist/icons/licenses/material-symbols/NOTICE +12 -0
  15. package/dist/icons/licenses/tabler/LICENSE +21 -0
  16. package/dist/icons/lucide.js +681 -0
  17. package/dist/icons/lucide.svg +34 -0
  18. package/dist/icons/material-symbols.js +681 -0
  19. package/dist/icons/material-symbols.svg +34 -0
  20. package/dist/icons/own.js +521 -0
  21. package/dist/icons/own.svg +34 -0
  22. package/dist/icons/tabler.js +681 -0
  23. package/dist/icons/tabler.svg +34 -0
  24. package/dist/network-layout-NOTICE.md +6 -0
  25. package/dist/network-layout-d3-dispatch-LICENSE.txt +13 -0
  26. package/dist/network-layout-d3-force-LICENSE.txt +13 -0
  27. package/dist/network-layout-d3-quadtree-LICENSE.txt +13 -0
  28. package/dist/network-layout-d3-timer-LICENSE.txt +13 -0
  29. package/dist/network-layout-dagre-LICENSE.txt +19 -0
  30. package/dist/network-layout.worker.mjs +2 -0
  31. package/package.json +246 -4
  32. package/src/a11y/announce.js +88 -0
  33. package/src/a11y/bind-machine.js +181 -0
  34. package/src/a11y/focus.js +169 -0
  35. package/src/a11y/index.d.ts +89 -0
  36. package/src/a11y/index.js +19 -0
  37. package/src/a11y/keys.js +182 -0
  38. package/src/a11y/roving.js +167 -0
  39. package/src/a11y/typeahead.js +82 -0
  40. package/src/behavior/actions.js +235 -0
  41. package/src/behavior/diagnostics.js +73 -0
  42. package/src/behavior/dom.d.ts +38 -0
  43. package/src/behavior/dom.js +420 -0
  44. package/src/behavior/index.d.ts +211 -0
  45. package/src/behavior/index.js +29 -0
  46. package/src/behavior/interpret.js +454 -0
  47. package/src/behavior/machines/disclosure.lino +46 -0
  48. package/src/behavior/machines/index.js +91 -0
  49. package/src/behavior/machines/toggle.lino +25 -0
  50. package/src/behavior/parse-machine.js +367 -0
  51. package/src/charts/README.md +78 -0
  52. package/src/charts/activity-layout.js +350 -0
  53. package/src/charts/activity-model.js +130 -0
  54. package/src/charts/activity-validation.js +31 -0
  55. package/src/charts/chart-model.js +667 -0
  56. package/src/charts/chart.js +518 -0
  57. package/src/charts/echarts-adapter.d.ts +23 -0
  58. package/src/charts/echarts-adapter.js +240 -0
  59. package/src/charts/element.js +330 -0
  60. package/src/charts/errors.js +62 -0
  61. package/src/charts/gauge.js +27 -0
  62. package/src/charts/index.d.ts +344 -0
  63. package/src/charts/index.js +59 -0
  64. package/src/charts/layout.js +542 -0
  65. package/src/charts/lino.js +158 -0
  66. package/src/charts/mark-options.js +78 -0
  67. package/src/charts/read.js +101 -0
  68. package/src/charts/renderer-features.js +8 -0
  69. package/src/charts/scales.js +223 -0
  70. package/src/charts/small-model.js +223 -0
  71. package/src/charts/small-svg.js +269 -0
  72. package/src/charts/sparkline.js +27 -0
  73. package/src/charts/stat-tile.js +37 -0
  74. package/src/charts/summary.js +193 -0
  75. package/src/charts/svg-renderer.js +226 -0
  76. package/src/charts/svg.js +69 -0
  77. package/src/charts/tag-cloud.js +129 -0
  78. package/src/charts/tokens.js +171 -0
  79. package/src/charts/tooltip.js +47 -0
  80. package/src/charts/values.js +146 -0
  81. package/src/chat/README.md +142 -0
  82. package/src/chat/actions.js +75 -0
  83. package/src/chat/chat-contract.js +95 -0
  84. package/src/chat/chat-list.js +42 -0
  85. package/src/chat/chat-model.js +125 -0
  86. package/src/chat/chat.css +228 -0
  87. package/src/chat/composer.js +131 -0
  88. package/src/chat/day-separator.js +12 -0
  89. package/src/chat/dom.js +33 -0
  90. package/src/chat/follow.js +49 -0
  91. package/src/chat/index.d.ts +142 -0
  92. package/src/chat/index.js +13 -0
  93. package/src/chat/message-bubble.js +191 -0
  94. package/src/chat/message-stream.js +331 -0
  95. package/src/chat/reasoning-trace.js +70 -0
  96. package/src/chat/selection.js +39 -0
  97. package/src/chat/skins/bubbles.lino +2 -0
  98. package/src/chat/skins/cards.lino +4 -0
  99. package/src/chat/skins/compact.lino +4 -0
  100. package/src/chat/skins/signal.lino +25 -0
  101. package/src/chat/skins/t3.lino +25 -0
  102. package/src/chat/skins/telegram.lino +31 -0
  103. package/src/chat/skins/whatsapp.lino +25 -0
  104. package/src/chat/stream-keys.js +57 -0
  105. package/src/chat/stream-window.js +159 -0
  106. package/src/chat/vocabulary.js +19 -0
  107. package/src/controls/accordion.js +160 -0
  108. package/src/controls/avatar.js +80 -0
  109. package/src/controls/badge.js +48 -0
  110. package/src/controls/button-template.js +32 -0
  111. package/src/controls/button.js +97 -0
  112. package/src/controls/catalog.lino +84 -0
  113. package/src/controls/checkbox.js +112 -0
  114. package/src/controls/chip.js +140 -0
  115. package/src/controls/choices.js +45 -0
  116. package/src/controls/color-field.js +217 -0
  117. package/src/controls/color-popover.js +135 -0
  118. package/src/controls/color-rgb.js +80 -0
  119. package/src/controls/color.js +67 -0
  120. package/src/controls/combobox.js +192 -0
  121. package/src/controls/dom.js +261 -0
  122. package/src/controls/icon-button.js +33 -0
  123. package/src/controls/index.d.ts +163 -0
  124. package/src/controls/index.js +182 -0
  125. package/src/controls/kinds-text.js +358 -0
  126. package/src/controls/kinds.lino +350 -0
  127. package/src/controls/label.js +52 -0
  128. package/src/controls/link.js +101 -0
  129. package/src/controls/listbox.js +144 -0
  130. package/src/controls/machines/button.lino +20 -0
  131. package/src/controls/machines/checkbox.lino +17 -0
  132. package/src/controls/machines/chip.lino +20 -0
  133. package/src/controls/machines/color-field.lino +23 -0
  134. package/src/controls/machines/combobox.lino +82 -0
  135. package/src/controls/machines/icon-button.lino +20 -0
  136. package/src/controls/machines/index.js +586 -0
  137. package/src/controls/machines/number-field.lino +71 -0
  138. package/src/controls/machines/radio-group.lino +17 -0
  139. package/src/controls/machines/select.lino +122 -0
  140. package/src/controls/machines/slider.lino +99 -0
  141. package/src/controls/machines/switch.lino +19 -0
  142. package/src/controls/machines/text-area.lino +26 -0
  143. package/src/controls/machines/text-field.lino +26 -0
  144. package/src/controls/number-field.js +239 -0
  145. package/src/controls/numeric-keys.js +125 -0
  146. package/src/controls/option.js +54 -0
  147. package/src/controls/progress.js +76 -0
  148. package/src/controls/radio-group.js +234 -0
  149. package/src/controls/select.js +229 -0
  150. package/src/controls/slider.js +234 -0
  151. package/src/controls/stories.js +172 -0
  152. package/src/controls/styles.css +1060 -0
  153. package/src/controls/switch.js +95 -0
  154. package/src/controls/text-area.js +39 -0
  155. package/src/controls/text-field.js +131 -0
  156. package/src/controls/vocabulary.js +164 -0
  157. package/src/data/data.css +95 -0
  158. package/src/data/index.d.ts +83 -0
  159. package/src/data/index.js +10 -0
  160. package/src/data/keyboard.js +189 -0
  161. package/src/data/list.js +215 -0
  162. package/src/data/render-data.js +116 -0
  163. package/src/data/selection-dom.js +39 -0
  164. package/src/data/selection-model.js +43 -0
  165. package/src/data/sort-model.js +42 -0
  166. package/src/data/source.js +45 -0
  167. package/src/data/table.js +160 -0
  168. package/src/data/tree-model.js +41 -0
  169. package/src/data/tree.js +55 -0
  170. package/src/data/viewport.js +216 -0
  171. package/src/data/virtual-range.js +92 -0
  172. package/src/data/vocabulary.js +67 -0
  173. package/src/diagrams/diagram-model.js +511 -0
  174. package/src/diagrams/diagram.js +204 -0
  175. package/src/diagrams/index.d.ts +225 -0
  176. package/src/diagrams/index.js +48 -0
  177. package/src/diagrams/layout-dagre.js +164 -0
  178. package/src/diagrams/layout-plugins.js +131 -0
  179. package/src/diagrams/mermaid-export.js +232 -0
  180. package/src/diagrams/mermaid-view.js +229 -0
  181. package/src/diagrams/svg-diagram.js +215 -0
  182. package/src/editor/code-editor.js +206 -0
  183. package/src/editor/documents-model.js +170 -0
  184. package/src/editor/documents-persistence.js +85 -0
  185. package/src/editor/editor-engine.js +22 -0
  186. package/src/editor/editor-ui.js +203 -0
  187. package/src/editor/editor.css +106 -0
  188. package/src/editor/engines/codemirror.js +227 -0
  189. package/src/editor/engines/monaco.js +219 -0
  190. package/src/editor/index.d.ts +111 -0
  191. package/src/editor/index.js +14 -0
  192. package/src/editor/lino-highlight.js +106 -0
  193. package/src/editor/lino-structure.js +85 -0
  194. package/src/editor/validate-lino.js +43 -0
  195. package/src/embed/README.md +161 -0
  196. package/src/embed/controller.js +223 -0
  197. package/src/embed/element.js +141 -0
  198. package/src/embed/index.d.ts +75 -0
  199. package/src/embed/index.js +9 -0
  200. package/src/embed/providers/telegram.d.ts +3 -0
  201. package/src/embed/providers/telegram.js +38 -0
  202. package/src/embed/providers/vk.d.ts +3 -0
  203. package/src/embed/providers/vk.js +42 -0
  204. package/src/embed/providers/x.d.ts +3 -0
  205. package/src/embed/providers/x.js +31 -0
  206. package/src/embed/registry.js +35 -0
  207. package/src/embed/script.js +73 -0
  208. package/src/embed/view.js +122 -0
  209. package/src/icons/adapters/lucide.d.ts +15 -0
  210. package/src/icons/adapters/lucide.js +142 -0
  211. package/src/icons/adapters/material-symbols.d.ts +13 -0
  212. package/src/icons/adapters/material-symbols.js +113 -0
  213. package/src/icons/adapters/shared.d.ts +38 -0
  214. package/src/icons/adapters/shared.js +157 -0
  215. package/src/icons/adapters/simple-icons.d.ts +9 -0
  216. package/src/icons/adapters/simple-icons.js +38 -0
  217. package/src/icons/adapters/tabler.d.ts +9 -0
  218. package/src/icons/adapters/tabler.js +86 -0
  219. package/src/icons/icon-registry.js +215 -0
  220. package/src/icons/icon.js +356 -0
  221. package/src/icons/index.d.ts +123 -0
  222. package/src/icons/index.js +30 -0
  223. package/src/icons/names.js +51 -0
  224. package/src/icons/own-icons.js +521 -0
  225. package/src/icons/presentation.js +55 -0
  226. package/src/icons/svg.js +136 -0
  227. package/src/index.d.ts +14 -0
  228. package/src/index.js +40 -0
  229. package/src/layout/README.md +102 -0
  230. package/src/layout/app-shell.js +150 -0
  231. package/src/layout/catalog.lino +27 -0
  232. package/src/layout/dock-model.js +576 -0
  233. package/src/layout/dock-view.js +312 -0
  234. package/src/layout/dock.js +352 -0
  235. package/src/layout/dom.js +312 -0
  236. package/src/layout/grid.js +192 -0
  237. package/src/layout/index.d.ts +267 -0
  238. package/src/layout/index.js +60 -0
  239. package/src/layout/layer-manager.js +120 -0
  240. package/src/layout/layout.css +760 -0
  241. package/src/layout/menu.js +141 -0
  242. package/src/layout/nav-strip.js +174 -0
  243. package/src/layout/page-links.js +166 -0
  244. package/src/layout/panel.js +26 -0
  245. package/src/layout/pref-switches.js +209 -0
  246. package/src/layout/split-model.js +270 -0
  247. package/src/layout/split.js +430 -0
  248. package/src/layout/stack.js +86 -0
  249. package/src/layout/surfaces.js +119 -0
  250. package/src/layout/tab-group.js +151 -0
  251. package/src/layout/tab-strip.js +277 -0
  252. package/src/layout/vocabulary.js +229 -0
  253. package/src/layout/window-frame.js +222 -0
  254. package/src/layout/window.js +146 -0
  255. package/src/links-view/animator.js +144 -0
  256. package/src/links-view/configuration-classes.js +150 -0
  257. package/src/links-view/configuration-model.js +191 -0
  258. package/src/links-view/configuration-notations.js +230 -0
  259. package/src/links-view/configurations.d.ts +73 -0
  260. package/src/links-view/configurations.js +33 -0
  261. package/src/links-view/create-layout-runner.js +79 -0
  262. package/src/links-view/doublet-curves.js +239 -0
  263. package/src/links-view/doublet-layout.js +148 -0
  264. package/src/links-view/doublet-markers.js +109 -0
  265. package/src/links-view/doublet-options.js +369 -0
  266. package/src/links-view/doublet-svg.js +156 -0
  267. package/src/links-view/doublet.js +230 -0
  268. package/src/links-view/export.js +146 -0
  269. package/src/links-view/geometry.js +409 -0
  270. package/src/links-view/index.d.ts +1029 -0
  271. package/src/links-view/index.js +140 -0
  272. package/src/links-view/labels.js +28 -0
  273. package/src/links-view/layout-worker-entry.mjs +2 -0
  274. package/src/links-view/layout-worker.js +28 -0
  275. package/src/links-view/layouts/circle.js +7 -0
  276. package/src/links-view/layouts/force.js +76 -0
  277. package/src/links-view/layouts/grid.js +7 -0
  278. package/src/links-view/layouts/hex.js +8 -0
  279. package/src/links-view/layouts/index.js +15 -0
  280. package/src/links-view/layouts/layered.js +29 -0
  281. package/src/links-view/layouts/regular.js +27 -0
  282. package/src/links-view/layouts/spiral.js +10 -0
  283. package/src/links-view/link-view.js +494 -0
  284. package/src/links-view/links-gallery.js +306 -0
  285. package/src/links-view/links-network.js +496 -0
  286. package/src/links-view/lino-network-source.js +122 -0
  287. package/src/links-view/lino-network.js +233 -0
  288. package/src/links-view/lino-to-network.js +252 -0
  289. package/src/links-view/markers.js +192 -0
  290. package/src/links-view/model.js +233 -0
  291. package/src/links-view/network-editor/dom.js +36 -0
  292. package/src/links-view/network-editor/editor.js +202 -0
  293. package/src/links-view/network-editor/model.js +163 -0
  294. package/src/links-view/network-editor/options.js +265 -0
  295. package/src/links-view/network-editor/panels.js +423 -0
  296. package/src/links-view/network-editor/presets.js +76 -0
  297. package/src/links-view/network-editor/provider.js +93 -0
  298. package/src/links-view/network-editor/remap.js +45 -0
  299. package/src/links-view/network-editor/schema.js +224 -0
  300. package/src/links-view/network-editor/share.js +232 -0
  301. package/src/links-view/network-editor/styles.js +19 -0
  302. package/src/links-view/network-editor/url-sync.js +131 -0
  303. package/src/links-view/network-interaction.js +228 -0
  304. package/src/links-view/network-model.js +85 -0
  305. package/src/links-view/network-renderer.js +259 -0
  306. package/src/links-view/network-scene.js +245 -0
  307. package/src/links-view/network-source.js +82 -0
  308. package/src/links-view/network-vocabulary.js +18 -0
  309. package/src/links-view/presentation.js +199 -0
  310. package/src/links-view/render-canvas.js +102 -0
  311. package/src/links-view/render-svg.js +118 -0
  312. package/src/links-view/scene.js +233 -0
  313. package/src/links-view/solver-job.js +106 -0
  314. package/src/links-view/tokens.js +114 -0
  315. package/src/links-view/zoom-pan.js +203 -0
  316. package/src/overlays/catalog.lino +89 -0
  317. package/src/overlays/context-menu.js +110 -0
  318. package/src/overlays/dialog.js +117 -0
  319. package/src/overlays/dom.js +168 -0
  320. package/src/overlays/drawer.js +8 -0
  321. package/src/overlays/index.d.ts +80 -0
  322. package/src/overlays/index.js +25 -0
  323. package/src/overlays/kinds.lino +137 -0
  324. package/src/overlays/list-popover.js +129 -0
  325. package/src/overlays/machines/index.js +71 -0
  326. package/src/overlays/machines/surface.lino +11 -0
  327. package/src/overlays/machines/tabs.lino +7 -0
  328. package/src/overlays/machines/toast.lino +16 -0
  329. package/src/overlays/machines/tooltip.lino +29 -0
  330. package/src/overlays/menu.js +240 -0
  331. package/src/overlays/popover.js +194 -0
  332. package/src/overlays/position.js +84 -0
  333. package/src/overlays/radial-geometry.js +38 -0
  334. package/src/overlays/radial-menu.js +50 -0
  335. package/src/overlays/styles.css +155 -0
  336. package/src/overlays/tabs.js +125 -0
  337. package/src/overlays/toast-queue.js +105 -0
  338. package/src/overlays/toast.js +163 -0
  339. package/src/overlays/tooltip.js +110 -0
  340. package/src/overlays/vocabulary.js +3 -0
  341. package/src/settings/conditions.js +44 -0
  342. package/src/settings/control-for.js +62 -0
  343. package/src/settings/field-control.js +201 -0
  344. package/src/settings/index.d.ts +201 -0
  345. package/src/settings/index.js +3 -0
  346. package/src/settings/messages.js +112 -0
  347. package/src/settings/miniature.js +26 -0
  348. package/src/settings/panel-actions.js +234 -0
  349. package/src/settings/panel-model.js +49 -0
  350. package/src/settings/panel-refresh.js +56 -0
  351. package/src/settings/panel-rows.js +200 -0
  352. package/src/settings/preset-cards.js +43 -0
  353. package/src/settings/saved-looks.js +227 -0
  354. package/src/settings/section-layout.js +95 -0
  355. package/src/settings/section-tabs.js +175 -0
  356. package/src/settings/settings-panel.js +192 -0
  357. package/src/settings/settings.css +178 -0
  358. package/stories/accordion.lino +14 -0
  359. package/stories/alert-dialog.lino +4 -0
  360. package/stories/app-bar.lino +10 -0
  361. package/stories/avatar.lino +7 -0
  362. package/stories/badge.lino +12 -0
  363. package/stories/button.lino +17 -0
  364. package/stories/card.lino +10 -0
  365. package/stories/checkbox.lino +14 -0
  366. package/stories/chip.lino +19 -0
  367. package/stories/color-field.lino +9 -0
  368. package/stories/combobox.lino +10 -0
  369. package/stories/container.lino +11 -0
  370. package/stories/context-menu.lino +15 -0
  371. package/stories/dialog.lino +16 -0
  372. package/stories/drawer.lino +12 -0
  373. package/stories/icon-button.lino +13 -0
  374. package/stories/label.lino +7 -0
  375. package/stories/link-cards.lino +9 -0
  376. package/stories/link.lino +9 -0
  377. package/stories/menu-item.lino +6 -0
  378. package/stories/menu-separator.lino +7 -0
  379. package/stories/menu.lino +30 -0
  380. package/stories/nav-strip.lino +11 -0
  381. package/stories/number-field.lino +16 -0
  382. package/stories/option.lino +10 -0
  383. package/stories/paper.lino +11 -0
  384. package/stories/popover.lino +4 -0
  385. package/stories/pref-switches.lino +4 -0
  386. package/stories/progress.lino +14 -0
  387. package/stories/radial-menu.lino +19 -0
  388. package/stories/radio-group.lino +22 -0
  389. package/stories/radio.lino +10 -0
  390. package/stories/section-nav.lino +9 -0
  391. package/stories/select.lino +16 -0
  392. package/stories/slider.lino +14 -0
  393. package/stories/switch.lino +10 -0
  394. package/stories/tab-panel.lino +7 -0
  395. package/stories/tab.lino +7 -0
  396. package/stories/tabs.lino +25 -0
  397. package/stories/text-area.lino +12 -0
  398. package/stories/text-field.lino +23 -0
  399. package/stories/titled-section.lino +7 -0
  400. package/stories/toast.lino +3 -0
  401. package/stories/toaster.lino +2 -0
  402. package/stories/tooltip.lino +3 -0
@@ -0,0 +1,211 @@
1
+ import type { RawValue, UiDocument, UiNode } from '@link-foundation/ui-core';
2
+
3
+ export interface Diagnostic {
4
+ readonly code: string;
5
+ readonly severity: 'error' | 'warning' | 'info';
6
+ readonly message: string;
7
+ readonly at: Readonly<Record<string, unknown>>;
8
+ }
9
+
10
+ /** A step of a transition, an entry or an exit. */
11
+ export interface Action {
12
+ type: string;
13
+ args: RawValue[];
14
+ }
15
+
16
+ export interface Transition {
17
+ /** The next state; `null` keeps the state (actions only). */
18
+ target: string | null;
19
+ actions: Action[];
20
+ /** Guard names; all must pass. */
21
+ guards: string[];
22
+ }
23
+
24
+ export interface DelayedTransition extends Transition {
25
+ /** Milliseconds. */
26
+ delay: number;
27
+ }
28
+
29
+ export interface StateNode {
30
+ entry: Action[];
31
+ exit: Action[];
32
+ on: Record<string, Transition[]>;
33
+ after: DelayedTransition[];
34
+ }
35
+
36
+ export interface PartSpec {
37
+ attrs: { name: string; value: RawValue }[];
38
+ keys: { key: string; event: string }[];
39
+ events: { event: string; send: string }[];
40
+ }
41
+
42
+ export interface Machine {
43
+ id: string | null;
44
+ initial: string | null;
45
+ context: Record<string, unknown>;
46
+ actions: Record<string, Action[]>;
47
+ states: Record<string, StateNode>;
48
+ parts: Record<string, PartSpec>;
49
+ }
50
+
51
+ export type MachineSource = string | UiDocument | UiNode | object;
52
+
53
+ export interface ParseMachineOptions {
54
+ parseOptions?: object;
55
+ }
56
+
57
+ export function parseMachine(
58
+ source: MachineSource,
59
+ options?: ParseMachineOptions
60
+ ): { machine: Machine | null; diagnostics: Diagnostic[] };
61
+ export function parseMachines(
62
+ source: MachineSource,
63
+ options?: ParseMachineOptions
64
+ ): { machines: Map<string, Machine>; diagnostics: Diagnostic[] };
65
+ export function createMachine(
66
+ source: MachineSource,
67
+ options?: ParseMachineOptions
68
+ ): Machine;
69
+ export class MachineError extends Error {
70
+ diagnostics: Diagnostic[];
71
+ }
72
+ export function parseDelay(raw: RawValue): number;
73
+ export function toValue(raw: RawValue): unknown;
74
+
75
+ export interface MachineEvent {
76
+ type: string;
77
+ [key: string]: unknown;
78
+ }
79
+
80
+ export type Guard = (
81
+ context: Readonly<Record<string, unknown>>,
82
+ event: MachineEvent
83
+ ) => boolean;
84
+
85
+ export interface Clock {
86
+ setTimeout(fn: () => void, ms: number): unknown;
87
+ clearTimeout(handle: unknown): void;
88
+ }
89
+
90
+ export interface ManualClock extends Clock {
91
+ readonly now: number;
92
+ advance(ms: number): void;
93
+ pending(): number;
94
+ }
95
+
96
+ export function createManualClock(): ManualClock;
97
+
98
+ /** The text of an attribute value form, or `null` to leave it out. */
99
+ export function attrValue(
100
+ raw: RawValue,
101
+ state: string,
102
+ context: Readonly<Record<string, unknown>>
103
+ ): string | null;
104
+
105
+ export interface Snapshot {
106
+ readonly state: string;
107
+ readonly context: Readonly<Record<string, unknown>>;
108
+ readonly event: MachineEvent | null;
109
+ }
110
+
111
+ export interface Service {
112
+ readonly machine: Machine;
113
+ readonly state: string;
114
+ readonly context: Readonly<Record<string, unknown>>;
115
+ readonly status: 'running' | 'stopped';
116
+ send(event: string | MachineEvent): boolean;
117
+ can(event: string | MachineEvent): boolean;
118
+ subscribe(fn: (snapshot: Snapshot) => void): () => void;
119
+ assign(patch: Record<string, unknown>): void;
120
+ use(effects: Record<string, (...args: any[]) => unknown>): () => void;
121
+ attrs(part: string): Record<string, string>;
122
+ stop(): void;
123
+ }
124
+
125
+ export interface InterpretOptions {
126
+ actions?: ActionRegistry | Record<string, ActionFn>;
127
+ guards?: Record<string, Guard>;
128
+ clock?: Clock;
129
+ context?: Record<string, unknown>;
130
+ onDiagnostic?: (diagnostic: Diagnostic) => void;
131
+ }
132
+
133
+ export function interpret(
134
+ machine: Machine | string,
135
+ options?: InterpretOptions
136
+ ): Service;
137
+
138
+ export interface ActionMeta {
139
+ source?: string | null;
140
+ event?: string;
141
+ state?: string;
142
+ context?: Readonly<Record<string, unknown>>;
143
+ assign?: (patch: Record<string, unknown>) => void;
144
+ effects?: Record<string, (...args: any[]) => unknown>;
145
+ }
146
+
147
+ export type ActionFn = (args: readonly unknown[], meta: ActionMeta) => unknown;
148
+
149
+ export interface DispatchResult {
150
+ ok: boolean;
151
+ value?: unknown;
152
+ diagnostic?: Diagnostic;
153
+ }
154
+
155
+ export interface ActionRegistry {
156
+ register(name: string, fn: ActionFn): () => void;
157
+ has(name: unknown): boolean;
158
+ names(): string[];
159
+ dispatch(
160
+ name: unknown,
161
+ args?: readonly unknown[],
162
+ meta?: ActionMeta
163
+ ): DispatchResult;
164
+ }
165
+
166
+ export interface HostActions {
167
+ navigate?(target: string, meta: ActionMeta): unknown;
168
+ emit?(event: string, args: readonly unknown[], meta: ActionMeta): unknown;
169
+ set?(
170
+ target: string,
171
+ property: string,
172
+ value: unknown,
173
+ meta: ActionMeta
174
+ ): unknown;
175
+ toggle?(target: string, property: string, meta: ActionMeta): unknown;
176
+ focus?(target: string, meta: ActionMeta): unknown;
177
+ }
178
+
179
+ export interface ActionRegistryOptions {
180
+ onUnknown?: (diagnostic: Diagnostic) => void;
181
+ onDiagnostic?: (diagnostic: Diagnostic) => void;
182
+ host?: HostActions;
183
+ defaults?: boolean;
184
+ }
185
+
186
+ export function createActionRegistry(
187
+ options?: ActionRegistryOptions
188
+ ): ActionRegistry;
189
+ export function dispatchHandler(
190
+ registry: ActionRegistry,
191
+ values: readonly unknown[],
192
+ meta?: ActionMeta
193
+ ): DispatchResult[];
194
+ export function checkHandler(
195
+ registry: ActionRegistry,
196
+ values: readonly unknown[],
197
+ at?: Record<string, unknown>
198
+ ): Diagnostic[];
199
+ export function fail(code: string, at?: Record<string, unknown>): never;
200
+ export const VOCABULARY_ACTIONS: readonly string[];
201
+
202
+ export function diagnostic(
203
+ code: string,
204
+ severity: 'error' | 'warning' | 'info',
205
+ at?: Record<string, unknown>
206
+ ): Diagnostic;
207
+ export function isUnsafeUrl(url: unknown): boolean;
208
+
209
+ export const TOGGLE_MACHINE: string;
210
+ export const DISCLOSURE_MACHINE: string;
211
+ export const REFERENCE_MACHINES: Readonly<Record<string, string>>;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * `@link-foundation/ui-components/behavior`: behaviour state machines in
3
+ * Links Notation, their interpreter and the actions registry. This entry
4
+ * point imports nothing from the DOM or from ui-dom, so it runs in Node,
5
+ * workers and tests without `window` or `document`.
6
+ */
7
+
8
+ export {
9
+ parseMachine,
10
+ parseMachines,
11
+ createMachine,
12
+ MachineError,
13
+ parseDelay,
14
+ toValue,
15
+ } from './parse-machine.js';
16
+ export { interpret, createManualClock, attrValue } from './interpret.js';
17
+ export {
18
+ createActionRegistry,
19
+ dispatchHandler,
20
+ checkHandler,
21
+ fail,
22
+ VOCABULARY_ACTIONS,
23
+ } from './actions.js';
24
+ export { diagnostic, isUnsafeUrl } from './diagnostics.js';
25
+ export {
26
+ TOGGLE_MACHINE,
27
+ DISCLOSURE_MACHINE,
28
+ REFERENCE_MACHINES,
29
+ } from './machines/index.js';
@@ -0,0 +1,454 @@
1
+ /**
2
+ * Run a machine: a DOM-free interpreter of the flat state machines read by
3
+ * `parseMachine`. Events go in with `send`, state and context come out by
4
+ * `subscribe` and `attrs(part)`. Every effect is data: `(set NAME VALUE)`
5
+ * and `(toggle NAME)` change the context, a machine action expands to its
6
+ * steps, and any other action name is dispatched through the actions
7
+ * registry, where an unknown name is a diagnostic — nothing is evaluated.
8
+ * Time comes from an injected clock, so `(after 500ms ...)` is testable
9
+ * without waiting.
10
+ */
11
+
12
+ import { createActionRegistry } from './actions.js';
13
+ import { diagnostic } from './diagnostics.js';
14
+ import { createMachine, toValue } from './parse-machine.js';
15
+
16
+ /**
17
+ * @typedef {import('./parse-machine.js').Machine} Machine
18
+ * @typedef {import('./parse-machine.js').Action} Action
19
+ * @typedef {import('./parse-machine.js').Transition} Transition
20
+ * @typedef {import('./parse-machine.js').RawValue} RawValue
21
+ * @typedef {import('./actions.js').ActionRegistry} ActionRegistry
22
+ * @typedef {import('./actions.js').ActionFn} ActionFn
23
+ * @typedef {ReturnType<typeof diagnostic>} Diagnostic
24
+ *
25
+ * @typedef {{type: string, [key: string]: unknown}} MachineEvent
26
+ *
27
+ * @typedef {(context: Readonly<Record<string, unknown>>,
28
+ * event: MachineEvent) => boolean} Guard
29
+ *
30
+ * @typedef {object} Clock where `after` timers come from
31
+ * @property {(fn: () => void, ms: number) => unknown} setTimeout
32
+ * @property {(handle: unknown) => void} clearTimeout
33
+ *
34
+ * @typedef {object} Snapshot
35
+ * @property {string} state
36
+ * @property {Readonly<Record<string, unknown>>} context
37
+ * @property {MachineEvent|null} event what caused the change
38
+ *
39
+ * @typedef {object} Service
40
+ * @property {Machine} machine
41
+ * @property {string} state the current state
42
+ * @property {Readonly<Record<string, unknown>>} context the current
43
+ * context (a frozen copy)
44
+ * @property {'running'|'stopped'} status
45
+ * @property {(event: string | MachineEvent) => boolean} send `true` when
46
+ * a transition was taken
47
+ * @property {(event: string | MachineEvent) => boolean} can whether
48
+ * `send(event)` would take a transition now
49
+ * @property {(fn: (snapshot: Snapshot) => void) => () => void} subscribe
50
+ * called after every change; returns the unsubscribe function
51
+ * @property {(patch: Record<string, unknown>) => void} assign change the
52
+ * context from outside (a host property, say)
53
+ * @property {(effects: Record<string, Function>) => () => void} use add
54
+ * host effects (such as `focus`) for the actions; returns their removal
55
+ * @property {(part: string) => Record<string, string>} attrs the
56
+ * attributes of a part in the current state and context
57
+ * @property {() => void} stop clear the timers and ignore later events
58
+ */
59
+
60
+ /** The built-in guards; a `guards` option of the same name wins. */
61
+ const BUILT_IN_GUARDS = Object.freeze({
62
+ 'not-disabled': (context) => context.disabled !== true,
63
+ });
64
+
65
+ /** How deep machine actions may expand into each other. */
66
+ const MAX_DEPTH = 32;
67
+
68
+ /** A clock on the global timers, read when a timer is set. */
69
+ const globalClock = Object.freeze({
70
+ setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
71
+ clearTimeout: (handle) => globalThis.clearTimeout(handle),
72
+ });
73
+
74
+ /**
75
+ * A clock that only moves when told to, for tests and for replaying a
76
+ * recorded session: `advance(ms)` runs every timer that falls due, in order.
77
+ * @returns {Clock & {now: number, advance: (ms: number) => void,
78
+ * pending: () => number}}
79
+ */
80
+ export function createManualClock() {
81
+ let now = 0;
82
+ let nextId = 1;
83
+ /** @type {Map<number, {at: number, fn: () => void}>} */
84
+ const timers = new Map();
85
+ return {
86
+ get now() {
87
+ return now;
88
+ },
89
+ setTimeout(fn, ms = 0) {
90
+ const id = nextId++;
91
+ timers.set(id, { at: now + Math.max(0, Number(ms) || 0), fn });
92
+ return id;
93
+ },
94
+ clearTimeout(id) {
95
+ timers.delete(id);
96
+ },
97
+ pending: () => timers.size,
98
+ advance(ms) {
99
+ const end = now + ms;
100
+ for (;;) {
101
+ let due = null;
102
+ for (const [id, timer] of timers) {
103
+ if (timer.at <= end && (due === null || timer.at < due[1].at)) {
104
+ due = [id, timer];
105
+ }
106
+ }
107
+ if (due === null) {
108
+ break;
109
+ }
110
+ timers.delete(due[0]);
111
+ now = due[1].at;
112
+ due[1].fn();
113
+ }
114
+ now = end;
115
+ },
116
+ };
117
+ }
118
+
119
+ /** The registry for an `actions` option: a registry, a map or nothing. */
120
+ function registryOf(actions, onDiagnostic) {
121
+ if (actions && typeof actions.dispatch === 'function') {
122
+ return actions;
123
+ }
124
+ const registry = createActionRegistry({ onDiagnostic });
125
+ for (const [name, fn] of Object.entries(actions ?? {})) {
126
+ registry.register(name, fn);
127
+ }
128
+ return registry;
129
+ }
130
+
131
+ const toEvent = (event) =>
132
+ typeof event === 'string' ? { type: event } : { ...event };
133
+
134
+ const isName = (value) => typeof value === 'string' && value !== '';
135
+
136
+ /**
137
+ * The text of an attribute value form in a state and context, or `null`
138
+ * to leave the attribute out:
139
+ *
140
+ * - an atom: the atom itself;
141
+ * - `(context NAME)`: the context value as text;
142
+ * - `(in STATE...)`: `'true'` in one of the states, else `'false'`;
143
+ * - `(not FORM)`: the opposite of a `'true'`/`'false'` form;
144
+ * - `(present FORM)`: `''` (a boolean attribute) when the form is `'true'`;
145
+ * - `(state)`: the state name.
146
+ * @param {RawValue} raw
147
+ * @param {string} state
148
+ * @param {Readonly<Record<string, unknown>>} context
149
+ * @returns {string|null}
150
+ */
151
+ export function attrValue(raw, state, context) {
152
+ if (typeof raw === 'string') {
153
+ return raw;
154
+ }
155
+ if (!Array.isArray(raw)) {
156
+ return null;
157
+ }
158
+ const [head, ...rest] = raw;
159
+ const inner = () => attrValue(rest[0] ?? 'false', state, context);
160
+ switch (head) {
161
+ case 'context': {
162
+ const value = context[rest[0]];
163
+ return value === undefined || value === null ? null : String(value);
164
+ }
165
+ case 'in':
166
+ return String(rest.includes(state));
167
+ case 'not': {
168
+ const value = inner();
169
+ return value === null ? null : String(value !== 'true');
170
+ }
171
+ case 'present':
172
+ return inner() === 'true' ? '' : null;
173
+ case 'state':
174
+ return state;
175
+ default:
176
+ return null;
177
+ }
178
+ }
179
+
180
+ /**
181
+ * Whether every guard passes. An unknown guard and a guard that throws
182
+ * block the transition (fail closed) and are reported.
183
+ */
184
+ function guardsPass(names, guards, context, event, report) {
185
+ return names.every((name) => {
186
+ const guard = guards[name];
187
+ if (typeof guard !== 'function') {
188
+ report('unknown-guard', 'warning', { guard: name });
189
+ return false;
190
+ }
191
+ try {
192
+ return guard(context, event) === true;
193
+ } catch (error) {
194
+ report('guard-error', 'error', {
195
+ guard: name,
196
+ error: String(error?.message ?? error),
197
+ });
198
+ return false;
199
+ }
200
+ });
201
+ }
202
+
203
+ /** Whether an event would take a transition now (no diagnostics). */
204
+ const canTake = (node, event, guards, context) =>
205
+ (node.on[event.type] ?? []).some((t) =>
206
+ guardsPass(t.guards, guards, context, event, () => {})
207
+ );
208
+
209
+ /** The attributes of a part (`attrValue` of each, `null` left out). */
210
+ function partAttrs(part, state, context) {
211
+ const attrs = {};
212
+ for (const { name, value } of part?.attrs ?? []) {
213
+ const text = attrValue(value, state, context);
214
+ if (text !== null) {
215
+ attrs[name] = text;
216
+ }
217
+ }
218
+ return attrs;
219
+ }
220
+
221
+ /** Host effects (`use`): added in layers, each removable on its own. */
222
+ function createEffects() {
223
+ let effects = Object.freeze({});
224
+ return {
225
+ get current() {
226
+ return effects;
227
+ },
228
+ use(more) {
229
+ effects = Object.freeze({ ...effects, ...more });
230
+ return () => {
231
+ const rest = { ...effects };
232
+ for (const [name, fn] of Object.entries(more)) {
233
+ if (rest[name] === fn) {
234
+ delete rest[name];
235
+ }
236
+ }
237
+ effects = Object.freeze(rest);
238
+ };
239
+ },
240
+ };
241
+ }
242
+
243
+ /** The pending `after` timers of the current state. */
244
+ function createTimers(clock) {
245
+ const handles = new Set();
246
+ return {
247
+ set(fn, ms) {
248
+ const handle = clock.setTimeout(() => {
249
+ handles.delete(handle);
250
+ fn();
251
+ }, ms);
252
+ handles.add(handle);
253
+ },
254
+ clear() {
255
+ for (const handle of handles) {
256
+ clock.clearTimeout(handle);
257
+ }
258
+ handles.clear();
259
+ },
260
+ };
261
+ }
262
+
263
+ /** Check a machine argument; LiNo text is read with `createMachine`. */
264
+ function machineOf(machine) {
265
+ const spec = typeof machine === 'string' ? createMachine(machine) : machine;
266
+ if (!spec || typeof spec !== 'object' || !spec.states) {
267
+ throw new TypeError('interpret: expected a machine from parseMachine');
268
+ }
269
+ if (!Object.hasOwn(spec.states, spec.initial ?? '')) {
270
+ throw new TypeError(
271
+ `interpret: machine ${JSON.stringify(spec.id)} has no valid initial state`
272
+ );
273
+ }
274
+ return spec;
275
+ }
276
+
277
+ /**
278
+ * Start a machine.
279
+ * @param {Machine | string} machine a machine from `parseMachine`, or LiNo
280
+ * text (read with `createMachine`, which throws on errors)
281
+ * @param {object} [options]
282
+ * @param {ActionRegistry | Record<string, ActionFn>} [options.actions] a
283
+ * registry, or actions to register in a new one with the vocabulary
284
+ * defaults
285
+ * @param {Record<string, Guard>} [options.guards]
286
+ * @param {Clock} [options.clock] defaults to the global timers
287
+ * @param {Record<string, unknown>} [options.context] overrides the
288
+ * initial context
289
+ * @param {(d: Diagnostic) => void} [options.onDiagnostic]
290
+ * @returns {Service}
291
+ */
292
+ export function interpret(machine, options = {}) {
293
+ const spec = machineOf(machine);
294
+ const onDiagnostic = options.onDiagnostic ?? (() => {});
295
+ const report = (code, severity, at) =>
296
+ onDiagnostic(diagnostic(code, severity, { machine: spec.id, ...at }));
297
+ const registry = registryOf(options.actions, onDiagnostic);
298
+ const guards = { ...BUILT_IN_GUARDS, ...options.guards };
299
+ const timers = createTimers(options.clock ?? globalClock);
300
+ const effects = createEffects();
301
+ const listeners = new Set();
302
+ const queue = [];
303
+
304
+ let state = spec.initial;
305
+ let context = Object.freeze({ ...spec.context, ...options.context });
306
+ let status = 'running';
307
+ let changed = false;
308
+ let busy = false;
309
+
310
+ const setContext = (patch) => {
311
+ context = Object.freeze({ ...context, ...patch });
312
+ changed = true;
313
+ };
314
+
315
+ const notify = (event) => {
316
+ if (changed) {
317
+ changed = false;
318
+ const snapshot = Object.freeze({ state, context, event });
319
+ [...listeners].forEach((listener) => listener(snapshot));
320
+ }
321
+ };
322
+
323
+ /** Run one action step: a machine action, a context op or a registry name. */
324
+ const run = (action, event, depth) => {
325
+ const { type, args } = action;
326
+ if (args.length === 0 && Object.hasOwn(spec.actions, type)) {
327
+ if (depth >= MAX_DEPTH) {
328
+ report('action-error', 'error', {
329
+ action: type,
330
+ error: 'machine actions expand too deep',
331
+ });
332
+ return;
333
+ }
334
+ spec.actions[type].forEach((step) => run(step, event, depth + 1));
335
+ } else if (type === 'set' && args.length === 2 && isName(args[0])) {
336
+ setContext({ [args[0]]: toValue(args[1]) });
337
+ } else if (type === 'toggle' && args.length === 1 && isName(args[0])) {
338
+ setContext({ [args[0]]: context[args[0]] !== true });
339
+ } else {
340
+ registry.dispatch(type, args, {
341
+ source: spec.id,
342
+ event: event.type,
343
+ state,
344
+ context,
345
+ assign: (patch) => setContext({ ...patch }),
346
+ effects: effects.current,
347
+ });
348
+ }
349
+ };
350
+
351
+ const runAll = (actions, event) =>
352
+ actions.forEach((action) => run(action, event, 0));
353
+
354
+ /** Schedule the `after` transitions of the current state. */
355
+ const schedule = () => {
356
+ for (const delayed of spec.states[state].after) {
357
+ timers.set(() => {
358
+ if (status === 'running') {
359
+ process({ type: `after:${delayed.delay}` }, [delayed]);
360
+ }
361
+ }, delayed.delay);
362
+ }
363
+ };
364
+
365
+ const take = (transition, event) => {
366
+ if (transition.target === null) {
367
+ runAll(transition.actions, event);
368
+ return;
369
+ }
370
+ runAll(spec.states[state].exit, event);
371
+ timers.clear();
372
+ runAll(transition.actions, event);
373
+ state = transition.target;
374
+ changed = true;
375
+ runAll(spec.states[state].entry, event);
376
+ schedule();
377
+ };
378
+
379
+ /** Handle one event; events sent by actions are queued and run after it. */
380
+ function process(event, candidates) {
381
+ if (busy) {
382
+ queue.push([event, candidates]);
383
+ return false;
384
+ }
385
+ busy = true;
386
+ let taken = false;
387
+ try {
388
+ for (
389
+ let next = [event, candidates];
390
+ next !== undefined && status === 'running';
391
+ next = queue.shift()
392
+ ) {
393
+ const [current, list] = next;
394
+ const transitions = list ?? spec.states[state].on[current.type] ?? [];
395
+ const transition = transitions.find((t) =>
396
+ guardsPass(t.guards, guards, context, current, report)
397
+ );
398
+ if (transition) {
399
+ take(transition, current);
400
+ taken ||= current === event;
401
+ }
402
+ notify(current);
403
+ }
404
+ } finally {
405
+ busy = false;
406
+ queue.length = 0;
407
+ }
408
+ return taken;
409
+ }
410
+
411
+ // Enter the initial state.
412
+ busy = true;
413
+ try {
414
+ runAll(spec.states[state].entry, { type: 'init' });
415
+ schedule();
416
+ } finally {
417
+ busy = false;
418
+ changed = false;
419
+ }
420
+
421
+ return Object.freeze({
422
+ machine: spec,
423
+ get state() {
424
+ return state;
425
+ },
426
+ get context() {
427
+ return context;
428
+ },
429
+ get status() {
430
+ return status;
431
+ },
432
+ send: (event) => status === 'running' && process(toEvent(event)),
433
+ can: (event) =>
434
+ status === 'running' &&
435
+ canTake(spec.states[state], toEvent(event), guards, context),
436
+ subscribe(fn) {
437
+ listeners.add(fn);
438
+ return () => listeners.delete(fn);
439
+ },
440
+ assign(patch) {
441
+ if (status === 'running') {
442
+ setContext({ ...patch });
443
+ notify({ type: 'assign' });
444
+ }
445
+ },
446
+ use: (more) => effects.use(more),
447
+ attrs: (part) => partAttrs(spec.parts[part], state, context),
448
+ stop() {
449
+ status = 'stopped';
450
+ timers.clear();
451
+ queue.length = 0;
452
+ },
453
+ });
454
+ }