@link-foundation/ui-components 0.0.0-stage → 0.1.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
package/README.md CHANGED
@@ -1,3 +1,1500 @@
1
- # Temporary Holding Version
1
+ # @link-foundation/ui-components
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Components of the associative UI framework, written in
4
+ [Links Notation](https://github.com/link-foundation/links-notation):
5
+
6
+ - **State machines in LiNo** (`./behavior`): `parseMachine` reads a
7
+ machine and reports problems as diagnostics. `interpret` runs it. This
8
+ entry point imports nothing from the DOM or from ui-dom, so it also runs
9
+ in Node, in workers and in tests.
10
+ - **An actions registry** that never evaluates code. An action name maps to
11
+ a host function, and an unknown name is a diagnostic. `navigate` rejects
12
+ `javascript:`, `data:` and `vbscript:` URLs.
13
+ - **Reference machines**: `toggle` and `disclosure`.
14
+ - **ui-dom integration** (`./behavior/dom`): `mountBehavior` starts one
15
+ machine service for each `(machine NAME ...)` element.
16
+ - **Accessibility helpers** (`./a11y`): focus trap and restoration, roving
17
+ tabindex, typeahead, key bindings, a shared live region, and
18
+ `bindMachine`.
19
+ - **Charts** (`./charts`): a chart dialect in the grammar of Vega-Lite
20
+ (`data`, `mark`, `encoding`), a deterministic SVG renderer, `<ui-chart>`
21
+ with a data table twin and keyboard navigation, and the small charts
22
+ `<ui-stat-tile>`, `<ui-gauge>` and `<ui-sparkline>`. The ECharts adapter
23
+ (`./charts/echarts`) is loaded only for `(renderer echarts)`.
24
+ - **Diagrams in LiNo** (`./diagrams`): flowchart, state, sequence and class
25
+ diagrams laid out by Dagre, drawn as accessible SVG, exported to Mermaid
26
+ text or drawn by a lazily loaded Mermaid adapter. See [Diagrams](#diagrams).
27
+ - **One link** (`./links-view`): `link-view` draws a single link from LiNo
28
+ with the [links-visuals](https://github.com/konard/links-visuals)
29
+ geometry, as SVG or on a canvas, with its own zoom and pan.
30
+ - **Layout and windowing** (`./layout`, `./layout.css`): `stack`, `grid`,
31
+ `split`, `tab-group`, `dock`, `window`, `app-shell` and the surfaces
32
+ `container`, `paper`, `card` and `app-bar`, as kinds for ui-dom,
33
+ a layer manager, and dock layouts saved as Links Notation.
34
+ - **Basic controls** (`./controls`, `./controls.css`): button,
35
+ icon-button, label, link, text-field, text-area, number-field,
36
+ color-field, checkbox, radio-group, switch, slider, select, combobox,
37
+ progress (a bar or a ring), badge, avatar, chip and accordion as ui-dom kinds over native elements, each
38
+ with its WAI-ARIA pattern, a LiNo machine and stories
39
+ ([Basic controls](#basic-controls)).
40
+ - **Icons** (`./icons`): a public-domain icon set of our own, the icon
41
+ registry, the `ui-icon` element, and adapters for Lucide, Tabler and
42
+ Material Symbols that emit licence records ([Icons](#icons)).
43
+
44
+ ```sh
45
+ npm install @link-foundation/ui-components
46
+ ```
47
+
48
+ | Entry point | What it has | DOM |
49
+ | ----------------------------------------------------- | ----------------------------------------------------------------------- | --- |
50
+ | `@link-foundation/ui-components` | everything below except `./behavior/dom` and adapters | yes |
51
+ | `@link-foundation/ui-components/behavior` | `parseMachine`, `interpret`, `createActionRegistry`, ... | no |
52
+ | `@link-foundation/ui-components/behavior/dom` | `mountBehavior`, `BEHAVIOR_CSS` | yes |
53
+ | `@link-foundation/ui-components/a11y` | `trapFocus`, `createRovingTabindex`, `bindKeys`, ... | yes |
54
+ | `@link-foundation/ui-components/charts` | `parseChart`, `renderChartSvg`, `defineChartElements`, ... | yes |
55
+ | `@link-foundation/ui-components/charts/echarts` | `toEChartsOption`, `renderECharts` | yes |
56
+ | `@link-foundation/ui-components/diagrams` | `parseDiagram`, `toMermaid`, `defineDiagram`, ... | yes |
57
+ | `@link-foundation/ui-components/layout` | the layout kinds, `createLayerManager`, `resizeSplit`, `movePanel`, ... | yes |
58
+ | `@link-foundation/ui-components/layout.css` | the CSS of the layout kinds | |
59
+ | `@link-foundation/ui-components/controls` | `mountControls`, `registerControls`, `nextValue`, `parseStories`, ... | yes |
60
+ | `@link-foundation/ui-components/controls.css` | the token-only CSS of the basic controls | |
61
+ | `@link-foundation/ui-components/links-view` | `defineLinkView`, `linkGeometry`, `renderLinkSvg`, ... | yes |
62
+ | `@link-foundation/ui-components/icons` | `resolveIcon`, `registerIconSet`, `ui-icon`, ... | yes |
63
+ | `.../icons/adapters/{lucide,tabler,material-symbols}` | an icon source over the npm package of the set | no |
64
+
65
+ ## A machine in LiNo
66
+
67
+ ```lino
68
+ toggle-machine: machine
69
+ initial off
70
+ context
71
+ pressed false
72
+ disabled false
73
+ action set-pressed
74
+ set pressed true
75
+ action clear-pressed
76
+ set pressed false
77
+ state off
78
+ on toggle
79
+ target on
80
+ do set-pressed
81
+ when not-disabled
82
+ state on
83
+ on toggle
84
+ target off
85
+ do clear-pressed
86
+ when not-disabled
87
+ part root
88
+ attr aria-pressed
89
+ context pressed
90
+ key Enter toggle
91
+ key Space toggle
92
+ on press toggle
93
+ ```
94
+
95
+ | Form | Meaning |
96
+ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
97
+ | `(initial STATE)` | the first state (required) |
98
+ | `(context (NAME VALUE) ...)` | the initial context. `true`, `false` and numbers are typed; other atoms stay text |
99
+ | `(state NAME ...)` | a flat state |
100
+ | `(on EVENT (target S) (do ...) (when ...))` | a transition. The first one whose guards all pass is taken. With no `target`, the state stays and no exit or entry runs |
101
+ | `(entry ACTION ...)`, `(exit ...)` | actions run when the state is entered or left |
102
+ | `(after 500ms (target S) ...)` | a delayed transition (`ms`, `s` or a plain number of milliseconds). It is cancelled when the state is left |
103
+ | `(action NAME STEP ...)` | a named list of steps |
104
+ | `(set NAME VALUE)`, `(toggle NAME)` | built-in steps that change the context |
105
+ | `(part NAME (attr A V) (key K E) (on UI-EVENT E))` | the attributes of a part, the keys that send machine events (`Enter`, `Space`, `Shift+Tab`, `Ctrl+k`), and the UI events (`press`, `focus`, `blur`, `hover`) that send them |
106
+
107
+ Attribute values: `'text'`, `(context NAME)`, `(state)`, `(in S ...)`
108
+ (`true` or `false`), `(not V)`, and `(present V)`. `(present V)` makes a
109
+ boolean attribute such as `hidden` that is present only when `V` is
110
+ `true`. Attributes starting with `on` are never set.
111
+
112
+ Guards are names, never expressions. `not-disabled` is built in, and other
113
+ guards come from the `guards` option. An unknown guard, or a guard that
114
+ throws, blocks the transition and is reported.
115
+
116
+ ### Diagnostics
117
+
118
+ `parseMachine(text)` returns `{ machine, diagnostics }`. A diagnostic is
119
+ `{ code, severity, message, at }`. The codes are:
120
+
121
+ - `missing-initial`, `unknown-initial`
122
+ - `duplicate-state`, `duplicate-action`
123
+ - `unknown-target`
124
+ - `invalid-delay`, `invalid-transition`, `invalid-action`
125
+ - `unknown-field` (a warning)
126
+
127
+ ui-core's parse diagnostics are also passed through. `createMachine(text)`
128
+ throws a `MachineError` that lists the errors.
129
+
130
+ ## Running a machine without a DOM
131
+
132
+ ```js
133
+ import {
134
+ createManualClock,
135
+ interpret,
136
+ DISCLOSURE_MACHINE,
137
+ } from '@link-foundation/ui-components/behavior';
138
+
139
+ const clock = createManualClock(); // or globalThis (the default)
140
+ const service = interpret(DISCLOSURE_MACHINE, { clock });
141
+ service.subscribe(({ state, context }) => console.log(state, context));
142
+ service.send('toggle'); // closed → open
143
+ service.send('close'); // open → closing
144
+ clock.advance(500); // closing → closed
145
+ service.attrs('trigger'); // { 'aria-expanded': 'false', 'data-state': 'closed' }
146
+ service.stop(); // clears the timers and the subscribers
147
+ ```
148
+
149
+ A `service` has:
150
+
151
+ - `state`, `context` and `status`
152
+ - `send(event)` and `can(event)`
153
+ - `subscribe(fn)`, which returns an unsubscribe function
154
+ - `assign(patch)`
155
+ - `use(effects)`
156
+ - `attrs(part)`
157
+ - `stop()`
158
+
159
+ Events sent from an action are queued and run after the current
160
+ transition. A loop that goes deeper than 32 steps stops with an
161
+ `action-error`.
162
+
163
+ ## The actions registry
164
+
165
+ ```js
166
+ import { createActionRegistry } from '@link-foundation/ui-components/behavior';
167
+
168
+ const registry = createActionRegistry({
169
+ onUnknown: (d) => console.warn(d.message), // unknown-action
170
+ host: { navigate: (url) => router.push(url) },
171
+ });
172
+ registry.register('save', (args, meta) => save(meta.source));
173
+ registry.dispatch('navigate', ['javascript:alert(1)']); // { ok: false, diagnostic: unsafe-url }
174
+ registry.dispatch('alert(1)'); // { ok: false, diagnostic: unknown-action }
175
+ ```
176
+
177
+ The vocabulary actions have defaults that validate their arguments and
178
+ then call the `host` function of the same name:
179
+
180
+ - `navigate`
181
+ - `emit`
182
+ - `set`
183
+ - `toggle`
184
+ - `focus`
185
+
186
+ Handler text such as `(on press 'alert(1)')` is never run. It is an
187
+ `unknown-action` diagnostic. ESLint forbids `eval`, `new Function` and
188
+ string timers in `src/` (`no-eval`, `no-new-func`, `no-implied-eval`), and
189
+ a test checks that the rules stay on.
190
+
191
+ ## In a ui-dom document
192
+
193
+ ```js
194
+ import { mountBehavior } from '@link-foundation/ui-components/behavior/dom';
195
+
196
+ const behavior = mountBehavior(
197
+ app,
198
+ `(page: document
199
+ (bold: button (label Bold) (machine toggle-machine))
200
+ (more: button (label Details) (machine disclosure-machine (content panel)))
201
+ (panel: stack (t: text 'Details')))`,
202
+ {
203
+ actions: { save: (args, meta) => save(meta.source) },
204
+ host: { navigate: (url) => router.push(url) },
205
+ }
206
+ );
207
+ behavior.serviceFor('bold').state; // 'off'
208
+ behavior.destroy();
209
+ ```
210
+
211
+ `(machine NAME (PART ID) ...)` connects an element to a machine. Each
212
+ `(PART ID)` maps a machine part to another element, and every other part
213
+ is the element itself. Machines are looked up in this order:
214
+
215
+ 1. the `machines` option
216
+ 2. `machine` elements in the document
217
+ 3. the reference machines (`referenceMachines: false` leaves them out)
218
+
219
+ Element properties that the machine context has, such as `disabled`, are
220
+ passed to the service.
221
+
222
+ `mountBehavior` takes every ui-dom `mountDocument` option. Handlers use
223
+ the same registry, so `(on press (save))` works once `save` is registered.
224
+ `BEHAVIOR_CSS` makes `[hidden]` parts hidden even on flex containers.
225
+
226
+ ## Accessibility helpers
227
+
228
+ | Helper | What it does |
229
+ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |
230
+ | `trapFocus(container)` | Tab and Shift+Tab cycle inside the container. It returns `release`, which restores the earlier focus |
231
+ | `createRovingTabindex(items)` | one `tabindex="0"` item, moved with the arrow keys, Home and End |
232
+ | `createTypeahead(getLabels)` | typing letters moves to the first matching item |
233
+ | `bindKeys(element, { 'Shift+Tab': fn })` | key bindings. Typing in a text field never triggers a plain key |
234
+ | `announce(message, { politeness })` | shared `aria-live` regions (polite and assertive) for each document |
235
+ | `bindMachine(root, service, parts)` | applies the `attr` values of a machine to elements and binds its keys, UI events and `focus` |
236
+
237
+ ## Charts
238
+
239
+ You describe a chart with the grammar of
240
+ [Vega-Lite](https://vega.github.io/vega-lite/): `data`, `mark` and
241
+ `encoding`. The package checks it, writes it back as Links Notation, and
242
+ renders it as an SVG. The SVG is the same for the same spec every time.
243
+
244
+ The `<ui-chart>` element shows that SVG with an accessible name, a data
245
+ table twin and keyboard navigation between the points. `<ui-stat-tile>`,
246
+ `<ui-gauge>` and `<ui-sparkline>` are smaller charts.
247
+
248
+ The charts use `links-notation` (the parser),
249
+ [d3-scale](https://d3js.org/d3-scale) and [d3-shape](https://d3js.org/d3-shape).
250
+ Both d3 packages are pinned and served from `node_modules`, never from a CDN.
251
+ [ECharts](https://echarts.apache.org) is an optional peer dependency. It is
252
+ loaded only for a chart with `(renderer echarts)`.
253
+
254
+ ```js
255
+ import {
256
+ ChartSpecError,
257
+ chartToLino,
258
+ parseChart,
259
+ renderChartSvg,
260
+ } from '@link-foundation/ui-components';
261
+
262
+ const spec = parseChart(`(sales: chart
263
+ (title 'Monthly sales')
264
+ (description 'Sales grew from 12 to 30 thousand in the first half of 2026')
265
+ (data
266
+ (row (month 2026-01) (value 12))
267
+ (row (month 2026-02) (value 18))
268
+ (row (month 2026-03) (value 30)))
269
+ (mark line (point true))
270
+ (encoding
271
+ (x (field month) (type temporal))
272
+ (y (field value) (type quantitative))))`);
273
+
274
+ const svg = renderChartSvg(spec); // '<svg ... role="img" aria-label="Sales grew ...">'
275
+ renderChartSvg(spec) === svg; // true: no clock, no random ids
276
+ parseChart(chartToLino(spec)); // equal to spec
277
+
278
+ try {
279
+ parseChart('(c: chart (data (row (a 1))) (mark pie))');
280
+ } catch (error) {
281
+ error instanceof ChartSpecError; // true
282
+ error.code; // 'unknown-mark'
283
+ error.path; // [0, 2]
284
+ error.message; // 'unknown mark "pie" (expected ...) (at link 1 > 3: (mark pie))'
285
+ }
286
+ ```
287
+
288
+ In a page:
289
+
290
+ ```html
291
+ <script type="module">
292
+ import { defineChartElements } from '@link-foundation/ui-components';
293
+ defineChartElements(window);
294
+ </script>
295
+
296
+ <ui-chart>
297
+ <script type="text/lino">
298
+ (sales: chart
299
+ (description 'Sales grew from 12 to 30 thousand')
300
+ (data (row (month 2026-01) (value 12)) (row (month 2026-02) (value 30)))
301
+ (mark bar)
302
+ (encoding (x (field month) (type ordinal)) (y (field value) (type quantitative))))
303
+ </script>
304
+ </ui-chart>
305
+ <ui-gauge label="CPU" value="72" unit="%"></ui-gauge>
306
+ <ui-stat-tile
307
+ label="Revenue"
308
+ value="30200"
309
+ unit="USD"
310
+ delta="12.5"
311
+ trend="12 18 15 21 25 30"
312
+ ></ui-stat-tile>
313
+ <ui-sparkline label="Visits" values="3 5 2 8 6 9" mark="area"></ui-sparkline>
314
+ ```
315
+
316
+ The gallery `examples/charts.html` shows the original marks. The
317
+ [activity chart guide](src/charts/README.md) documents calendar, range,
318
+ composition, tag clouds, log scales and rich top-layer tooltips. To open it, run
319
+ `node scripts/serve-static.mjs` from the repository root and go to
320
+ http://127.0.0.1:4173/packages/ui-components/examples/charts.html.
321
+
322
+ ### Grammar
323
+
324
+ A chart is a `chart` element with an id:
325
+
326
+ | Link | Meaning |
327
+ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
328
+ | `(title 'text')` | Optional. Shown above the chart and used as the table caption. |
329
+ | `(description 'text')` | The accessible name of the chart. Without it, the title is used, and without a title, a summary of the data. |
330
+ | `(data (row (FIELD VALUE) ...) ...)` | The data rows. Numbers become numbers; other values stay text. |
331
+ | `(mark TYPE OPTION...)` | `line`, `area`, `bar`, `point` or `arc`. |
332
+ | `(encoding (CHANNEL (field F) (type T)))` | Which field goes to which channel. `T` is `quantitative`, `temporal`, `ordinal` or `nominal`. `(title 'text')` names the axis. |
333
+ | `(renderer svg)` / `(renderer echarts)` | Optional. `svg` is the default. |
334
+ | `(width N)` / `(height N)` | Optional. The default is 640 × 360. |
335
+
336
+ The channels of each mark:
337
+
338
+ | Mark | Channels | Options |
339
+ | -------------- | ------------------------------------ | --------------------------------------------------------------- |
340
+ | `line`, `area` | `x`, `y`, `color`, `tooltip` | `(interpolate linear\|monotone\|step)`, `(point true)` for dots |
341
+ | `bar` | `x`, `y`, `color`, `tooltip` | |
342
+ | `point` | `x`, `y`, `color`, `size`, `tooltip` | |
343
+ | `arc` | `theta`, `color`, `tooltip` | `(inner-radius N)` for a donut |
344
+
345
+ Bars and areas with a `color` field are stacked. `tooltip` takes one field,
346
+ `(tooltip (field f) (type t))`, or several,
347
+ `(tooltip ((field a) (type t)) ((field b) (type t)))`.
348
+
349
+ The small charts are elements too, so they can be written in Links Notation
350
+ as well: `(cpu: gauge (label CPU) (value 72) (unit %))`, `stat-tile` and
351
+ `sparkline`.
352
+
353
+ #### Errors
354
+
355
+ `chartFromLinks` and `parseChart` throw a `ChartSpecError` for a bad spec.
356
+ It has a `code`, a `reason`, the `path` of the link (the index of each link
357
+ from the top) and the `link` itself, written back as Links Notation. The
358
+ message ends with the position, for example `(at link 1 > 3: (mark pie))`.
359
+ Among the codes are `unknown-mark`, `unknown-type`, `missing-field`,
360
+ `missing-mark`, `invalid-data`, `invalid-value`, `empty-data` and
361
+ `duplicate-property`.
362
+
363
+ ### API
364
+
365
+ | Export | What it does |
366
+ | ---------------------------------------------- | ---------------------------------------------------------------------------------- |
367
+ | `parseChart(text)` | Parse one chart (or small chart) written in Links Notation. |
368
+ | `chartFromLinks(links)` / `chartsFromLinks()` | Read the links of the official parser into a spec (or all specs). |
369
+ | `chartToLino(spec)` | Write a spec back. `parseChart(chartToLino(spec))` is equal to `spec`. |
370
+ | `layoutChart(spec, options)` | Scales, series and points in pixels: what the renderers share. |
371
+ | `renderChartSvg(spec, options)` | The SVG as a string. The same spec always gives the same SVG. |
372
+ | `summarizeChart`, `chartLabel`, `chartTable` | The accessible name, the summary and the table twin of a spec. |
373
+ | `CHART_TOKENS`, `CHART_CSS`, `chartTokensLino` | The chart colour tokens as values, as CSS custom properties and as Links Notation. |
374
+ | `defineChartElements(window)` | Define `<ui-chart>`, `<ui-stat-tile>`, `<ui-gauge>` and `<ui-sparkline>`. |
375
+
376
+ `renderChartSvg` uses CSS custom properties for colours. Pass
377
+ `{ tokens: CHART_TOKENS.light }` to write literal colours instead, for
378
+ example for a file.
379
+
380
+ ### Accessibility
381
+
382
+ Every chart element renders:
383
+
384
+ - an SVG with `role="img"` and an `aria-label` taken from `(description ...)`;
385
+ - a visually hidden data table with a caption, one row per data row, and a
386
+ **Show data table** button (`aria-expanded`, `aria-controls`) that shows it;
387
+ - a polite `aria-live` region that announces the focused point.
388
+
389
+ The chart is one tab stop. With the focus on it:
390
+
391
+ | Key | Action |
392
+ | ------------------------- | ---------------------------------------------- |
393
+ | `ArrowRight`, `ArrowLeft` | The next or previous point of the series. |
394
+ | `ArrowDown`, `ArrowUp` | The same point in the next or previous series. |
395
+ | `Home`, `End` | The first or last point. |
396
+ | `Escape` | Hide the tooltip and the focus ring. |
397
+
398
+ Each move shows a tooltip and a focus ring, announces the point (for
399
+ example `Month: Jan 2026, Sales, thousand USD: 12, point 1 of 6`), and
400
+ sends a `chart-point` event. A bad spec shows a `role="alert"` message and
401
+ sends a `chart-error` event with the `ChartSpecError`.
402
+
403
+ The colours are checked in light and dark: every series colour has at least
404
+ 3:1 contrast with the chart background, and the chart text has at least 4.5:1.
405
+
406
+ ### Tokens
407
+
408
+ | Token | Light |
409
+ | ------------------------------------- | -------------------------------------------------------------------------------------- |
410
+ | `color.chart.1` … `color.chart.8` | `#1f6fb2`, `#c2410c`, `#15803d`, `#b91c5c`, `#6d28d9`, `#0e7490`, `#a16207`, `#4b5563` |
411
+ | `color.chart.background`, `.text` | `#ffffff`, `#1c1b1f` |
412
+ | `color.chart.muted`, `.axis`, `.grid` | `#5f6368`, `#5f6368`, `#e3e3e8` |
413
+ | `color.chart.focus` | `#1c1b1f` |
414
+
415
+ The dark values apply with `prefers-color-scheme: dark` or
416
+ `data-theme="dark"` on an ancestor. They become CSS custom properties such
417
+ as `--color-chart-1`, so a theme can override them. `chartTokensLino()`
418
+ writes them as a `@link-foundation/ui-tokens` theme.
419
+
420
+ ### ECharts
421
+
422
+ ```js
423
+ import { toEChartsOption } from '@link-foundation/ui-components/charts/echarts';
424
+
425
+ const option = toEChartsOption(spec, { theme: 'dark' }); // plain data, no functions
426
+ ```
427
+
428
+ `toEChartsOption` is pure. It gives the same option for the same spec, with
429
+ the literal token colours of the theme. With `(renderer echarts)`,
430
+ `<ui-chart>` loads the adapter with `import('./echarts-adapter.js')`, and the
431
+ adapter loads `import('echarts')`. ECharts then draws the chart. The SVG
432
+ stays in the page, visually hidden, as the accessible image, and the
433
+ keyboard moves show the ECharts tooltip. Charts without
434
+ `(renderer echarts)` never load either module, so a bundler puts ECharts
435
+ in a lazy chunk. `tests/charts/bundle.test.js` checks this.
436
+
437
+ ## Diagrams
438
+
439
+ A flowchart, state, sequence or class diagram is a `diagram` link.
440
+ [Dagre](https://github.com/dagrejs/dagre) (MIT) lays it out and our own SVG
441
+ renderer draws it. It can also be written out as Mermaid text, or drawn by
442
+ [Mermaid](https://mermaid.js.org) (MIT), which is loaded only when a page
443
+ shows a Mermaid diagram.
444
+
445
+ ```lino
446
+ login-flow: diagram
447
+ kind flowchart
448
+ direction down
449
+ start: node
450
+ label 'Start'
451
+ check: node
452
+ label 'Signed in?'
453
+ shape diamond
454
+ home: node
455
+ label 'Home'
456
+ edge
457
+ from start
458
+ to check
459
+ edge
460
+ from check
461
+ to home
462
+ label 'yes'
463
+ ```
464
+
465
+ ```js
466
+ import { defineDiagram } from '@link-foundation/ui-components';
467
+
468
+ defineDiagram();
469
+ const diagram = document.createElement('ui-diagram');
470
+ diagram.source = loginFlowLino; // the LiNo above
471
+ document.body.append(diagram);
472
+ ```
473
+
474
+ The LiNo can also be the text content of `<ui-diagram>`.
475
+ See [`examples/diagrams.html`](examples/diagrams.html). Run
476
+ `node scripts/serve-static.mjs` from the repository root and open
477
+ `http://127.0.0.1:4173/packages/ui-components/examples/diagrams.html`.
478
+
479
+ ### The diagram dialect
480
+
481
+ | Link | Meaning |
482
+ | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
483
+ | `(ID: diagram …)` | a diagram; the ID names it |
484
+ | `(kind K)` | `flowchart` (default), `state`, `sequence` or `class` |
485
+ | `(direction D)` | `down` (default), `up`, `right` or `left` |
486
+ | `(label 'Text')` | the title of the diagram (used by screen readers) |
487
+ | `(renderer R)` | `svg` or `mermaid`; by default `svg` for flowcharts and states and `mermaid` for sequence and class diagrams |
488
+ | `(layout NAME)` | a registered layout engine (default `dagre`) |
489
+ | `(ID: node …)` | a node with `(label …)`, `(shape …)` and `(group ID)` |
490
+ | `(shape S)` | `box` (default), `round`, `stadium`, `circle`, `diamond`, `start` or `end` |
491
+ | `(edge (from A) (to B) …)` | a connection, with an optional `(label …)`; `(ID: edge …)` names it |
492
+ | `(ID: group (label …) (group P))` | a group (subgraph, composite state) inside group `P` if given |
493
+
494
+ The nested form, the one-line form `(f: diagram (a: node) (b: node))` and
495
+ the multi-line parenthesized form give the same model. `parseDiagram` reads
496
+ the first diagram of a text, `diagramsFromLinks` every diagram of a parsed
497
+ document, and `diagramToLino` writes a model back in the nested form:
498
+ `diagramFromLinks(parse(diagramToLino(model)))` equals `model`. Every error is a `DiagramError` with a `code` (`no-diagram`,
499
+ `unknown-property`, `invalid-value`, `missing-value`, `duplicate-id`,
500
+ `unknown-node`, `unknown-group`) and an `at` position: the index path of the
501
+ link and its text, since `links-notation` gives no line numbers.
502
+
503
+ ### API
504
+
505
+ ```js
506
+ import {
507
+ parseDiagram, // LiNo text → DiagramModel
508
+ diagramFromLinks, // links-notation links → DiagramModel
509
+ diagramToLino, // DiagramModel → LiNo text
510
+ layoutDiagram, // DiagramModel → Layout (Dagre, deterministic)
511
+ runLayout, // the layout picked by (layout NAME)
512
+ registerLayout, // add a layout engine
513
+ renderDiagramSvg, // DiagramModel + Layout → SVG string
514
+ toMermaid, // DiagramModel → Mermaid text
515
+ defineDiagram, // <ui-diagram> and <ui-mermaid-view>
516
+ setMermaidImporter, // where Mermaid is imported from
517
+ } from '@link-foundation/ui-components';
518
+ ```
519
+
520
+ `toMermaid` of the login flow above returns, with no trailing newline:
521
+
522
+ ```text
523
+ flowchart TD
524
+ start["Start"]
525
+ check{"Signed in?"}
526
+ home["Home"]
527
+ start --> check
528
+ check -->|yes| home
529
+ ```
530
+
531
+ `layoutDiagram` gives the same coordinates for the same model every time,
532
+ and no two nodes overlap. Node sizes come from the labels
533
+ (`estimateNodeSize`), or from `options.nodeSize`.
534
+
535
+ `renderDiagramSvg(model, layout, tokens)` draws flowcharts and states. The
536
+ colours are design tokens (`surface`, `onSurface`, `edge`, `group`,
537
+ `groupOutline`, `accent`, `fontFamily`, `fontSize`), which default to the
538
+ `--color-*` CSS custom properties of ui-tokens. Every label is escaped.
539
+
540
+ ### Elements
541
+
542
+ `<ui-diagram>` reads its LiNo from its text content, or from its `source`
543
+ property. The `renderer` and `layout` attributes override the ones in the
544
+ LiNo. `layoutOptions` and `tokens` are properties. It sets `data-state`
545
+ (`loading`, `ready`, `error`) and `data-renderer`, and it fires a
546
+ `ui-diagram-state` event. Invalid LiNo is shown as source text with
547
+ `role="alert"`.
548
+
549
+ `<ui-mermaid-view label="…">` draws Mermaid text with Mermaid. Mermaid is
550
+ imported the first time one is shown (`import('mermaid')`, or the importer
551
+ given to `setMermaidImporter`), with `securityLevel: 'strict'`. While Mermaid
552
+ loads, and whenever loading or rendering fails, the view shows the source
553
+ text with an error message, so a diagram never just disappears.
554
+
555
+ #### Accessibility
556
+
557
+ The drawing has `role="img"` and an `aria-label` that names the diagram and
558
+ counts its nodes and connections. A visually hidden list of the nodes and of
559
+ the connections ("Signed in? leads to Home (yes)") follows it. The fallback
560
+ source is a focusable `pre`. axe finds no WCAG 2.2 A/AA violation on the
561
+ example page.
562
+
563
+ ### Layout plugins and licences
564
+
565
+ This package depends only on MIT and Unlicense code: Dagre and
566
+ `links-notation`. Mermaid is an optional peer dependency (`^11 || ^12`).
567
+ Mermaid 11 brings in no EPL code. **Mermaid 12 depends on `elkjs`
568
+ (EPL-2.0)**, so installing Mermaid 12 is the app's choice.
569
+
570
+ Other engines, such as ELK.js (EPL-2.0) or Graphviz through
571
+ `@hpcc-js/wasm-graphviz`, can be plugged in by the app:
572
+
573
+ ```js
574
+ import ELK from 'elkjs/lib/elk.bundled.js'; // EPL-2.0: the app's choice
575
+ import { registerLayout } from '@link-foundation/ui-components';
576
+
577
+ registerLayout('elk', async (model, options) => {
578
+ // … return { width, height, nodes, edges, groups } like layoutDiagram
579
+ });
580
+ ```
581
+
582
+ Diagrams that should use it write `(layout elk)`. See
583
+ `src/diagrams/layout-plugins.js` for the full ELK adapter. A test checks
584
+ that no package of this repository lists an EPL package in its
585
+ `dependencies`.
586
+
587
+ ## One link: `link-view`
588
+
589
+ `link-view` draws a single link. The geometry, markers and colours follow
590
+ [links-visuals](https://github.com/konard/links-visuals) (Unlicense).
591
+ The element reads its model from Links Notation through the official parser
592
+ (`@link-foundation/ui-core` over `links-notation`) and draws it as SVG (the
593
+ default) or on a canvas. Each element has its own zoom and pan, and asks for
594
+ no animation frame while nothing moves.
595
+
596
+ ```html
597
+ <link-view
598
+ lino="(simple: link-view (link (id 1) (source 1) (target 2)) (markers (source bar) (target arrow)))"
599
+ ></link-view>
600
+
601
+ <script type="module">
602
+ import { defineLinkView } from '@link-foundation/ui-components/links-view';
603
+ defineLinkView(window);
604
+ </script>
605
+ ```
606
+
607
+ The model, as LiNo:
608
+
609
+ ```lino
610
+ simple: link-view
611
+ link
612
+ id 1
613
+ source 1
614
+ target 2
615
+ markers
616
+ source bar
617
+ target arrow
618
+ blueprint true
619
+ grid true
620
+ ```
621
+
622
+ - **Ends.** A `source` or `target` that is missing or `0` is a free end, drawn
623
+ with a `cross` unless a marker is given. A link whose source and target are
624
+ the same reference is a self-loop.
625
+ - **Markers.** `bar`, `arrow`, `cross`, `dot` and `none`. They are data in
626
+ `markers.js` (`MARKERS`), which the SVG renderer (`svgMarkerDefs`) and the
627
+ Canvas renderer (`drawMarker`, `Path2D`) both draw from.
628
+ - **Blueprint.** `(blueprint true)` shows the nine construction points: start
629
+ green, end red, centre black (the line colour in dark mode), the others
630
+ blue, with a dashed guide. `(grid true)` draws the grid behind the link.
631
+ - **Attributes.** `renderer` (`svg` or `canvas`), `theme` (`light` or
632
+ `dark`; by default it follows `prefers-color-scheme`), `blueprint`, `grid`,
633
+ `bend` and `label` override the LiNo model.
634
+ - **Accessibility.** The element has `role="img"` and is focusable. Its name
635
+ comes from the model, for example "Link 1 from 1 to 2", "Link 2 from 3 to
636
+ 3, a self-loop" or "Link 3 from 1 to a free end".
637
+ - **Keyboard.** `+` and `-` zoom, `0` resets, and the arrow keys pan.
638
+ - **Pointer.** The wheel zooms around the pointer by `0.999 ** delta`. A drag
639
+ pans, with pointer capture, and two fingers pinch. The zoom stays between
640
+ 0.1 and 20.
641
+ - **Colours.** The colours are ui-tokens design tokens (`color.link.*`, with
642
+ a `dark` mode, in `LINK_TOKENS`). A page can override them with the
643
+ `--color-link-*` CSS custom properties.
644
+
645
+ In a ui-dom document, `registerLinkViewKind(window)` renders a `link-view`
646
+ element of the document as this element.
647
+
648
+ ### Building blocks
649
+
650
+ All of these are pure functions, or objects you create, with no
651
+ module-level state:
652
+
653
+ | Module | Exports |
654
+ | ------------------ | ---------------------------------------------------------------------------------- |
655
+ | `geometry.js` | `linkGeometry`, `pointAtLength`, `endAngles`, `catmullRomToCubics`, `pathToSvgD` … |
656
+ | `markers.js` | `MARKERS`, `getMarker`, `svgMarkerDefs`, `drawMarker` |
657
+ | `render-svg.js` | `renderLinkSvg(geometry, style)`: a deterministic SVG string |
658
+ | `render-canvas.js` | `drawLinkCanvas(ctx, geometry, style)` |
659
+ | `zoom-pan.js` | `createZoomPan(element, {min, max, onChange})`, which `destroy()` undoes |
660
+ | `animator.js` | `createAnimator({now, raf, caf, reducedMotion})` |
661
+ | `model.js` | `parseLinkView(text)`, `readLinkView(raw)`, `accessibleName(model)` |
662
+ | `link-view.js` | `defineLinkView(window)`, `registerLinkViewKind(window)` |
663
+
664
+ ```js
665
+ import {
666
+ linkGeometry,
667
+ linkColors,
668
+ renderLinkSvg,
669
+ } from '@link-foundation/ui-components';
670
+
671
+ const geometry = linkGeometry({
672
+ source: { x: 0, y: 0 },
673
+ target: { x: 100, y: 0 },
674
+ });
675
+ const svg = renderLinkSvg(geometry, {
676
+ width: 320,
677
+ height: 200,
678
+ colors: linkColors(),
679
+ ends: { source: 'bar', target: 'arrow' },
680
+ });
681
+ ```
682
+
683
+ The gallery `examples/link-view.html` shows four cases: simple, self-loop,
684
+ free end and blueprint. Serve the repository with
685
+ `node scripts/serve-static.mjs` and open
686
+ `/packages/ui-components/examples/link-view.html`. It loads every module from
687
+ the repository, never from a CDN.
688
+
689
+ ### Tests
690
+
691
+ ```bash
692
+ node --test packages/ui-components/tests/links-view/*.test.js
693
+ npx playwright test packages/ui-components/tests/e2e/link-view.spec.js
694
+ ```
695
+
696
+ ## Layout and windowing
697
+
698
+ `./layout` adds the layout kinds `stack`, `grid`, `split`, `tab-group`,
699
+ `dock`, `window` and `app-shell` to ui-dom. A layer manager orders every
700
+ floating surface, and a dock layout can be saved and read back as Links
701
+ Notation.
702
+
703
+ ```js
704
+ import { mountDocument } from '@link-foundation/ui-dom';
705
+ import {
706
+ createLayerManager,
707
+ layoutVocabulary,
708
+ } from '@link-foundation/ui-components/layout';
709
+
710
+ mountDocument(app, text, {
711
+ parseOptions: { vocabulary: layoutVocabulary() },
712
+ layout: { storage: window.localStorage, layers: createLayerManager() },
713
+ });
714
+ ```
715
+
716
+ ```html
717
+ <link rel="stylesheet" href="@link-foundation/ui-components/layout.css" />
718
+ ```
719
+
720
+ Importing `./layout` (or the package) registers the layout kinds with
721
+ ui-dom. The CSS gives
722
+ them their layout (dividers, tab strips, window frames, dock regions, shell
723
+ modes); every colour and size is a design token or a `--ui-*` custom
724
+ property with a fallback.
725
+
726
+ The gallery `examples/layout.html` (served with
727
+ `node scripts/serve-static.mjs`) shows every kind; its Playwright spec is
728
+ `tests/e2e/layout.spec.js`.
729
+
730
+ Page links, section navigation, titled sections, whole-link card grids and
731
+ quick preference controls are described in [Page navigation and quick preferences](src/layout/README.md).
732
+
733
+ ### Layout kinds
734
+
735
+ | Kind | Example | What it does |
736
+ | ----------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
737
+ | `stack` | `(stack (direction row) (gap 8px) (align center) (justify space-between) (wrap true) ...)` | CSS flexbox. `direction` takes `vertical`, `horizontal`, `row`, `column` and their `-reverse` forms. |
738
+ | `grid` | `(grid (columns 16rem 1fr) (rows auto 1fr) (areas 'nav main') ...)` | CSS grid. Tracks are lengths, `fr`, `auto`, `(repeat N ...)`, `(minmax MIN MAX)` and `(fit-content L)`; every token is checked. A child whose id names an area goes into it. |
739
+ | `split` | `(split (sizes 30 70) (min 20) (collapsible true false) (remember-size chat.split) ...)` | Panes with dividers (WAI-ARIA window splitter). Sizes are percentages with a constant total. `remember-size` keeps `sizes 30 70` in the render storage. |
740
+ | `tab-group` | `(tab-group (label Inspector) (active styles) (styles: panel (title Styles) ...) ...)` | Panels behind a tab strip (WAI-ARIA tabs, automatic activation). Tabs can be closed, reordered and dragged; a "More tabs" menu appears when they overflow. |
741
+ | `panel` | `(panel (title Styles) (closable true) ...)` | A titled panel: a tab of a tab group or a dock panel. |
742
+ | `dock` | `(dock (persist designer.layout) (left: region (size 16rem) (panels toolbox outline)) ...)` | Panels docked left, right, top, bottom and center; each region shows its panels as tabs. A panel can move to another region, float, close and come back; the layout is saved under `persist`. |
743
+ | `window` | `(window (title Inspector) (open false) (x 120) (y 96) (width 360) (height 280) ...)` | A floating, movable, resizable non-modal dialog. It stays inside the viewport and is raised by the layer manager. |
744
+ | `app-shell` | `(app-shell (breakpoints 640 1024) (bottom-bar tabs) (rail rail-nav) (drawer drawer-nav) ...)` | A bottom bar up to the first breakpoint, a rail up to the second one and a drawer from it on. The shell fills the viewport, its content scrolls, and it writes its `mode` attribute. |
745
+ | `container` | `(page: container (size medium) ...)` | A centred column: `size` extra-small to extra-large or full, `gutters` |
746
+ | `paper` | `(note: paper (elevation 2) ...)` | A surface: `elevation` 0 to 5, `variant` elevated or outlined, `square` |
747
+ | `card` | `(plan: card Starter (subtitle 'For one') ...)` | A surface with a title and a subtitle, a group named by its title; `variant` elevated, filled or outlined |
748
+ | `app-bar` | `(top: app-bar Inbox (position sticky) ...)` | A native `<header>` with a title and actions; `position` static, sticky or fixed, `tone` surface or primary |
749
+
750
+ Parse layout documents with `{ vocabulary: layoutVocabulary() }` so their
751
+ properties are checked; `LAYOUT_VOCABULARY_TEXT` is the same vocabulary as
752
+ Links Notation.
753
+
754
+ ### Keyboard
755
+
756
+ | Element | Keys |
757
+ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
758
+ | Divider | Arrows move by 1 (Shift: 10). Home gives the smallest size (collapses a collapsible pane), End the largest. Enter collapses or restores the pane. |
759
+ | Tab strip | Left and Right select, Home and End go to the ends, Delete closes a closable tab, Ctrl+Shift+Left and Right reorder. |
760
+ | Window | Alt+Arrow moves by 16px, Alt+Shift+Arrow resizes, Escape closes and gives the focus back to the opener. |
761
+ | Dock | The "Panel actions" menu (⋮) moves, floats, closes or collapses the shown panel. Ctrl+F6 and Ctrl+Shift+F6 go to the next and previous panel. |
762
+
763
+ The keys are bound with `bindKeys` of [`./a11y`](#accessibility-helpers), so only
764
+ these exact combinations act (a divider leaves Ctrl+Arrow to the browser),
765
+ and the menus move their focus with `createRovingTabindex`.
766
+
767
+ ### Events
768
+
769
+ The elements change themselves and tell the application, which may write the
770
+ change back to its store: `split-resize` (`detail.sizes`), `tab-change`
771
+ (`detail.active`), `tab-close` (`detail.panel`), `tab-reorder`
772
+ (`detail.order`), `window-change` (`detail.rect`), `window-close`
773
+ (`detail.id`), `dock-change` (`detail.layout`, `detail.lino`) and
774
+ `shell-mode` (`detail.mode`).
775
+
776
+ ### Render options
777
+
778
+ `mountDocument(..., { layout: { storage, layers } })`:
779
+
780
+ - `storage`: an object with `getItem` and `setItem` (such as
781
+ `localStorage`). Splits with `remember-size` and docks with `persist` use
782
+ it.
783
+ - `layers`: a layer manager (`createLayerManager()`); by default one is
784
+ shared by the document.
785
+
786
+ ### Pure models
787
+
788
+ The models have no DOM and return new values.
789
+
790
+ #### Layer manager
791
+
792
+ ```js
793
+ import {
794
+ createLayerManager,
795
+ LAYERS,
796
+ } from '@link-foundation/ui-components/layout';
797
+
798
+ const layers = createLayerManager();
799
+ layers.register('confirm', 'modal');
800
+ layers.register('inspector', 'window');
801
+ layers.raise('inspector');
802
+ layers.zIndexOf('confirm') > layers.zIndexOf('inspector'); // true
803
+ ```
804
+
805
+ The layers have a fixed order (`LAYERS`: `base`, `dock`, `window`,
806
+ `popover`, `modal`, `toast`). Raising a surface moves it only within its
807
+ layer, so a raised window never covers a modal.
808
+
809
+ #### Split sizes
810
+
811
+ ```js
812
+ import {
813
+ resizeSplit,
814
+ collapsePane,
815
+ } from '@link-foundation/ui-components/layout';
816
+
817
+ resizeSplit([30, 70], 0, 60, { min: 20, max: 75 }); // [75, 25]
818
+ collapsePane([30, 70], 0, { min: 20, collapsible: true }); // [0, 100]
819
+ ```
820
+
821
+ `resizeSplit`, `collapsePane`, `restorePane` and `normalizeSizes` keep the
822
+ total and every pane within its `min` and `max` (a collapsed pane is 0).
823
+
824
+ #### Dock layout
825
+
826
+ ```js
827
+ import {
828
+ dockLayoutFromLinks,
829
+ dockLayoutToLino,
830
+ movePanel,
831
+ } from '@link-foundation/ui-components/layout';
832
+
833
+ const layout = dockLayoutFromLinks(`designer: dock
834
+ persist designer.layout
835
+ left: region
836
+ size 16rem
837
+ panels toolbox outline
838
+ right: region
839
+ size 20rem
840
+ panels properties
841
+ center: region
842
+ panels canvas`);
843
+ dockLayoutToLino(movePanel(layout, 'outline', 'right'));
844
+ // designer: dock
845
+ // persist designer.layout
846
+ // left: region
847
+ // size 16rem
848
+ // panels toolbox
849
+ // right: region
850
+ // size 20rem
851
+ // panels properties outline
852
+ // center: region
853
+ // panels canvas
854
+ ```
855
+
856
+ `movePanel`, `floatPanel`, `closePanel`, `restorePanel`, `activatePanel` and
857
+ `updateRegion` change a layout. The layout is written in the nested form;
858
+ a floating panel is a `float PANEL` line with the indented lines `x ...`,
859
+ `y ...`, `width ...`, `height ...` and `region SIDE`, and a closed panel is a
860
+ `closed PANEL SIDE` line. Reading the written text gives the same layout
861
+ back, and the parenthesized form reads the same.
862
+
863
+ ## Basic controls
864
+
865
+ `./controls` adds the basic controls to ui-dom. Each kind renders native
866
+ elements in light DOM (a `<button>`, an `<input>`, ...) with Open UI part
867
+ names in `data-part`, follows its
868
+ [APG pattern](https://www.w3.org/WAI/ARIA/apg/patterns/) and, when it has
869
+ state, runs its machine (`src/controls/machines/<kind>.lino`).
870
+
871
+ ```js
872
+ import { mountControls } from '@link-foundation/ui-components/controls';
873
+
874
+ const mounted = mountControls(
875
+ form,
876
+ `(settings: document
877
+ (email: text-field 'Email' (name email) (type email) (required true))
878
+ (wifi: switch 'Wi-Fi' (name wifi) (checked true))
879
+ (volume: slider 'Volume' (name volume) (min 0) (max 100) (step 5) (value 40))
880
+ (save: button 'Save' (on press (emit save))))`
881
+ );
882
+ mounted.store.get('volume'); // the committed values live in the store
883
+ ```
884
+
885
+ ```html
886
+ <link rel="stylesheet" href="@link-foundation/ui-components/controls.css" />
887
+ ```
888
+
889
+ `mountControls(container, text, options)` is `mountBehavior` with the
890
+ control kinds: every value a control commits is written to the store with
891
+ one `setProp` (one transaction per user change), then the element's
892
+ `(on change ...)` handlers run. `registerControls()` registers the kinds
893
+ with ui-dom for `mountDocument`; parse with
894
+ `{ vocabulary: controlsVocabulary() }` to check their properties.
895
+
896
+ | Kind | Element and role | Keyboard |
897
+ | -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
898
+ | `button` | `<button type=button>` | Enter, Space |
899
+ | `icon-button` | `<button aria-label>`; no `label` is an error | Enter, Space |
900
+ | `label` | `<label for>` of a control | |
901
+ | `link` | `<a href>`; unsafe URLs are never followed | Enter |
902
+ | `text-field` | `<input>` and its `<label>` | commits on Enter or leaving; Escape restores |
903
+ | `text-area` | `<textarea>` and its `<label>` | commits on leaving; Escape restores |
904
+ | `number-field` | `<input role=spinbutton>` | arrows step (Shift ×10), PageUp/PageDown, Home/End |
905
+ | `color-field` | a hex `<input>` and `<input type=color>` | commits a normalised `#rrggbb` |
906
+ | `checkbox` | `<input type=checkbox>`, `(checked mixed)` | Space |
907
+ | `radio-group` | `radiogroup` of `radio`s, one tab stop | arrows move and check, Space checks |
908
+ | `switch` | `<button role=switch aria-checked>` | Space, Enter |
909
+ | `slider` | `slider` with `aria-valuenow/min/max/text` | arrows step (Shift ×10), PageUp/PageDown, Home/End |
910
+ | `select` | select-only `combobox` and a `listbox` | arrows, Home/End open and move, Enter/Space choose, Escape closes, typeahead |
911
+ | `combobox` | `<input role=combobox>` with list autocomplete | typing filters, arrows move, Enter chooses, Escape closes or clears |
912
+ | `option` | `option` of a select or a combobox | |
913
+ | `progress` | `progressbar`, bar or `(shape circular)` ring; no `value` is indeterminate | |
914
+ | `badge` | a short status text with a `tone` | |
915
+ | `avatar` | `<img alt>`, or initials with `role=img` | |
916
+ | `chip` | a `<button aria-label>` removes it; `ui-change` of `removed` | Enter, Space, Delete and Backspace remove; focus moves to the next chip |
917
+ | `accordion` | heading, `<button aria-expanded aria-controls>`, `region` | Enter and Space toggle; arrows, Home and End move between headers; Escape closes from the section |
918
+
919
+ Every input control has a `name` and takes part in its native `<form>`
920
+ (`FormData`). The key bindings of `bindKeys` ignore keys typed in text
921
+ inputs, so a letter typed in a field never fires a page shortcut.
922
+ `controls.css` uses only design tokens (with system colour fallbacks), has
923
+ `:focus-visible` rings and a `forced-colors: active` block.
924
+
925
+ ### Stories and the catalog
926
+
927
+ Each control has stories in `stories/<kind>.lino` and an entry in
928
+ `src/controls/catalog.lino`:
929
+
930
+ ```lino
931
+ button-stories: stories
932
+ component button
933
+ story filled
934
+ button 'Save'
935
+ variant filled
936
+ button: control
937
+ title 'Button'
938
+ stories button-stories
939
+ apg button
940
+ ```
941
+
942
+ `parseStories`, `parseCatalog` and `storiesDocument` read them; the page
943
+ `e2e/pages/controls.html` shows a form of every control and a gallery of
944
+ every story. `tests/controls/catalog.test.js` fails when a control lacks
945
+ its kind entry, story file, catalog entry or test file.
946
+
947
+ ## Icons
948
+
949
+ - a public-domain (CC0-1.0) icon set of our own;
950
+ - the `ui-icon` element and the `icon` kind of
951
+ [`@link-foundation/ui-dom`](../ui-dom/README.md);
952
+ - adapters for Lucide, Tabler and Material Symbols. Every icon they supply
953
+ carries its licence record.
954
+
955
+ ```js
956
+ import {
957
+ registerIconSet,
958
+ resolveIcon,
959
+ } from '@link-foundation/ui-components/icons';
960
+ import { createLucideSource } from '@link-foundation/ui-components/icons/adapters/lucide';
961
+
962
+ await resolveIcon('close'); // {viewBox, body, mirrorInRtl, record, set: 'own'}
963
+ registerIconSet('lucide', createLucideSource());
964
+ await resolveIcon({ set: 'lucide', name: 'check' }); // record: ISC, Lucide
965
+ ```
966
+
967
+ ```html
968
+ <ui-icon name="close"></ui-icon>
969
+ <!-- decorative: aria-hidden -->
970
+ <ui-icon set="lucide" name="check" label="Done"></ui-icon>
971
+ <!-- role="img", named "Done" -->
972
+ ```
973
+
974
+ ```lino
975
+ app: document
976
+ icon close
977
+ ok: icon
978
+ set lucide
979
+ name check
980
+ label 'Done'
981
+ ```
982
+
983
+ The complete example is `examples/ui-components-icons.mjs`. The gallery
984
+ `examples/icons.html` shows every set in light and dark themes and in both
985
+ text directions. To serve it, run `node scripts/build-icons.mjs` and then
986
+ `node scripts/serve-static.mjs`, and open
987
+ `/packages/ui-components/examples/icons.html`.
988
+
989
+ ### The own set
990
+
991
+ [`assets/icons/own/`](../../assets/icons/own/) holds 32 icons, each with a
992
+ record in [`assets/assets.lino`](../../assets/assets.lino) (CC0-1.0, copyright
993
+ `none`). They follow these rules:
994
+
995
+ - a 24×24 grid with a 2 px stroke;
996
+ - round caps and joins;
997
+ - `currentColor`, so an icon takes the colour of the text around it and
998
+ follows the theme.
999
+
1000
+ The names are `ICON_NAMES`: `close`, `menu`, `more`, the chevrons, `check`,
1001
+ `plus`, `minus`, `search`, `settings`, `reset`, `copy`, `paste`, `send`,
1002
+ `attach`, `drag-handle`, the dock icons, `float`, `zoom-in`, `zoom-out`, `fit`,
1003
+ `play`, `pause`, `record`, `warning`, `error`, `info` and `link`. `send`
1004
+ and `reset` point in the reading direction (`MIRROR_IN_RTL`), so they are
1005
+ mirrored in right-to-left text.
1006
+
1007
+ ### The registry
1008
+
1009
+ | Export | Meaning |
1010
+ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
1011
+ | `registerIconSet(set, source)` | add or replace a set. It returns a function that unregisters the set. Rendered icons of the set redraw. |
1012
+ | `resolveIcon(ref)` | resolves `close`, `lucide:check` or `{set, name}` to `IconData`. A missing name falls back to the own set and then to `PLACEHOLDER_ICON`. |
1013
+ | `iconRecords(sets?)` | the asset records of the registered sets, for attribution screens |
1014
+ | `createStaticSource(module)` | a source over a module built by `scripts/build-icons.mjs` (`dist/icons/<set>.js`) |
1015
+ | `parseIconRef`, `iconSets`, `getIconSet`, `onIconSetsChange` | helpers |
1016
+
1017
+ `IconData` is `{viewBox, body, mirrorInRtl, record}`. `body` is SVG markup
1018
+ drawn in `currentColor`. `record` is the asset record, in the format of
1019
+ [docs/licensing.md](../../docs/licensing.md).
1020
+
1021
+ ### The element
1022
+
1023
+ `ui-icon` is defined on import in browsers. In other windows, such as jsdom,
1024
+ call `defineIconElement(window)`. It has these attributes:
1025
+
1026
+ - `name`;
1027
+ - `set` (the default is `own`);
1028
+ - `label`;
1029
+ - `mirror` (`true` or `false`, which overrides `MIRROR_IN_RTL`).
1030
+
1031
+ Without a label the icon is decorative (`aria-hidden="true"`). With a label it
1032
+ is `role="img"`, and the label is its accessible name. The default size is
1033
+ 1.5em; `--ui-icon-size` changes it. Markup from a source is cleaned before it
1034
+ is shown: scripts, `foreignObject`, event handlers and external `href`s are
1035
+ removed.
1036
+
1037
+ ui-core `ui-dialect/0` has no `icon` kind yet; see
1038
+ [docs/spec/open-questions.md](../../docs/spec/open-questions.md). To read
1039
+ `(icon ...)` without warnings, parse with `iconVocabulary()`.
1040
+
1041
+ ### Adapters
1042
+
1043
+ | Entry point | Package (optional peer) | Licence |
1044
+ | --------------------------------- | ------------------------------------ | --------------------------------------------------------- |
1045
+ | `icons/adapters/lucide` | `lucide` (≥ 1.0) | ISC, or `ISC AND MIT` for icons derived from Feather |
1046
+ | `icons/adapters/tabler` | `@tabler/icons` (≥ 3.0) | MIT |
1047
+ | `icons/adapters/material-symbols` | `@material-symbols/svg-400` (≥ 0.40) | Apache-2.0. Its LICENSE and a NOTICE ship with the icons. |
1048
+
1049
+ Install a package only if you use its set. Each adapter maps the logical names
1050
+ to library names and reads the SVG files through the module resolver: a
1051
+ `file:` URL in Node, Bun and Deno, or `fetch` with a browser import map. Pass
1052
+ `{load}` to read from your own copy instead. Records give the source, the SPDX
1053
+ licence, the copyright and a link to the notice. Every record has
1054
+ `(attribution required)`.
1055
+
1056
+ ### Building
1057
+
1058
+ `node scripts/build-icons.mjs` (also `npm run build:icons`) writes
1059
+ `packages/ui-components/dist/icons/`:
1060
+
1061
+ - `<set>.js` and a `<set>.svg` sprite for each set (`<symbol
1062
+ id="<set>-<name>">`);
1063
+ - `NOTICE.lino`, with every shipped record;
1064
+ - `ATTRIBUTION.md`;
1065
+ - `licenses/<set>/`.
1066
+
1067
+ SVGO cleans every icon, and fixed colours become `currentColor`. The build
1068
+ fails, and writes nothing, when:
1069
+
1070
+ - a used icon has no record;
1071
+ - a licence is not on the allow list;
1072
+ - a record or a dependency names Remix Icon or SF Symbols (see
1073
+ [docs/licensing.md](../../docs/licensing.md)).
1074
+
1075
+ `--check` validates without writing, and fails when `src/icons/own-icons.js` is
1076
+ stale. CI runs it in the Licensing workflow.
1077
+
1078
+ ## Future work
1079
+
1080
+ The machine format starts small on purpose. These are not supported yet:
1081
+
1082
+ - **nested (hierarchical) states**: `(state open (state loading) ...)`
1083
+ - **parallel states**: regions that are active at the same time
1084
+ - **history states**: re-entering the last active child state
1085
+ - event payload guards with arguments, and spawned or invoked child machines
1086
+ - more reference machines (`dialog`, `menu`, `tabs`, `listbox`) on top of
1087
+ the a11y helpers
1088
+
1089
+ ## License
1090
+
1091
+ The code is [Unlicense](LICENSE). The own icons are CC0-1.0. Third-party
1092
+ icons keep their licences, as recorded in [Adapters](#adapters).
1093
+
1094
+ ## Overlays and navigation
1095
+
1096
+ `@link-foundation/ui-components/overlays` registers dialog, alert-dialog,
1097
+ popover, tooltip, menu, menu-item, menu-separator, context-menu, radial-menu,
1098
+ tabs, tab, tab-panel, toast, toaster and drawer. Load `overlays.css` and see
1099
+ [the overlay guide](../../docs/overlays.md) for LiNo examples, controllers,
1100
+ keyboard behavior, injected clocks and the runnable gallery.
1101
+ `positionFloating` is also exported as the shared positioning API for select.
1102
+
1103
+ ## Lists, trees and tables
1104
+
1105
+ Import `@link-foundation/ui-components/data` to register the `list`, `tree`
1106
+ and `table` ui-dom kinds and load `@link-foundation/ui-components/data.css`.
1107
+ Parse with `{ vocabulary: dataVocabulary() }`. The
1108
+ [data gallery](examples/data.html) runs without a bundler when served with
1109
+ `node scripts/serve-static.mjs`.
1110
+
1111
+ ```lino
1112
+ chats: list
1113
+ label Chats
1114
+ items
1115
+ param chats
1116
+ selection multi
1117
+ virtualized true
1118
+ item-height 32
1119
+ template chat-row
1120
+ on select
1121
+ navigate chat
1122
+ param item.id
1123
+
1124
+ people: table
1125
+ caption People
1126
+ items
1127
+ param people
1128
+ columns
1129
+ name: column
1130
+ label Name
1131
+ sortable true
1132
+ age: column
1133
+ label Age
1134
+ sortable true
1135
+ align end
1136
+ ```
1137
+
1138
+ `items (param chats)` reads `options.data.sources.chats`. A source is an
1139
+ array or an observable `{ get(): Item[], subscribe(listener): unsubscribe }`;
1140
+ `createDataSource(items)` provides that adapter with `set(items)`. Each item
1141
+ has a stable, unique string `id` and a `label` (falling back to `name`, then
1142
+ `id`). Updating the source retains measurements and focus by ID. Inline
1143
+ records are also supported:
1144
+
1145
+ ```lino
1146
+ choices: list
1147
+ label Choices
1148
+ items
1149
+ (id first) (label First)
1150
+ (id second) (label Second)
1151
+ ```
1152
+
1153
+ The original issue's `$chats` and `$item.id` examples were working names.
1154
+ Use the dialect's structured `param` links instead: dollar sigils remain
1155
+ reserved. `on select` and `on activate` go through ui-dom and the #33 action
1156
+ registry (`mountBehavior`); `(param item.id)` resolves an own property of the
1157
+ current item. No action or template text is evaluated. `ui-select` carries
1158
+ `{item, selected}` and `ui-activate` carries `{item}` for host listeners.
1159
+
1160
+ `selection` is `single` (default), `multi`, or `none`. Single selection follows
1161
+ arrow/typeahead focus; multi selection moves focus independently, Space toggles,
1162
+ Shift extends a range, Ctrl/Cmd toggles on click, and Ctrl/Cmd+A selects all.
1163
+ Home/End, PageUp/PageDown and typeahead work on listboxes and trees. Trees
1164
+ also support Right/Left for expansion/parent navigation and `*` for sibling
1165
+ expansion. Enter activates; double-click also activates.
1166
+
1167
+ A tree item may have `children: Item[]` or `hasChildren: true`. For lazy branches,
1168
+ provide `options.data.loadChildren(item, {signal}) -> Promise<Item[]>`. Loaded
1169
+ children are cached by parent ID; loading/error text is announced, closing a
1170
+ branch during a load leaves it closed, and destroying a render aborts pending
1171
+ requests. Reopen a failed branch to retry. Tree `aria-level`, `aria-posinset`
1172
+ and `aria-setsize` describe the complete visible hierarchy, including rows
1173
+ outside the rendered window.
1174
+
1175
+ A table reads `columns` records with `label`, `sortable`, `align` (`start` or
1176
+ `end`) and `width` (pixels). The caption names the grid. Sort cycles ascending,
1177
+ descending, none; equal values retain input order and none restores source
1178
+ order. Arrows move between cells; Home/End move within a row, Ctrl/Cmd+Home/End
1179
+ move to the first header/last data cell, and Up from the first row reaches the header.
1180
+ Header arrows navigate columns, Down returns to the data. Space selects
1181
+ rows and Shift extends selection. Header buttons activate sorting with
1182
+ Enter/Space. Column dividers resize by pointer drag; focus a divider by clicking
1183
+ it and use Left/Right (10px), Home (48px), End (600px). The header stays visible
1184
+ inside the table's scrolling viewport.
1185
+
1186
+ `template NAME` selects a trusted host renderer from
1187
+ `options.data.templates[NAME](item, {document})`, returning a string or a DOM
1188
+ node. Strings render as text. Listbox options should contain text, without
1189
+ interactive descendants (use a grid for interactive cells). Tree labels can use
1190
+ the same template contract. `item-height` is the positive estimated/minimum
1191
+ height in CSS pixels; actual variable row heights come from one shared
1192
+ `ResizeObserver` per viewport, with writes deferred to `requestAnimationFrame`.
1193
+ `virtualized false` deliberately renders the whole collection. Virtualization
1194
+ is on by default, with one viewport of overscan, retaining focused rows outside
1195
+ the range. The scroll area is styled through `.ui-data-scroll`; native wheel,
1196
+ touch and nested scroll chaining are preserved. Each component also accepts
1197
+ `loading true`, `error 'message'`, and `empty 'message'`.
1198
+
1199
+ The DOM-free modules `data/virtual-range.js`, `data/selection-model.js`,
1200
+ `data/sort-model.js`, and `data/tree-model.js` can be imported by relative source
1201
+ path internally. Public exports include `listOffsets`, `indexAt`, `listRange`,
1202
+ `anchorScrollTop`, `selectItem`, `nextSort`, `sortItems`, and `flattenTree`.
1203
+ The chat kit can reuse them without timeline logic here. `anchorScrollTop`
1204
+ takes `{keys, offsets, scrollTop}` before, `{keys, offsets}` after, and an anchor
1205
+ key, preserving that row's intra-row offset. Range ends are exclusive;
1206
+ `indexAt` returns `-1` for an empty collection.
1207
+
1208
+ ### Links network
1209
+
1210
+ `@link-foundation/ui-components/links-view` also exports `defineLinksNetwork`
1211
+ and `registerLinksNetworkKind`. Pass `parseOptions: { vocabulary: networkVocabulary() }`
1212
+ to `mountDocument` when rendering the kind and its LiNo event handlers. Define the element explicitly, set `items` to
1213
+ `{ id, source, target, label? }[]`, or set `store` to a real `ui-store` instance.
1214
+ Store nodes of kind `link` use `source`/`target` properties (or the first two
1215
+ positional values). The subscription applies committed insert, update, remove
1216
+ and rename events while preserving unrelated SVG items and positions.
1217
+
1218
+ ```lino
1219
+ network: links-network
1220
+ layout circle
1221
+ style glyph
1222
+ labels
1223
+ min-zoom 0.6
1224
+ items
1225
+ link
1226
+ id a
1227
+ source p
1228
+ target q
1229
+ link
1230
+ id b
1231
+ source a
1232
+ target 0
1233
+ ```
1234
+
1235
+ IDs refer to points or the centre anchors of other links; `0` is a free end.
1236
+ Cycles and self-references are supported. `layout` selects `circle`, `grid`,
1237
+ `hex`, `spiral`, `force` or `layered` (Dagre). `style-mode` selects `glyph` or
1238
+ `node-edge`; `theme` selects `light` or `dark` (system by default), with the
1239
+ same `--color-link-*` overrides as `link-view`. Layout work runs in a
1240
+ cancellable worker; `ready` resolves when it completes, and `layout()` requests
1241
+ another layout. Dragged vertices remain pinned across layouts. Force uses a
1242
+ fixed seed, `alphaMin` and at most 300 ticks, with no ongoing animation.
1243
+
1244
+ Click selects; Shift+click toggles an additional item; drag pins a vertex;
1245
+ background drag pans; the wheel zooms. Home selects the first vertex, arrows
1246
+ select the nearest neighbour in the pressed direction, Shift+arrows extend the
1247
+ selection, Enter dispatches `ui-activate` (and the `activate` hook), Escape clears selection, `+`/`-` zoom,
1248
+ `0` resets, Alt+arrows pan and Shift+F10 opens the `networkcontextmenu` hook.
1249
+ The hooks bubble across the shadow root with `detail: { id, item, originalEvent }`.
1250
+ `selectionchange` carries `detail.ids`; `ui-select` carries `detail.item` for LiNo handlers. A live status announces selection in
1251
+ both SVG and Canvas. The `networkStore` ui-dom render option can supply the
1252
+ store to a registered kind. Applications handle activation and editing.
1253
+
1254
+ Up to 2,000 links use SVG; larger networks use Canvas. Geometry and marker
1255
+ shapes are shared. Labels hide below the configured zoom and use greedy
1256
+ priority overlap removal. `toSvg()` returns the preview markup, and
1257
+ `toPng(scale)` returns a PNG Blob. The pure APIs `buildNetwork`, `NETWORK_LAYOUTS`,
1258
+ `visibleLabels`, `createLayoutRunner`, `networkToSvg` and `networkToPng` work
1259
+ independently of the custom element. Worker cancellation rejects with
1260
+ `AbortError`; other errors appear in `diagnostics` and `layouterror`.
1261
+
1262
+ Run `node scripts/serve-static.mjs` and open
1263
+ `/packages/ui-components/examples/links-network.html` for 10, 500 and 5,000
1264
+ links. The server and package prepack build the self-contained worker with
1265
+ pinned npm dependencies and accompanying license notices; there is no CDN or
1266
+ runtime download. Consumers must preserve the relative
1267
+ `dist/network-layout.worker.mjs` asset when bundling the package, or inject a
1268
+ `createWorker` factory for their bundler's worker handling.
1269
+
1270
+ ## Arbitrary Links Notation as a network
1271
+
1272
+ `linoToNetwork(text, { maxInputSize, maxDepth })` reads any LiNo with the
1273
+ pinned official parser. It returns `{ links, diagnostics, sourceMap }`.
1274
+ `buildNetwork(links)` accepts the converter's explicit point/value records as
1275
+ well as link records. Quoted values remain separate from references with the
1276
+ same text, and isolated words remain visible. Positions are one-based line
1277
+ and column; parse errors and limit errors are diagnostics rather than throws.
1278
+
1279
+ Binary links use their two values as endpoints. Longer sequences start at
1280
+ the named anchor: `a: b c d` gives a→b, b→c, c→d under IDs a, a/1, a/2.
1281
+ Nested anonymous links use their parent path, such as a/0; anonymous roots
1282
+ use @0, @1, etc. Collisions add ~1, ~2, etc. The model reserves 0 for free
1283
+ ends, so an explicit LiNo ID 0 gets a generated alias. Duplicate definitions
1284
+ warn and keep the first definition. Ordinary undefined words are labelled
1285
+ points; undefined numeric IDs warn. This distinction keeps ordinary prose
1286
+ valid because LiNo has no separate syntax for an unresolved reference.
1287
+
1288
+ `networkToLino(result)` (also accepting `result.links` or a built network)
1289
+ uses the retained LiNo structure and writes nested text with ui-core. IDs,
1290
+ references, empty links and quoted values survive a conversion round trip.
1291
+ Formatting is not preserved. Writing view edits into text is outside this API.
1292
+ Networks without LiNo origin metadata are rejected.
1293
+
1294
+ ```js
1295
+ import { defineLinoNetwork } from '@link-foundation/ui-components/links-view';
1296
+ defineLinoNetwork();
1297
+ const view = document.createElement('lino-network');
1298
+ view.textContent = "greeting: hello 'world'";
1299
+ view.addEventListener('select', ({ detail: { id, line, column } }) => {
1300
+ console.log(id, line, column);
1301
+ });
1302
+ document.body.append(view);
1303
+ await view.ready;
1304
+ ```
1305
+
1306
+ The element accepts inline text, the `lino` property/attribute, or a `src`
1307
+ URL (which takes precedence). It displays diagnostics and highlights the
1308
+ source token selected with the pointer or keyboard. Inline text changes
1309
+ reload automatically; newer loads cancel older requests. `layout`,
1310
+ `style-mode`, `theme` and `label` forward to the existing network view.
1311
+ `network`, `sourceMap`, `diagnostics`, `networkView`, `select(id)`, `toSvg()`
1312
+ and `toPng(scale)` are available after `ready`. A fetch failure clears the
1313
+ old view and reports a diagnostic. Imports are safe in Node.
1314
+
1315
+ ```bash
1316
+ npx lino-network input.lino --layout force --out network.svg
1317
+ ```
1318
+
1319
+ The CLI supports all six network layouts, defaults to circle, and writes
1320
+ SVG to stdout if `--out` is absent. Input is bounded to 1 MiB; force is
1321
+ bounded to 300 ticks. Warnings go to stderr; errors exit unsuccessfully.
1322
+ Run the static server and open
1323
+ [`examples/lino-network.html`](examples/lino-network.html) for document,
1324
+ token and other case-study samples, source selection, and error diagnostics.
1325
+
1326
+ ## Code and LiNo source editor
1327
+
1328
+ Import `@link-foundation/ui-components/editor` to register `<ui-code-editor>`
1329
+ and the `code-editor` ui-dom kind. Load `@link-foundation/ui-components/editor.css`
1330
+ and `@link-foundation/ui-components/controls.css` in the host page. The editor
1331
+ uses the existing basic buttons, light DOM, theme tokens and APG document tabs.
1332
+ Run `node scripts/serve-static.mjs` and open
1333
+ `/packages/ui-components/examples/editor.html` for the two sample files.
1334
+
1335
+ ```js
1336
+ import '@link-foundation/ui-components/editor';
1337
+ const editor = document.createElement('ui-code-editor');
1338
+ editor.setAttribute('label', 'Document source');
1339
+ editor.editorOptions = { storage: localStorage };
1340
+ editor.openDocument({ id: 'document.lino', text: 'app: document' });
1341
+ document.body.append(editor);
1342
+ await editor.ready;
1343
+ editor.externalUpdate('document.lino', 'app: document\n title Updated');
1344
+ editor.addEventListener('ui-save', ({ detail: { id, text } }) => {
1345
+ // Commit to the application's source repository; text may be ''.
1346
+ console.log(id, text);
1347
+ });
1348
+ ```
1349
+
1350
+ Configure `editorOptions` before accessing `model` or connecting the element.
1351
+ `createDocumentsModel({storage, clock, key})` is DOM-free. Storage has synchronous
1352
+ `getItem`/`setItem` methods; the optional clock has `setTimeout`/`clearTimeout`.
1353
+ The default storage key is `editor-tabs`; document drafts use
1354
+ `editor-tabs:draft:<encoded-document-id>`. Both tabs and drafts are nested LiNo,
1355
+ read by `links-notation` and written with ui-core `formatLinks`. Use distinct
1356
+ keys for independent workspaces. An edit writes its draft after 500 ms; save,
1357
+ conflict resolution and disconnect flush immediately. `save(id)` returns text
1358
+ and marks it clean; external persistence is the host's responsibility. Failed
1359
+ storage writes throw so the host can report them. Reopening an already-open id
1360
+ selects its draft; send new source through `externalUpdate`, which preserves a
1361
+ dirty draft until `resolve(id, 'mine'|'theirs')`. Save is disabled during a
1362
+ conflict. `close(id)` returns `unsaved` until confirmed; the element prompts,
1363
+ or accepts a synchronous `confirmClose(document)` callback.
1364
+
1365
+ ```lino
1366
+ source: code-editor
1367
+ label 'Document source'
1368
+ document-id document.lino
1369
+ title document.lino
1370
+ language lino
1371
+ value 'app: document'
1372
+ ```
1373
+
1374
+ `mountCodeEditor(host, options)` supports imperative mounting and explicit
1375
+ teardown. Engine adapters implement `setDocument`, `setDiagnostics`,
1376
+ `setReadOnly`, `focus` and `destroy`; `createEditorEngine` loads only the
1377
+ selected engine. Read-only mode preserves keyboard focus, selection and copying,
1378
+ including after switching documents. CodeMirror
1379
+ is the default. Its JavaScript, CSS, JSON and Markdown support loads from the
1380
+ corresponding language package when selected. Sessions retain selection and
1381
+ undo history across tab switches. LiNo validation uses the official parser,
1382
+ with its exact one-based error positions, a 64-level depth bound and a 1 MiB
1383
+ input bound. Syntax diagnostics appear inline and in a polite live list;
1384
+ selecting a diagnostic moves the cursor. Quoted strings, comments, ids and
1385
+ references are coloured lexically; only parser-confirmed links can fold.
1386
+ Escape followed by Tab leaves the engine. Opening or comparing source never
1387
+ executes it, and the editor never reformats source or removes comments.
1388
+
1389
+ For Monaco, install the optional `monaco-editor` peer and set `engine="monaco"`
1390
+ before connection. The default adapter dynamically imports that package; your
1391
+ bundler must configure its CSS and worker URLs as Monaco documents. A host can
1392
+ instead supply `engineOptions.loadMonaco: () => Promise<MonacoAPI>`. The example
1393
+ uses the installed peer's AMD loader only after **Load optional Monaco** is
1394
+ selected, so both adapters can be exercised without a bundler. Disconnect
1395
+ tears down editor views, listeners, timers and Monaco models; reconnect keeps
1396
+ the document model. A failed engine import renders an alert and rejects
1397
+ `ready`.
1398
+
1399
+ All new engine packages are MIT licensed: CodeMirror's state, view, language,
1400
+ commands, lint and four language packages, plus the Lezer highlighter and their
1401
+ transitive editor dependencies. Their installed npm manifests and licence
1402
+ files contain the notices; none is vendored. Monaco 0.58.0-dev-20261103 is MIT and remains
1403
+ an optional peer (a development dependency for the browser adapter tests).
1404
+ The pinned development build includes patched DOMPurify 3.4.17. Stable Monaco
1405
+ 0.57.0 bundles vulnerable DOMPurify even when its npm dependency is overridden;
1406
+ see [the upstream report](https://github.com/microsoft/monaco-editor/issues/5517).
1407
+ The peer range accepts the corresponding stable 0.58 release when available.
1408
+ See the [CodeMirror licence](https://github.com/codemirror/dev/blob/main/LICENSE)
1409
+ and [Monaco licence](https://github.com/microsoft/monaco-editor/blob/main/LICENSE.txt).
1410
+
1411
+ ## Chat kit
1412
+
1413
+ The provider-neutral [chat kit](src/chat/README.md) supplies a chat list,
1414
+ virtual message stream, bubbles, reasoning traces, day separators and a floating
1415
+ composer. It uses one LiNo data contract, capability-driven actions, bounded
1416
+ history and four light/dark skins. Try [the 10,000-message example](examples/chat.html).
1417
+
1418
+ ## Settings panel
1419
+
1420
+ Import `createSettingsPanel`, `controlFor` and `buildPanelModel` from
1421
+ `@link-foundation/ui-components/settings` and load `controls.css` and
1422
+ `settings.css` from this package. The panel uses the real `ui-settings`
1423
+ schema engine and the basic controls. See
1424
+ [`examples/settings.html`](examples/settings.html) (serve with
1425
+ `node scripts/serve-static.mjs`).
1426
+
1427
+ ```js
1428
+ const panel = createSettingsPanel(schema, {
1429
+ values,
1430
+ previewRoot: document.querySelector('#preview'),
1431
+ // target: bindConfig(config, schema, { layer: 'session' }),
1432
+ mode: 'drawer', // or 'page' (the default)
1433
+ random: seededRandom,
1434
+ });
1435
+ document.body.append(panel.element);
1436
+ openButton.addEventListener('click', () => panel.open(openButton));
1437
+ // panel.update({ 'liquid.blur': 24 }); panel.values(); panel.destroy();
1438
+ ```
1439
+
1440
+ The optional target has `values()`, `update(values)` and
1441
+ `subscribe(listener)` (returning an unsubscribe function), matching
1442
+ `ui-settings`' `bindConfig`. Writes are validated before reaching it.
1443
+ `previewRoot` receives schema CSS variable and data attribute hints. Holding
1444
+ Peek defaults applies defaults only to the preview and controls; releasing
1445
+ restores current values without writing the target. Sections are native
1446
+ collapsible groups. Drawer mode is non-modal; Escape closes it and restores
1447
+ focus to its opener. Destroy the panel to release subscriptions and controls.
1448
+
1449
+ Choice fields use a select; ranges include the existing slider, a number
1450
+ input and a unit output. The `vector`/`vector3` and `list` controls support
1451
+ application-defined array types registered through `defineFieldType` of
1452
+ `ui-settings`; the example demonstrates this without adding schema types.
1453
+ Paste changes validates a complete diff document before applying it; absent
1454
+ fields restore defaults. Clipboard failures reveal a selectable text field.
1455
+
1456
+ See [control and settings integration contracts](../../docs/case-studies/issue-210/contracts.md)
1457
+ for external labels, popup sizing, live editors, rich panel extensions, normalization
1458
+ and compatibility codec hooks. The [rich panel example](../ui-components/examples/rich-settings.html)
1459
+ demonstrates conditional fields, section tabs, previews and whole-section columns.
1460
+
1461
+ Settings panels accept a `messages` string/function catalog for generated chrome
1462
+ and field-specific editor actions; `panel.setMessages(catalog)` changes language
1463
+ without losing values. Color editors include grouped RGB sliders and numeric
1464
+ channels (field property `rgb false` hides them). Number controls and `nextValue`
1465
+ accept `snapping: 'directional'` to step continuous imported values to the next
1466
+ tick in the requested direction. See the [integration contracts](../../docs/case-studies/issue-210/contracts.md).
1467
+
1468
+ For continuous typed values, use `normalization clamp` on number fields or
1469
+ `readNumber(text, { ...range, normalization: 'clamp' })`. This is independent of
1470
+ key/pointer snapping; generated editors inherit the schema engine's
1471
+ `normalization.numbers` policy. The default remains step-snapped.
1472
+
1473
+ ### Host network presentation providers
1474
+
1475
+ `createNetworkPresentation` connects geometry, collision solving and SVG/raster
1476
+ backends to a single transactional snapshot. Assign it to
1477
+ `linksNetwork.presentation` to share the preview and export scene. See the
1478
+ [provider contract](../../docs/spec/network-providers.md) for cancellation,
1479
+ large decimal indexes, LiNo settings and host ownership.
1480
+
1481
+ The [network editor adapter](NETWORK-EDITOR.md) adds live notations, per-link
1482
+ controls, declarative options, looks and sizes, saved styles, sharing and
1483
+ held-input URL synchronization around a host-owned network presentation.
1484
+
1485
+ See the [settings gallery guide](../../docs/case-studies/issue-231/README.md)
1486
+ for balanced columns, preset cards, saved looks, colour popovers and cross-tab sync.
1487
+
1488
+ ### Doublet configurations and gallery
1489
+
1490
+ See [the configurations guide](CONFIGURATIONS.md) for exact enumeration,
1491
+ notation conversion, editing helpers, renaming classes and `<links-gallery>`.
1492
+
1493
+ ## Deferred social embeds
1494
+
1495
+ The opt-in [`embed` module](src/embed/README.md) provides `<ui-embed>` and
1496
+ `embedVocabulary()`, deferred SDK loading, archive fallback and a toggle.
1497
+ Import X, Telegram and VK adapters from `@link-foundation/ui-components/embed/providers/`.
1498
+
1499
+ See [brand marks, presentation variants and static subsets](ICONS.md) for
1500
+ Simple Icons and localized inline messages.