@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
@@ -7,6 +7,31 @@ import { button } from '../button/button.js';
7
7
 
8
8
  /** @typedef {'info'|'success'|'warning'|'error'} MessageKind */
9
9
 
10
+ /**
11
+ * Where a floating region sits in the viewport: the block edge, then the inline position. Logical,
12
+ * so `start` and `end` follow the writing direction; `top` and `bottom` alone are centred.
13
+ * @typedef {'top-start'|'top'|'top-end'|'bottom-start'|'bottom'|'bottom-end'} MessagePlacement
14
+ */
15
+
16
+ /** The placements a floating region accepts. */
17
+ const PLACEMENTS = new Set(['top-start', 'top', 'top-end', 'bottom-start', 'bottom', 'bottom-end']);
18
+
19
+ /** The corner floating messages use unless told otherwise. */
20
+ const DEFAULT_PLACEMENT = 'top-end';
21
+
22
+ /** How many messages a collapsed stack shows behind the front one. */
23
+ const STACK_PEEK = 2;
24
+
25
+ /** How much smaller each message behind the front one is drawn in a collapsed stack. */
26
+ const STACK_SCALE_STEP = 0.05;
27
+
28
+ /**
29
+ * How a message stands out beyond its kind icon. `false` draws the plain card; `'border'` (or
30
+ * `true`) draws its border in the kind colour; `'animated'` adds a light that travels around that
31
+ * border — a kind-coloured border where motion is reduced.
32
+ * @typedef {boolean|'border'|'animated'} MessageHighlight
33
+ */
34
+
10
35
  /**
11
36
  * The one command a message may carry, drawn as a small button beside its text.
12
37
  * @typedef {Object} MessageAction
@@ -28,7 +53,10 @@ import { button } from '../button/button.js';
28
53
  * @property {Node|{toElement: () => Node|null}|null} [leading=null] Visual shown in place of the
29
54
  * kind icon, such as an Avatar's element. It is decorative — the message text must say what it
30
55
  * shows.
56
+ * @property {MessageHighlight} [highlight=false] Draws the border in the kind colour (`'border'` or
57
+ * `true`), or sends a light around it (`'animated'`); the default is the area's `highlight`.
31
58
  * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns a floating toast.
59
+ * @property {MessagePlacement} [placement='top-end'] Where a floating toast sits in the viewport; the default is the one set with `Message.setPlacement()`. Messages of one placement share a region. Ignored by an inline area.
32
60
  */
33
61
 
34
62
  /**
@@ -37,6 +65,39 @@ import { button } from '../button/button.js';
37
65
  * @property {number} [timeout=4000] Default auto-dismiss delay.
38
66
  * @property {boolean} [closable=true] Default close-button visibility.
39
67
  * @property {number} [maxVisible=5] Maximum number of visible messages.
68
+ * @property {MessageHighlight} [highlight=false] Default highlight of the messages shown here.
69
+ * @property {boolean} [stack=false] Piles the visible messages into one stack, the newest in front
70
+ * and two more peeking out behind it. The stack opens while the pointer is over it or focus is
71
+ * inside it, and a press on it keeps it open until a press outside it or Escape; while it is open
72
+ * by any of these, no message in it times out.
73
+ * @property {boolean} [expanded=false] Keeps a stack open. Its messages still time out.
74
+ */
75
+
76
+ /**
77
+ * A length in a stack: measured pixels plus a number of spacing steps, so the spacing stays a
78
+ * theme setting. A step is `--zx-message-gap` in an open stack, the space between two messages,
79
+ * and `--zx-message-peek` in a collapsed one, how far each message behind the front shows.
80
+ * @typedef {Object} MessageStackLength
81
+ * @property {number} px Measured part, in pixels.
82
+ * @property {number} steps Spacing steps added to it (negative or fractional where it is cut back).
83
+ */
84
+
85
+ /**
86
+ * Where one message sits in a stack.
87
+ * @typedef {Object} MessageStackItem
88
+ * @property {number} depth Place in the pile, 0 for the front (newest) message, counting back.
89
+ * @property {MessageStackLength} y How far the message moves from the stack's edge.
90
+ * @property {number} scale Drawn size, 1 at the front.
91
+ * @property {MessageStackLength|null} clip How much is cut from the message's inner edge, in its
92
+ * own unscaled size, so that only the strip peeking out past the message in front of it shows —
93
+ * nothing behind a translucent card shows through it. Null where nothing is cut.
94
+ * @property {boolean} hidden Whether the message is out of sight behind the visible pile.
95
+ */
96
+
97
+ /**
98
+ * @typedef {Object} MessageStackLayout
99
+ * @property {MessageStackItem[]} items One per message, the front first.
100
+ * @property {MessageStackLength} size The stack's own height.
40
101
  */
41
102
 
42
103
  /**
@@ -148,7 +209,15 @@ export class MessageQueue {
148
209
 
149
210
  /**
150
211
  * Inline message area and static toast service.
212
+ *
213
+ * With `stack` the visible messages pile up into one card, the newest in front, and the pile
214
+ * opens to show them all — the same for an inline area and a floating region. Floating regions
215
+ * stack by default (`Message.setStack(false)` lists their messages instead); an inline area stacks
216
+ * with `stack: true`. The root then carries `data-stack` and `data-state="collapsed"` or
217
+ * `"expanded"`.
151
218
  * @extends {Component<MessageOptions>}
219
+ * @fires Message#expand
220
+ * @fires Message#collapse
152
221
  */
153
222
  export class Message extends Component {
154
223
  static cssName = 'message';
@@ -158,9 +227,18 @@ export class Message extends Component {
158
227
  kind: 'info',
159
228
  timeout: 4000,
160
229
  closable: true,
161
- maxVisible: 5
230
+ maxVisible: 5,
231
+ highlight: false,
232
+ stack: false,
233
+ expanded: false
162
234
  };
163
235
 
236
+ /** @type {MessagePlacement} Where floating messages appear when a call names no placement. */
237
+ static #placement = DEFAULT_PLACEMENT;
238
+
239
+ /** @type {boolean} Whether floating regions stack their messages; they do unless told not to. */
240
+ static #stack = true;
241
+
164
242
  /** @returns {HTMLElement} */
165
243
  render() {
166
244
  const created = !this.el;
@@ -172,6 +250,8 @@ export class Message extends Component {
172
250
  this._floatingHost = null;
173
251
  /** @type {Element|null} Where the floating region was last put: its scope, or the topmost modal. */
174
252
  this._placedIn = null;
253
+ /** @type {MessagePlacement|null} The placement this instance is the floating region of. */
254
+ this._placement = null;
175
255
  /** @type {import('../../core/overlay-stack.js').OverlayHandle|null} The region's toast entry. */
176
256
  this._overlay = null;
177
257
  /** @type {(() => void)|null} Stops following the overlay stack. */
@@ -179,9 +259,37 @@ export class Message extends Component {
179
259
  this._queue = new MessageQueue(normalizeLimit(this.options.maxVisible), (entry) => {
180
260
  this._activate(entry);
181
261
  });
262
+ /** @type {any[]} The active messages, oldest first, closing ones until they are gone. */
263
+ this._shown = [];
264
+ /** Activation counter: a newer message paints over an older one in a stack. */
265
+ this._seq = 0;
266
+ this._stack = Boolean(this.options.stack);
267
+ /** Stack holds: the pointer is over it, focus is inside it, a press or `expand()` pinned it. */
268
+ this._hovered = false;
269
+ this._focusWithin = false;
270
+ this._pinned = false;
271
+ /** @type {boolean} Whether the timers were last held by the stack. */
272
+ this._wasHeld = false;
273
+ /** @type {Element|null} Where focus came from when it entered the stack, for Escape. */
274
+ this._stackReturn = null;
275
+ /** @type {number} When the stack was last pinned, so the press that pinned it does not unpin it. */
276
+ this._pinnedAt = -Infinity;
277
+ /** @type {boolean|null} Whether the stack last piled from the foot; null before the first layout. */
278
+ this._pileFromEnd = null;
279
+ /** Set while messages are moved, so the focus they lose and regain is not read as leaving. */
280
+ this._reordering = false;
281
+ this._resizeObserver = typeof ResizeObserver === 'function'
282
+ ? new ResizeObserver(() => this._syncStack()) : null;
182
283
  root.replaceChildren();
183
284
  root.setAttribute('role', 'status');
184
285
  root.setAttribute('aria-live', 'polite');
286
+ /** @type {boolean} What the last `expand`/`collapse` event said. */
287
+ this._wasExpanded = this.isExpanded();
288
+ if (this._stack) {
289
+ root.setAttribute('data-stack', '');
290
+ root.setAttribute('data-state', this._wasExpanded ? 'expanded' : 'collapsed');
291
+ }
292
+ this._listenStack(root);
185
293
  return root;
186
294
  }
187
295
 
@@ -198,7 +306,8 @@ export class Message extends Component {
198
306
  timeout: messageTimeout(options.timeout ?? this.options.timeout, action !== null),
199
307
  closable: options.closable ?? Boolean(this.options.closable),
200
308
  action,
201
- leading: resolveLeading(options.leading)
309
+ leading: resolveLeading(options.leading),
310
+ highlight: normalizeMessageHighlight(options.highlight ?? this.options.highlight)
202
311
  };
203
312
  const entry = this._createEntry(msg, settings);
204
313
  this._entries.add(entry);
@@ -253,17 +362,65 @@ export class Message extends Component {
253
362
  * @returns {MessageHandle}
254
363
  */
255
364
  static show(msg, options = {}) {
256
- return this.#floatingRegion(options.scope).show(msg, options);
365
+ return Message.#floatingRegion(options.scope, options.placement).show(msg, options);
257
366
  }
258
367
 
259
368
  /**
260
369
  * Shows a floating progress status.
261
370
  * @param {string} text Initial status text.
262
- * @param {{scope?: Element|string|null}} [options={}] Floating-region scope.
371
+ * @param {{scope?: Element|string|null, placement?: MessagePlacement, highlight?: MessageHighlight}} [options={}]
372
+ * Floating-region scope and placement, and the message's highlight.
263
373
  * @returns {ProgressHandle}
264
374
  */
265
375
  static progress(text, options = {}) {
266
- return this.#floatingRegion(options.scope)._progress(text);
376
+ return Message.#floatingRegion(options.scope, options.placement)._progress(text, options);
377
+ }
378
+
379
+ /**
380
+ * Sets whether floating regions stack their messages (see the `stack` option); they do by
381
+ * default, and `false` lists them one below another instead. Unlike a placement it applies at
382
+ * once, to the regions on screen as well as those to come.
383
+ * @param {boolean} enabled Whether to stack.
384
+ * @returns {boolean} Whether floating regions stack now.
385
+ */
386
+ static setStack(enabled) {
387
+ Message.#stack = Boolean(enabled);
388
+ for (const entry of overlayStack.entries()) {
389
+ if (entry.kind === 'toast' && entry.owner instanceof Message) entry.owner.setStack(Message.#stack);
390
+ }
391
+ return Message.#stack;
392
+ }
393
+
394
+ /**
395
+ * Returns whether floating regions stack their messages, true unless `setStack(false)` was called.
396
+ * @returns {boolean}
397
+ */
398
+ static getStack() {
399
+ return Message.#stack;
400
+ }
401
+
402
+ /**
403
+ * Sets where floating messages appear when a call names no `placement`. It applies to messages
404
+ * shown from then on; a region already on screen stays where it is until its last toast closes.
405
+ *
406
+ * The region carries the placement as `data-placement`, and its distance from the viewport edge
407
+ * is the `--zx-message-offset` custom property (default `var(--zx-space-4)`), read from the
408
+ * region's theme scope. At 640px and narrower every placement spans the foot of the viewport.
409
+ * @param {MessagePlacement} placement One of `'top-start'`, `'top'`, `'top-end'`, `'bottom-start'`,
410
+ * `'bottom'`, `'bottom-end'`; anything else restores `'top-end'`.
411
+ * @returns {MessagePlacement} The placement now in effect.
412
+ */
413
+ static setPlacement(placement) {
414
+ Message.#placement = normalizeMessagePlacement(placement);
415
+ return Message.#placement;
416
+ }
417
+
418
+ /**
419
+ * Returns where floating messages appear when a call names no `placement`.
420
+ * @returns {MessagePlacement}
421
+ */
422
+ static getPlacement() {
423
+ return Message.#placement;
267
424
  }
268
425
 
269
426
  /**
@@ -272,6 +429,8 @@ export class Message extends Component {
272
429
  * A region already removes itself when its last toast closes, and one whose host has left the
273
430
  * document is replaced on the next toast, so this is only for a host being torn down while
274
431
  * toasts are still showing — an application view unmounting its themed shell, say.
432
+ *
433
+ * A scope has one region per placement in use; all of them are removed.
275
434
  * @param {Element|string} scope Element or selector whose nearest Zx theme scope owns the region,
276
435
  * as passed to `show()`.
277
436
  * @returns {boolean} Whether there was a region to remove.
@@ -280,16 +439,86 @@ export class Message extends Component {
280
439
  if (scope == null) return false;
281
440
  const context = resolveElement(scope);
282
441
  if (!context) return false;
283
- const region = Message.#regionFor(overlayScope(context));
284
- if (!region) return false;
285
- region._disposeFloating();
286
- return true;
442
+ const regions = Message.#regionsOf(overlayScope(context));
443
+ for (const region of regions) region._disposeFloating();
444
+ return regions.length > 0;
445
+ }
446
+
447
+ /**
448
+ * Turns stacking on or off for this area or region (see the `stack` option). The messages on
449
+ * screen move into the pile, or back into a list, where they are.
450
+ * @param {boolean} enabled Whether to stack.
451
+ * @returns {this}
452
+ */
453
+ setStack(enabled) {
454
+ const next = Boolean(enabled);
455
+ if (next === this._stack) return this;
456
+ this._stack = next;
457
+ const root = /** @type {HTMLElement} */ (this.el);
458
+ const wasExpanded = this._wasExpanded;
459
+ if (next) {
460
+ root.setAttribute('data-stack', '');
461
+ } else {
462
+ this._pinned = false;
463
+ this._hovered = false;
464
+ this._focusWithin = false;
465
+ this._wasExpanded = false;
466
+ this._pileFromEnd = null;
467
+ root.removeAttribute('data-stack');
468
+ root.removeAttribute('data-state');
469
+ root.removeAttribute('data-overflow');
470
+ for (const name of ['--zx-message-stack-size', '--zx-message-stack-hold']) root.style.removeProperty(name);
471
+ for (const entry of this._shown) clearStackStyle(entry.node);
472
+ }
473
+ this._order();
474
+ this._refreshStack();
475
+ // A stack that was open and is now a list has closed, as far as anyone listening knows.
476
+ if (!next && wasExpanded) this.emit('collapse');
477
+ return this;
478
+ }
479
+
480
+ /**
481
+ * Opens a stack and keeps it open until `collapse()`, Escape, or a press outside it. Does
482
+ * nothing without `stack`.
483
+ * @returns {this}
484
+ * @fires Message#expand
485
+ */
486
+ expand() {
487
+ if (!this._stack) return this;
488
+ this._pinned = true;
489
+ this._pinnedAt = now();
490
+ this._refreshStack();
491
+ return this;
492
+ }
493
+
494
+ /**
495
+ * Closes a stack opened by a press, `expand()`, or the pointer. A stack holding focus stays open
496
+ * until focus leaves it, and one with `expanded: true` never closes.
497
+ * @returns {this}
498
+ * @fires Message#collapse
499
+ */
500
+ collapse() {
501
+ if (!this._stack) return this;
502
+ this._pinned = false;
503
+ this._hovered = false;
504
+ this._refreshStack();
505
+ return this;
506
+ }
507
+
508
+ /**
509
+ * Reports whether the stack is open. Always false without `stack`.
510
+ * @returns {boolean}
511
+ */
512
+ isExpanded() {
513
+ return this._stack && Boolean(this.options.expanded || this._pinned || this._hovered || this._focusWithin);
287
514
  }
288
515
 
289
516
  /** @returns {void} */
290
517
  destroy() {
291
518
  if (this._cleaned) return;
292
519
  this._cleaned = true;
520
+ this._resizeObserver?.disconnect();
521
+ this._resizeObserver = null;
293
522
  this._unfollow?.();
294
523
  this._unfollow = null;
295
524
  const overlay = this._overlay;
@@ -297,21 +526,28 @@ export class Message extends Component {
297
526
  overlay?.release();
298
527
  this._floatingHost = null;
299
528
  this._placedIn = null;
529
+ this._placement = null;
300
530
  for (const entry of this._entries) {
301
531
  clearEntryTimers(entry);
302
532
  entry.node.remove();
303
533
  }
304
534
  this._queue.clear();
305
535
  this._entries.clear();
536
+ this._shown.length = 0;
306
537
  super.destroy();
307
538
  if (!this._createdRoot && this._original) restore(this.el, this._original);
308
539
  }
309
540
 
310
- /** @param {string} text @returns {ProgressHandle} */
311
- _progress(text) {
541
+ /**
542
+ * @param {string} text
543
+ * @param {{highlight?: MessageHighlight}} [options={}]
544
+ * @returns {ProgressHandle}
545
+ */
546
+ _progress(text, options = {}) {
312
547
  const state = { pct: 0, text: String(text) };
313
548
  const entry = this._createEntry(state.text, {
314
- kind: 'info', timeout: 0, closable: false
549
+ kind: 'info', timeout: 0, closable: false,
550
+ highlight: normalizeMessageHighlight(options.highlight ?? this.options.highlight)
315
551
  }, state);
316
552
  this._entries.add(entry);
317
553
  this._queue.enqueue(entry);
@@ -351,7 +587,7 @@ export class Message extends Component {
351
587
 
352
588
  /**
353
589
  * @param {string|Node} msg
354
- * @param {{kind: MessageKind, timeout: number, closable: boolean, action?: MessageAction|null, leading?: Node|null}} settings
590
+ * @param {{kind: MessageKind, timeout: number, closable: boolean, action?: MessageAction|null, leading?: Node|null, highlight?: 'border'|'animated'|null}} settings
355
591
  * @param {{pct: number, text: string}|null} [progress=null]
356
592
  * @returns {any}
357
593
  */
@@ -382,9 +618,11 @@ export class Message extends Component {
382
618
  focused: false,
383
619
  returnFocus: null,
384
620
  progressBar: null,
385
- progressFill: null
621
+ progressFill: null,
622
+ seq: 0
386
623
  };
387
624
  if (settings.leading) node.dataset.leading = '';
625
+ if (settings.highlight) node.dataset.highlight = settings.highlight;
388
626
 
389
627
  if (progress) {
390
628
  node.dataset.progress = '';
@@ -460,13 +698,21 @@ export class Message extends Component {
460
698
  _activate(entry) {
461
699
  if (entry.closed) return;
462
700
  entry.node.dataset.state = 'open';
463
- this.el.append(entry.node);
701
+ this._seq += 1;
702
+ entry.seq = this._seq;
703
+ // A stack keeps document order in visual order, so Tab meets the messages as they are seen:
704
+ // the newest first where it piles from the top, last where it piles from the foot.
705
+ if (this._stack && !this._fromEnd()) this.el.prepend(entry.node);
706
+ else this.el.append(entry.node);
707
+ this._shown.push(entry);
708
+ this._resizeObserver?.observe(entry.node);
709
+ this._syncStack();
464
710
  this._schedule(entry);
465
711
  }
466
712
 
467
713
  /** @param {any} entry @returns {void} */
468
714
  _schedule(entry) {
469
- if (entry.closed || entry.remaining <= 0 || entry.hovered || entry.focused) return;
715
+ if (entry.closed || entry.remaining <= 0 || entry.hovered || entry.focused || this._held()) return;
470
716
  entry.startedAt = Date.now();
471
717
  entry.timer = setTimeout(() => this._close(entry), entry.remaining);
472
718
  }
@@ -481,7 +727,7 @@ export class Message extends Component {
481
727
 
482
728
  /** @param {any} entry @returns {void} */
483
729
  _resume(entry) {
484
- if (entry.closed || entry.timer !== null || entry.hovered || entry.focused) return;
730
+ if (entry.closed || entry.timer !== null || entry.hovered || entry.focused || this._held()) return;
485
731
  if (entry.timeout === 0) return;
486
732
  if (entry.remaining <= 0) {
487
733
  this._close(entry);
@@ -495,7 +741,7 @@ export class Message extends Component {
495
741
  if (entry.closed) return;
496
742
  entry.closed = true;
497
743
  clearEntryTimers(entry);
498
- returnFocus(entry);
744
+ this._handOffFocus(entry);
499
745
  if (!this._queue.isActive(entry)) {
500
746
  this._queue.remove(entry);
501
747
  entry.node.remove();
@@ -505,6 +751,8 @@ export class Message extends Component {
505
751
  }
506
752
 
507
753
  entry.node.dataset.state = 'closing';
754
+ // The rest of a stack closes up at once, while this one leaves.
755
+ this._syncStack();
508
756
  if (!shouldAnimate()) {
509
757
  this._finish(entry);
510
758
  return;
@@ -520,12 +768,281 @@ export class Message extends Component {
520
768
  _finish(entry) {
521
769
  if (!this._entries.has(entry)) return;
522
770
  clearEntryTimers(entry);
771
+ this._resizeObserver?.unobserve(entry.node);
523
772
  entry.node.remove();
524
773
  this._entries.delete(entry);
774
+ const index = this._shown.indexOf(entry);
775
+ if (index !== -1) this._shown.splice(index, 1);
525
776
  this._queue.remove(entry);
777
+ if (this._shown.length === 0) {
778
+ // An emptied stack starts over: nothing is left to hold open.
779
+ this._pinned = false;
780
+ this._hovered = false;
781
+ }
782
+ const active = this.el.ownerDocument?.activeElement;
783
+ if (this._focusWithin && !(active && this.el.contains(active))) this._focusWithin = false;
784
+ this._refreshStack();
526
785
  this._releaseIfEmpty();
527
786
  }
528
787
 
788
+ /**
789
+ * Whether a stack holds every timer: it is open because someone is looking at it.
790
+ * @returns {boolean}
791
+ */
792
+ _held() {
793
+ return this._stack && (this._pinned || this._hovered || this._focusWithin);
794
+ }
795
+
796
+ /**
797
+ * Whether the stack piles from the foot: a bottom placement, or any placement on a phone. Read
798
+ * from the region's `--zx-message-dir`, which the stylesheet sets for both.
799
+ * @returns {boolean}
800
+ */
801
+ _fromEnd() {
802
+ const view = this.el.ownerDocument?.defaultView;
803
+ if (!view || typeof view.getComputedStyle !== 'function') return false;
804
+ return view.getComputedStyle(this.el).getPropertyValue('--zx-message-dir').trim() === '-1';
805
+ }
806
+
807
+ /**
808
+ * Puts the messages in document order: oldest first, or newest first in a stack that piles from
809
+ * the top. Moves only when the order is wrong. A moved message keeps focus, and does not play
810
+ * its entrance again (`data-entered`).
811
+ * @param {boolean} [fromEnd] Whether the stack piles from the foot, when already known.
812
+ * @returns {void}
813
+ */
814
+ _order(fromEnd = this._fromEnd()) {
815
+ const nodes = this._shown.map((entry) => entry.node).filter((node) => node.parentNode === this.el);
816
+ if (this._stack && !fromEnd) nodes.reverse();
817
+ const current = Array.from(this.el.children).filter((node) => nodes.includes(node));
818
+ if (current.every((node, index) => node === nodes[index])) return;
819
+ const doc = this.el.ownerDocument;
820
+ const active = doc?.activeElement;
821
+ const keep = active && this.el.contains(active) ? /** @type {HTMLElement} */ (active) : null;
822
+ this._reordering = true;
823
+ try {
824
+ for (const node of nodes) {
825
+ node.setAttribute('data-entered', '');
826
+ this.el.append(node);
827
+ }
828
+ if (keep?.isConnected && doc?.activeElement !== keep) keep.focus({ preventScroll: true });
829
+ } finally {
830
+ this._reordering = false;
831
+ }
832
+ }
833
+
834
+ /**
835
+ * Moves focus off a message that is closing with focus inside it. In a stack it goes to the
836
+ * same control of the next message (the one before, for the last), so a keyboard reader closes
837
+ * one message after another without leaving the stack; from the stack's last message it goes
838
+ * back to where it was before it came into the stack. A list hands it back to where it was
839
+ * before it came into the message.
840
+ * @param {any} entry Closing message.
841
+ * @returns {void}
842
+ */
843
+ _handOffFocus(entry) {
844
+ const active = entry.node.ownerDocument?.activeElement;
845
+ if (!this._stack || !active || !entry.node.contains(active)) {
846
+ returnFocus(entry);
847
+ return;
848
+ }
849
+ const nodes = Array.from(this.el.children);
850
+ const live = this._shown.filter((other) => !other.closed && other.node.parentNode === this.el)
851
+ .map((other) => other.node);
852
+ const at = nodes.indexOf(entry.node);
853
+ const after = live.filter((node) => nodes.indexOf(node) > at)
854
+ .sort((a, b) => nodes.indexOf(a) - nodes.indexOf(b))[0];
855
+ const before = live.filter((node) => nodes.indexOf(node) < at)
856
+ .sort((a, b) => nodes.indexOf(b) - nodes.indexOf(a))[0];
857
+ const neighbour = after ?? before;
858
+ const same = active.classList.contains('zx-message__close') ? '.zx-message__close' : '.zx-message__action';
859
+ const target = /** @type {HTMLElement|null} */ (neighbour?.querySelector(same) ?? neighbour?.querySelector('button'));
860
+ if (target) {
861
+ target.focus({ preventScroll: true });
862
+ return;
863
+ }
864
+ const back = /** @type {HTMLElement|null} */ (this._stackReturn);
865
+ if (back?.isConnected && typeof back.focus === 'function') {
866
+ this._stackReturn = null;
867
+ back.focus({ preventScroll: true });
868
+ return;
869
+ }
870
+ returnFocus(entry);
871
+ }
872
+
873
+ /**
874
+ * Settles a stack after anything that may open or close it: holds or releases the timers,
875
+ * lays the messages out, and reports a change of state.
876
+ * @returns {void}
877
+ */
878
+ _refreshStack() {
879
+ const held = this._held();
880
+ if (held !== this._wasHeld) {
881
+ this._wasHeld = held;
882
+ for (const entry of this._shown.slice()) {
883
+ if (held) this._pause(entry);
884
+ else this._resume(entry);
885
+ }
886
+ }
887
+ this._syncStack();
888
+ if (!this._stack) return;
889
+ const expanded = this.isExpanded();
890
+ if (expanded === this._wasExpanded) return;
891
+ this._wasExpanded = expanded;
892
+ this.emit(expanded ? 'expand' : 'collapse');
893
+ }
894
+
895
+ /**
896
+ * Lays a stack out from its messages' measured heights: each one's place, size, and clip, and
897
+ * the stack's own height. Runs again whenever a message changes size.
898
+ * @returns {void}
899
+ */
900
+ _syncStack() {
901
+ if (!this._stack || this._cleaned) return;
902
+ const root = /** @type {HTMLElement} */ (this.el);
903
+ // A region crossing the phone breakpoint changes the way it piles: keep Tab in visual order.
904
+ const fromEnd = this._fromEnd();
905
+ if (fromEnd !== this._pileFromEnd) {
906
+ this._pileFromEnd = fromEnd;
907
+ this._order(fromEnd);
908
+ }
909
+ const expanded = this.isExpanded();
910
+ root.setAttribute('data-state', expanded ? 'expanded' : 'collapsed');
911
+ const live = this._shown.filter((entry) => !entry.closed).reverse();
912
+ const layout = messageStackLayout(live.map((entry) => entry.node.offsetHeight), expanded);
913
+ this._syncOverflow(expanded, layout.size, fromEnd);
914
+ const step = expanded ? '--zx-message-gap' : '--zx-message-peek';
915
+ live.forEach((entry, index) => {
916
+ const item = layout.items[index];
917
+ const style = entry.node.style;
918
+ style.setProperty('--zx-message-y', stackLength(item.y, step));
919
+ style.setProperty('--zx-message-scale', String(round(item.scale)));
920
+ style.setProperty('--zx-message-z', String(entry.seq));
921
+ if (item.clip) style.setProperty('--zx-message-clip', `max(0px, ${stackLength(item.clip, step)})`);
922
+ else style.removeProperty('--zx-message-clip');
923
+ entry.node.setAttribute('data-depth', item.hidden ? 'hidden' : String(item.depth));
924
+ });
925
+ root.style.setProperty('--zx-message-stack-size', stackLength(layout.size, step));
926
+ // While the pointer is over an open stack it does not shrink under it: a message closing at
927
+ // the far end would otherwise pull the edge past the pointer and fold the stack it is reading.
928
+ if (expanded && this._hovered) {
929
+ const held = Math.max(parseFloat(root.style.getPropertyValue('--zx-message-stack-hold')) || 0,
930
+ root.getBoundingClientRect().height);
931
+ root.style.setProperty('--zx-message-stack-hold', `${round(held)}px`);
932
+ } else {
933
+ root.style.removeProperty('--zx-message-stack-hold');
934
+ }
935
+ }
936
+
937
+ /**
938
+ * An open floating stack taller than the viewport becomes a list that scrolls
939
+ * (`data-overflow`), the newest message in view, so every message stays reachable. An inline
940
+ * stack grows with the page and never needs it.
941
+ * @param {boolean} expanded Whether the stack is open.
942
+ * @param {MessageStackLength} size The open stack's height.
943
+ * @param {boolean} fromEnd Whether it piles from the foot.
944
+ * @returns {void}
945
+ */
946
+ _syncOverflow(expanded, size, fromEnd) {
947
+ const root = /** @type {HTMLElement} */ (this.el);
948
+ const view = root.ownerDocument?.defaultView;
949
+ let overflow = false;
950
+ if (expanded && this._floatingHost && view && typeof view.getComputedStyle === 'function') {
951
+ const gap = parseFloat(view.getComputedStyle(root).rowGap) || 0;
952
+ const rect = root.getBoundingClientRect();
953
+ // The region keeps the same offset from both viewport edges.
954
+ const edge = fromEnd ? view.innerHeight - rect.bottom : rect.top;
955
+ overflow = size.px + (size.steps * gap) > view.innerHeight - (2 * Math.max(0, edge)) + 0.5;
956
+ }
957
+ if (overflow === root.hasAttribute('data-overflow')) return;
958
+ root.toggleAttribute('data-overflow', overflow);
959
+ if (overflow && fromEnd) root.scrollTop = root.scrollHeight;
960
+ }
961
+
962
+ /**
963
+ * Wires the ways a stack opens and closes: pointer over it, focus inside it, a press on it (a
964
+ * tap included) that keeps it open until a press outside it, and Escape.
965
+ * @param {HTMLElement} root
966
+ * @returns {void}
967
+ */
968
+ _listenStack(root) {
969
+ this.listen(root, 'pointerenter', (event) => {
970
+ // An emptied stack does not open: Chrome enters the root again when the message under the
971
+ // pointer goes.
972
+ if (!this._stack || this._shown.length === 0) return;
973
+ if (/** @type {PointerEvent} */ (event).pointerType === 'touch') return;
974
+ this._hovered = true;
975
+ this._refreshStack();
976
+ });
977
+ this.listen(root, 'pointerleave', (event) => {
978
+ if (!this._stack || /** @type {PointerEvent} */ (event).pointerType === 'touch') return;
979
+ this._hovered = false;
980
+ this._refreshStack();
981
+ });
982
+ this.listen(root, 'pointerdown', (event) => {
983
+ if (!this._stack || this._pinned || this._shown.length === 0) return;
984
+ const target = /** @type {Element|null} */ (event.target);
985
+ // A control acts on its own message: closing the front one needs no opening first.
986
+ if (target?.closest?.('button, a[href], input, select, textarea, [tabindex]')) return;
987
+ this._pinned = true;
988
+ this._pinnedAt = now();
989
+ this._refreshStack();
990
+ });
991
+ const doc = root.ownerDocument;
992
+ if (doc) {
993
+ // A press elsewhere unpins the stack once the press has been handled — after the click
994
+ // handlers, so a button outside that toggles the stack (`isExpanded() ? collapse() :
995
+ // expand()`) sees it as it was, and a stack the press pinned stays pinned. Captured, so a
996
+ // handler stopping propagation does not keep the stack open.
997
+ this.listen(doc, 'click', (event) => {
998
+ if (!this._stack || root.contains(/** @type {Node} */ (event.target))) return;
999
+ const pressed = event.timeStamp;
1000
+ setTimeout(() => {
1001
+ if (this._cleaned || !this._pinned || this._pinnedAt >= pressed) return;
1002
+ this._pinned = false;
1003
+ this._refreshStack();
1004
+ }, 0);
1005
+ }, { capture: true });
1006
+ }
1007
+ this.listen(root, 'focusin', (event) => {
1008
+ if (!this._stack || this._reordering) return;
1009
+ if (!this._focusWithin) {
1010
+ const from = /** @type {FocusEvent} */ (event).relatedTarget;
1011
+ this._stackReturn = isNode(from) && !root.contains(/** @type {Node} */ (from))
1012
+ ? /** @type {Element} */ (from) : null;
1013
+ }
1014
+ this._focusWithin = true;
1015
+ this._refreshStack();
1016
+ });
1017
+ this.listen(root, 'focusout', (event) => {
1018
+ if (!this._stack || this._reordering) return;
1019
+ const to = /** @type {FocusEvent} */ (event).relatedTarget;
1020
+ if (isNode(to) && root.contains(/** @type {Node} */ (to))) return;
1021
+ this._focusWithin = false;
1022
+ this._refreshStack();
1023
+ });
1024
+ this.listen(root, 'keydown', (event) => {
1025
+ const key = /** @type {KeyboardEvent} */ (event);
1026
+ if (key.key !== 'Escape' || key.defaultPrevented || key.isComposing) return;
1027
+ if (!this._stack || this.options.expanded || !this.isExpanded()) return;
1028
+ // Escape folds the stack and hands focus back to where it was before it came in.
1029
+ key.preventDefault();
1030
+ this._pinned = false;
1031
+ this._hovered = false;
1032
+ const active = doc?.activeElement;
1033
+ if (active && root.contains(active)) {
1034
+ const back = this._stackReturn;
1035
+ this._stackReturn = null;
1036
+ if (back?.isConnected && typeof (/** @type {HTMLElement} */ (back)).focus === 'function') {
1037
+ /** @type {HTMLElement} */ (back).focus({ preventScroll: true });
1038
+ } else {
1039
+ /** @type {HTMLElement} */ (active).blur?.();
1040
+ }
1041
+ }
1042
+ this._refreshStack();
1043
+ });
1044
+ }
1045
+
529
1046
  /**
530
1047
  * Takes a floating region out of the document once its last toast has gone, so an emptied host
531
1048
  * is not left holding a region nobody uses. Inline areas stay: their element is the caller's.
@@ -575,17 +1092,19 @@ export class Message extends Component {
575
1092
  }
576
1093
 
577
1094
  /**
578
- * Finds or creates the floating region for a scope. A cached region is reused only while it is
579
- * still where it was put: a host emptied by `replaceChildren()` would otherwise keep receiving
580
- * toasts in a node nobody can see.
1095
+ * Finds or creates the floating region of a scope for one placement. A cached region is reused
1096
+ * only while it is still where it was put: a host emptied by `replaceChildren()` would otherwise
1097
+ * keep receiving toasts in a node nobody can see.
581
1098
  * @param {Element|string|null|undefined} scope
1099
+ * @param {unknown} [requested] Placement asked for; the default placement when absent or unknown.
582
1100
  * @returns {Message}
583
1101
  */
584
- static #floatingRegion(scope) {
1102
+ static #floatingRegion(scope, requested) {
585
1103
  let host = overlayScope(scope ?? null);
586
1104
  // A scope that has itself left the document cannot show anything; the toast still must be seen.
587
1105
  if (!host.isConnected) host = overlayScope(null);
588
- const existing = this.#regionFor(host);
1106
+ const placement = normalizeMessagePlacement(requested, Message.#placement);
1107
+ const existing = Message.#regionsOf(host).find((region) => region._placement === placement) ?? null;
589
1108
  if (existing && existing.el.isConnected && existing.el.parentElement === existing._placedIn) {
590
1109
  existing._rehome();
591
1110
  return existing;
@@ -595,10 +1114,12 @@ export class Message extends Component {
595
1114
  class: 'zx-message-region',
596
1115
  popover: 'manual',
597
1116
  role: 'status',
598
- ariaLive: 'polite'
1117
+ ariaLive: 'polite',
1118
+ dataset: { placement }
599
1119
  });
600
- const floating = new Message(region);
1120
+ const floating = new Message(region, { stack: Message.#stack });
601
1121
  floating._floatingHost = host;
1122
+ floating._placement = placement;
602
1123
  // A toast entry on the overlay stack: the registry of regions, and the reason a press on a
603
1124
  // toast dismisses no drawer or menu. Following the stack moves the region into a modal dialog
604
1125
  // when one opens and back out when it closes.
@@ -609,17 +1130,19 @@ export class Message extends Component {
609
1130
  }
610
1131
 
611
1132
  /**
612
- * The live floating region of a theme scope, from the overlay stack's toast entries.
1133
+ * The live floating regions of a theme scope — one per placement in use — from the overlay
1134
+ * stack's toast entries.
613
1135
  * @param {Element} host Theme scope.
614
- * @returns {Message|null}
1136
+ * @returns {Message[]}
615
1137
  */
616
- static #regionFor(host) {
1138
+ static #regionsOf(host) {
1139
+ const regions = [];
617
1140
  for (const entry of overlayStack.entries()) {
618
1141
  if (entry.kind === 'toast' && entry.owner instanceof Message && entry.owner._floatingHost === host) {
619
- return entry.owner;
1142
+ regions.push(entry.owner);
620
1143
  }
621
1144
  }
622
- return null;
1145
+ return regions;
623
1146
  }
624
1147
 
625
1148
  /** @param {Message} region Floating region whose last toast closed. @returns {void} */
@@ -635,6 +1158,104 @@ function normalizeKind(value) {
635
1158
  /** @type {MessageKind} */ (value) : 'info';
636
1159
  }
637
1160
 
1161
+ /**
1162
+ * Settles a floating-message placement: the value when it is one of the six, the fallback otherwise.
1163
+ * @param {unknown} value Requested placement.
1164
+ * @param {MessagePlacement} [fallback='top-end'] Placement used when the value is absent or unknown.
1165
+ * @returns {MessagePlacement}
1166
+ */
1167
+ export function normalizeMessagePlacement(value, fallback = DEFAULT_PLACEMENT) {
1168
+ return PLACEMENTS.has(/** @type {string} */ (value)) ? /** @type {MessagePlacement} */ (value) : fallback;
1169
+ }
1170
+
1171
+ /**
1172
+ * Settles a message highlight: `'border'` for `true` or `'border'`, `'animated'` for `'animated'`,
1173
+ * and null — the plain card — for anything else.
1174
+ * @param {unknown} value Requested highlight.
1175
+ * @returns {'border'|'animated'|null}
1176
+ */
1177
+ export function normalizeMessageHighlight(value) {
1178
+ if (value === true || value === 'border') return 'border';
1179
+ return value === 'animated' ? 'animated' : null;
1180
+ }
1181
+
1182
+ /**
1183
+ * Lays out a stack of messages from their heights, the front (newest) first.
1184
+ *
1185
+ * Open, the messages follow one another from the stack's edge. Collapsed, the front one sits at
1186
+ * the edge and the next two peek out behind it: each lined up with the front one's far edge, one
1187
+ * peek further out, a step smaller, and cut down to the strip that shows below the one in front of
1188
+ * it. The rest wait out of sight behind them.
1189
+ * @param {number[]} heights Height of each message in pixels, the front first.
1190
+ * @param {boolean} expanded Whether the stack is open.
1191
+ * @returns {MessageStackLayout}
1192
+ */
1193
+ export function messageStackLayout(heights, expanded) {
1194
+ const sizes = Array.from(heights ?? [], (height) => {
1195
+ const value = Number(height);
1196
+ return Number.isFinite(value) && value > 0 ? value : 0;
1197
+ });
1198
+ const front = sizes[0] ?? 0;
1199
+ let before = 0;
1200
+ const items = sizes.map((height, index) => {
1201
+ if (expanded) {
1202
+ const item = { depth: index, y: { px: before, steps: index }, scale: 1, clip: null, hidden: false };
1203
+ before += height;
1204
+ return item;
1205
+ }
1206
+ const depth = Math.min(index, STACK_PEEK);
1207
+ const scale = 1 - (depth * STACK_SCALE_STEP);
1208
+ return {
1209
+ depth,
1210
+ y: { px: front - height, steps: depth },
1211
+ scale,
1212
+ // Drawn at `scale`, one peek on screen is 1/scale of the message's own height.
1213
+ clip: depth === 0 ? null : { px: height, steps: -1 / scale },
1214
+ hidden: index > STACK_PEEK
1215
+ };
1216
+ });
1217
+ /** @type {MessageStackLength} */
1218
+ let size = { px: 0, steps: 0 };
1219
+ if (sizes.length > 0) {
1220
+ size = expanded
1221
+ ? { px: before, steps: sizes.length - 1 }
1222
+ : { px: front, steps: Math.min(sizes.length - 1, STACK_PEEK) };
1223
+ }
1224
+ return { items, size };
1225
+ }
1226
+
1227
+ /**
1228
+ * Writes a stack length as CSS.
1229
+ * @param {MessageStackLength} length
1230
+ * @param {string} step The custom property one step is.
1231
+ * @returns {string}
1232
+ */
1233
+ function stackLength(length, step) {
1234
+ return `calc(${round(length.px)}px + ${round(length.steps)} * var(${step}))`;
1235
+ }
1236
+
1237
+ /** @returns {number} The current time on the clock event time stamps use. */
1238
+ function now() {
1239
+ return typeof performance === 'object' && typeof performance.now === 'function' ? performance.now() : Date.now();
1240
+ }
1241
+
1242
+ /** @param {number} value @returns {number} Value rounded to two decimals, for inline styles. */
1243
+ function round(value) {
1244
+ return Math.round(value * 100) / 100;
1245
+ }
1246
+
1247
+ /**
1248
+ * Removes what a stack set on a message, when its area stops stacking.
1249
+ * @param {HTMLElement} node Message element.
1250
+ * @returns {void}
1251
+ */
1252
+ function clearStackStyle(node) {
1253
+ for (const name of ['--zx-message-y', '--zx-message-scale', '--zx-message-z', '--zx-message-clip']) {
1254
+ node.style.removeProperty(name);
1255
+ }
1256
+ node.removeAttribute('data-depth');
1257
+ }
1258
+
638
1259
  /** @param {unknown} value @returns {number} */
639
1260
  function normalizeTimeout(value) {
640
1261
  const timeout = Number(value);
@@ -759,3 +1380,16 @@ function restore(element, state) {
759
1380
  for (const [name, value] of state.attributes) element.setAttribute(name, value);
760
1381
  element.replaceChildren(...state.children);
761
1382
  }
1383
+
1384
+ /**
1385
+ * Fired when a stack opens: the pointer came over it, focus came into it, it was pressed, or
1386
+ * `expand()` was called.
1387
+ * @event Message#expand
1388
+ * @type {CustomEvent<Record<string, never>>}
1389
+ */
1390
+
1391
+ /**
1392
+ * Fired when a stack closes again.
1393
+ * @event Message#collapse
1394
+ * @type {CustomEvent<Record<string, never>>}
1395
+ */