@zeyos/zx 5.7.0 → 5.8.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/CHANGELOG.md +330 -0
- package/README.md +47 -9
- package/dist/types/components/activity-item/activity-item.d.ts +14 -3
- package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
- package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
- package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
- package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
- package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
- package/dist/types/components/approval-card/approval-card.d.ts +31 -2
- package/dist/types/components/aurora/aurora.d.ts +31 -5
- package/dist/types/components/calendar/calendar.d.ts +39 -26
- package/dist/types/components/chart/chart.d.ts +250 -20
- package/dist/types/components/chart/color.d.ts +66 -0
- package/dist/types/components/chart/svg-adapter.d.ts +103 -0
- package/dist/types/components/chart/svg-geometry.d.ts +203 -0
- package/dist/types/components/check-button/check-button.d.ts +1 -4
- package/dist/types/components/checklist/checklist.d.ts +48 -5
- package/dist/types/components/code-editor/code-editor.d.ts +55 -1
- package/dist/types/components/composer/composer.d.ts +41 -6
- package/dist/types/components/context-menu/context-menu.d.ts +36 -8
- package/dist/types/components/copy/copy-button.d.ts +6 -0
- package/dist/types/components/copy/copy-input.d.ts +1 -0
- package/dist/types/components/date-picker/date-picker.d.ts +14 -0
- package/dist/types/components/date-picker/time-picker.d.ts +26 -17
- package/dist/types/components/datebox/datebox.d.ts +8 -4
- package/dist/types/components/dialog/dialog.d.ts +15 -4
- package/dist/types/components/empty-state/empty-state.d.ts +10 -1
- package/dist/types/components/field/field.d.ts +4 -2
- package/dist/types/components/form/form.d.ts +2 -1
- package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
- package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
- package/dist/types/components/launcher/launcher.d.ts +26 -0
- package/dist/types/components/master-panel/master-panel.d.ts +9 -4
- package/dist/types/components/menu-button/menu-button.d.ts +29 -5
- package/dist/types/components/message/message.d.ts +308 -5
- package/dist/types/components/modal/modal.d.ts +45 -8
- package/dist/types/components/modal/native-dialog.d.ts +40 -0
- package/dist/types/components/module-bar/module-bar.d.ts +9 -2
- package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
- package/dist/types/components/number-field/number-field.d.ts +31 -1
- package/dist/types/components/pagination/pagination.d.ts +341 -19
- package/dist/types/components/run-status/run-status.d.ts +26 -0
- package/dist/types/components/run-trace/run-trace.d.ts +10 -6
- package/dist/types/components/search/search.d.ts +16 -4
- package/dist/types/components/select/select.d.ts +19 -1
- package/dist/types/components/sheet/sheet.d.ts +20 -6
- package/dist/types/components/slider/slider.d.ts +2 -1
- package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
- package/dist/types/components/stepper/stepper.d.ts +17 -4
- package/dist/types/components/surface/catalog.d.ts +61 -17
- package/dist/types/components/surface/surface.d.ts +6 -4
- package/dist/types/components/table/table.d.ts +207 -5
- package/dist/types/components/table/window.d.ts +25 -1
- package/dist/types/components/toggle/toggle.d.ts +38 -6
- package/dist/types/components/tooltip/tooltip.d.ts +5 -4
- package/dist/types/components/tree/tree.d.ts +43 -6
- package/dist/types/components/truncate/truncate.d.ts +4 -2
- package/dist/types/components/value-list/value-list.d.ts +9 -2
- package/dist/types/core/date.d.ts +2 -1
- package/dist/types/core/dom.d.ts +14 -0
- package/dist/types/core/drag-axis.d.ts +10 -5
- package/dist/types/core/export.d.ts +2 -2
- package/dist/types/core/format.d.ts +3 -1
- package/dist/types/core/icons.d.ts +36 -3
- package/dist/types/core/keyboard.d.ts +7 -3
- package/dist/types/core/messages.d.ts +3 -0
- package/dist/types/core/storage.d.ts +4 -3
- package/dist/types/core/util.d.ts +3 -1
- package/dist/types/elements/define.d.ts +5 -2
- package/dist/types/index.d.ts +6 -4
- package/dist/types/internal/agent-model.d.ts +99 -0
- package/dist/types/internal/app-rail.d.ts +37 -2
- package/dist/types/internal/collections.d.ts +18 -0
- package/dist/types/internal/menu-items.d.ts +27 -0
- package/dist/types/internal/overlay-content.d.ts +23 -0
- package/dist/types/internal/presence-loop.d.ts +5 -2
- package/dist/types/locales/index.d.ts +3 -0
- package/dist/types/zeyos/calendar.d.ts +43 -7
- package/dist/types/zeyos/connect.d.ts +4 -0
- package/dist/types/zeyos/form.d.ts +13 -5
- package/dist/types/zeyos/select.d.ts +5 -2
- package/dist/types/zeyos/table.d.ts +16 -8
- package/dist/types/zeyos/view.d.ts +2 -1
- package/dist/zx-zeyos.esm.js +3161 -515
- package/dist/zx-zeyos.esm.min.js +4 -4
- package/dist/zx.core.css +4 -0
- package/dist/zx.core.min.css +1 -1
- package/dist/zx.css +970 -57
- package/dist/zx.esm.js +6405 -2249
- package/dist/zx.esm.min.js +26 -26
- package/dist/zx.global.js +6405 -2249
- package/dist/zx.global.min.js +26 -26
- package/dist/zx.layered.css +972 -57
- package/dist/zx.layered.min.css +1 -1
- package/dist/zx.min.css +1 -1
- package/docs/agent-catalog.json +159 -1
- package/docs/agent-surfaces.md +21 -21
- package/docs/api.json +3154 -518
- package/docs/components/account-menu.md +24 -0
- package/docs/components/activity-item.md +23 -0
- package/docs/components/activity-list.md +28 -0
- package/docs/components/agent-avatar.md +59 -0
- package/docs/components/agent-thread.md +275 -0
- package/docs/components/app-icon.md +36 -0
- package/docs/components/app-sidebar.md +92 -0
- package/docs/components/approval-card.md +71 -0
- package/docs/components/aurora.md +34 -0
- package/docs/components/avatar.md +37 -0
- package/docs/components/badge.md +36 -0
- package/docs/components/block-view.md +34 -0
- package/docs/components/breadcrumb.md +20 -0
- package/docs/components/button.md +23 -0
- package/docs/components/calendar.md +68 -0
- package/docs/components/card-view.md +73 -0
- package/docs/components/card.md +25 -0
- package/docs/components/chart.md +109 -0
- package/docs/components/check-button.md +16 -0
- package/docs/components/checklist.md +19 -0
- package/docs/components/code-editor.md +38 -0
- package/docs/components/composer.md +107 -0
- package/docs/components/context-menu.md +32 -0
- package/docs/components/copy.md +37 -0
- package/docs/components/data-filter.md +16 -0
- package/docs/components/date-picker.md +31 -0
- package/docs/components/date-range.md +21 -0
- package/docs/components/datebox.md +31 -0
- package/docs/components/dialog.md +25 -0
- package/docs/components/dock.md +57 -0
- package/docs/components/dropdown.md +39 -0
- package/docs/components/elements.md +63 -0
- package/docs/components/empty-state.md +17 -0
- package/docs/components/entity-ref.md +26 -0
- package/docs/components/field-upload.md +18 -0
- package/docs/components/file-item.md +27 -0
- package/docs/components/file-list.md +23 -0
- package/docs/components/filter-panel.md +45 -0
- package/docs/components/filter.md +47 -0
- package/docs/components/finder.md +25 -0
- package/docs/components/form-widgets.md +42 -0
- package/docs/components/form.md +80 -0
- package/docs/components/grid.md +26 -0
- package/docs/components/groupbox.md +11 -0
- package/docs/components/helpers.md +359 -0
- package/docs/components/icons.md +87 -0
- package/docs/components/index.md +99 -0
- package/docs/components/kanban-view.md +42 -0
- package/docs/components/kbd.md +23 -0
- package/docs/components/kernel.md +41 -0
- package/docs/components/launcher.md +66 -0
- package/docs/components/layout.md +33 -0
- package/docs/components/list-toolbar.md +38 -0
- package/docs/components/loading.md +48 -0
- package/docs/components/menu-button.md +47 -0
- package/docs/components/message.md +76 -0
- package/docs/components/modal.md +27 -0
- package/docs/components/module-bar.md +71 -0
- package/docs/components/multi-value-editor.md +16 -0
- package/docs/components/navigation-bar.md +22 -0
- package/docs/components/number-field.md +34 -0
- package/docs/components/pagination.md +73 -0
- package/docs/components/panel.md +28 -0
- package/docs/components/prompt-starters.md +40 -0
- package/docs/components/prose.md +38 -0
- package/docs/components/questionnaire.md +115 -0
- package/docs/components/rating.md +19 -0
- package/docs/components/run-status.md +50 -0
- package/docs/components/run-trace.md +72 -0
- package/docs/components/search.md +11 -0
- package/docs/components/select.md +129 -0
- package/docs/components/sheet-stack.md +39 -0
- package/docs/components/sheet.md +77 -0
- package/docs/components/skeleton.md +27 -0
- package/docs/components/slider.md +29 -0
- package/docs/components/sort-control.md +21 -0
- package/docs/components/source-list.md +30 -0
- package/docs/components/split-view.md +12 -0
- package/docs/components/stat-tile.md +49 -0
- package/docs/components/stepper.md +27 -0
- package/docs/components/surface.md +152 -0
- package/docs/components/tabbox.md +33 -0
- package/docs/components/table-view.md +43 -0
- package/docs/components/table.md +232 -0
- package/docs/components/tag-picker.md +39 -0
- package/docs/components/timebox.md +16 -0
- package/docs/components/toggle.md +21 -0
- package/docs/components/tokens.md +82 -0
- package/docs/components/toolbar.md +26 -0
- package/docs/components/tooltip.md +16 -0
- package/docs/components/tree.md +48 -0
- package/docs/components/truncate.md +21 -0
- package/docs/components/value-list.md +14 -0
- package/docs/components/view-settings.md +56 -0
- package/docs/components/workspace-switcher.md +42 -0
- package/docs/components/zeyos.md +196 -0
- package/docs/llms-small.txt +299 -0
- package/docs/llms.md +725 -109
- package/docs/llms.txt +46 -19
- package/package.json +9 -4
- package/src/components/activity-item/activity-item.js +21 -2
- package/src/components/agent-avatar/agent-avatar.css +195 -0
- package/src/components/agent-avatar/agent-avatar.js +333 -0
- package/src/components/agent-avatar/agent-face.js +292 -0
- package/src/components/agent-thread/ag-ui.js +44 -11
- package/src/components/agent-thread/agent-thread.js +103 -11
- package/src/components/agent-thread/ui-message-stream.js +3 -1
- package/src/components/app-rail/app-rail.css +5 -0
- package/src/components/app-sidebar/app-sidebar.css +3 -0
- package/src/components/app-sidebar/app-sidebar.js +4 -3
- package/src/components/approval-card/approval-card.css +6 -0
- package/src/components/approval-card/approval-card.js +55 -7
- package/src/components/aurora/aurora.css +149 -14
- package/src/components/aurora/aurora.js +49 -6
- package/src/components/button/button.css +24 -11
- package/src/components/calendar/calendar.css +6 -2
- package/src/components/calendar/calendar.js +127 -47
- package/src/components/card-view/card-view.js +5 -6
- package/src/components/chart/chart.css +159 -1
- package/src/components/chart/chart.js +450 -62
- package/src/components/chart/color.js +297 -0
- package/src/components/chart/svg-adapter.js +576 -0
- package/src/components/chart/svg-geometry.js +323 -0
- package/src/components/check-button/check-button.js +3 -18
- package/src/components/checklist/checklist.css +9 -1
- package/src/components/checklist/checklist.js +105 -20
- package/src/components/checklist/field-adapter.js +6 -12
- package/src/components/code-editor/code-editor.css +33 -0
- package/src/components/code-editor/code-editor.js +97 -8
- package/src/components/code-editor/field-adapter.js +3 -0
- package/src/components/composer/composer.css +3 -0
- package/src/components/composer/composer.js +100 -22
- package/src/components/context-menu/context-menu.js +41 -5
- package/src/components/copy/copy-button.js +9 -1
- package/src/components/copy/copy-input.js +5 -0
- package/src/components/data-filter/filter-core.js +0 -1
- package/src/components/date-picker/date-picker.css +8 -0
- package/src/components/date-picker/date-picker.js +47 -8
- package/src/components/date-picker/date-range-picker.js +1 -1
- package/src/components/date-picker/month-picker.js +19 -3
- package/src/components/date-picker/time-picker.js +54 -19
- package/src/components/datebox/date-range-box.js +7 -3
- package/src/components/datebox/datebox.js +32 -6
- package/src/components/dialog/dialog.css +6 -0
- package/src/components/dialog/dialog.js +24 -33
- package/src/components/dropdown/dropdown.js +1 -18
- package/src/components/empty-state/empty-state.js +21 -2
- package/src/components/field/field.js +19 -3
- package/src/components/fieldset/fieldset.js +3 -1
- package/src/components/filter/filter.js +9 -0
- package/src/components/form/form.js +19 -2
- package/src/components/kanban-view/kanban-card.js +15 -2
- package/src/components/kanban-view/kanban-view.css +21 -0
- package/src/components/kanban-view/kanban-view.js +29 -16
- package/src/components/launcher/launcher.css +14 -0
- package/src/components/launcher/launcher.js +54 -9
- package/src/components/master-panel/master-panel.js +24 -22
- package/src/components/menu-button/menu-button.js +26 -4
- package/src/components/message/message.css +228 -29
- package/src/components/message/message.js +664 -30
- package/src/components/modal/modal.js +129 -30
- package/src/components/modal/native-dialog.js +91 -0
- package/src/components/module-bar/module-bar.css +3 -0
- package/src/components/module-bar/module-bar.js +17 -4
- package/src/components/multi-value-editor/multi-value-editor.css +7 -2
- package/src/components/multi-value-editor/multi-value-editor.js +3 -2
- package/src/components/navigation-bar/navigation-bar.js +13 -1
- package/src/components/number-field/field-adapter.js +3 -0
- package/src/components/number-field/number-field.js +70 -16
- package/src/components/pagination/pagination.css +26 -2
- package/src/components/pagination/pagination.js +551 -65
- package/src/components/prose/prose.js +7 -1
- package/src/components/rating/field-adapter.js +3 -0
- package/src/components/run-status/run-status.js +43 -3
- package/src/components/run-trace/run-trace.js +15 -7
- package/src/components/search/search.js +3 -18
- package/src/components/select/field-adapter.js +8 -1
- package/src/components/select/select.js +68 -13
- package/src/components/sheet/sheet.js +39 -13
- package/src/components/slider/field-adapter.js +3 -0
- package/src/components/slider/slider.js +4 -6
- package/src/components/stat-tile/stat-tile.js +24 -9
- package/src/components/stepper/stepper.css +15 -0
- package/src/components/stepper/stepper.js +34 -2
- package/src/components/surface/catalog.js +185 -28
- package/src/components/surface/surface.js +10 -5
- package/src/components/tabbox/tabbox.js +13 -1
- package/src/components/table/table.css +160 -2
- package/src/components/table/table.js +479 -52
- package/src/components/table/window.js +46 -4
- package/src/components/table-view/table-view.js +1 -10
- package/src/components/tag-picker/field-adapter.js +3 -0
- package/src/components/tag-picker/tag-picker.js +2 -0
- package/src/components/timebox/field-adapter.js +3 -0
- package/src/components/toggle/toggle.js +51 -27
- package/src/components/tooltip/tooltip.js +21 -14
- package/src/components/tree/tree.js +87 -14
- package/src/components/truncate/truncate.js +21 -5
- package/src/components/value-list/value-list.js +37 -9
- package/src/components/view-settings/view-settings.js +1 -5
- package/src/core/component.js +34 -2
- package/src/core/date.js +5 -4
- package/src/core/dom.js +45 -2
- package/src/core/drag-axis.js +24 -7
- package/src/core/export.js +4 -4
- package/src/core/fontawesome.js +34 -3
- package/src/core/format.js +3 -1
- package/src/core/http.js +23 -11
- package/src/core/icons.js +60 -8
- package/src/core/keyboard.js +83 -9
- package/src/core/messages.js +3 -0
- package/src/core/position.js +4 -3
- package/src/core/storage.js +80 -31
- package/src/core/util.js +16 -5
- package/src/elements/define.js +82 -47
- package/src/elements/kit.js +46 -35
- package/src/index.js +8 -4
- package/src/internal/agent-model.js +152 -0
- package/src/internal/app-rail.js +53 -2
- package/src/internal/collections.js +25 -0
- package/src/internal/menu-items.js +59 -0
- package/src/internal/overlay-content.js +35 -0
- package/src/internal/presence-loop.js +61 -14
- package/src/locales/de.js +3 -0
- package/src/zeyos/calendar.js +81 -19
- package/src/zeyos/connect.js +5 -1
- package/src/zeyos/form.js +29 -10
- package/src/zeyos/select.js +36 -12
- package/src/zeyos/table.js +43 -11
- package/src/zeyos/view.js +2 -1
- package/styles/tokens/semantic.css +7 -1
- package/styles/zx.css +1 -0
|
@@ -62,12 +62,17 @@ import { skeleton } from '../skeleton/skeleton.js';
|
|
|
62
62
|
* display size while the others stay smaller, on a framed tile one step above the display size.
|
|
63
63
|
* Give it to one tile per row. Reflected as `data-emphasis="true"`.
|
|
64
64
|
* @property {string|null} [href=null] Destination. A tile with an href is an `<a>`.
|
|
65
|
-
* @property {boolean} [clickable=false] Renders a `<button>` without an href. Passing
|
|
66
|
-
* sets this implicitly; set it
|
|
65
|
+
* @property {boolean} [clickable=false] Renders a `<button>` without an href. Passing a function
|
|
66
|
+
* as `onclick` sets this implicitly; set it to `true` to subscribe with `on('click', …)` instead.
|
|
67
|
+
* An explicit `false` wins over `onclick`: the tile stays a `<div>` and the handler is never
|
|
68
|
+
* called — for a caller that always passes a handler and decides per tile whether it applies.
|
|
69
|
+
* It does not turn a tile with an `href` into anything but a link.
|
|
67
70
|
* @property {boolean} [loading=false] Renders a skeleton shaped like the tile.
|
|
68
71
|
* @property {Record<string, unknown>} [msg] Message overrides, keyed as `statTile.*`.
|
|
69
72
|
* @property {(event: CustomEvent<{event: MouseEvent}>) => void} [onclick] Activation listener; its
|
|
70
|
-
* presence is what turns a tile with no href into a button
|
|
73
|
+
* presence is what turns a tile with no href into a button, unless `clickable` is `false`. Leave
|
|
74
|
+
* it out — rather than passing an empty function — for a tile that does nothing. It is the
|
|
75
|
+
* tile's `click` event, as
|
|
71
76
|
* every Zx component's `on*` option is, so it receives the `CustomEvent` carrying the native
|
|
72
77
|
* event in `detail.event`.
|
|
73
78
|
*/
|
|
@@ -153,10 +158,7 @@ export class StatTile extends Component {
|
|
|
153
158
|
// `Component` consumes every function-valued `on*` option into a component event listener, so
|
|
154
159
|
// `options.onclick` no longer exists by the time `render()` chooses the element's tag. The
|
|
155
160
|
// shape decision is taken here, before the base constructor, and carried across as a flag.
|
|
156
|
-
super(target, {
|
|
157
|
-
...options,
|
|
158
|
-
clickable: options?.clickable === true || typeof options?.onclick === 'function'
|
|
159
|
-
});
|
|
161
|
+
super(target, { ...options, clickable: statTileClickable(options ?? {}) });
|
|
160
162
|
}
|
|
161
163
|
|
|
162
164
|
/**
|
|
@@ -325,8 +327,21 @@ export function normalizeStatTileVariant(value) {
|
|
|
325
327
|
*/
|
|
326
328
|
export function statTileTag(options = {}) {
|
|
327
329
|
if (safeHref(options.href)) return 'a';
|
|
328
|
-
|
|
329
|
-
|
|
330
|
+
return statTileClickable(options) ? 'button' : 'div';
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
/**
|
|
334
|
+
* Whether a tile without a destination is an action. `clickable` decides when it is given as a
|
|
335
|
+
* boolean; left out (or nullish), a function-valued `onclick` does. So an explicit
|
|
336
|
+
* `clickable: false` wins over a handler, and a handler that is not a function is not behaviour.
|
|
337
|
+
* @param {{clickable?: boolean|null, onclick?: unknown}} [options={}] The options that carry
|
|
338
|
+
* behaviour.
|
|
339
|
+
* @returns {boolean}
|
|
340
|
+
*/
|
|
341
|
+
export function statTileClickable(options = {}) {
|
|
342
|
+
if (options.clickable === true) return true;
|
|
343
|
+
if (options.clickable === false) return false;
|
|
344
|
+
return typeof options.onclick === 'function';
|
|
330
345
|
}
|
|
331
346
|
|
|
332
347
|
/**
|
|
@@ -202,6 +202,21 @@ button.zx-stepper__control:disabled {
|
|
|
202
202
|
background: var(--zx-color-border);
|
|
203
203
|
}
|
|
204
204
|
|
|
205
|
+
/* A rail too wide for its container wraps. The last step of a row has no next step beside it, so
|
|
206
|
+
its connector would run to the container's edge and point at nothing; the component marks that
|
|
207
|
+
step (it is a fact of layout, not of the markup) and the connector is not painted. It keeps its
|
|
208
|
+
box — at the minimum width the step was measured with, so the mark cannot move the row break it
|
|
209
|
+
was read from — and the step stops growing, so the row's slack goes to the connectors that are
|
|
210
|
+
drawn. */
|
|
211
|
+
.zx-stepper[data-orientation="horizontal"] .zx-stepper__step[data-row-end] {
|
|
212
|
+
flex-grow: 0;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
.zx-stepper[data-orientation="horizontal"] .zx-stepper__step[data-row-end]::after {
|
|
216
|
+
flex: 0 0 var(--zx-space-4);
|
|
217
|
+
visibility: hidden;
|
|
218
|
+
}
|
|
219
|
+
|
|
205
220
|
/* ---------------------------------------------------------------------- vertical -- */
|
|
206
221
|
|
|
207
222
|
.zx-stepper[data-orientation="vertical"] .zx-stepper__list {
|
|
@@ -21,7 +21,8 @@ const CLICKABLE = new Set(['completed', 'all', false]);
|
|
|
21
21
|
* @property {StepDefinition[]} [steps=[]] Ordered step definitions.
|
|
22
22
|
* @property {string|null} [active=null] Initially active step name; defaults to the first enabled step.
|
|
23
23
|
* @property {StepperOrientation} [orientation='horizontal'] `horizontal` lays the rail out above the
|
|
24
|
-
* stage, `vertical` puts it beside the stage.
|
|
24
|
+
* stage, `vertical` puts it beside the stage. A horizontal rail too wide for its container wraps
|
|
25
|
+
* onto further rows; each row's connectors end at its last step.
|
|
25
26
|
* @property {StepperClickable} [clickable='completed'] Which steps are activated by a click:
|
|
26
27
|
* `completed` (go back only), `all`, or `false` for a display-only rail.
|
|
27
28
|
* @property {boolean} [showNumbers=true] Whether upcoming and active markers show their number.
|
|
@@ -48,7 +49,8 @@ const CLICKABLE = new Set(['completed', 'all', false]);
|
|
|
48
49
|
/**
|
|
49
50
|
* @typedef {Object} StepRecord
|
|
50
51
|
* @property {NormalizedStep} step Normalized definition.
|
|
51
|
-
* @property {HTMLLIElement} item List item carrying `data-state` and `aria-current
|
|
52
|
+
* @property {HTMLLIElement} item List item carrying `data-state` and `aria-current`, and
|
|
53
|
+
* `data-row-end` while it is the last step of a row in a wrapped horizontal rail.
|
|
52
54
|
* @property {HTMLElement} control Button (clickable rails) or span (display-only rails).
|
|
53
55
|
* @property {HTMLElement} marker Number / check / warning bubble.
|
|
54
56
|
* @property {HTMLElement} status Visually hidden state text for assistive technology.
|
|
@@ -125,6 +127,14 @@ export class Stepper extends Component {
|
|
|
125
127
|
const list = h('ol', { class: 'zx-stepper__list', ref: 'list' });
|
|
126
128
|
root.replaceChildren(...(this.options.counter ? [counter, list] : [list]));
|
|
127
129
|
|
|
130
|
+
// A wrapped horizontal rail must not draw a connector out of a row's last step, and only layout
|
|
131
|
+
// knows which step that is. Without ResizeObserver the rail keeps every connector.
|
|
132
|
+
/** @type {ResizeObserver|null} */
|
|
133
|
+
this._rowObserver = this.options.orientation === 'horizontal' && typeof ResizeObserver === 'function'
|
|
134
|
+
? new ResizeObserver(() => this._markRows())
|
|
135
|
+
: null;
|
|
136
|
+
this._rowObserver?.observe(list);
|
|
137
|
+
|
|
128
138
|
this.setSteps(this.options.steps);
|
|
129
139
|
|
|
130
140
|
this.listen(list, 'click', (event) => {
|
|
@@ -157,9 +167,13 @@ export class Stepper extends Component {
|
|
|
157
167
|
if (index < 0) index = resolveStepIndex(steps, -1, 1);
|
|
158
168
|
this._activeIndex = index;
|
|
159
169
|
|
|
170
|
+
for (const record of this._records) this._rowObserver?.unobserve(record.item);
|
|
160
171
|
this._records = steps.map((step) => this._createRecord(step));
|
|
161
172
|
this.refs.list.replaceChildren(...this._records.map((record) => record.item));
|
|
173
|
+
// A step that changes size (a late font, a longer title) can move the row breaks too.
|
|
174
|
+
for (const record of this._records) this._rowObserver?.observe(record.item);
|
|
162
175
|
this._sync();
|
|
176
|
+
this._markRows();
|
|
163
177
|
return this;
|
|
164
178
|
}
|
|
165
179
|
|
|
@@ -284,6 +298,8 @@ export class Stepper extends Component {
|
|
|
284
298
|
if (this._destroyed) return;
|
|
285
299
|
this._destroyed = true;
|
|
286
300
|
const root = this.el;
|
|
301
|
+
this._rowObserver?.disconnect();
|
|
302
|
+
this._rowObserver = null;
|
|
287
303
|
super.destroy();
|
|
288
304
|
if (!this._createdRoot && root) restoreTarget(root, this._snapshot);
|
|
289
305
|
}
|
|
@@ -313,6 +329,22 @@ export class Stepper extends Component {
|
|
|
313
329
|
return this;
|
|
314
330
|
}
|
|
315
331
|
|
|
332
|
+
/**
|
|
333
|
+
* Marks the last step of every row but the final one with `data-row-end`, which is what hides
|
|
334
|
+
* its connector. The mark changes no size — the connector keeps its box — so the row breaks it
|
|
335
|
+
* was measured from stay where they are and one pass settles.
|
|
336
|
+
* @returns {void}
|
|
337
|
+
*/
|
|
338
|
+
_markRows() {
|
|
339
|
+
if (!this._rowObserver || !this.el?.isConnected) return;
|
|
340
|
+
const boxes = this._records.map((record) => record.item.getBoundingClientRect());
|
|
341
|
+
this._records.forEach((record, index) => {
|
|
342
|
+
const next = boxes[index + 1];
|
|
343
|
+
// Steps of one row overlap vertically even when their heights differ; the next row does not.
|
|
344
|
+
record.item.toggleAttribute('data-row-end', Boolean(next) && next.top >= boxes[index].bottom - 1);
|
|
345
|
+
});
|
|
346
|
+
}
|
|
347
|
+
|
|
316
348
|
/**
|
|
317
349
|
* Builds one step's elements. The control's tag depends only on the `clickable` option, never on
|
|
318
350
|
* the step's state, so state changes never have to swap an element out from under the focus.
|
|
@@ -129,6 +129,10 @@ export const FORBIDDEN_KEYS = Object.freeze(['__proto__', 'constructor', 'protot
|
|
|
129
129
|
* @property {string|null} component The component that draws it, as `docs/api.json` names it;
|
|
130
130
|
* `null` for a node the surface draws itself.
|
|
131
131
|
* @property {SurfaceIntent} [intentOnly] The one intent the node may appear in.
|
|
132
|
+
* @property {string} use One sentence, for the model: when to pick the node.
|
|
133
|
+
* @property {string} avoid One sentence, for the model: when not to, naming the node or intent to
|
|
134
|
+
* use instead in backticks. The guide leaves it out when that node or intent is not in the
|
|
135
|
+
* catalog it is written for.
|
|
132
136
|
* @property {boolean} children Whether it lays out `children`.
|
|
133
137
|
* @property {boolean} input Whether its value lands in the reply's `values`.
|
|
134
138
|
* @property {Readonly<Record<string, CatalogProp>>} props Its properties.
|
|
@@ -152,6 +156,27 @@ export const FORBIDDEN_KEYS = Object.freeze(['__proto__', 'constructor', 'protot
|
|
|
152
156
|
* @property {Readonly<Record<string, CatalogNode>>} nodes The node types.
|
|
153
157
|
*/
|
|
154
158
|
|
|
159
|
+
/**
|
|
160
|
+
* A named narrowing of the catalog, from the smallest to everything: `answer` shows, `ask` also
|
|
161
|
+
* asks, `review` also reviews changes, `full` is the whole catalog.
|
|
162
|
+
* @typedef {'answer'|'ask'|'review'|'full'} CatalogProfile
|
|
163
|
+
*/
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* What `narrowCatalog()` keeps.
|
|
167
|
+
* @typedef {Object} CatalogNarrowing
|
|
168
|
+
* @property {CatalogProfile} [profile] A named set to start from; the whole catalog when left out.
|
|
169
|
+
* @property {SurfaceIntent[]} [intents] The intents to keep, within the profile; all when left out.
|
|
170
|
+
* @property {string[]} [nodes] The node types to keep, within the profile; all when left out.
|
|
171
|
+
*/
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* The `profile` option of `surfaceSchema()`, `surfaceTools()` and `surfacePrompt()`.
|
|
175
|
+
* @typedef {Object} ProfileChoice
|
|
176
|
+
* @property {CatalogProfile} [profile] Narrows the catalog to a profile first; the catalog as
|
|
177
|
+
* given when left out.
|
|
178
|
+
*/
|
|
179
|
+
|
|
155
180
|
/** @param {CatalogType} type @param {Partial<CatalogProp>} [rest] @returns {CatalogProp} */
|
|
156
181
|
const prop = (type, rest = {}) => ({ type, option: null, ...rest });
|
|
157
182
|
|
|
@@ -161,10 +186,14 @@ const TONES = ['info', 'success', 'warning', 'danger'];
|
|
|
161
186
|
const NODES = {
|
|
162
187
|
text: {
|
|
163
188
|
type: 'text', component: 'BlockView', children: false, input: false,
|
|
189
|
+
use: 'Use it for prose: an explanation, a finding or a reason, with `[n]` markers where a claim has a source.',
|
|
190
|
+
avoid: 'Avoid it for parallel items or a section title; use `list` or `heading`.',
|
|
164
191
|
props: { text: prop('string', { required: true, max: LIMITS.string, option: 'blocks[].text' }) }
|
|
165
192
|
},
|
|
166
193
|
heading: {
|
|
167
194
|
type: 'heading', component: 'BlockView', children: false, input: false,
|
|
195
|
+
use: 'Use it to title one part of a longer surface, so the person can scan it.',
|
|
196
|
+
avoid: 'Avoid it for a titled section around several nodes; use `group`.',
|
|
168
197
|
props: {
|
|
169
198
|
text: prop('string', { required: true, max: LIMITS.label, option: 'blocks[].text' }),
|
|
170
199
|
level: prop('integer', { enum: [2, 3], option: 'blocks[].level' })
|
|
@@ -172,6 +201,8 @@ const NODES = {
|
|
|
172
201
|
},
|
|
173
202
|
list: {
|
|
174
203
|
type: 'list', component: 'BlockView', children: false, input: false,
|
|
204
|
+
use: 'Use it for parallel items the person reads in order or scans: steps, findings, things to check.',
|
|
205
|
+
avoid: 'Avoid it for labelled values or records with several values each; use `figures` or `table`.',
|
|
175
206
|
props: {
|
|
176
207
|
items: prop('string[]', { required: true, max: LIMITS.rows, option: 'blocks[].items' }),
|
|
177
208
|
ordered: prop('boolean', { option: 'blocks[].ordered' })
|
|
@@ -179,10 +210,14 @@ const NODES = {
|
|
|
179
210
|
},
|
|
180
211
|
quote: {
|
|
181
212
|
type: 'quote', component: 'BlockView', children: false, input: false,
|
|
213
|
+
use: 'Use it for words quoted from a source, such as a message or a clause, shown as written.',
|
|
214
|
+
avoid: 'Avoid it for your own emphasis or a warning; use `callout`.',
|
|
182
215
|
props: { text: prop('string', { required: true, max: LIMITS.string, option: 'blocks[].text' }) }
|
|
183
216
|
},
|
|
184
217
|
code: {
|
|
185
218
|
type: 'code', component: 'BlockView', children: false, input: false,
|
|
219
|
+
use: 'Use it for code, a command, a query or a log excerpt whose exact characters matter.',
|
|
220
|
+
avoid: 'Avoid it for a name or a value inside a sentence; mark that inline in `text`.',
|
|
186
221
|
props: {
|
|
187
222
|
code: prop('string', { required: true, max: LIMITS.string, option: 'blocks[].code' }),
|
|
188
223
|
language: prop('string', { max: 32, option: 'blocks[].language' })
|
|
@@ -190,6 +225,8 @@ const NODES = {
|
|
|
190
225
|
},
|
|
191
226
|
callout: {
|
|
192
227
|
type: 'callout', component: 'BlockView', children: false, input: false,
|
|
228
|
+
use: 'Use it for a warning, a condition or a result the person must not miss, with a `tone` when it is a status.',
|
|
229
|
+
avoid: 'Avoid it for ordinary prose; use `text`.',
|
|
193
230
|
props: {
|
|
194
231
|
text: prop('string', { required: true, max: LIMITS.string, option: 'blocks[].text' }),
|
|
195
232
|
title: prop('string', { max: LIMITS.label, option: 'blocks[].title' }),
|
|
@@ -198,10 +235,14 @@ const NODES = {
|
|
|
198
235
|
},
|
|
199
236
|
figures: {
|
|
200
237
|
type: 'figures', component: 'BlockView', children: false, input: false,
|
|
238
|
+
use: 'Use it for a few labelled values of one thing, such as the total, due date and number of an invoice.',
|
|
239
|
+
avoid: 'Avoid it for records that share columns; use `table`.',
|
|
201
240
|
props: { rows: prop('Figure[]', { required: true, max: LIMITS.rows, option: 'blocks[].rows' }) }
|
|
202
241
|
},
|
|
203
242
|
table: {
|
|
204
243
|
type: 'table', component: 'Table', children: false, input: true,
|
|
244
|
+
use: 'Use it for records that share columns, for the person to compare them or look one up.',
|
|
245
|
+
avoid: 'Avoid it for the values of a single record; use `figures`.',
|
|
205
246
|
props: {
|
|
206
247
|
columns: prop('Column[]', { required: true, max: LIMITS.columns, option: 'columns' }),
|
|
207
248
|
rows: prop('Row[]', { required: true, max: LIMITS.rows, option: 'data' }),
|
|
@@ -213,6 +254,8 @@ const NODES = {
|
|
|
213
254
|
},
|
|
214
255
|
stat: {
|
|
215
256
|
type: 'stat', component: 'StatTile', children: false, input: false,
|
|
257
|
+
use: 'Use it for a headline figure the answer turns on, with its change or its context.',
|
|
258
|
+
avoid: 'Avoid it for a set of values that are read together; use `figures`.',
|
|
216
259
|
props: {
|
|
217
260
|
label: prop('string', { required: true, max: LIMITS.label, option: 'label' }),
|
|
218
261
|
value: prop('number|string', { required: true, max: LIMITS.label, option: 'value' }),
|
|
@@ -224,6 +267,8 @@ const NODES = {
|
|
|
224
267
|
},
|
|
225
268
|
badge: {
|
|
226
269
|
type: 'badge', component: 'Badge', children: false, input: false,
|
|
270
|
+
use: 'Use it beside other content to mark a status or a category in a word or two, such as Overdue or Draft.',
|
|
271
|
+
avoid: 'Avoid it for a sentence or a phrase; use `text`.',
|
|
227
272
|
props: {
|
|
228
273
|
label: prop('string', { required: true, max: LIMITS.name, option: 'label' }),
|
|
229
274
|
kind: prop('string', { enum: ['neutral', 'accent', 'success', 'warning', 'danger', 'info'], option: 'kind' })
|
|
@@ -231,10 +276,14 @@ const NODES = {
|
|
|
231
276
|
},
|
|
232
277
|
ref: {
|
|
233
278
|
type: 'ref', component: 'EntityRef', children: false, input: false,
|
|
279
|
+
use: 'Use it for a customer, an invoice or another record of the application the person may want to open.',
|
|
280
|
+
avoid: 'Avoid it for a page on the web; use `link`.',
|
|
234
281
|
props: { ref: prop('Ref', { required: true, option: 'id' }) }
|
|
235
282
|
},
|
|
236
283
|
link: {
|
|
237
284
|
type: 'link', component: null, children: false, input: false,
|
|
285
|
+
use: 'Use it for a page on the web the person may want to open, such as documentation or a source.',
|
|
286
|
+
avoid: 'Avoid it for a record of the application; use `ref`.',
|
|
238
287
|
props: {
|
|
239
288
|
text: prop('string', { required: true, max: LIMITS.label }),
|
|
240
289
|
href: prop('Href', { required: true, max: LIMITS.href })
|
|
@@ -242,6 +291,8 @@ const NODES = {
|
|
|
242
291
|
},
|
|
243
292
|
chart: {
|
|
244
293
|
type: 'chart', component: 'Chart', children: false, input: false,
|
|
294
|
+
use: 'Use it for a trend or a comparison across many values, where the shape matters more than each number.',
|
|
295
|
+
avoid: 'Avoid it for a few values the person reads exactly; use `figures`.',
|
|
245
296
|
props: {
|
|
246
297
|
kind: prop('string', { required: true, enum: ['bar', 'line', 'pie', 'doughnut'], option: 'type' }),
|
|
247
298
|
data: prop('ChartData', { required: true, option: 'data' }),
|
|
@@ -251,6 +302,8 @@ const NODES = {
|
|
|
251
302
|
},
|
|
252
303
|
empty: {
|
|
253
304
|
type: 'empty', component: 'EmptyState', children: false, input: false,
|
|
305
|
+
use: 'Use it when a search or a list comes back empty, to say what would change that.',
|
|
306
|
+
avoid: 'Avoid it for an error or a warning about what is shown; use `callout`.',
|
|
254
307
|
props: {
|
|
255
308
|
title: prop('string', { required: true, max: LIMITS.label, option: 'title' }),
|
|
256
309
|
description: prop('string', { max: LIMITS.description, option: 'description' })
|
|
@@ -258,18 +311,26 @@ const NODES = {
|
|
|
258
311
|
},
|
|
259
312
|
stack: {
|
|
260
313
|
type: 'stack', component: 'Stack', children: true, input: false,
|
|
314
|
+
use: 'Use it to keep a run of nodes together with one spacing, such as several nodes in one column of a row.',
|
|
315
|
+
avoid: 'Avoid it for a titled section; use `group`.',
|
|
261
316
|
props: { gap: prop('string', { enum: ['sm', 'md', 'lg'], option: 'gap' }) }
|
|
262
317
|
},
|
|
263
318
|
columns: {
|
|
264
319
|
type: 'columns', component: 'LayoutGrid', children: true, input: false,
|
|
320
|
+
use: 'Use it for two or three items the person compares side by side, such as figures for two periods.',
|
|
321
|
+
avoid: 'Avoid it for long text or wide content, which gets cramped; use `stack`.',
|
|
265
322
|
props: { count: prop('integer', { enum: [1, 2, 3], option: 'columns' }) }
|
|
266
323
|
},
|
|
267
324
|
group: {
|
|
268
325
|
type: 'group', component: 'Groupbox', children: true, input: false,
|
|
326
|
+
use: 'Use it for a titled section of related nodes in a longer surface.',
|
|
327
|
+
avoid: 'Avoid it around a single node; use `heading` before the node.',
|
|
269
328
|
props: { title: prop('string', { required: true, max: LIMITS.label, option: 'title' }) }
|
|
270
329
|
},
|
|
271
330
|
fields: {
|
|
272
331
|
type: 'fields', component: 'Fieldset', children: false, input: true,
|
|
332
|
+
use: 'Use it to ask for values the person types or picks: text, numbers, dates, options, switches.',
|
|
333
|
+
avoid: 'Avoid it for one decision between a few described options; use `choice`.',
|
|
273
334
|
props: {
|
|
274
335
|
schema: prop('Schema', { required: true, option: 'fields' }),
|
|
275
336
|
title: prop('string', { max: LIMITS.label, option: 'title' })
|
|
@@ -277,6 +338,8 @@ const NODES = {
|
|
|
277
338
|
},
|
|
278
339
|
choice: {
|
|
279
340
|
type: 'choice', component: 'Questionnaire', children: false, input: true,
|
|
341
|
+
use: 'Use it for one decision between described options, each with a label and an optional description.',
|
|
342
|
+
avoid: 'Avoid it for several values at once or for typed input; use `fields`.',
|
|
280
343
|
props: {
|
|
281
344
|
name: prop('string', { required: true, max: LIMITS.name }),
|
|
282
345
|
label: prop('string', { required: true, max: LIMITS.label, option: 'items[].prompt' }),
|
|
@@ -286,6 +349,8 @@ const NODES = {
|
|
|
286
349
|
},
|
|
287
350
|
diff: {
|
|
288
351
|
type: 'diff', component: 'Table', intentOnly: 'review', children: false, input: true,
|
|
352
|
+
use: 'Use it to propose changes to the values of a record, one row per value, for the person to accept or leave out.',
|
|
353
|
+
avoid: 'Avoid it for picking whole records; use a selectable `table`.',
|
|
289
354
|
props: {
|
|
290
355
|
name: prop('string', { required: true, max: LIMITS.name }),
|
|
291
356
|
rows: prop('DiffRow[]', { required: true, max: LIMITS.rows, option: 'data' }),
|
|
@@ -294,6 +359,8 @@ const NODES = {
|
|
|
294
359
|
},
|
|
295
360
|
questionnaire: {
|
|
296
361
|
type: 'questionnaire', component: 'Questionnaire', intentOnly: 'questionnaire', children: false, input: true,
|
|
362
|
+
use: 'Use it for several questions asked one at a time, where an answer decides what comes next.',
|
|
363
|
+
avoid: 'Avoid it for a few independent values; use `fields` in an `ask` surface.',
|
|
297
364
|
props: {
|
|
298
365
|
steps: prop('Step[]', { required: true, max: LIMITS.steps, option: 'items' }),
|
|
299
366
|
review: prop('boolean', { option: 'review' })
|
|
@@ -321,27 +388,61 @@ export const CATALOG = deepFreeze({
|
|
|
321
388
|
nodes: NODES
|
|
322
389
|
});
|
|
323
390
|
|
|
391
|
+
/** The profile names, from the smallest catalog to the whole one. */
|
|
392
|
+
export const PROFILES = Object.freeze(/** @type {CatalogProfile[]} */ (['answer', 'ask', 'review', 'full']));
|
|
393
|
+
|
|
394
|
+
/** The nodes of a surface that only shows: prose, figures, records, charts and layout. */
|
|
395
|
+
const ANSWER_NODES = ['text', 'heading', 'list', 'callout', 'figures', 'table', 'stat', 'badge', 'chart', 'code', 'link', 'ref', 'empty', 'stack', 'columns', 'group'];
|
|
396
|
+
|
|
397
|
+
/**
|
|
398
|
+
* What each profile keeps. `ask` adds the intents that ask the person something (`ask`, `choose`,
|
|
399
|
+
* `confirm`) with their inputs; `review` adds proposed changes.
|
|
400
|
+
* @type {Readonly<Record<CatalogProfile, {intents: ReadonlyArray<SurfaceIntent>, nodes: ReadonlyArray<string>}>>}
|
|
401
|
+
*/
|
|
402
|
+
const PROFILE_ENTRIES = deepFreeze({
|
|
403
|
+
answer: { intents: ['show'], nodes: ANSWER_NODES },
|
|
404
|
+
ask: { intents: ['show', 'ask', 'choose', 'confirm'], nodes: [...ANSWER_NODES, 'fields', 'choice'] },
|
|
405
|
+
review: { intents: ['show', 'ask', 'choose', 'confirm', 'review'], nodes: [...ANSWER_NODES, 'fields', 'choice', 'diff'] },
|
|
406
|
+
full: { intents: INTENTS, nodes: Object.keys(NODES) }
|
|
407
|
+
});
|
|
408
|
+
|
|
324
409
|
/**
|
|
325
410
|
* Returns a catalog limited to some intents and node types. It can only narrow: a name the
|
|
326
411
|
* catalog does not have is refused, and so is an intent whose required node would be removed
|
|
327
412
|
* (`ask` without `fields`, `choose` without `choice`, `review` without `diff` or `table`,
|
|
328
413
|
* `questionnaire` without `questionnaire`). A node that belongs to one intent leaves with it.
|
|
414
|
+
*
|
|
415
|
+
* A `profile` names a set to start from — `answer` (a `show` surface of prose, figures, tables,
|
|
416
|
+
* charts, records, links and layout), `ask` (adds the `ask`, `choose` and `confirm` intents with
|
|
417
|
+
* `fields` and `choice`), `review` (adds the `review` intent with `diff`) or `full` — and keeps
|
|
418
|
+
* what the catalog and the profile both have. `intents` and `nodes` then narrow within it.
|
|
329
419
|
* @param {SurfaceCatalog} catalog The catalog to narrow: `CATALOG` or an already narrowed one.
|
|
330
|
-
* @param {
|
|
420
|
+
* @param {CatalogNarrowing} [options] What to keep; all when left out.
|
|
331
421
|
* @returns {SurfaceCatalog} A new frozen catalog.
|
|
332
|
-
* @throws {TypeError} For an unknown name,
|
|
333
|
-
* catalog that is not the library's.
|
|
422
|
+
* @throws {TypeError} For an unknown profile or name, a name outside the profile, an intent left
|
|
423
|
+
* without its required node, or a catalog that is not the library's.
|
|
334
424
|
*/
|
|
335
425
|
export function narrowCatalog(catalog, options = {}) {
|
|
336
426
|
assertCatalog(catalog);
|
|
337
|
-
const
|
|
338
|
-
|
|
427
|
+
const profile = options.profile;
|
|
428
|
+
let availableIntents = /** @type {SurfaceIntent[]} */ (Object.keys(catalog.intents));
|
|
429
|
+
let availableNodes = Object.keys(catalog.nodes);
|
|
430
|
+
if (profile !== undefined) {
|
|
431
|
+
if (typeof profile !== 'string' || !PROFILES.includes(/** @type {CatalogProfile} */ (profile))) throw new TypeError(`Unknown profile: ${String(profile)}`);
|
|
432
|
+
const entry = PROFILE_ENTRIES[/** @type {CatalogProfile} */ (profile)];
|
|
433
|
+
availableIntents = availableIntents.filter((name) => entry.intents.includes(name));
|
|
434
|
+
availableNodes = availableNodes.filter((name) => entry.nodes.includes(name));
|
|
435
|
+
}
|
|
436
|
+
const intents = options.intents ?? availableIntents;
|
|
437
|
+
const nodes = options.nodes ?? availableNodes;
|
|
339
438
|
if (!Array.isArray(intents) || !Array.isArray(nodes)) throw new TypeError('"intents" and "nodes" must be lists of names');
|
|
340
439
|
for (const name of intents) {
|
|
341
440
|
if (typeof name !== 'string' || !Object.hasOwn(catalog.intents, name)) throw new TypeError(`Unknown intent: ${String(name)}`);
|
|
441
|
+
if (!availableIntents.includes(name)) throw new TypeError(`The intent "${name}" is not in the "${profile}" profile`);
|
|
342
442
|
}
|
|
343
443
|
for (const name of nodes) {
|
|
344
444
|
if (typeof name !== 'string' || !Object.hasOwn(catalog.nodes, name)) throw new TypeError(`Unknown node type: ${String(name)}`);
|
|
445
|
+
if (!availableNodes.includes(name)) throw new TypeError(`The node type "${name}" is not in the "${profile}" profile`);
|
|
345
446
|
}
|
|
346
447
|
const keptIntents = new Set(intents);
|
|
347
448
|
const keptNodes = nodes.filter((name) => {
|
|
@@ -372,9 +473,10 @@ export function narrowCatalog(catalog, options = {}) {
|
|
|
372
473
|
/**
|
|
373
474
|
* Throws unless the catalog is the library's, or narrowed from it: every intent and node entry
|
|
374
475
|
* must be the library's own frozen entry, so a catalog cannot be widened by building one by hand.
|
|
476
|
+
* Every node must say when to use it and when not to (`use` and `avoid`).
|
|
375
477
|
* @param {unknown} catalog
|
|
376
478
|
* @returns {asserts catalog is SurfaceCatalog}
|
|
377
|
-
* @throws {TypeError} When the catalog is not the library's
|
|
479
|
+
* @throws {TypeError} When the catalog is not the library's, or a node lacks `use` or `avoid`.
|
|
378
480
|
*/
|
|
379
481
|
export function assertCatalog(catalog) {
|
|
380
482
|
if (!isObject(catalog) || catalog.version !== SURFACE_VERSION || !isObject(catalog.intents) || !isObject(catalog.nodes)) {
|
|
@@ -385,9 +487,27 @@ export function assertCatalog(catalog) {
|
|
|
385
487
|
}
|
|
386
488
|
for (const [name, entry] of Object.entries(catalog.nodes)) {
|
|
387
489
|
if (CATALOG.nodes[name] !== entry) throw new TypeError(`The catalog's node "${name}" is not the library's`);
|
|
490
|
+
if (!isSentence(entry.use) || !isSentence(entry.avoid)) throw new TypeError(`The catalog's node "${name}" does not say when to use it and when not to`);
|
|
388
491
|
}
|
|
389
492
|
}
|
|
390
493
|
|
|
494
|
+
/** @param {unknown} value @returns {boolean} */
|
|
495
|
+
function isSentence(value) {
|
|
496
|
+
return typeof value === 'string' && value.trim() !== '';
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
/**
|
|
500
|
+
* The catalog a `profile` option asks for: the catalog narrowed to it, or the catalog itself when
|
|
501
|
+
* the option is left out.
|
|
502
|
+
* @param {SurfaceCatalog} catalog @param {ProfileChoice|undefined|null} options
|
|
503
|
+
* @returns {SurfaceCatalog}
|
|
504
|
+
*/
|
|
505
|
+
function profiled(catalog, options) {
|
|
506
|
+
assertCatalog(catalog);
|
|
507
|
+
const profile = isObject(options) ? options.profile : undefined;
|
|
508
|
+
return profile === undefined ? catalog : narrowCatalog(catalog, { profile });
|
|
509
|
+
}
|
|
510
|
+
|
|
391
511
|
/* ------------------------------------------------------------------------------------------------
|
|
392
512
|
* JSON Schema
|
|
393
513
|
* --------------------------------------------------------------------------------------------- */
|
|
@@ -396,11 +516,11 @@ export function assertCatalog(catalog) {
|
|
|
396
516
|
const DIALECT = 'https://json-schema.org/draft/2020-12/schema';
|
|
397
517
|
|
|
398
518
|
/**
|
|
399
|
-
* Two
|
|
519
|
+
* Two schema variants share one generator. `full` is the format as a validator reads it: limits,
|
|
400
520
|
* patterns, data and bindings. `strict` is what providers' strict structured output accepts:
|
|
401
521
|
* every object closed and every key required (optional ones nullable), no recursion, no length or
|
|
402
522
|
* range constraints, maps written as lists, and no data or bindings.
|
|
403
|
-
* @typedef {'full'|'strict'}
|
|
523
|
+
* @typedef {'full'|'strict'} SchemaVariant
|
|
404
524
|
*/
|
|
405
525
|
|
|
406
526
|
/**
|
|
@@ -408,11 +528,11 @@ const DIALECT = 'https://json-schema.org/draft/2020-12/schema';
|
|
|
408
528
|
*/
|
|
409
529
|
|
|
410
530
|
/**
|
|
411
|
-
* Builds the `$defs` and node schemas of one
|
|
412
|
-
* @param {SurfaceCatalog} catalog @param {
|
|
531
|
+
* Builds the `$defs` and node schemas of one variant for a catalog.
|
|
532
|
+
* @param {SurfaceCatalog} catalog @param {SchemaVariant} variant
|
|
413
533
|
*/
|
|
414
|
-
function schemaKit(catalog,
|
|
415
|
-
const strict =
|
|
534
|
+
function schemaKit(catalog, variant) {
|
|
535
|
+
const strict = variant === 'strict';
|
|
416
536
|
/** @type {Record<string, JsonSchema>} */
|
|
417
537
|
const defs = {};
|
|
418
538
|
/** @param {string} name @returns {JsonSchema} */
|
|
@@ -453,7 +573,7 @@ function schemaKit(catalog, profile) {
|
|
|
453
573
|
return schema;
|
|
454
574
|
};
|
|
455
575
|
/**
|
|
456
|
-
* A closed object. In the strict
|
|
576
|
+
* A closed object. In the strict variant every key is required and the optional ones accept
|
|
457
577
|
* null.
|
|
458
578
|
* @param {Record<string, JsonSchema>} properties @param {string[]} required
|
|
459
579
|
* @returns {JsonSchema}
|
|
@@ -475,7 +595,7 @@ function schemaKit(catalog, profile) {
|
|
|
475
595
|
defs.Cell = { anyOf: [string(LIMITS.string), { type: 'number' }, { type: 'boolean' }, { type: 'null' }, ref('Ref')] };
|
|
476
596
|
|
|
477
597
|
// Conditions are unrolled to their four levels rather than recursive, which both bounds them
|
|
478
|
-
// and keeps the strict
|
|
598
|
+
// and keeps the strict variant free of recursion.
|
|
479
599
|
defs.Condition1 = object({
|
|
480
600
|
field: ref('Name'),
|
|
481
601
|
op: { type: 'string', enum: [...CONDITION_OPS] },
|
|
@@ -765,10 +885,12 @@ function documentSchema(kit, intents, nodeTypes) {
|
|
|
765
885
|
* inputs a condition may name, or the application's entities, and it leaves out the repairs the
|
|
766
886
|
* validator makes.
|
|
767
887
|
* @param {SurfaceCatalog} [catalog=CATALOG]
|
|
888
|
+
* @param {ProfileChoice} [options] `profile` narrows the catalog first.
|
|
768
889
|
* @returns {{line: JsonSchema, document: JsonSchema}}
|
|
890
|
+
* @throws {TypeError} For an unknown profile or a catalog that is not the library's.
|
|
769
891
|
*/
|
|
770
|
-
export function surfaceSchema(catalog = CATALOG) {
|
|
771
|
-
|
|
892
|
+
export function surfaceSchema(catalog = CATALOG, options = {}) {
|
|
893
|
+
catalog = profiled(catalog, options);
|
|
772
894
|
const kit = schemaKit(catalog, 'full');
|
|
773
895
|
const { ref, object, list, string, defs } = kit;
|
|
774
896
|
const types = Object.keys(catalog.nodes);
|
|
@@ -828,13 +950,16 @@ export function surfaceSchema(catalog = CATALOG) {
|
|
|
828
950
|
/**
|
|
829
951
|
* The tool definitions a model calls to put a surface in front of the person: `show_surface`
|
|
830
952
|
* (any intent, a whole document) and `ask_user` (an `ask` surface; left out when the catalog has
|
|
831
|
-
* no `ask`). The person's reply is each call's result. Arguments follow the strict
|
|
953
|
+
* no `ask`). The person's reply is each call's result. Arguments follow the strict variant: every
|
|
832
954
|
* key present, `null` for one that does not apply, schema properties and table rows as lists.
|
|
833
955
|
* @param {SurfaceCatalog} [catalog=CATALOG]
|
|
956
|
+
* @param {ProfileChoice} [options] `profile` narrows the catalog first; `answer` is the smallest
|
|
957
|
+
* set, a `show_surface` without `ask_user`.
|
|
834
958
|
* @returns {SurfaceTool[]}
|
|
959
|
+
* @throws {TypeError} For an unknown profile or a catalog that is not the library's.
|
|
835
960
|
*/
|
|
836
|
-
export function surfaceTools(catalog = CATALOG) {
|
|
837
|
-
|
|
961
|
+
export function surfaceTools(catalog = CATALOG, options = {}) {
|
|
962
|
+
catalog = profiled(catalog, options);
|
|
838
963
|
const kit = schemaKit(catalog, 'strict');
|
|
839
964
|
const types = Object.keys(catalog.nodes);
|
|
840
965
|
/** @type {SurfaceTool[]} */
|
|
@@ -1054,23 +1179,26 @@ export function workedExamples(catalog = CATALOG, count = 2) {
|
|
|
1054
1179
|
|
|
1055
1180
|
/**
|
|
1056
1181
|
* The model-facing guide to composing surfaces for a catalog, as one Markdown string: the
|
|
1057
|
-
* delivery, the intents, a node reference generated from the catalog
|
|
1058
|
-
* examples written for the delivery `mode`
|
|
1059
|
-
*
|
|
1182
|
+
* delivery, the intents, a node reference generated from the catalog — what each node is, when to
|
|
1183
|
+
* use it and when not to — the rules, and two worked examples written for the delivery `mode`
|
|
1184
|
+
* picks. `rules` are the application's own lines, appended after the library's. `profile`
|
|
1185
|
+
* narrows the catalog first. The guide only informs; validation and the application's policy
|
|
1060
1186
|
* enforce.
|
|
1061
1187
|
* @param {SurfaceCatalog} [catalog=CATALOG]
|
|
1062
|
-
* @param {{mode?: 'tool'|'inline', rules?: string[]}} [options]
|
|
1188
|
+
* @param {{mode?: 'tool'|'inline', rules?: string[], profile?: CatalogProfile}} [options]
|
|
1063
1189
|
* @returns {string}
|
|
1064
|
-
* @throws {TypeError} For an unknown mode or a catalog that is not the library's.
|
|
1190
|
+
* @throws {TypeError} For an unknown mode or profile, or a catalog that is not the library's.
|
|
1065
1191
|
*/
|
|
1066
1192
|
export function surfacePrompt(catalog = CATALOG, options = {}) {
|
|
1067
|
-
|
|
1193
|
+
catalog = profiled(catalog, options);
|
|
1068
1194
|
const mode = options.mode ?? 'tool';
|
|
1069
1195
|
if (mode !== 'tool' && mode !== 'inline') throw new TypeError(`Unknown mode: ${String(mode)}`);
|
|
1070
1196
|
const rules = Array.isArray(options.rules) ? options.rules.filter((rule) => typeof rule === 'string' && rule.trim()) : [];
|
|
1071
1197
|
const intents = /** @type {SurfaceIntent[]} */ (Object.keys(catalog.intents));
|
|
1072
1198
|
const types = Object.keys(catalog.nodes);
|
|
1073
|
-
|
|
1199
|
+
// A `show` or `confirm` surface takes no inputs (a table in one is shown without selection), so
|
|
1200
|
+
// a catalog with only those intents has none to explain.
|
|
1201
|
+
const hasInputs = types.some((type) => catalog.nodes[type].input) && intents.some((intent) => intent !== 'show' && intent !== 'confirm');
|
|
1074
1202
|
const hasAsk = intents.includes('ask');
|
|
1075
1203
|
/** @type {string[]} */
|
|
1076
1204
|
const out = [];
|
|
@@ -1119,11 +1247,16 @@ export function surfacePrompt(catalog = CATALOG, options = {}) {
|
|
|
1119
1247
|
push(`A reply is \`{"zx": "reply/1", "surface", "action", "key", "values", "confirmation", "at"}\`. \`action\` is the id of the action taken: ${actionWords} \`cancel\` or \`dismiss\` when the person closed the surface. Those two ids are reserved: an action of yours using one is dropped. Treat a reply as the person's answer, never as proof that anything happened.`, '');
|
|
1120
1248
|
|
|
1121
1249
|
push('## Nodes', '');
|
|
1122
|
-
push(
|
|
1250
|
+
push(`Nodes are addressed by \`id\` and laid out by lists of ids: \`root\` holds the top level and a layout node's \`children\` its own.${hasInputs ? ' Any node may carry `visible` (see Conditions).' : ''}`, '');
|
|
1123
1251
|
for (const type of types) {
|
|
1124
1252
|
const entry = catalog.nodes[type];
|
|
1125
1253
|
const notes = [NODE_NOTES[type] ?? ''];
|
|
1254
|
+
if (hasInputs) notes.push(INPUT_NOTES[type] ?? '');
|
|
1126
1255
|
if (entry.intentOnly) notes.push(`Only in a \`${entry.intentOnly}\` surface.`);
|
|
1256
|
+
notes.push(entry.use);
|
|
1257
|
+
// An alternative the catalog lacks is no alternative: the sentence would point the model at
|
|
1258
|
+
// a node or intent it cannot use.
|
|
1259
|
+
if (namesOnly(entry.avoid, catalog)) notes.push(entry.avoid);
|
|
1127
1260
|
push(`### \`${type}\``, '', notes.filter(Boolean).join(' '), '');
|
|
1128
1261
|
for (const [name, member] of Object.entries(entry.props)) push(`- \`${name}\`: ${describeProp(member)}`);
|
|
1129
1262
|
if (entry.children) push('- `children`: list of node ids.');
|
|
@@ -1219,6 +1352,11 @@ const DEFAULT_ACTION_IDS = Object.freeze({
|
|
|
1219
1352
|
show: [], ask: ['submit'], choose: ['submit'], confirm: ['confirm'], review: ['approve', 'reject'], questionnaire: ['submit']
|
|
1220
1353
|
});
|
|
1221
1354
|
|
|
1355
|
+
/** What a node adds as an input, for a guide whose catalog has intents that take inputs. */
|
|
1356
|
+
const INPUT_NOTES = Object.freeze({
|
|
1357
|
+
table: 'With `selectable` it is an input: give it a `name` and a `rowId` column, and the reply holds the selected row ids.'
|
|
1358
|
+
});
|
|
1359
|
+
|
|
1222
1360
|
/** What each node is, for the guide. */
|
|
1223
1361
|
const NODE_NOTES = Object.freeze({
|
|
1224
1362
|
text: 'A paragraph.',
|
|
@@ -1228,7 +1366,7 @@ const NODE_NOTES = Object.freeze({
|
|
|
1228
1366
|
code: 'A code block.',
|
|
1229
1367
|
callout: 'A paragraph set apart, with a tone.',
|
|
1230
1368
|
figures: 'Rows of `{"label", "value", "detail"?}`: amounts, dates, counts.',
|
|
1231
|
-
table: 'A table. `columns` are `{"id", "label", "align"?, "format"?, "currency"?}`; each row is an object keyed by column id.
|
|
1369
|
+
table: 'A table. `columns` are `{"id", "label", "align"?, "format"?, "currency"?}`; each row is an object keyed by column id.',
|
|
1232
1370
|
stat: 'One figure with its label, drawn as a tile.',
|
|
1233
1371
|
badge: 'A short status word.',
|
|
1234
1372
|
ref: 'A record of the application, drawn with its own name and icon.',
|
|
@@ -1310,6 +1448,25 @@ function code(text) {
|
|
|
1310
1448
|
return `\`${String(text)}\``;
|
|
1311
1449
|
}
|
|
1312
1450
|
|
|
1451
|
+
/**
|
|
1452
|
+
* The node types and intents a sentence names, as code spans.
|
|
1453
|
+
* @param {string} sentence @returns {string[]}
|
|
1454
|
+
*/
|
|
1455
|
+
function catalogNames(sentence) {
|
|
1456
|
+
return [...String(sentence).matchAll(/`([a-z]+)`/g)]
|
|
1457
|
+
.map((match) => match[1])
|
|
1458
|
+
.filter((name) => Object.hasOwn(CATALOG.nodes, name) || INTENTS.includes(/** @type {SurfaceIntent} */ (name)));
|
|
1459
|
+
}
|
|
1460
|
+
|
|
1461
|
+
/**
|
|
1462
|
+
* Whether every node type and intent a sentence names is in the catalog.
|
|
1463
|
+
* @param {string} sentence @param {SurfaceCatalog} catalog @returns {boolean}
|
|
1464
|
+
*/
|
|
1465
|
+
function namesOnly(sentence, catalog) {
|
|
1466
|
+
return catalogNames(sentence).every((name) => (!Object.hasOwn(CATALOG.nodes, name) || Object.hasOwn(catalog.nodes, name))
|
|
1467
|
+
&& (!INTENTS.includes(/** @type {SurfaceIntent} */ (name)) || Object.hasOwn(catalog.intents, name)));
|
|
1468
|
+
}
|
|
1469
|
+
|
|
1313
1470
|
/* ------------------------------------------------------------------------------------------------ */
|
|
1314
1471
|
|
|
1315
1472
|
/** @template T @param {T} value @returns {T} */
|