@link-foundation/ui-components 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONFIGURATIONS.md +74 -0
- package/ICONS.md +76 -0
- package/LICENSE +24 -0
- package/README.md +1499 -2
- package/bin/lino-network.mjs +71 -0
- package/dist/icons/ATTRIBUTION.md +602 -0
- package/dist/icons/NOTICE.lino +1261 -0
- package/dist/icons/brand.js +31 -0
- package/dist/icons/brand.svg +3 -0
- package/dist/icons/licenses/brand/DISCLAIMER.md +51 -0
- package/dist/icons/licenses/brand/LICENSE.md +30 -0
- package/dist/icons/licenses/lucide/LICENSE +43 -0
- package/dist/icons/licenses/material-symbols/LICENSE +202 -0
- package/dist/icons/licenses/material-symbols/NOTICE +12 -0
- package/dist/icons/licenses/tabler/LICENSE +21 -0
- package/dist/icons/lucide.js +681 -0
- package/dist/icons/lucide.svg +34 -0
- package/dist/icons/material-symbols.js +681 -0
- package/dist/icons/material-symbols.svg +34 -0
- package/dist/icons/own.js +521 -0
- package/dist/icons/own.svg +34 -0
- package/dist/icons/tabler.js +681 -0
- package/dist/icons/tabler.svg +34 -0
- package/dist/network-layout-NOTICE.md +6 -0
- package/dist/network-layout-d3-dispatch-LICENSE.txt +13 -0
- package/dist/network-layout-d3-force-LICENSE.txt +13 -0
- package/dist/network-layout-d3-quadtree-LICENSE.txt +13 -0
- package/dist/network-layout-d3-timer-LICENSE.txt +13 -0
- package/dist/network-layout-dagre-LICENSE.txt +19 -0
- package/dist/network-layout.worker.mjs +2 -0
- package/package.json +246 -4
- package/src/a11y/announce.js +88 -0
- package/src/a11y/bind-machine.js +181 -0
- package/src/a11y/focus.js +169 -0
- package/src/a11y/index.d.ts +89 -0
- package/src/a11y/index.js +19 -0
- package/src/a11y/keys.js +182 -0
- package/src/a11y/roving.js +167 -0
- package/src/a11y/typeahead.js +82 -0
- package/src/behavior/actions.js +235 -0
- package/src/behavior/diagnostics.js +73 -0
- package/src/behavior/dom.d.ts +38 -0
- package/src/behavior/dom.js +420 -0
- package/src/behavior/index.d.ts +211 -0
- package/src/behavior/index.js +29 -0
- package/src/behavior/interpret.js +454 -0
- package/src/behavior/machines/disclosure.lino +46 -0
- package/src/behavior/machines/index.js +91 -0
- package/src/behavior/machines/toggle.lino +25 -0
- package/src/behavior/parse-machine.js +367 -0
- package/src/charts/README.md +78 -0
- package/src/charts/activity-layout.js +350 -0
- package/src/charts/activity-model.js +130 -0
- package/src/charts/activity-validation.js +31 -0
- package/src/charts/chart-model.js +667 -0
- package/src/charts/chart.js +518 -0
- package/src/charts/echarts-adapter.d.ts +23 -0
- package/src/charts/echarts-adapter.js +240 -0
- package/src/charts/element.js +330 -0
- package/src/charts/errors.js +62 -0
- package/src/charts/gauge.js +27 -0
- package/src/charts/index.d.ts +344 -0
- package/src/charts/index.js +59 -0
- package/src/charts/layout.js +542 -0
- package/src/charts/lino.js +158 -0
- package/src/charts/mark-options.js +78 -0
- package/src/charts/read.js +101 -0
- package/src/charts/renderer-features.js +8 -0
- package/src/charts/scales.js +223 -0
- package/src/charts/small-model.js +223 -0
- package/src/charts/small-svg.js +269 -0
- package/src/charts/sparkline.js +27 -0
- package/src/charts/stat-tile.js +37 -0
- package/src/charts/summary.js +193 -0
- package/src/charts/svg-renderer.js +226 -0
- package/src/charts/svg.js +69 -0
- package/src/charts/tag-cloud.js +129 -0
- package/src/charts/tokens.js +171 -0
- package/src/charts/tooltip.js +47 -0
- package/src/charts/values.js +146 -0
- package/src/chat/README.md +142 -0
- package/src/chat/actions.js +75 -0
- package/src/chat/chat-contract.js +95 -0
- package/src/chat/chat-list.js +42 -0
- package/src/chat/chat-model.js +125 -0
- package/src/chat/chat.css +228 -0
- package/src/chat/composer.js +131 -0
- package/src/chat/day-separator.js +12 -0
- package/src/chat/dom.js +33 -0
- package/src/chat/follow.js +49 -0
- package/src/chat/index.d.ts +142 -0
- package/src/chat/index.js +13 -0
- package/src/chat/message-bubble.js +191 -0
- package/src/chat/message-stream.js +331 -0
- package/src/chat/reasoning-trace.js +70 -0
- package/src/chat/selection.js +39 -0
- package/src/chat/skins/bubbles.lino +2 -0
- package/src/chat/skins/cards.lino +4 -0
- package/src/chat/skins/compact.lino +4 -0
- package/src/chat/skins/signal.lino +25 -0
- package/src/chat/skins/t3.lino +25 -0
- package/src/chat/skins/telegram.lino +31 -0
- package/src/chat/skins/whatsapp.lino +25 -0
- package/src/chat/stream-keys.js +57 -0
- package/src/chat/stream-window.js +159 -0
- package/src/chat/vocabulary.js +19 -0
- package/src/controls/accordion.js +160 -0
- package/src/controls/avatar.js +80 -0
- package/src/controls/badge.js +48 -0
- package/src/controls/button-template.js +32 -0
- package/src/controls/button.js +97 -0
- package/src/controls/catalog.lino +84 -0
- package/src/controls/checkbox.js +112 -0
- package/src/controls/chip.js +140 -0
- package/src/controls/choices.js +45 -0
- package/src/controls/color-field.js +217 -0
- package/src/controls/color-popover.js +135 -0
- package/src/controls/color-rgb.js +80 -0
- package/src/controls/color.js +67 -0
- package/src/controls/combobox.js +192 -0
- package/src/controls/dom.js +261 -0
- package/src/controls/icon-button.js +33 -0
- package/src/controls/index.d.ts +163 -0
- package/src/controls/index.js +182 -0
- package/src/controls/kinds-text.js +358 -0
- package/src/controls/kinds.lino +350 -0
- package/src/controls/label.js +52 -0
- package/src/controls/link.js +101 -0
- package/src/controls/listbox.js +144 -0
- package/src/controls/machines/button.lino +20 -0
- package/src/controls/machines/checkbox.lino +17 -0
- package/src/controls/machines/chip.lino +20 -0
- package/src/controls/machines/color-field.lino +23 -0
- package/src/controls/machines/combobox.lino +82 -0
- package/src/controls/machines/icon-button.lino +20 -0
- package/src/controls/machines/index.js +586 -0
- package/src/controls/machines/number-field.lino +71 -0
- package/src/controls/machines/radio-group.lino +17 -0
- package/src/controls/machines/select.lino +122 -0
- package/src/controls/machines/slider.lino +99 -0
- package/src/controls/machines/switch.lino +19 -0
- package/src/controls/machines/text-area.lino +26 -0
- package/src/controls/machines/text-field.lino +26 -0
- package/src/controls/number-field.js +239 -0
- package/src/controls/numeric-keys.js +125 -0
- package/src/controls/option.js +54 -0
- package/src/controls/progress.js +76 -0
- package/src/controls/radio-group.js +234 -0
- package/src/controls/select.js +229 -0
- package/src/controls/slider.js +234 -0
- package/src/controls/stories.js +172 -0
- package/src/controls/styles.css +1060 -0
- package/src/controls/switch.js +95 -0
- package/src/controls/text-area.js +39 -0
- package/src/controls/text-field.js +131 -0
- package/src/controls/vocabulary.js +164 -0
- package/src/data/data.css +95 -0
- package/src/data/index.d.ts +83 -0
- package/src/data/index.js +10 -0
- package/src/data/keyboard.js +189 -0
- package/src/data/list.js +215 -0
- package/src/data/render-data.js +116 -0
- package/src/data/selection-dom.js +39 -0
- package/src/data/selection-model.js +43 -0
- package/src/data/sort-model.js +42 -0
- package/src/data/source.js +45 -0
- package/src/data/table.js +160 -0
- package/src/data/tree-model.js +41 -0
- package/src/data/tree.js +55 -0
- package/src/data/viewport.js +216 -0
- package/src/data/virtual-range.js +92 -0
- package/src/data/vocabulary.js +67 -0
- package/src/diagrams/diagram-model.js +511 -0
- package/src/diagrams/diagram.js +204 -0
- package/src/diagrams/index.d.ts +225 -0
- package/src/diagrams/index.js +48 -0
- package/src/diagrams/layout-dagre.js +164 -0
- package/src/diagrams/layout-plugins.js +131 -0
- package/src/diagrams/mermaid-export.js +232 -0
- package/src/diagrams/mermaid-view.js +229 -0
- package/src/diagrams/svg-diagram.js +215 -0
- package/src/editor/code-editor.js +206 -0
- package/src/editor/documents-model.js +170 -0
- package/src/editor/documents-persistence.js +85 -0
- package/src/editor/editor-engine.js +22 -0
- package/src/editor/editor-ui.js +203 -0
- package/src/editor/editor.css +106 -0
- package/src/editor/engines/codemirror.js +227 -0
- package/src/editor/engines/monaco.js +219 -0
- package/src/editor/index.d.ts +111 -0
- package/src/editor/index.js +14 -0
- package/src/editor/lino-highlight.js +106 -0
- package/src/editor/lino-structure.js +85 -0
- package/src/editor/validate-lino.js +43 -0
- package/src/embed/README.md +161 -0
- package/src/embed/controller.js +223 -0
- package/src/embed/element.js +141 -0
- package/src/embed/index.d.ts +75 -0
- package/src/embed/index.js +9 -0
- package/src/embed/providers/telegram.d.ts +3 -0
- package/src/embed/providers/telegram.js +38 -0
- package/src/embed/providers/vk.d.ts +3 -0
- package/src/embed/providers/vk.js +42 -0
- package/src/embed/providers/x.d.ts +3 -0
- package/src/embed/providers/x.js +31 -0
- package/src/embed/registry.js +35 -0
- package/src/embed/script.js +73 -0
- package/src/embed/view.js +122 -0
- package/src/icons/adapters/lucide.d.ts +15 -0
- package/src/icons/adapters/lucide.js +142 -0
- package/src/icons/adapters/material-symbols.d.ts +13 -0
- package/src/icons/adapters/material-symbols.js +113 -0
- package/src/icons/adapters/shared.d.ts +38 -0
- package/src/icons/adapters/shared.js +157 -0
- package/src/icons/adapters/simple-icons.d.ts +9 -0
- package/src/icons/adapters/simple-icons.js +38 -0
- package/src/icons/adapters/tabler.d.ts +9 -0
- package/src/icons/adapters/tabler.js +86 -0
- package/src/icons/icon-registry.js +215 -0
- package/src/icons/icon.js +356 -0
- package/src/icons/index.d.ts +123 -0
- package/src/icons/index.js +30 -0
- package/src/icons/names.js +51 -0
- package/src/icons/own-icons.js +521 -0
- package/src/icons/presentation.js +55 -0
- package/src/icons/svg.js +136 -0
- package/src/index.d.ts +14 -0
- package/src/index.js +40 -0
- package/src/layout/README.md +102 -0
- package/src/layout/app-shell.js +150 -0
- package/src/layout/catalog.lino +27 -0
- package/src/layout/dock-model.js +576 -0
- package/src/layout/dock-view.js +312 -0
- package/src/layout/dock.js +352 -0
- package/src/layout/dom.js +312 -0
- package/src/layout/grid.js +192 -0
- package/src/layout/index.d.ts +267 -0
- package/src/layout/index.js +60 -0
- package/src/layout/layer-manager.js +120 -0
- package/src/layout/layout.css +760 -0
- package/src/layout/menu.js +141 -0
- package/src/layout/nav-strip.js +174 -0
- package/src/layout/page-links.js +166 -0
- package/src/layout/panel.js +26 -0
- package/src/layout/pref-switches.js +209 -0
- package/src/layout/split-model.js +270 -0
- package/src/layout/split.js +430 -0
- package/src/layout/stack.js +86 -0
- package/src/layout/surfaces.js +119 -0
- package/src/layout/tab-group.js +151 -0
- package/src/layout/tab-strip.js +277 -0
- package/src/layout/vocabulary.js +229 -0
- package/src/layout/window-frame.js +222 -0
- package/src/layout/window.js +146 -0
- package/src/links-view/animator.js +144 -0
- package/src/links-view/configuration-classes.js +150 -0
- package/src/links-view/configuration-model.js +191 -0
- package/src/links-view/configuration-notations.js +230 -0
- package/src/links-view/configurations.d.ts +73 -0
- package/src/links-view/configurations.js +33 -0
- package/src/links-view/create-layout-runner.js +79 -0
- package/src/links-view/doublet-curves.js +239 -0
- package/src/links-view/doublet-layout.js +148 -0
- package/src/links-view/doublet-markers.js +109 -0
- package/src/links-view/doublet-options.js +369 -0
- package/src/links-view/doublet-svg.js +156 -0
- package/src/links-view/doublet.js +230 -0
- package/src/links-view/export.js +146 -0
- package/src/links-view/geometry.js +409 -0
- package/src/links-view/index.d.ts +1029 -0
- package/src/links-view/index.js +140 -0
- package/src/links-view/labels.js +28 -0
- package/src/links-view/layout-worker-entry.mjs +2 -0
- package/src/links-view/layout-worker.js +28 -0
- package/src/links-view/layouts/circle.js +7 -0
- package/src/links-view/layouts/force.js +76 -0
- package/src/links-view/layouts/grid.js +7 -0
- package/src/links-view/layouts/hex.js +8 -0
- package/src/links-view/layouts/index.js +15 -0
- package/src/links-view/layouts/layered.js +29 -0
- package/src/links-view/layouts/regular.js +27 -0
- package/src/links-view/layouts/spiral.js +10 -0
- package/src/links-view/link-view.js +494 -0
- package/src/links-view/links-gallery.js +306 -0
- package/src/links-view/links-network.js +496 -0
- package/src/links-view/lino-network-source.js +122 -0
- package/src/links-view/lino-network.js +233 -0
- package/src/links-view/lino-to-network.js +252 -0
- package/src/links-view/markers.js +192 -0
- package/src/links-view/model.js +233 -0
- package/src/links-view/network-editor/dom.js +36 -0
- package/src/links-view/network-editor/editor.js +202 -0
- package/src/links-view/network-editor/model.js +163 -0
- package/src/links-view/network-editor/options.js +265 -0
- package/src/links-view/network-editor/panels.js +423 -0
- package/src/links-view/network-editor/presets.js +76 -0
- package/src/links-view/network-editor/provider.js +93 -0
- package/src/links-view/network-editor/remap.js +45 -0
- package/src/links-view/network-editor/schema.js +224 -0
- package/src/links-view/network-editor/share.js +232 -0
- package/src/links-view/network-editor/styles.js +19 -0
- package/src/links-view/network-editor/url-sync.js +131 -0
- package/src/links-view/network-interaction.js +228 -0
- package/src/links-view/network-model.js +85 -0
- package/src/links-view/network-renderer.js +259 -0
- package/src/links-view/network-scene.js +245 -0
- package/src/links-view/network-source.js +82 -0
- package/src/links-view/network-vocabulary.js +18 -0
- package/src/links-view/presentation.js +199 -0
- package/src/links-view/render-canvas.js +102 -0
- package/src/links-view/render-svg.js +118 -0
- package/src/links-view/scene.js +233 -0
- package/src/links-view/solver-job.js +106 -0
- package/src/links-view/tokens.js +114 -0
- package/src/links-view/zoom-pan.js +203 -0
- package/src/overlays/catalog.lino +89 -0
- package/src/overlays/context-menu.js +110 -0
- package/src/overlays/dialog.js +117 -0
- package/src/overlays/dom.js +168 -0
- package/src/overlays/drawer.js +8 -0
- package/src/overlays/index.d.ts +80 -0
- package/src/overlays/index.js +25 -0
- package/src/overlays/kinds.lino +137 -0
- package/src/overlays/list-popover.js +129 -0
- package/src/overlays/machines/index.js +71 -0
- package/src/overlays/machines/surface.lino +11 -0
- package/src/overlays/machines/tabs.lino +7 -0
- package/src/overlays/machines/toast.lino +16 -0
- package/src/overlays/machines/tooltip.lino +29 -0
- package/src/overlays/menu.js +240 -0
- package/src/overlays/popover.js +194 -0
- package/src/overlays/position.js +84 -0
- package/src/overlays/radial-geometry.js +38 -0
- package/src/overlays/radial-menu.js +50 -0
- package/src/overlays/styles.css +155 -0
- package/src/overlays/tabs.js +125 -0
- package/src/overlays/toast-queue.js +105 -0
- package/src/overlays/toast.js +163 -0
- package/src/overlays/tooltip.js +110 -0
- package/src/overlays/vocabulary.js +3 -0
- package/src/settings/conditions.js +44 -0
- package/src/settings/control-for.js +62 -0
- package/src/settings/field-control.js +201 -0
- package/src/settings/index.d.ts +201 -0
- package/src/settings/index.js +3 -0
- package/src/settings/messages.js +112 -0
- package/src/settings/miniature.js +26 -0
- package/src/settings/panel-actions.js +234 -0
- package/src/settings/panel-model.js +49 -0
- package/src/settings/panel-refresh.js +56 -0
- package/src/settings/panel-rows.js +200 -0
- package/src/settings/preset-cards.js +43 -0
- package/src/settings/saved-looks.js +227 -0
- package/src/settings/section-layout.js +95 -0
- package/src/settings/section-tabs.js +175 -0
- package/src/settings/settings-panel.js +192 -0
- package/src/settings/settings.css +178 -0
- package/stories/accordion.lino +14 -0
- package/stories/alert-dialog.lino +4 -0
- package/stories/app-bar.lino +10 -0
- package/stories/avatar.lino +7 -0
- package/stories/badge.lino +12 -0
- package/stories/button.lino +17 -0
- package/stories/card.lino +10 -0
- package/stories/checkbox.lino +14 -0
- package/stories/chip.lino +19 -0
- package/stories/color-field.lino +9 -0
- package/stories/combobox.lino +10 -0
- package/stories/container.lino +11 -0
- package/stories/context-menu.lino +15 -0
- package/stories/dialog.lino +16 -0
- package/stories/drawer.lino +12 -0
- package/stories/icon-button.lino +13 -0
- package/stories/label.lino +7 -0
- package/stories/link-cards.lino +9 -0
- package/stories/link.lino +9 -0
- package/stories/menu-item.lino +6 -0
- package/stories/menu-separator.lino +7 -0
- package/stories/menu.lino +30 -0
- package/stories/nav-strip.lino +11 -0
- package/stories/number-field.lino +16 -0
- package/stories/option.lino +10 -0
- package/stories/paper.lino +11 -0
- package/stories/popover.lino +4 -0
- package/stories/pref-switches.lino +4 -0
- package/stories/progress.lino +14 -0
- package/stories/radial-menu.lino +19 -0
- package/stories/radio-group.lino +22 -0
- package/stories/radio.lino +10 -0
- package/stories/section-nav.lino +9 -0
- package/stories/select.lino +16 -0
- package/stories/slider.lino +14 -0
- package/stories/switch.lino +10 -0
- package/stories/tab-panel.lino +7 -0
- package/stories/tab.lino +7 -0
- package/stories/tabs.lino +25 -0
- package/stories/text-area.lino +12 -0
- package/stories/text-field.lino +23 -0
- package/stories/titled-section.lino +7 -0
- package/stories/toast.lino +3 -0
- package/stories/toaster.lino +2 -0
- package/stories/tooltip.lino +3 -0
package/README.md
CHANGED
|
@@ -1,3 +1,1500 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @link-foundation/ui-components
|
|
2
2
|
|
|
3
|
-
|
|
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.
|