@zeyos/zx 5.7.1 → 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 (326) hide show
  1. package/CHANGELOG.md +296 -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 +19 -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 +13 -2
  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 +11 -0
  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 +7 -0
  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 +18 -4
  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/drag-axis.d.ts +10 -5
  61. package/dist/types/core/export.d.ts +2 -2
  62. package/dist/types/core/format.d.ts +3 -1
  63. package/dist/types/core/icons.d.ts +36 -3
  64. package/dist/types/core/keyboard.d.ts +7 -3
  65. package/dist/types/core/messages.d.ts +3 -0
  66. package/dist/types/core/storage.d.ts +4 -3
  67. package/dist/types/core/util.d.ts +3 -1
  68. package/dist/types/elements/define.d.ts +5 -2
  69. package/dist/types/index.d.ts +6 -4
  70. package/dist/types/internal/agent-model.d.ts +99 -0
  71. package/dist/types/internal/app-rail.d.ts +37 -2
  72. package/dist/types/internal/collections.d.ts +18 -0
  73. package/dist/types/internal/menu-items.d.ts +27 -0
  74. package/dist/types/internal/overlay-content.d.ts +23 -0
  75. package/dist/types/internal/presence-loop.d.ts +5 -2
  76. package/dist/types/locales/index.d.ts +3 -0
  77. package/dist/types/zeyos/calendar.d.ts +43 -7
  78. package/dist/types/zeyos/connect.d.ts +4 -0
  79. package/dist/types/zeyos/form.d.ts +13 -5
  80. package/dist/types/zeyos/select.d.ts +5 -2
  81. package/dist/types/zeyos/table.d.ts +16 -8
  82. package/dist/types/zeyos/view.d.ts +2 -1
  83. package/dist/zx-zeyos.esm.js +2998 -451
  84. package/dist/zx-zeyos.esm.min.js +4 -4
  85. package/dist/zx.core.css +4 -0
  86. package/dist/zx.core.min.css +1 -1
  87. package/dist/zx.css +948 -48
  88. package/dist/zx.esm.js +7432 -3408
  89. package/dist/zx.esm.min.js +26 -26
  90. package/dist/zx.global.js +7432 -3408
  91. package/dist/zx.global.min.js +26 -26
  92. package/dist/zx.layered.css +950 -48
  93. package/dist/zx.layered.min.css +1 -1
  94. package/dist/zx.min.css +1 -1
  95. package/docs/agent-catalog.json +159 -1
  96. package/docs/agent-surfaces.md +21 -21
  97. package/docs/api.json +3122 -528
  98. package/docs/components/account-menu.md +24 -0
  99. package/docs/components/activity-item.md +23 -0
  100. package/docs/components/activity-list.md +28 -0
  101. package/docs/components/agent-avatar.md +59 -0
  102. package/docs/components/agent-thread.md +275 -0
  103. package/docs/components/app-icon.md +36 -0
  104. package/docs/components/app-sidebar.md +92 -0
  105. package/docs/components/approval-card.md +71 -0
  106. package/docs/components/aurora.md +34 -0
  107. package/docs/components/avatar.md +37 -0
  108. package/docs/components/badge.md +36 -0
  109. package/docs/components/block-view.md +34 -0
  110. package/docs/components/breadcrumb.md +20 -0
  111. package/docs/components/button.md +23 -0
  112. package/docs/components/calendar.md +68 -0
  113. package/docs/components/card-view.md +73 -0
  114. package/docs/components/card.md +25 -0
  115. package/docs/components/chart.md +109 -0
  116. package/docs/components/check-button.md +16 -0
  117. package/docs/components/checklist.md +19 -0
  118. package/docs/components/code-editor.md +38 -0
  119. package/docs/components/composer.md +107 -0
  120. package/docs/components/context-menu.md +32 -0
  121. package/docs/components/copy.md +37 -0
  122. package/docs/components/data-filter.md +16 -0
  123. package/docs/components/date-picker.md +31 -0
  124. package/docs/components/date-range.md +21 -0
  125. package/docs/components/datebox.md +31 -0
  126. package/docs/components/dialog.md +25 -0
  127. package/docs/components/dock.md +57 -0
  128. package/docs/components/dropdown.md +39 -0
  129. package/docs/components/elements.md +63 -0
  130. package/docs/components/empty-state.md +17 -0
  131. package/docs/components/entity-ref.md +26 -0
  132. package/docs/components/field-upload.md +18 -0
  133. package/docs/components/file-item.md +27 -0
  134. package/docs/components/file-list.md +23 -0
  135. package/docs/components/filter-panel.md +45 -0
  136. package/docs/components/filter.md +47 -0
  137. package/docs/components/finder.md +25 -0
  138. package/docs/components/form-widgets.md +42 -0
  139. package/docs/components/form.md +80 -0
  140. package/docs/components/grid.md +26 -0
  141. package/docs/components/groupbox.md +11 -0
  142. package/docs/components/helpers.md +359 -0
  143. package/docs/components/icons.md +87 -0
  144. package/docs/components/index.md +99 -0
  145. package/docs/components/kanban-view.md +42 -0
  146. package/docs/components/kbd.md +23 -0
  147. package/docs/components/kernel.md +41 -0
  148. package/docs/components/launcher.md +66 -0
  149. package/docs/components/layout.md +33 -0
  150. package/docs/components/list-toolbar.md +38 -0
  151. package/docs/components/loading.md +48 -0
  152. package/docs/components/menu-button.md +47 -0
  153. package/docs/components/message.md +76 -0
  154. package/docs/components/modal.md +27 -0
  155. package/docs/components/module-bar.md +71 -0
  156. package/docs/components/multi-value-editor.md +16 -0
  157. package/docs/components/navigation-bar.md +22 -0
  158. package/docs/components/number-field.md +34 -0
  159. package/docs/components/pagination.md +73 -0
  160. package/docs/components/panel.md +28 -0
  161. package/docs/components/prompt-starters.md +40 -0
  162. package/docs/components/prose.md +38 -0
  163. package/docs/components/questionnaire.md +115 -0
  164. package/docs/components/rating.md +19 -0
  165. package/docs/components/run-status.md +50 -0
  166. package/docs/components/run-trace.md +72 -0
  167. package/docs/components/search.md +11 -0
  168. package/docs/components/select.md +129 -0
  169. package/docs/components/sheet-stack.md +39 -0
  170. package/docs/components/sheet.md +77 -0
  171. package/docs/components/skeleton.md +27 -0
  172. package/docs/components/slider.md +29 -0
  173. package/docs/components/sort-control.md +21 -0
  174. package/docs/components/source-list.md +30 -0
  175. package/docs/components/split-view.md +12 -0
  176. package/docs/components/stat-tile.md +49 -0
  177. package/docs/components/stepper.md +27 -0
  178. package/docs/components/surface.md +152 -0
  179. package/docs/components/tabbox.md +33 -0
  180. package/docs/components/table-view.md +43 -0
  181. package/docs/components/table.md +232 -0
  182. package/docs/components/tag-picker.md +39 -0
  183. package/docs/components/timebox.md +16 -0
  184. package/docs/components/toggle.md +21 -0
  185. package/docs/components/tokens.md +82 -0
  186. package/docs/components/toolbar.md +26 -0
  187. package/docs/components/tooltip.md +16 -0
  188. package/docs/components/tree.md +48 -0
  189. package/docs/components/truncate.md +21 -0
  190. package/docs/components/value-list.md +14 -0
  191. package/docs/components/view-settings.md +56 -0
  192. package/docs/components/workspace-switcher.md +42 -0
  193. package/docs/components/zeyos.md +196 -0
  194. package/docs/llms-small.txt +299 -0
  195. package/docs/llms.md +697 -100
  196. package/docs/llms.txt +46 -19
  197. package/package.json +9 -4
  198. package/src/components/activity-item/activity-item.js +21 -2
  199. package/src/components/agent-avatar/agent-avatar.css +195 -0
  200. package/src/components/agent-avatar/agent-avatar.js +333 -0
  201. package/src/components/agent-avatar/agent-face.js +292 -0
  202. package/src/components/agent-thread/ag-ui.js +44 -11
  203. package/src/components/agent-thread/agent-thread.js +103 -11
  204. package/src/components/agent-thread/ui-message-stream.js +3 -1
  205. package/src/components/app-rail/app-rail.css +5 -0
  206. package/src/components/app-sidebar/app-sidebar.css +3 -0
  207. package/src/components/app-sidebar/app-sidebar.js +4 -3
  208. package/src/components/approval-card/approval-card.css +6 -0
  209. package/src/components/approval-card/approval-card.js +55 -7
  210. package/src/components/aurora/aurora.css +149 -14
  211. package/src/components/aurora/aurora.js +49 -6
  212. package/src/components/calendar/calendar.css +6 -2
  213. package/src/components/calendar/calendar.js +127 -47
  214. package/src/components/card-view/card-view.js +5 -6
  215. package/src/components/chart/chart.css +159 -1
  216. package/src/components/chart/chart.js +450 -62
  217. package/src/components/chart/color.js +297 -0
  218. package/src/components/chart/svg-adapter.js +576 -0
  219. package/src/components/chart/svg-geometry.js +323 -0
  220. package/src/components/check-button/check-button.js +3 -18
  221. package/src/components/checklist/checklist.js +46 -17
  222. package/src/components/checklist/field-adapter.js +4 -1
  223. package/src/components/code-editor/code-editor.css +33 -0
  224. package/src/components/code-editor/code-editor.js +97 -8
  225. package/src/components/code-editor/field-adapter.js +3 -0
  226. package/src/components/composer/composer.css +3 -0
  227. package/src/components/composer/composer.js +100 -22
  228. package/src/components/context-menu/context-menu.js +41 -5
  229. package/src/components/copy/copy-button.js +9 -1
  230. package/src/components/copy/copy-input.js +5 -0
  231. package/src/components/data-filter/filter-core.js +0 -1
  232. package/src/components/date-picker/date-picker.css +8 -0
  233. package/src/components/date-picker/date-picker.js +47 -8
  234. package/src/components/date-picker/date-range-picker.js +1 -1
  235. package/src/components/date-picker/month-picker.js +19 -3
  236. package/src/components/date-picker/time-picker.js +54 -19
  237. package/src/components/datebox/date-range-box.js +7 -3
  238. package/src/components/datebox/datebox.js +32 -6
  239. package/src/components/dialog/dialog.css +6 -0
  240. package/src/components/dialog/dialog.js +22 -30
  241. package/src/components/dropdown/dropdown.js +1 -18
  242. package/src/components/empty-state/empty-state.js +21 -2
  243. package/src/components/field/field.js +19 -3
  244. package/src/components/fieldset/fieldset.js +3 -1
  245. package/src/components/filter/filter.js +9 -0
  246. package/src/components/form/form.js +19 -2
  247. package/src/components/kanban-view/kanban-card.js +15 -2
  248. package/src/components/kanban-view/kanban-view.css +21 -0
  249. package/src/components/kanban-view/kanban-view.js +29 -16
  250. package/src/components/launcher/launcher.css +14 -0
  251. package/src/components/launcher/launcher.js +54 -9
  252. package/src/components/master-panel/master-panel.js +24 -22
  253. package/src/components/menu-button/menu-button.js +26 -4
  254. package/src/components/message/message.css +228 -29
  255. package/src/components/message/message.js +664 -30
  256. package/src/components/modal/modal.js +70 -25
  257. package/src/components/modal/native-dialog.js +91 -0
  258. package/src/components/module-bar/module-bar.css +3 -0
  259. package/src/components/module-bar/module-bar.js +17 -4
  260. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  261. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  262. package/src/components/navigation-bar/navigation-bar.js +13 -1
  263. package/src/components/number-field/field-adapter.js +3 -0
  264. package/src/components/number-field/number-field.js +2 -1
  265. package/src/components/pagination/pagination.css +26 -2
  266. package/src/components/pagination/pagination.js +551 -65
  267. package/src/components/prose/prose.js +7 -1
  268. package/src/components/rating/field-adapter.js +3 -0
  269. package/src/components/run-status/run-status.js +43 -3
  270. package/src/components/run-trace/run-trace.js +15 -7
  271. package/src/components/search/search.js +3 -18
  272. package/src/components/select/field-adapter.js +8 -1
  273. package/src/components/select/select.js +68 -13
  274. package/src/components/sheet/sheet.js +27 -8
  275. package/src/components/slider/field-adapter.js +3 -0
  276. package/src/components/slider/slider.js +4 -6
  277. package/src/components/stat-tile/stat-tile.js +24 -9
  278. package/src/components/stepper/stepper.css +15 -0
  279. package/src/components/stepper/stepper.js +34 -2
  280. package/src/components/surface/catalog.js +185 -28
  281. package/src/components/surface/surface.js +10 -5
  282. package/src/components/tabbox/tabbox.js +13 -1
  283. package/src/components/table/table.css +160 -2
  284. package/src/components/table/table.js +479 -52
  285. package/src/components/table/window.js +46 -4
  286. package/src/components/table-view/table-view.js +1 -10
  287. package/src/components/tag-picker/field-adapter.js +3 -0
  288. package/src/components/tag-picker/tag-picker.js +2 -0
  289. package/src/components/timebox/field-adapter.js +3 -0
  290. package/src/components/toggle/toggle.js +51 -27
  291. package/src/components/tooltip/tooltip.js +21 -14
  292. package/src/components/tree/tree.js +87 -14
  293. package/src/components/truncate/truncate.js +21 -5
  294. package/src/components/value-list/value-list.js +37 -9
  295. package/src/components/view-settings/view-settings.js +1 -5
  296. package/src/core/component.js +34 -2
  297. package/src/core/date.js +5 -4
  298. package/src/core/drag-axis.js +24 -7
  299. package/src/core/export.js +4 -4
  300. package/src/core/fontawesome.js +34 -3
  301. package/src/core/format.js +3 -1
  302. package/src/core/http.js +23 -11
  303. package/src/core/icons.js +51 -10
  304. package/src/core/keyboard.js +83 -9
  305. package/src/core/messages.js +3 -0
  306. package/src/core/position.js +2 -2
  307. package/src/core/storage.js +80 -31
  308. package/src/core/util.js +16 -5
  309. package/src/elements/define.js +82 -47
  310. package/src/elements/kit.js +46 -35
  311. package/src/index.js +8 -4
  312. package/src/internal/agent-model.js +152 -0
  313. package/src/internal/app-rail.js +53 -2
  314. package/src/internal/collections.js +25 -0
  315. package/src/internal/menu-items.js +59 -0
  316. package/src/internal/overlay-content.js +35 -0
  317. package/src/internal/presence-loop.js +61 -14
  318. package/src/locales/de.js +3 -0
  319. package/src/zeyos/calendar.js +81 -19
  320. package/src/zeyos/connect.js +5 -1
  321. package/src/zeyos/form.js +29 -10
  322. package/src/zeyos/select.js +36 -12
  323. package/src/zeyos/table.js +43 -11
  324. package/src/zeyos/view.js +2 -1
  325. package/styles/tokens/semantic.css +7 -1
  326. package/styles/zx.css +1 -0
@@ -90,6 +90,8 @@
90
90
  "component": "BlockView",
91
91
  "children": false,
92
92
  "input": false,
93
+ "use": "Use it for prose: an explanation, a finding or a reason, with `[n]` markers where a claim has a source.",
94
+ "avoid": "Avoid it for parallel items or a section title; use `list` or `heading`.",
93
95
  "props": {
94
96
  "text": {
95
97
  "type": "string",
@@ -104,6 +106,8 @@
104
106
  "component": "BlockView",
105
107
  "children": false,
106
108
  "input": false,
109
+ "use": "Use it to title one part of a longer surface, so the person can scan it.",
110
+ "avoid": "Avoid it for a titled section around several nodes; use `group`.",
107
111
  "props": {
108
112
  "text": {
109
113
  "type": "string",
@@ -126,6 +130,8 @@
126
130
  "component": "BlockView",
127
131
  "children": false,
128
132
  "input": false,
133
+ "use": "Use it for parallel items the person reads in order or scans: steps, findings, things to check.",
134
+ "avoid": "Avoid it for labelled values or records with several values each; use `figures` or `table`.",
129
135
  "props": {
130
136
  "items": {
131
137
  "type": "string[]",
@@ -144,6 +150,8 @@
144
150
  "component": "BlockView",
145
151
  "children": false,
146
152
  "input": false,
153
+ "use": "Use it for words quoted from a source, such as a message or a clause, shown as written.",
154
+ "avoid": "Avoid it for your own emphasis or a warning; use `callout`.",
147
155
  "props": {
148
156
  "text": {
149
157
  "type": "string",
@@ -158,6 +166,8 @@
158
166
  "component": "BlockView",
159
167
  "children": false,
160
168
  "input": false,
169
+ "use": "Use it for code, a command, a query or a log excerpt whose exact characters matter.",
170
+ "avoid": "Avoid it for a name or a value inside a sentence; mark that inline in `text`.",
161
171
  "props": {
162
172
  "code": {
163
173
  "type": "string",
@@ -177,6 +187,8 @@
177
187
  "component": "BlockView",
178
188
  "children": false,
179
189
  "input": false,
190
+ "use": "Use it for a warning, a condition or a result the person must not miss, with a `tone` when it is a status.",
191
+ "avoid": "Avoid it for ordinary prose; use `text`.",
180
192
  "props": {
181
193
  "text": {
182
194
  "type": "string",
@@ -206,6 +218,8 @@
206
218
  "component": "BlockView",
207
219
  "children": false,
208
220
  "input": false,
221
+ "use": "Use it for a few labelled values of one thing, such as the total, due date and number of an invoice.",
222
+ "avoid": "Avoid it for records that share columns; use `table`.",
209
223
  "props": {
210
224
  "rows": {
211
225
  "type": "Figure[]",
@@ -220,6 +234,8 @@
220
234
  "component": "Table",
221
235
  "children": false,
222
236
  "input": true,
237
+ "use": "Use it for records that share columns, for the person to compare them or look one up.",
238
+ "avoid": "Avoid it for the values of a single record; use `figures`.",
223
239
  "props": {
224
240
  "columns": {
225
241
  "type": "Column[]",
@@ -263,6 +279,8 @@
263
279
  "component": "StatTile",
264
280
  "children": false,
265
281
  "input": false,
282
+ "use": "Use it for a headline figure the answer turns on, with its change or its context.",
283
+ "avoid": "Avoid it for a set of values that are read together; use `figures`.",
266
284
  "props": {
267
285
  "label": {
268
286
  "type": "string",
@@ -307,6 +325,8 @@
307
325
  "component": "Badge",
308
326
  "children": false,
309
327
  "input": false,
328
+ "use": "Use it beside other content to mark a status or a category in a word or two, such as Overdue or Draft.",
329
+ "avoid": "Avoid it for a sentence or a phrase; use `text`.",
310
330
  "props": {
311
331
  "label": {
312
332
  "type": "string",
@@ -333,6 +353,8 @@
333
353
  "component": "EntityRef",
334
354
  "children": false,
335
355
  "input": false,
356
+ "use": "Use it for a customer, an invoice or another record of the application the person may want to open.",
357
+ "avoid": "Avoid it for a page on the web; use `link`.",
336
358
  "props": {
337
359
  "ref": {
338
360
  "type": "Ref",
@@ -346,6 +368,8 @@
346
368
  "component": null,
347
369
  "children": false,
348
370
  "input": false,
371
+ "use": "Use it for a page on the web the person may want to open, such as documentation or a source.",
372
+ "avoid": "Avoid it for a record of the application; use `ref`.",
349
373
  "props": {
350
374
  "text": {
351
375
  "type": "string",
@@ -366,6 +390,8 @@
366
390
  "component": "Chart",
367
391
  "children": false,
368
392
  "input": false,
393
+ "use": "Use it for a trend or a comparison across many values, where the shape matters more than each number.",
394
+ "avoid": "Avoid it for a few values the person reads exactly; use `figures`.",
369
395
  "props": {
370
396
  "kind": {
371
397
  "type": "string",
@@ -401,6 +427,8 @@
401
427
  "component": "EmptyState",
402
428
  "children": false,
403
429
  "input": false,
430
+ "use": "Use it when a search or a list comes back empty, to say what would change that.",
431
+ "avoid": "Avoid it for an error or a warning about what is shown; use `callout`.",
404
432
  "props": {
405
433
  "title": {
406
434
  "type": "string",
@@ -420,6 +448,8 @@
420
448
  "component": "Stack",
421
449
  "children": true,
422
450
  "input": false,
451
+ "use": "Use it to keep a run of nodes together with one spacing, such as several nodes in one column of a row.",
452
+ "avoid": "Avoid it for a titled section; use `group`.",
423
453
  "props": {
424
454
  "gap": {
425
455
  "type": "string",
@@ -437,6 +467,8 @@
437
467
  "component": "LayoutGrid",
438
468
  "children": true,
439
469
  "input": false,
470
+ "use": "Use it for two or three items the person compares side by side, such as figures for two periods.",
471
+ "avoid": "Avoid it for long text or wide content, which gets cramped; use `stack`.",
440
472
  "props": {
441
473
  "count": {
442
474
  "type": "integer",
@@ -454,6 +486,8 @@
454
486
  "component": "Groupbox",
455
487
  "children": true,
456
488
  "input": false,
489
+ "use": "Use it for a titled section of related nodes in a longer surface.",
490
+ "avoid": "Avoid it around a single node; use `heading` before the node.",
457
491
  "props": {
458
492
  "title": {
459
493
  "type": "string",
@@ -468,6 +502,8 @@
468
502
  "component": "Fieldset",
469
503
  "children": false,
470
504
  "input": true,
505
+ "use": "Use it to ask for values the person types or picks: text, numbers, dates, options, switches.",
506
+ "avoid": "Avoid it for one decision between a few described options; use `choice`.",
471
507
  "props": {
472
508
  "schema": {
473
509
  "type": "Schema",
@@ -486,6 +522,8 @@
486
522
  "component": "Questionnaire",
487
523
  "children": false,
488
524
  "input": true,
525
+ "use": "Use it for one decision between described options, each with a label and an optional description.",
526
+ "avoid": "Avoid it for several values at once or for typed input; use `fields`.",
489
527
  "props": {
490
528
  "name": {
491
529
  "type": "string",
@@ -517,6 +555,8 @@
517
555
  "intentOnly": "review",
518
556
  "children": false,
519
557
  "input": true,
558
+ "use": "Use it to propose changes to the values of a record, one row per value, for the person to accept or leave out.",
559
+ "avoid": "Avoid it for picking whole records; use a selectable `table`.",
520
560
  "props": {
521
561
  "name": {
522
562
  "type": "string",
@@ -543,6 +583,8 @@
543
583
  "intentOnly": "questionnaire",
544
584
  "children": false,
545
585
  "input": true,
586
+ "use": "Use it for several questions asked one at a time, where an answer decides what comes next.",
587
+ "avoid": "Avoid it for a few independent values; use `fields` in an `ask` surface.",
546
588
  "props": {
547
589
  "steps": {
548
590
  "type": "Step[]",
@@ -12497,5 +12539,121 @@
12497
12539
  }
12498
12540
  }
12499
12541
  }
12500
- ]
12542
+ ],
12543
+ "profiles": {
12544
+ "answer": {
12545
+ "intents": [
12546
+ "show"
12547
+ ],
12548
+ "nodes": [
12549
+ "text",
12550
+ "heading",
12551
+ "list",
12552
+ "code",
12553
+ "callout",
12554
+ "figures",
12555
+ "table",
12556
+ "stat",
12557
+ "badge",
12558
+ "ref",
12559
+ "link",
12560
+ "chart",
12561
+ "empty",
12562
+ "stack",
12563
+ "columns",
12564
+ "group"
12565
+ ]
12566
+ },
12567
+ "ask": {
12568
+ "intents": [
12569
+ "show",
12570
+ "ask",
12571
+ "choose",
12572
+ "confirm"
12573
+ ],
12574
+ "nodes": [
12575
+ "text",
12576
+ "heading",
12577
+ "list",
12578
+ "code",
12579
+ "callout",
12580
+ "figures",
12581
+ "table",
12582
+ "stat",
12583
+ "badge",
12584
+ "ref",
12585
+ "link",
12586
+ "chart",
12587
+ "empty",
12588
+ "stack",
12589
+ "columns",
12590
+ "group",
12591
+ "fields",
12592
+ "choice"
12593
+ ]
12594
+ },
12595
+ "review": {
12596
+ "intents": [
12597
+ "show",
12598
+ "ask",
12599
+ "choose",
12600
+ "confirm",
12601
+ "review"
12602
+ ],
12603
+ "nodes": [
12604
+ "text",
12605
+ "heading",
12606
+ "list",
12607
+ "code",
12608
+ "callout",
12609
+ "figures",
12610
+ "table",
12611
+ "stat",
12612
+ "badge",
12613
+ "ref",
12614
+ "link",
12615
+ "chart",
12616
+ "empty",
12617
+ "stack",
12618
+ "columns",
12619
+ "group",
12620
+ "fields",
12621
+ "choice",
12622
+ "diff"
12623
+ ]
12624
+ },
12625
+ "full": {
12626
+ "intents": [
12627
+ "show",
12628
+ "ask",
12629
+ "choose",
12630
+ "confirm",
12631
+ "review",
12632
+ "questionnaire"
12633
+ ],
12634
+ "nodes": [
12635
+ "text",
12636
+ "heading",
12637
+ "list",
12638
+ "quote",
12639
+ "code",
12640
+ "callout",
12641
+ "figures",
12642
+ "table",
12643
+ "stat",
12644
+ "badge",
12645
+ "ref",
12646
+ "link",
12647
+ "chart",
12648
+ "empty",
12649
+ "stack",
12650
+ "columns",
12651
+ "group",
12652
+ "fields",
12653
+ "choice",
12654
+ "diff",
12655
+ "questionnaire"
12656
+ ]
12657
+ }
12658
+ }
12501
12659
  }
@@ -29,40 +29,40 @@ Nodes are addressed by `id` and laid out by lists of ids: `root` holds the top l
29
29
 
30
30
  ### `text`
31
31
 
32
- A paragraph.
32
+ A paragraph. Use it for prose: an explanation, a finding or a reason, with `[n]` markers where a claim has a source. Avoid it for parallel items or a section title; use `list` or `heading`.
33
33
 
34
34
  - `text`: text, at most 20,000 characters, required
35
35
 
36
36
  ### `heading`
37
37
 
38
- A heading inside the surface; level 2 or 3.
38
+ A heading inside the surface; level 2 or 3. Use it to title one part of a longer surface, so the person can scan it. Avoid it for a titled section around several nodes; use `group`.
39
39
 
40
40
  - `text`: text, at most 200 characters, required
41
41
  - `level`: one of `2`, `3`
42
42
 
43
43
  ### `list`
44
44
 
45
- A bulleted list, or numbered with `ordered`.
45
+ A bulleted list, or numbered with `ordered`. Use it for parallel items the person reads in order or scans: steps, findings, things to check. Avoid it for labelled values or records with several values each; use `figures` or `table`.
46
46
 
47
47
  - `items`: list of texts, at most 1,000, required
48
48
  - `ordered`: `true` or `false`
49
49
 
50
50
  ### `quote`
51
51
 
52
- A quotation.
52
+ A quotation. Use it for words quoted from a source, such as a message or a clause, shown as written. Avoid it for your own emphasis or a warning; use `callout`.
53
53
 
54
54
  - `text`: text, at most 20,000 characters, required
55
55
 
56
56
  ### `code`
57
57
 
58
- A code block.
58
+ A code block. Use it for code, a command, a query or a log excerpt whose exact characters matter. Avoid it for a name or a value inside a sentence; mark that inline in `text`.
59
59
 
60
60
  - `code`: text, at most 20,000 characters, required
61
61
  - `language`: text, at most 32 characters
62
62
 
63
63
  ### `callout`
64
64
 
65
- A paragraph set apart, with a tone.
65
+ A paragraph set apart, with a tone. Use it for a warning, a condition or a result the person must not miss, with a `tone` when it is a status. Avoid it for ordinary prose; use `text`.
66
66
 
67
67
  - `text`: text, at most 20,000 characters, required
68
68
  - `title`: text, at most 200 characters
@@ -70,13 +70,13 @@ A paragraph set apart, with a tone.
70
70
 
71
71
  ### `figures`
72
72
 
73
- Rows of `{"label", "value", "detail"?}`: amounts, dates, counts.
73
+ Rows of `{"label", "value", "detail"?}`: amounts, dates, counts. Use it for a few labelled values of one thing, such as the total, due date and number of an invoice. Avoid it for records that share columns; use `table`.
74
74
 
75
75
  - `rows`: list of figure rows, at most 1,000, required
76
76
 
77
77
  ### `table`
78
78
 
79
- 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.
79
+ 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. Use it for records that share columns, for the person to compare them or look one up. Avoid it for the values of a single record; use `figures`.
80
80
 
81
81
  - `columns`: list of columns, at most 50, required
82
82
  - `rows`: list of rows, at most 1,000, required
@@ -87,7 +87,7 @@ A table. `columns` are `{"id", "label", "align"?, "format"?, "currency"?}`; each
87
87
 
88
88
  ### `stat`
89
89
 
90
- One figure with its label, drawn as a tile.
90
+ One figure with its label, drawn as a tile. Use it for a headline figure the answer turns on, with its change or its context. Avoid it for a set of values that are read together; use `figures`.
91
91
 
92
92
  - `label`: text, at most 200 characters, required
93
93
  - `value`: number or text, at most 200 characters, required
@@ -98,27 +98,27 @@ One figure with its label, drawn as a tile.
98
98
 
99
99
  ### `badge`
100
100
 
101
- A short status word.
101
+ A short status word. Use it beside other content to mark a status or a category in a word or two, such as Overdue or Draft. Avoid it for a sentence or a phrase; use `text`.
102
102
 
103
103
  - `label`: text, at most 64 characters, required
104
104
  - `kind`: one of `"neutral"`, `"accent"`, `"success"`, `"warning"`, `"danger"`, `"info"`
105
105
 
106
106
  ### `ref`
107
107
 
108
- A record of the application, drawn with its own name and icon.
108
+ A record of the application, drawn with its own name and icon. Use it for a customer, an invoice or another record of the application the person may want to open. Avoid it for a page on the web; use `link`.
109
109
 
110
110
  - `ref`: record `{"$ref", "id"}`, required
111
111
 
112
112
  ### `link`
113
113
 
114
- An external link.
114
+ An external link. Use it for a page on the web the person may want to open, such as documentation or a source. Avoid it for a record of the application; use `ref`.
115
115
 
116
116
  - `text`: text, at most 200 characters, required
117
117
  - `href`: `https:` address, at most 2,000 characters, required
118
118
 
119
119
  ### `chart`
120
120
 
121
- A chart; its data table is always offered. `data` is `{"labels": […], "datasets": [{"label", "data": […]}]}`.
121
+ A chart; its data table is always offered. `data` is `{"labels": […], "datasets": [{"label", "data": […]}]}`. Use it for a trend or a comparison across many values, where the shape matters more than each number. Avoid it for a few values the person reads exactly; use `figures`.
122
122
 
123
123
  - `kind`: one of `"bar"`, `"line"`, `"pie"`, `"doughnut"`, required
124
124
  - `data`: chart data, required
@@ -127,42 +127,42 @@ A chart; its data table is always offered. `data` is `{"labels": […], "dataset
127
127
 
128
128
  ### `empty`
129
129
 
130
- An empty state: nothing to show, and why.
130
+ An empty state: nothing to show, and why. Use it when a search or a list comes back empty, to say what would change that. Avoid it for an error or a warning about what is shown; use `callout`.
131
131
 
132
132
  - `title`: text, at most 200 characters, required
133
133
  - `description`: text, at most 2,000 characters
134
134
 
135
135
  ### `stack`
136
136
 
137
- Lays out its children one under the other.
137
+ Lays out its children one under the other. Use it to keep a run of nodes together with one spacing, such as several nodes in one column of a row. Avoid it for a titled section; use `group`.
138
138
 
139
139
  - `gap`: one of `"sm"`, `"md"`, `"lg"`
140
140
  - `children`: list of node ids.
141
141
 
142
142
  ### `columns`
143
143
 
144
- Lays out its children side by side, one column when narrow.
144
+ Lays out its children side by side, one column when narrow. Use it for two or three items the person compares side by side, such as figures for two periods. Avoid it for long text or wide content, which gets cramped; use `stack`.
145
145
 
146
146
  - `count`: one of `1`, `2`, `3`
147
147
  - `children`: list of node ids.
148
148
 
149
149
  ### `group`
150
150
 
151
- A titled section around its children.
151
+ A titled section around its children. Use it for a titled section of related nodes in a longer surface. Avoid it around a single node; use `heading` before the node.
152
152
 
153
153
  - `title`: text, at most 200 characters, required
154
154
  - `children`: list of node ids.
155
155
 
156
156
  ### `fields`
157
157
 
158
- A form: a JSON Schema whose properties become fields (see Inputs).
158
+ A form: a JSON Schema whose properties become fields (see Inputs). Use it to ask for values the person types or picks: text, numbers, dates, options, switches. Avoid it for one decision between a few described options; use `choice`.
159
159
 
160
160
  - `schema`: input schema, required
161
161
  - `title`: text, at most 200 characters
162
162
 
163
163
  ### `choice`
164
164
 
165
- Options to pick from: `choices` are `{"value", "label", "description"?, "icon"?}`; `multiple` allows several.
165
+ Options to pick from: `choices` are `{"value", "label", "description"?, "icon"?}`; `multiple` allows several. Use it for one decision between described options, each with a label and an optional description. Avoid it for several values at once or for typed input; use `fields`.
166
166
 
167
167
  - `name`: text, at most 64 characters, required
168
168
  - `label`: text, at most 200 characters, required
@@ -171,7 +171,7 @@ Options to pick from: `choices` are `{"value", "label", "description"?, "icon"?}
171
171
 
172
172
  ### `diff`
173
173
 
174
- Proposed changes, one row per value: `{"id", "field", "label", "before", "after", "ref"?}`. The reply holds the ids of the accepted rows. Only in a `review` surface.
174
+ Proposed changes, one row per value: `{"id", "field", "label", "before", "after", "ref"?}`. The reply holds the ids of the accepted rows. Only in a `review` surface. Use it to propose changes to the values of a record, one row per value, for the person to accept or leave out. Avoid it for picking whole records; use a selectable `table`.
175
175
 
176
176
  - `name`: text, at most 64 characters, required
177
177
  - `rows`: list of changes, at most 1,000, required
@@ -179,7 +179,7 @@ Proposed changes, one row per value: `{"id", "field", "label", "before", "after"
179
179
 
180
180
  ### `questionnaire`
181
181
 
182
- Steps asked one at a time: `{"name", "prompt", "choices"?, "input"?, "required"?, "multiple"?, "when"?, "next"?, "validate"?}`. `next` is a step name, `$review`, `$submit`, or `[{"if": condition, "goto": name}, …]`, and is dropped if it names a step that was dropped or can lead back to its own step; `validate` lists rules (`required`, `minLength`, `maxLength`, `minimum`, `maximum`, `format`, `oneOf`, each with an optional `message`). Only in a `questionnaire` surface.
182
+ Steps asked one at a time: `{"name", "prompt", "choices"?, "input"?, "required"?, "multiple"?, "when"?, "next"?, "validate"?}`. `next` is a step name, `$review`, `$submit`, or `[{"if": condition, "goto": name}, …]`, and is dropped if it names a step that was dropped or can lead back to its own step; `validate` lists rules (`required`, `minLength`, `maxLength`, `minimum`, `maximum`, `format`, `oneOf`, each with an optional `message`). Only in a `questionnaire` surface. Use it for several questions asked one at a time, where an answer decides what comes next. Avoid it for a few independent values; use `fields` in an `ask` surface.
183
183
 
184
184
  - `steps`: list of steps, at most 50, required
185
185
  - `review`: `true` or `false`