@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.
Files changed (330) hide show
  1. package/CHANGELOG.md +330 -0
  2. package/README.md +47 -9
  3. package/dist/types/components/activity-item/activity-item.d.ts +14 -3
  4. package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
  5. package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
  9. package/dist/types/components/approval-card/approval-card.d.ts +31 -2
  10. package/dist/types/components/aurora/aurora.d.ts +31 -5
  11. package/dist/types/components/calendar/calendar.d.ts +39 -26
  12. package/dist/types/components/chart/chart.d.ts +250 -20
  13. package/dist/types/components/chart/color.d.ts +66 -0
  14. package/dist/types/components/chart/svg-adapter.d.ts +103 -0
  15. package/dist/types/components/chart/svg-geometry.d.ts +203 -0
  16. package/dist/types/components/check-button/check-button.d.ts +1 -4
  17. package/dist/types/components/checklist/checklist.d.ts +48 -5
  18. package/dist/types/components/code-editor/code-editor.d.ts +55 -1
  19. package/dist/types/components/composer/composer.d.ts +41 -6
  20. package/dist/types/components/context-menu/context-menu.d.ts +36 -8
  21. package/dist/types/components/copy/copy-button.d.ts +6 -0
  22. package/dist/types/components/copy/copy-input.d.ts +1 -0
  23. package/dist/types/components/date-picker/date-picker.d.ts +14 -0
  24. package/dist/types/components/date-picker/time-picker.d.ts +26 -17
  25. package/dist/types/components/datebox/datebox.d.ts +8 -4
  26. package/dist/types/components/dialog/dialog.d.ts +15 -4
  27. package/dist/types/components/empty-state/empty-state.d.ts +10 -1
  28. package/dist/types/components/field/field.d.ts +4 -2
  29. package/dist/types/components/form/form.d.ts +2 -1
  30. package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
  32. package/dist/types/components/launcher/launcher.d.ts +26 -0
  33. package/dist/types/components/master-panel/master-panel.d.ts +9 -4
  34. package/dist/types/components/menu-button/menu-button.d.ts +29 -5
  35. package/dist/types/components/message/message.d.ts +308 -5
  36. package/dist/types/components/modal/modal.d.ts +45 -8
  37. package/dist/types/components/modal/native-dialog.d.ts +40 -0
  38. package/dist/types/components/module-bar/module-bar.d.ts +9 -2
  39. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
  40. package/dist/types/components/number-field/number-field.d.ts +31 -1
  41. package/dist/types/components/pagination/pagination.d.ts +341 -19
  42. package/dist/types/components/run-status/run-status.d.ts +26 -0
  43. package/dist/types/components/run-trace/run-trace.d.ts +10 -6
  44. package/dist/types/components/search/search.d.ts +16 -4
  45. package/dist/types/components/select/select.d.ts +19 -1
  46. package/dist/types/components/sheet/sheet.d.ts +20 -6
  47. package/dist/types/components/slider/slider.d.ts +2 -1
  48. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
  49. package/dist/types/components/stepper/stepper.d.ts +17 -4
  50. package/dist/types/components/surface/catalog.d.ts +61 -17
  51. package/dist/types/components/surface/surface.d.ts +6 -4
  52. package/dist/types/components/table/table.d.ts +207 -5
  53. package/dist/types/components/table/window.d.ts +25 -1
  54. package/dist/types/components/toggle/toggle.d.ts +38 -6
  55. package/dist/types/components/tooltip/tooltip.d.ts +5 -4
  56. package/dist/types/components/tree/tree.d.ts +43 -6
  57. package/dist/types/components/truncate/truncate.d.ts +4 -2
  58. package/dist/types/components/value-list/value-list.d.ts +9 -2
  59. package/dist/types/core/date.d.ts +2 -1
  60. package/dist/types/core/dom.d.ts +14 -0
  61. package/dist/types/core/drag-axis.d.ts +10 -5
  62. package/dist/types/core/export.d.ts +2 -2
  63. package/dist/types/core/format.d.ts +3 -1
  64. package/dist/types/core/icons.d.ts +36 -3
  65. package/dist/types/core/keyboard.d.ts +7 -3
  66. package/dist/types/core/messages.d.ts +3 -0
  67. package/dist/types/core/storage.d.ts +4 -3
  68. package/dist/types/core/util.d.ts +3 -1
  69. package/dist/types/elements/define.d.ts +5 -2
  70. package/dist/types/index.d.ts +6 -4
  71. package/dist/types/internal/agent-model.d.ts +99 -0
  72. package/dist/types/internal/app-rail.d.ts +37 -2
  73. package/dist/types/internal/collections.d.ts +18 -0
  74. package/dist/types/internal/menu-items.d.ts +27 -0
  75. package/dist/types/internal/overlay-content.d.ts +23 -0
  76. package/dist/types/internal/presence-loop.d.ts +5 -2
  77. package/dist/types/locales/index.d.ts +3 -0
  78. package/dist/types/zeyos/calendar.d.ts +43 -7
  79. package/dist/types/zeyos/connect.d.ts +4 -0
  80. package/dist/types/zeyos/form.d.ts +13 -5
  81. package/dist/types/zeyos/select.d.ts +5 -2
  82. package/dist/types/zeyos/table.d.ts +16 -8
  83. package/dist/types/zeyos/view.d.ts +2 -1
  84. package/dist/zx-zeyos.esm.js +3161 -515
  85. package/dist/zx-zeyos.esm.min.js +4 -4
  86. package/dist/zx.core.css +4 -0
  87. package/dist/zx.core.min.css +1 -1
  88. package/dist/zx.css +970 -57
  89. package/dist/zx.esm.js +6405 -2249
  90. package/dist/zx.esm.min.js +26 -26
  91. package/dist/zx.global.js +6405 -2249
  92. package/dist/zx.global.min.js +26 -26
  93. package/dist/zx.layered.css +972 -57
  94. package/dist/zx.layered.min.css +1 -1
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +159 -1
  97. package/docs/agent-surfaces.md +21 -21
  98. package/docs/api.json +3154 -518
  99. package/docs/components/account-menu.md +24 -0
  100. package/docs/components/activity-item.md +23 -0
  101. package/docs/components/activity-list.md +28 -0
  102. package/docs/components/agent-avatar.md +59 -0
  103. package/docs/components/agent-thread.md +275 -0
  104. package/docs/components/app-icon.md +36 -0
  105. package/docs/components/app-sidebar.md +92 -0
  106. package/docs/components/approval-card.md +71 -0
  107. package/docs/components/aurora.md +34 -0
  108. package/docs/components/avatar.md +37 -0
  109. package/docs/components/badge.md +36 -0
  110. package/docs/components/block-view.md +34 -0
  111. package/docs/components/breadcrumb.md +20 -0
  112. package/docs/components/button.md +23 -0
  113. package/docs/components/calendar.md +68 -0
  114. package/docs/components/card-view.md +73 -0
  115. package/docs/components/card.md +25 -0
  116. package/docs/components/chart.md +109 -0
  117. package/docs/components/check-button.md +16 -0
  118. package/docs/components/checklist.md +19 -0
  119. package/docs/components/code-editor.md +38 -0
  120. package/docs/components/composer.md +107 -0
  121. package/docs/components/context-menu.md +32 -0
  122. package/docs/components/copy.md +37 -0
  123. package/docs/components/data-filter.md +16 -0
  124. package/docs/components/date-picker.md +31 -0
  125. package/docs/components/date-range.md +21 -0
  126. package/docs/components/datebox.md +31 -0
  127. package/docs/components/dialog.md +25 -0
  128. package/docs/components/dock.md +57 -0
  129. package/docs/components/dropdown.md +39 -0
  130. package/docs/components/elements.md +63 -0
  131. package/docs/components/empty-state.md +17 -0
  132. package/docs/components/entity-ref.md +26 -0
  133. package/docs/components/field-upload.md +18 -0
  134. package/docs/components/file-item.md +27 -0
  135. package/docs/components/file-list.md +23 -0
  136. package/docs/components/filter-panel.md +45 -0
  137. package/docs/components/filter.md +47 -0
  138. package/docs/components/finder.md +25 -0
  139. package/docs/components/form-widgets.md +42 -0
  140. package/docs/components/form.md +80 -0
  141. package/docs/components/grid.md +26 -0
  142. package/docs/components/groupbox.md +11 -0
  143. package/docs/components/helpers.md +359 -0
  144. package/docs/components/icons.md +87 -0
  145. package/docs/components/index.md +99 -0
  146. package/docs/components/kanban-view.md +42 -0
  147. package/docs/components/kbd.md +23 -0
  148. package/docs/components/kernel.md +41 -0
  149. package/docs/components/launcher.md +66 -0
  150. package/docs/components/layout.md +33 -0
  151. package/docs/components/list-toolbar.md +38 -0
  152. package/docs/components/loading.md +48 -0
  153. package/docs/components/menu-button.md +47 -0
  154. package/docs/components/message.md +76 -0
  155. package/docs/components/modal.md +27 -0
  156. package/docs/components/module-bar.md +71 -0
  157. package/docs/components/multi-value-editor.md +16 -0
  158. package/docs/components/navigation-bar.md +22 -0
  159. package/docs/components/number-field.md +34 -0
  160. package/docs/components/pagination.md +73 -0
  161. package/docs/components/panel.md +28 -0
  162. package/docs/components/prompt-starters.md +40 -0
  163. package/docs/components/prose.md +38 -0
  164. package/docs/components/questionnaire.md +115 -0
  165. package/docs/components/rating.md +19 -0
  166. package/docs/components/run-status.md +50 -0
  167. package/docs/components/run-trace.md +72 -0
  168. package/docs/components/search.md +11 -0
  169. package/docs/components/select.md +129 -0
  170. package/docs/components/sheet-stack.md +39 -0
  171. package/docs/components/sheet.md +77 -0
  172. package/docs/components/skeleton.md +27 -0
  173. package/docs/components/slider.md +29 -0
  174. package/docs/components/sort-control.md +21 -0
  175. package/docs/components/source-list.md +30 -0
  176. package/docs/components/split-view.md +12 -0
  177. package/docs/components/stat-tile.md +49 -0
  178. package/docs/components/stepper.md +27 -0
  179. package/docs/components/surface.md +152 -0
  180. package/docs/components/tabbox.md +33 -0
  181. package/docs/components/table-view.md +43 -0
  182. package/docs/components/table.md +232 -0
  183. package/docs/components/tag-picker.md +39 -0
  184. package/docs/components/timebox.md +16 -0
  185. package/docs/components/toggle.md +21 -0
  186. package/docs/components/tokens.md +82 -0
  187. package/docs/components/toolbar.md +26 -0
  188. package/docs/components/tooltip.md +16 -0
  189. package/docs/components/tree.md +48 -0
  190. package/docs/components/truncate.md +21 -0
  191. package/docs/components/value-list.md +14 -0
  192. package/docs/components/view-settings.md +56 -0
  193. package/docs/components/workspace-switcher.md +42 -0
  194. package/docs/components/zeyos.md +196 -0
  195. package/docs/llms-small.txt +299 -0
  196. package/docs/llms.md +725 -109
  197. package/docs/llms.txt +46 -19
  198. package/package.json +9 -4
  199. package/src/components/activity-item/activity-item.js +21 -2
  200. package/src/components/agent-avatar/agent-avatar.css +195 -0
  201. package/src/components/agent-avatar/agent-avatar.js +333 -0
  202. package/src/components/agent-avatar/agent-face.js +292 -0
  203. package/src/components/agent-thread/ag-ui.js +44 -11
  204. package/src/components/agent-thread/agent-thread.js +103 -11
  205. package/src/components/agent-thread/ui-message-stream.js +3 -1
  206. package/src/components/app-rail/app-rail.css +5 -0
  207. package/src/components/app-sidebar/app-sidebar.css +3 -0
  208. package/src/components/app-sidebar/app-sidebar.js +4 -3
  209. package/src/components/approval-card/approval-card.css +6 -0
  210. package/src/components/approval-card/approval-card.js +55 -7
  211. package/src/components/aurora/aurora.css +149 -14
  212. package/src/components/aurora/aurora.js +49 -6
  213. package/src/components/button/button.css +24 -11
  214. package/src/components/calendar/calendar.css +6 -2
  215. package/src/components/calendar/calendar.js +127 -47
  216. package/src/components/card-view/card-view.js +5 -6
  217. package/src/components/chart/chart.css +159 -1
  218. package/src/components/chart/chart.js +450 -62
  219. package/src/components/chart/color.js +297 -0
  220. package/src/components/chart/svg-adapter.js +576 -0
  221. package/src/components/chart/svg-geometry.js +323 -0
  222. package/src/components/check-button/check-button.js +3 -18
  223. package/src/components/checklist/checklist.css +9 -1
  224. package/src/components/checklist/checklist.js +105 -20
  225. package/src/components/checklist/field-adapter.js +6 -12
  226. package/src/components/code-editor/code-editor.css +33 -0
  227. package/src/components/code-editor/code-editor.js +97 -8
  228. package/src/components/code-editor/field-adapter.js +3 -0
  229. package/src/components/composer/composer.css +3 -0
  230. package/src/components/composer/composer.js +100 -22
  231. package/src/components/context-menu/context-menu.js +41 -5
  232. package/src/components/copy/copy-button.js +9 -1
  233. package/src/components/copy/copy-input.js +5 -0
  234. package/src/components/data-filter/filter-core.js +0 -1
  235. package/src/components/date-picker/date-picker.css +8 -0
  236. package/src/components/date-picker/date-picker.js +47 -8
  237. package/src/components/date-picker/date-range-picker.js +1 -1
  238. package/src/components/date-picker/month-picker.js +19 -3
  239. package/src/components/date-picker/time-picker.js +54 -19
  240. package/src/components/datebox/date-range-box.js +7 -3
  241. package/src/components/datebox/datebox.js +32 -6
  242. package/src/components/dialog/dialog.css +6 -0
  243. package/src/components/dialog/dialog.js +24 -33
  244. package/src/components/dropdown/dropdown.js +1 -18
  245. package/src/components/empty-state/empty-state.js +21 -2
  246. package/src/components/field/field.js +19 -3
  247. package/src/components/fieldset/fieldset.js +3 -1
  248. package/src/components/filter/filter.js +9 -0
  249. package/src/components/form/form.js +19 -2
  250. package/src/components/kanban-view/kanban-card.js +15 -2
  251. package/src/components/kanban-view/kanban-view.css +21 -0
  252. package/src/components/kanban-view/kanban-view.js +29 -16
  253. package/src/components/launcher/launcher.css +14 -0
  254. package/src/components/launcher/launcher.js +54 -9
  255. package/src/components/master-panel/master-panel.js +24 -22
  256. package/src/components/menu-button/menu-button.js +26 -4
  257. package/src/components/message/message.css +228 -29
  258. package/src/components/message/message.js +664 -30
  259. package/src/components/modal/modal.js +129 -30
  260. package/src/components/modal/native-dialog.js +91 -0
  261. package/src/components/module-bar/module-bar.css +3 -0
  262. package/src/components/module-bar/module-bar.js +17 -4
  263. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  264. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  265. package/src/components/navigation-bar/navigation-bar.js +13 -1
  266. package/src/components/number-field/field-adapter.js +3 -0
  267. package/src/components/number-field/number-field.js +70 -16
  268. package/src/components/pagination/pagination.css +26 -2
  269. package/src/components/pagination/pagination.js +551 -65
  270. package/src/components/prose/prose.js +7 -1
  271. package/src/components/rating/field-adapter.js +3 -0
  272. package/src/components/run-status/run-status.js +43 -3
  273. package/src/components/run-trace/run-trace.js +15 -7
  274. package/src/components/search/search.js +3 -18
  275. package/src/components/select/field-adapter.js +8 -1
  276. package/src/components/select/select.js +68 -13
  277. package/src/components/sheet/sheet.js +39 -13
  278. package/src/components/slider/field-adapter.js +3 -0
  279. package/src/components/slider/slider.js +4 -6
  280. package/src/components/stat-tile/stat-tile.js +24 -9
  281. package/src/components/stepper/stepper.css +15 -0
  282. package/src/components/stepper/stepper.js +34 -2
  283. package/src/components/surface/catalog.js +185 -28
  284. package/src/components/surface/surface.js +10 -5
  285. package/src/components/tabbox/tabbox.js +13 -1
  286. package/src/components/table/table.css +160 -2
  287. package/src/components/table/table.js +479 -52
  288. package/src/components/table/window.js +46 -4
  289. package/src/components/table-view/table-view.js +1 -10
  290. package/src/components/tag-picker/field-adapter.js +3 -0
  291. package/src/components/tag-picker/tag-picker.js +2 -0
  292. package/src/components/timebox/field-adapter.js +3 -0
  293. package/src/components/toggle/toggle.js +51 -27
  294. package/src/components/tooltip/tooltip.js +21 -14
  295. package/src/components/tree/tree.js +87 -14
  296. package/src/components/truncate/truncate.js +21 -5
  297. package/src/components/value-list/value-list.js +37 -9
  298. package/src/components/view-settings/view-settings.js +1 -5
  299. package/src/core/component.js +34 -2
  300. package/src/core/date.js +5 -4
  301. package/src/core/dom.js +45 -2
  302. package/src/core/drag-axis.js +24 -7
  303. package/src/core/export.js +4 -4
  304. package/src/core/fontawesome.js +34 -3
  305. package/src/core/format.js +3 -1
  306. package/src/core/http.js +23 -11
  307. package/src/core/icons.js +60 -8
  308. package/src/core/keyboard.js +83 -9
  309. package/src/core/messages.js +3 -0
  310. package/src/core/position.js +4 -3
  311. package/src/core/storage.js +80 -31
  312. package/src/core/util.js +16 -5
  313. package/src/elements/define.js +82 -47
  314. package/src/elements/kit.js +46 -35
  315. package/src/index.js +8 -4
  316. package/src/internal/agent-model.js +152 -0
  317. package/src/internal/app-rail.js +53 -2
  318. package/src/internal/collections.js +25 -0
  319. package/src/internal/menu-items.js +59 -0
  320. package/src/internal/overlay-content.js +35 -0
  321. package/src/internal/presence-loop.js +61 -14
  322. package/src/locales/de.js +3 -0
  323. package/src/zeyos/calendar.js +81 -19
  324. package/src/zeyos/connect.js +5 -1
  325. package/src/zeyos/form.js +29 -10
  326. package/src/zeyos/select.js +36 -12
  327. package/src/zeyos/table.js +43 -11
  328. package/src/zeyos/view.js +2 -1
  329. package/styles/tokens/semantic.css +7 -1
  330. 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 `onclick`
66
- * sets this implicitly; set it directly to subscribe with `on('click', …)` instead.
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. It is the tile's `click` event, as
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
- if (options.clickable === true || typeof options.onclick === 'function') return 'button';
329
- return 'div';
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 {{intents?: SurfaceIntent[], nodes?: string[]}} [options] What to keep; all when left out.
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, an intent left without its required node, or a
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 intents = options.intents ?? /** @type {SurfaceIntent[]} */ (Object.keys(catalog.intents));
338
- const nodes = options.nodes ?? Object.keys(catalog.nodes);
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 profiles share one generator. `full` is the format as a validator reads it: limits,
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'} Profile
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 profile for a catalog.
412
- * @param {SurfaceCatalog} catalog @param {Profile} profile
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, profile) {
415
- const strict = profile === '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 profile every key is required and the optional ones accept
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 profile free of recursion.
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
- assertCatalog(catalog);
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 profile: every
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
- assertCatalog(catalog);
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, the rules, and two worked
1058
- * examples written for the delivery `mode` picks. `rules` are the application's own lines,
1059
- * appended after the library's. The guide only informs; validation and the application's policy
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
- assertCatalog(catalog);
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
- const hasInputs = types.some((type) => catalog.nodes[type].input);
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('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. Any node may carry `visible` (see Conditions).', '');
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. With `selectable` it is an input: give it a `name` and a `rowId` column, and the reply holds the selected row ids.',
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} */