@zeyos/zx 5.3.0 → 5.5.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 (114) hide show
  1. package/CHANGELOG.md +125 -0
  2. package/README.md +49 -16
  3. package/dist/types/components/app-sidebar/app-sidebar.d.ts +33 -0
  4. package/dist/types/components/badge/badge.d.ts +5 -4
  5. package/dist/types/components/datebox/date-range-box.d.ts +15 -2
  6. package/dist/types/components/datebox/datebox.d.ts +37 -3
  7. package/dist/types/components/kbd/kbd.d.ts +41 -0
  8. package/dist/types/components/launcher/launcher.d.ts +4 -2
  9. package/dist/types/components/prose/prose.d.ts +69 -0
  10. package/dist/types/components/questionnaire/questionnaire.d.ts +0 -36
  11. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -0
  12. package/dist/types/components/tag-picker/tag-picker.d.ts +11 -5
  13. package/dist/types/components/tree/tree.d.ts +44 -3
  14. package/dist/types/core/icons.d.ts +22 -1
  15. package/dist/types/index.d.ts +4 -2
  16. package/dist/types/internal/app-rail.d.ts +10 -3
  17. package/dist/types/internal/row-actions.d.ts +151 -0
  18. package/dist/zx-zeyos.esm.js +264 -82
  19. package/dist/zx-zeyos.esm.min.js +4 -4
  20. package/dist/zx.css +1288 -439
  21. package/dist/zx.esm.js +952 -392
  22. package/dist/zx.esm.min.js +6 -6
  23. package/dist/zx.global.js +952 -392
  24. package/dist/zx.global.min.js +6 -6
  25. package/dist/zx.min.css +1 -1
  26. package/docs/api.json +112 -4
  27. package/docs/llms.md +433 -38
  28. package/docs/llms.txt +21 -1
  29. package/package.json +1 -1
  30. package/src/components/account-menu/account-menu.js +2 -2
  31. package/src/components/app-rail/app-rail.css +11 -11
  32. package/src/components/app-sidebar/app-sidebar.css +90 -17
  33. package/src/components/app-sidebar/app-sidebar.js +120 -12
  34. package/src/components/badge/badge.css +33 -20
  35. package/src/components/badge/badge.js +5 -4
  36. package/src/components/breadcrumb/breadcrumb.css +28 -3
  37. package/src/components/breadcrumb/breadcrumb.js +2 -2
  38. package/src/components/button/button.css +24 -13
  39. package/src/components/button/button.js +20 -2
  40. package/src/components/calendar/calendar.css +14 -4
  41. package/src/components/card-view/card-view.js +2 -2
  42. package/src/components/chart/chart.js +20 -5
  43. package/src/components/check-button/check-button.css +11 -3
  44. package/src/components/check-button/check-button.js +3 -3
  45. package/src/components/context-menu/context-menu.css +7 -1
  46. package/src/components/date-picker/date-picker.css +6 -0
  47. package/src/components/date-picker/date-picker.js +5 -5
  48. package/src/components/date-picker/date-range-picker.css +6 -0
  49. package/src/components/date-picker/date-range-picker.js +3 -3
  50. package/src/components/date-picker/month-picker.js +3 -3
  51. package/src/components/date-picker/time-picker.css +6 -0
  52. package/src/components/datebox/date-range-box.js +30 -6
  53. package/src/components/datebox/datebox.js +44 -7
  54. package/src/components/dialog/dialog.css +0 -1
  55. package/src/components/dialog/dialog.js +2 -1
  56. package/src/components/dock/dock.js +2 -2
  57. package/src/components/dropdown/dropdown.css +2 -1
  58. package/src/components/entity-ref/entity-ref.css +8 -1
  59. package/src/components/file-item/file-item.css +1 -1
  60. package/src/components/finder/finder.js +2 -2
  61. package/src/components/groupbox/groupbox.js +2 -2
  62. package/src/components/kanban-view/kanban-view.css +8 -4
  63. package/src/components/kanban-view/kanban-view.js +3 -3
  64. package/src/components/kbd/kbd.css +64 -0
  65. package/src/components/kbd/kbd.js +121 -0
  66. package/src/components/launcher/launcher.css +30 -25
  67. package/src/components/launcher/launcher.js +15 -21
  68. package/src/components/list-toolbar/list-toolbar.css +7 -1
  69. package/src/components/menu-button/menu-button.css +9 -2
  70. package/src/components/message/message.css +6 -2
  71. package/src/components/message/message.js +2 -2
  72. package/src/components/module-bar/module-bar.css +11 -1
  73. package/src/components/multi-value-editor/multi-value-editor.js +4 -4
  74. package/src/components/navigation-bar/navigation-bar.css +3 -2
  75. package/src/components/pagination/pagination.js +2 -2
  76. package/src/components/panel/panel.js +2 -2
  77. package/src/components/prose/prose.css +53 -0
  78. package/src/components/prose/prose.js +152 -0
  79. package/src/components/questionnaire/questionnaire.css +7 -17
  80. package/src/components/questionnaire/questionnaire.js +16 -1
  81. package/src/components/rating/rating.css +3 -1
  82. package/src/components/search/search.js +2 -2
  83. package/src/components/select/glyphs.js +3 -3
  84. package/src/components/select/select.css +35 -7
  85. package/src/components/select/select.js +4 -4
  86. package/src/components/stat-tile/stat-tile.css +56 -2
  87. package/src/components/stat-tile/stat-tile.js +25 -2
  88. package/src/components/stepper/stepper.css +2 -1
  89. package/src/components/stepper/stepper.js +3 -3
  90. package/src/components/tabbox/tabbox.css +2 -2
  91. package/src/components/tabbox/tabbox.js +2 -2
  92. package/src/components/table/table.css +52 -16
  93. package/src/components/table/table.js +7 -5
  94. package/src/components/tag-picker/tag-picker.css +56 -43
  95. package/src/components/tag-picker/tag-picker.js +21 -16
  96. package/src/components/tree/tree.css +44 -0
  97. package/src/components/tree/tree.js +97 -9
  98. package/src/components/value-list/value-list.css +25 -4
  99. package/src/components/value-list/value-list.js +2 -1
  100. package/src/components/view/record-view.js +3 -3
  101. package/src/components/view-settings/view-settings.css +2 -1
  102. package/src/components/workspace-switcher/workspace-switcher.js +3 -3
  103. package/src/core/icons.js +34 -3
  104. package/src/elements/define.js +1 -0
  105. package/src/index.js +4 -2
  106. package/src/internal/app-rail.js +5 -1
  107. package/src/internal/row-actions.js +203 -0
  108. package/styles/base.css +26 -1
  109. package/styles/prose.css +306 -0
  110. package/styles/tokens/dark.css +108 -103
  111. package/styles/tokens/global.css +24 -9
  112. package/styles/tokens/semantic.css +520 -198
  113. package/styles/tokens/themes.css +9 -0
  114. package/styles/zx.css +3 -0
package/CHANGELOG.md CHANGED
@@ -8,6 +8,131 @@ and friends remain the complete record.
8
8
 
9
9
  ## Unreleased
10
10
 
11
+ ## 5.5.0 — 2026-11-03
12
+
13
+ Calm and precise: a reading register beside the interface one, one row rhythm, navigation that
14
+ recedes, figures without boxes, one chip shape, keycaps everywhere, and colour overrides that reach
15
+ every theme region.
16
+
17
+ ### Added
18
+
19
+ - **Reading type.** `.zx-prose` sets authored content — a document, a record's notes, a message
20
+ body, an assistant's answer — in its own register: `--zx-font-prose`, `--zx-prose-size`,
21
+ `--zx-prose-leading` and `--zx-prose-measure`, so a product can set its documents in a serif
22
+ without touching a control. Headings, lists, quotes, code, marks, frameless tables and figures
23
+ are covered; `data-size="sm"` sets prose at the interface size and `data-zx-measure="full"` drops
24
+ the measure. `.zx-callout` sets a paragraph apart: neutral by default, `data-kind` for a status,
25
+ `data-tone` for a category. `proseAnchors(root)` adds a revealed copy-link to every heading with
26
+ an id.
27
+ - **`kbd()`** — keycaps for every shortcut hint, with platform glyphs for `Mod` and the named keys
28
+ (`keyLabels()` returns the labels without DOM). Button shortcuts, the Launcher's hints and the
29
+ Questionnaire's keys use it; menu shortcuts share its type.
30
+ - **Row rhythm and one type base.** `--zx-row-height` (36px by default) follows the control height,
31
+ and Table body rows are exactly that tall. `--zx-text-base` drives every `--zx-text-*` step, so
32
+ changing the base keeps the hierarchy; setting `--zx-text-md` alone still moves only the control
33
+ size.
34
+ - **Revealed affordances.** `data-zx-reveal-host` / `data-zx-reveal` show a secondary action while
35
+ its row is pointed at, focused, current, selected or has a menu open — keeping its space and its
36
+ tab order, and always visible on touch screens and under contrast preferences. TreeView
37
+ `rowActions(node)` and AppSidebar item `actions` build on it: up to two icon buttons per row, the
38
+ rest in an overflow menu, every label naming its row, the same actions in a context menu, and the
39
+ APG keyboard maps unchanged.
40
+ - **StatTile** `variant: 'plain'` (no frame or fill; the figure at the title weight in tabular
41
+ figures) and `emphasis` (one figure leads its row).
42
+ - **Datebox, DateTimeBox and DateRangeBox** take `displayFormat`, shown while the field is not
43
+ focused, so a screen reads one date format; `format` stays the typing format.
44
+ - **Named icon sizes** per role (`ICON_SIZE`) in the icon module; every chevron, dismiss and check in
45
+ the components uses them, and the text glyphs that stood in for icons are icons.
46
+ - New roles: `--zx-color-text-chrome` (navigation at rest, above 7:1 on the chrome),
47
+ `--zx-color-border-chrome` (the line where a chrome column meets the canvas: none in light, a
48
+ hairline in dark, under `prefers-contrast: more` and in forced colours), `--zx-radius-panel` (a
49
+ panel's corner, concentric with the rounded items it holds) and `--zx-weight-title`.
50
+ - Theme studio: text size moves the whole type scale; **Rows** (Compact, Default, Relaxed) and
51
+ **Reading** (typeface, size, measure) controls with a prose specimen; a **Paper** neutral tint
52
+ whose warmth reaches the page and tapers away in dark; and the **Folio** preset
53
+ (`data-zx-preset="folio"`): ink blue on paper with a serif for reading. Ocean takes compact rows.
54
+
55
+ ### Changed
56
+
57
+ - **Colour overrides on `:root` reach every theme region.** Every colour role is declared once on
58
+ `:root`, as `light-dark(<light>, <dark>)` where the themes differ, and a theme element sets only
59
+ `color-scheme`; an application's or the theme studio's override now reaches light, dark, auto and
60
+ nested regions alike. Browsers without `light-dark()` keep the per-theme blocks. Script that reads
61
+ a colour token as text receives the `light-dark()` expression — resolve it through a probe's
62
+ computed colour, as Chart now does. Rendering is unchanged.
63
+ - **Focus is one opaque 2px accent line** that reaches 3.5:1 or better on every surface and row,
64
+ for every preset and tint, in both themes.
65
+ - **State is never lost under the pointer:** selected, current and striped table rows, pressed
66
+ CheckButtons, the current navigation item and pressed list tools keep their fill on hover, and a
67
+ trigger stays pressed while its menu is open. Hover now shows in dark on default buttons and
68
+ CheckButtons.
69
+ - Menus, listboxes, the tag picker and the Launcher use the concentric panel corner (6px at the
70
+ default base); segmented thumbs are concentric with their tracks.
71
+ - Navigation labels rest one ink step under the content and come up to the full text colour on
72
+ hover, focus and when current. Breadcrumb ancestors shorten before the current page does.
73
+ - **One chip shape.** Badge takes its height from the row and keeps 12px text at both sizes; a
74
+ status is a pill with a 6px dot, a toned tag a small rectangle. TagPicker draws its tags with the
75
+ same construction (they now carry `zx-badge`). Chips use one fill and no border; their remove
76
+ buttons sit inset.
77
+ - Placeholder and border inks used as text or data marks (Stepper's "Optional", StatTile's
78
+ sparkline, Rating's empty stars, ViewSettings' lock, Select's neutral status icon) moved to the
79
+ muted and subtle text roles. Counts and badges use tabular figures; avatar stacks overlap less
80
+ and their overflow chip is opaque. In dark, a resting surface gets a lit top edge instead of a
81
+ shadow.
82
+ - Layouts: reading surfaces (wiki article, issue description, mail body, assistant answers, record
83
+ notes) use `.zx-prose`; property lists share one label column per inspector and one value edge;
84
+ header rules appear once content scrolls under them; record pages set their figures on the page.
85
+
86
+ ### Fixed
87
+
88
+ - FileItem's progress track used `--zx-radius-pill`, which nothing declares.
89
+ - The documentation site's header showed a stale version when served from source.
90
+
91
+ ## 5.4.0 — 2026-10-29
92
+
93
+ Glass rebuilt as a lit pane with a body under it, five more materials in the theme studio, and a
94
+ choosing guide at the head of the agent reference.
95
+
96
+ ### Added
97
+
98
+ - Five materials in the theme studio beside Flat, Glass and Deep glass: **Frost** (milk glass —
99
+ heavy diffusion, no coherent reflection), **Smoke** (tinted glass with a real body that darkens
100
+ the scene behind it), **Paper** (opaque and matte: a contact shadow, a modest cast and a fine
101
+ tooth), **Satin** (opaque and brushed: a soft sheen across raised surfaces, a bright rim on
102
+ controls) and **Enamel** (an opaque body under a glossy coat: a narrow highlight along the top
103
+ edge and a darker foot). The opaque three filter nothing, so they render cheaply and survive
104
+ every fallback unchanged. Every material is a complete recipe over the same roles, exported as
105
+ token overrides.
106
+ - Six glass ingredients the stylesheet declares per theme and every recipe composes —
107
+ `--zx-color-glass-rim`, `-ring`, `-lift`, `-shade`, `-edge`, `-tint` — and `--zx-glass-grain`,
108
+ a faint grey tooth; one material recipe therefore serves light and dark alike. The shade is a
109
+ pane's own body — white in light, black in dark — so every translucent material keeps a floor
110
+ under which the scene cannot drag text contrast, and the browser smoke suite asserts that floor.
111
+ - The agent reference opens with "Choosing what to build with": every screen mapped to the layout
112
+ to start from, every job to its component, the theming decisions an application makes, and
113
+ what never to build by hand; both `llms.txt` indexes and the README carry the layout-first rule.
114
+
115
+ ### Changed
116
+
117
+ - **Glass is a lit pane, not a grey tint.** The stylesheet's own material (the studio's Glass) is
118
+ rebuilt: a thinner base under a white lift from the top edge instead of a grey wash, the light
119
+ on the pane's edge — a near-white top rim, a hairline inner ring and, in dark, a cut outer line —
120
+ rather than a corner specular on its face, a filter that saturates so the colour behind survives
121
+ the blur, and a faint accent caustic at the far corner. The lift stops short of the pane's
122
+ middle, so the face stays optically quiet. **Deep glass** is a genuinely thick pane rather than
123
+ the same numbers turned up: a lit top line, a darker foot, a narrow inner glow, one faint
124
+ diagonal band, more refraction and a fine grain under the reflection. Applications that override
125
+ `--zx-overlay-surface-image`, `--zx-glass-overlay-shadow` or the glass filters keep their
126
+ values; everything else follows.
127
+
128
+ ### Fixed
129
+
130
+ - A toast's status tint reached only the info colour: the tint was written into the toast image
131
+ token, which resolves at the theme root. The toast composes its own tint over the shared image.
132
+ - Without `backdrop-filter` support, cards, navigation chrome and controls kept their translucent
133
+ glass colours; the fallback now makes every glass role opaque, as the overlays already were.
134
+ - A resting card on an opaque material took the overlay's elevation.
135
+
11
136
  ## 5.3.0 — 2026-10-29
12
137
 
13
138
  The record collection's toolbar, chips, drawers and pager become one shared composition in the
package/README.md CHANGED
@@ -95,7 +95,8 @@ ZeyOS binding — see `src/zeyos/modules.js`.
95
95
  | API | Description |
96
96
  | --- | --- |
97
97
  | `button()`, `buttonGroup()` | Styled native button and grouped-button factories. |
98
- | `badge()`, `badgeGroup()` | Status-pill factories with semantic kinds, variants, and sizes. |
98
+ | `badge()`, `badgeGroup()` | Status pills with semantic kinds, variants, and sizes; with a `tone`, a categorical tag. |
99
+ | `kbd()` | Keycaps for every shortcut hint, with platform glyphs for `Mod` and the named keys. |
99
100
  | `CheckButton` | Two-state pressed button with optional state-specific labels. |
100
101
  | `Toggle` | Native-button switch with a separate submitted value. |
101
102
  | `Search` | Search input with debounced input, submit, and clear events. |
@@ -108,7 +109,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
108
109
  | `DatePicker` | APG calendar grid with bounds, week numbers, and optional time selection. |
109
110
  | `MonthPicker` | Twelve-month grid with year navigation. |
110
111
  | `TimePicker` | Segmented local-time picker. |
111
- | `Datebox`, `DateTimeBox` | Formatted date input and its date-time factory variant. |
112
+ | `Datebox`, `DateTimeBox` | Formatted date input and its date-time factory variant; `displayFormat` shows a screen's own date format while the field is not focused. |
112
113
  | `DateRangePicker` | Two-month range calendar with presets, night bounds, and range preview. |
113
114
  | `DateRangeBox` | Formatted date-range input with an anchored range calendar. |
114
115
  | `Timebox` | Segmented signed or unsigned duration input. |
@@ -144,7 +145,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
144
145
  | `DataFilter` | Declarative select, text, and custom filters for client-side row sets. |
145
146
  | `FilterPanel` | Typed filter form built from a server's own field metadata, drafted then applied. |
146
147
  | `ListToolbar` | Search, result count, view switch, and badged tools above a record view. |
147
- | `TreeView` | APG tree with lazy children, filtering, and tri-state checkboxes. |
148
+ | `TreeView` | APG tree with lazy children, filtering, tri-state checkboxes, and hover-revealed `rowActions`. |
148
149
  | `Finder` | Miller-columns hierarchy browser with an optional preview pane. |
149
150
  | `Pagination` | Page, page-size, and load-more pager, with the pure `paginationRange()` helper. |
150
151
 
@@ -170,7 +171,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
170
171
  | `Avatar` | Fixed-size user image with initials fallback and optional presence. |
171
172
  | `Groupbox` | Collapsible section backed by native `<details>`. |
172
173
  | `Card` | Semantic content/record surface with media, native title link, actions, and footer. |
173
- | `StatTile`, `statTile()` | Labelled metric with optional delta, sparkline, and loading state. |
174
+ | `StatTile`, `statTile()` | Labelled metric with optional delta, sparkline, and loading state; `variant: 'plain'` sets the figure on the page, and `emphasis` lets one figure lead. |
174
175
  | `Aurora` | One- to four-colour ambient canvas light; chrome, raised content, and overlays respond through shared material tokens. |
175
176
  | `Launcher` | Cmd/Ctrl+K application and record launcher with ranked local items and abortable grouped sources. |
176
177
  | `Panel` | Framed, optionally collapsible section with a footer. |
@@ -191,6 +192,25 @@ ZeyOS binding — see `src/zeyos/modules.js`.
191
192
  | `skeleton()`, `skeletonText()`, `skeletonTable()` | Placeholders shaped like the content that is coming. |
192
193
  | `truncate()` | Clamps text to a number of lines, with the full value on hover. |
193
194
 
195
+ ## Start from a layout
196
+
197
+ The [layout gallery](https://zx.zeyos.com/layouts) holds complete, working screens on one shared
198
+ application shell, each with its source. Start a new screen from the closest one and change the
199
+ data and the copy, rather than composing components on a blank page: the columns, toolbar,
200
+ drawers, states, and keyboard map come with it.
201
+
202
+ - **Templates** — complete applications: `mail`, `issue-tracker`, `wiki`, `ai-chat`,
203
+ `agent-workspace`, `invoice-editor`, `item-inventory`, `workflows`, `infrastructure`, `crm`.
204
+ - **Patterns** — single screens: `master-detail`, `record-collection` (any list of records as a
205
+ table, list, cards, gallery, or board), `dashboard`, `inbox`, `record-page`, `agent-chat`,
206
+ `record-wizard`, `checkout-wizard`, `settings-workspace`, `system-states`, `zeyos-invoices`.
207
+
208
+ `layouts.html#<id>` opens one; `layout.html#<id>` shows it alone. The shell helpers
209
+ (`layouts/kit.js`, `kit.css`) and the record-screen composition (`createOverview()` in
210
+ `layouts/overview.js`, `overview.css`) are served beside the layouts and are meant to be copied into an application.
211
+ The agent reference ([docs/llms.md](docs/llms.md), "Choosing what to build with") maps every
212
+ screen to a layout and every job to a component.
213
+
194
214
  ## Talking to ZeyOS
195
215
 
196
216
  Use `@zeyos/client` for ZeyOS authentication, transport, generated resource operations, and runtime
@@ -267,14 +287,21 @@ region of it — override those tokens rather than switching a mode:
267
287
  }
268
288
  ```
269
289
 
290
+ Data rows follow the control height through `--zx-row-height` (36px by default), and type is one
291
+ base, `--zx-text-base` (14px), with every `--zx-text-*` step derived from it. Authored content —
292
+ a document, a record's notes, a message — takes a second, separate register: wrap it in
293
+ `.zx-prose` and it reads `--zx-font-prose`, `--zx-prose-size`, `--zx-prose-leading` and
294
+ `--zx-prose-measure`, so a product can set its documents in a serif without touching a control.
295
+ `.zx-callout` sets a paragraph apart, neutral unless it is a status or a category.
296
+
270
297
  A second attribute picks the **accent**, orthogonally to the theme:
271
298
 
272
299
  ```html
273
300
  <html data-zx-theme="dark" data-zx-preset="ocean">
274
301
  ```
275
302
 
276
- Six presets ship — `zx` (the ZeyOS green, and the default), `zeyos`, `ocean`, `violet`, `rose`,
277
- `slate`. Each is five declarations of the tier-1 accent ramp that the semantic tier resolves
303
+ Seven presets ship — `zx` (the ZeyOS green, and the default), `zeyos`, `ocean`, `violet`, `rose`,
304
+ `slate`, `folio`. Each is five declarations of the tier-1 accent ramp that the semantic tier resolves
278
305
  through, so a preset rethemes light, dark, and auto at once:
279
306
 
280
307
  ```css
@@ -294,18 +321,24 @@ ink in both themes, so the one solid accent on a screen never turns into a brigh
294
321
  [theme studio](https://zx.zeyos.com/theme.html) renders every component family under a live theme and
295
322
  exports the result.
296
323
 
297
- Anything beyond the accent is a semantic token override, without reaching into component CSS:
324
+ The studio's **Material** is how surfaces answer light — Glass (the default, a thin lit pane),
325
+ Deep glass, Frost (milk glass), Smoke (tinted glass), Paper, Satin and Enamel (opaque: matte,
326
+ brushed or glazed, no blur), or Flat. Each is a set of token overrides composed from six per-theme ingredients
327
+ (`--zx-color-glass-rim`, `-ring`, `-lift`, `-shade`, `-edge`, `-tint`), so one recipe serves
328
+ light and dark, and reduced-transparency, high-contrast and forced-colour settings restore solid
329
+ surfaces on their own.
330
+
331
+ Anything beyond the accent is a semantic token override, without reaching into component CSS.
332
+ Declare it once on `:root`, as `light-dark(<light>, <dark>)` where the two appearances differ: a
333
+ theme attribute only picks which half a region reads, so the override reaches light, dark, auto,
334
+ and nested regions alike, and the roles derived from it follow.
298
335
 
299
336
  ```css
300
- :root[data-zx-theme="acme"] {
301
- --zx-color-bg-page: #f4f1eb;
302
- --zx-color-bg-surface: #fffdf8;
303
- --zx-color-bg-control: #ffffff;
304
- --zx-color-border-control: #978e80;
305
- --zx-color-text: #26221d;
306
- --zx-color-text-muted: #655e54;
307
- --zx-color-accent: #176b52;
308
- --zx-color-on-accent: #ffffff;
337
+ :root {
338
+ --zx-color-bg-page: light-dark(#f4f1eb, #1a1815);
339
+ --zx-color-bg-surface: light-dark(#fffdf8, #22201c);
340
+ --zx-color-text: light-dark(#26221d, #ece6dc);
341
+ --zx-color-text-muted: light-dark(#655e54, #a89f92);
309
342
  }
310
343
  ```
311
344
 
@@ -97,6 +97,11 @@ export type AppSidebarOptions = {
97
97
  * Navigation accessible label.
98
98
  */
99
99
  label?: string;
100
+ /**
101
+ * Name of a destination's overflow menu when its
102
+ * `actions` fold; every action name is followed by the destination's label.
103
+ */
104
+ moreLabel?: string;
100
105
  /**
101
106
  * Expanded header content;
102
107
  * in the modules layout, content above every module's menu.
@@ -221,6 +226,8 @@ export type AppSidebarOptions = {
221
226
  * switch between presentations. Turn it off when the choice lives elsewhere — an account menu,
222
227
  * through `presentationChoice()`.
223
228
  * @property {string} [label='Applications'] Navigation accessible label.
229
+ * @property {string} [moreLabel='More actions'] Name of a destination's overflow menu when its
230
+ * `actions` fold; every action name is followed by the destination's label.
224
231
  * @property {Node|string|number|{toElement: () => Node|null}|null} [header=null] Expanded header content;
225
232
  * in the modules layout, content above every module's menu.
226
233
  * @property {Node|string|number|{toElement: () => Node|null}|null} [footer=null] Expanded sticky footer content.
@@ -271,6 +278,12 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
271
278
  _stripTooltips: any[];
272
279
  _shownId: string | number;
273
280
  _modeAbort: AbortController;
281
+ /** @type {Map<string, import('../../internal/row-actions.js').RowActionStrip>} Destinations' actions, by id. */
282
+ _strips: Map<string, import('../../internal/row-actions.js').RowActionStrip>;
283
+ /** @type {import('../context-menu/context-menu.js').ContextMenu|null} */
284
+ _rowMenu: import('../context-menu/context-menu.js').ContextMenu | null;
285
+ /** @type {HTMLElement|null} The list the row menu is attached to. */
286
+ _rowMenuList: HTMLElement | null;
274
287
  static cssName: string;
275
288
  /** @type {Readonly<AppSidebarOptions>} */
276
289
  static defaults: Readonly<AppSidebarOptions>;
@@ -504,6 +517,26 @@ export declare class AppSidebar extends Component<AppSidebarOptions> {
504
517
  * @returns {HTMLElement}
505
518
  */
506
519
  _sectionRow(item: AppNavItem, level: number): HTMLElement;
520
+ /**
521
+ * Builds a destination's action strip, when it lists actions.
522
+ * @param {AppNavItem} item Destination.
523
+ * @returns {import('../../internal/row-actions.js').RowActionStrip|null}
524
+ */
525
+ _renderRowActions(item: AppNavItem): import('../../internal/row-actions.js').RowActionStrip | null;
526
+ /**
527
+ * Makes the actions of the row holding focus Tab stops, and every other row's not.
528
+ * @param {EventTarget|null} target What took focus.
529
+ * @returns {void}
530
+ */
531
+ _syncActionStops(target: EventTarget | null): void;
532
+ /**
533
+ * Destroys the destinations' action strips, and with `menu` the row menu bound to the list.
534
+ * @param {{menu?: boolean}} [options={}]
535
+ * @returns {void}
536
+ */
537
+ _dropRowActions({ menu }?: {
538
+ menu?: boolean;
539
+ }): void;
507
540
  /** @param {Event} event @returns {void} */
508
541
  _onTreeClick(event: Event): void;
509
542
  /** @param {KeyboardEvent} event @returns {void} */
@@ -15,8 +15,8 @@ export type BadgeOptions = {
15
15
  /**
16
16
  * Categorical colour — a project, a label, a module — from
17
17
  * the tone palette rather than the status set, so a tag never reads as a warning. When set it
18
- * decides the colour and `kind` is ignored for it; `variant` still applies. Unknown names are
19
- * ignored.
18
+ * decides the colour and the shape — a tag's small corners instead of a status pill — and `kind`
19
+ * is ignored for it; `variant` still applies. Unknown names are ignored.
20
20
  */
21
21
  tone?: BadgeTone | null;
22
22
  /**
@@ -42,8 +42,9 @@ export type BadgeOptions = {
42
42
  */
43
43
  export declare const BADGE_TONES: ReadonlyArray<BadgeTone>;
44
44
  /**
45
- * Creates a status pill: a small, non-interactive label carrying a semantic colour — or, with
46
- * `tone`, a categorical one.
45
+ * Creates a chip: a small, non-interactive label carrying a semantic colour as a status pill — or,
46
+ * with `tone`, a categorical one as a tag. `TagPicker` builds its tags with it, so a label has one
47
+ * construction wherever it appears.
47
48
  *
48
49
  * The badge is plain text content, so it needs no ARIA of its own. A badge without a label but
49
50
  * with a `title` is named for assistive technology through `role="img"`.
@@ -17,9 +17,16 @@ export type DateRangeBoxOptions = {
17
17
  */
18
18
  end?: Date | number | string | null;
19
19
  /**
20
- * Kernel date format used for both endpoints.
20
+ * Kernel date format the reader types for both endpoints,
21
+ * shown while the field has focus. Numeric tokens only, since it is parsed.
21
22
  */
22
23
  format?: string;
24
+ /**
25
+ * Format both endpoints are shown in while the field
26
+ * does not have focus. It is never parsed, so it may use any `formatDate()` token, month and
27
+ * weekday names included. Null shows `format`.
28
+ */
29
+ displayFormat?: string | null;
23
30
  /**
24
31
  * Text placed between the two formatted dates.
25
32
  */
@@ -122,9 +129,11 @@ export declare class DateRangeBox extends Component<DateRangeBoxOptions> {
122
129
  _originalAriaDisabled: string;
123
130
  _originalClearable: string;
124
131
  _format: string;
132
+ _displayFormat: string;
125
133
  _separator: string;
126
134
  _disabled: boolean;
127
135
  _open: boolean;
136
+ _focused: boolean;
128
137
  _position: import("../../core/position.js").PositionController;
129
138
  _range: import("../date-picker/date-range-picker.js").DateRange | {
130
139
  start: unknown;
@@ -209,7 +218,11 @@ export declare class DateRangeBox extends Component<DateRangeBoxOptions> {
209
218
  _clamp(range: DateRange): DateRange;
210
219
  /** @returns {string} */
211
220
  _placeholder(): string;
212
- /** @returns {void} */
221
+ /**
222
+ * Writes the range into the input: in the typing format while the input has focus, in the
223
+ * display format otherwise. Text that is already there is left alone, so the caret stays put.
224
+ * @returns {void}
225
+ */
213
226
  _syncDisplay(): void;
214
227
  /** A disabled box offers no clear button: there is nothing it could do. @returns {void} */
215
228
  _syncClear(): void;
@@ -6,9 +6,16 @@ export type DateboxOptions = {
6
6
  */
7
7
  value?: Date | number | string | null;
8
8
  /**
9
- * Kernel date format.
9
+ * Kernel date format the reader types, shown while the
10
+ * field has focus. Numeric tokens only (`%d %e %m %Y %y %H %M %S`), since it is parsed.
10
11
  */
11
12
  format?: string;
13
+ /**
14
+ * Format the field shows while it does not have focus,
15
+ * so a date reads as the rest of the screen writes dates. It is never parsed, so it may use any
16
+ * `formatDate()` token, month and weekday names included. Null shows `format`.
17
+ */
18
+ displayFormat?: string | null;
12
19
  /**
13
20
  * Append `%H:%M` and show time controls.
14
21
  */
@@ -62,7 +69,11 @@ export type DateboxUnit = 'date' | 'seconds';
62
69
  /**
63
70
  * @typedef {Object} DateboxOptions
64
71
  * @property {Date|number|string|null} [value=null] Date, Unix seconds, or formatted string.
65
- * @property {string} [format='%d.%m.%Y'] Kernel date format.
72
+ * @property {string} [format='%d.%m.%Y'] Kernel date format the reader types, shown while the
73
+ * field has focus. Numeric tokens only (`%d %e %m %Y %y %H %M %S`), since it is parsed.
74
+ * @property {string|null} [displayFormat=null] Format the field shows while it does not have focus,
75
+ * so a date reads as the rest of the screen writes dates. It is never parsed, so it may use any
76
+ * `formatDate()` token, month and weekday names included. Null shows `format`.
66
77
  * @property {boolean} [time=false] Append `%H:%M` and show time controls.
67
78
  * @property {Date|null} [min=null] Earliest selectable date.
68
79
  * @property {Date|null} [max=null] Latest selectable date.
@@ -90,8 +101,10 @@ export declare class Datebox extends Component<DateboxOptions> {
90
101
  _originalAriaDisabled: string;
91
102
  _originalClearable: string;
92
103
  _format: string;
104
+ _displayFormat: string;
93
105
  _disabled: boolean;
94
106
  _open: boolean;
107
+ _focused: boolean;
95
108
  _position: import("../../core/position.js").PositionController;
96
109
  _min: Date;
97
110
  _max: Date;
@@ -143,7 +156,11 @@ export declare class Datebox extends Component<DateboxOptions> {
143
156
  _commitText(): void;
144
157
  /** @param {Date|number|string|null|unknown} value @returns {Date|null} */
145
158
  _normalizeValue(value: Date | number | string | null | unknown): Date | null;
146
- /** @returns {void} */
159
+ /**
160
+ * Writes the value into the input: in the typing format while the input has focus, in the
161
+ * display format otherwise. Text that is already there is left alone, so the caret stays put.
162
+ * @returns {void}
163
+ */
147
164
  _syncDisplay(): void;
148
165
  /** A disabled box offers no clear button: there is nothing it could do. @returns {void} */
149
166
  _syncClear(): void;
@@ -163,3 +180,20 @@ export declare class Datebox extends Component<DateboxOptions> {
163
180
  * @returns {Datebox}
164
181
  */
165
182
  export declare const DateTimeBox: (target: Element | string | null, options?: DateboxOptions) => Datebox;
183
+ /**
184
+ * Resolves the two formats a Datebox works with: `format`, which the reader types and the field
185
+ * shows while focused, and `display`, which the field shows at rest. A missing format is
186
+ * `'%d.%m.%Y'`, a missing display format is the typing format, and with `time` either one that
187
+ * names no hour or minute gets `' %H:%M'` appended, so the time is never hidden.
188
+ * @param {{format?: string|null, displayFormat?: string|null, time?: boolean}} [options={}]
189
+ * The Datebox options that decide them.
190
+ * @returns {{format: string, display: string}}
191
+ */
192
+ export declare function dateboxFormats({ format, displayFormat, time }?: {
193
+ format?: string | null;
194
+ displayFormat?: string | null;
195
+ time?: boolean;
196
+ }): {
197
+ format: string;
198
+ display: string;
199
+ };
@@ -0,0 +1,41 @@
1
+ export type KbdOptions = {
2
+ /**
3
+ * Keycap size; `sm` sits inside a button or a menu row.
4
+ */
5
+ size?: 'md' | 'sm';
6
+ /**
7
+ * `inherit` draws the keycaps in the surrounding
8
+ * ink — on a solid primary button, a dark toast — instead of the neutral surface keycap.
9
+ */
10
+ tone?: 'neutral' | 'inherit';
11
+ };
12
+ /**
13
+ * The keycap labels `kbd()` draws for a chord or a list of keys, without building any DOM.
14
+ * @example
15
+ * keyLabels('Mod+Shift+K'); // ['⌘', '⇧', 'K'] on macOS, ['Ctrl', 'Shift', 'K'] elsewhere
16
+ * keyLabels('Mod+K', { apple: false }); // ['Ctrl', 'K']
17
+ * @param {string|string[]} keys A chord (`'Mod+Shift+K'`) or the key labels, in order.
18
+ * @param {{apple?: boolean}} [options] `apple` overrides the platform check.
19
+ * @returns {string[]}
20
+ */
21
+ export declare function keyLabels(keys: string | string[], { apple }?: {
22
+ apple?: boolean;
23
+ }): string[];
24
+ /**
25
+ * Renders a key or key combination as keycaps: one `<kbd class="zx-kbd">` holding a nested
26
+ * `<kbd class="zx-kbd__key">` per key, which is how HTML marks up a combination. Every place that
27
+ * shows a shortcut — a button, a menu, the launcher's hints, a shortcut sheet — uses it, so keys
28
+ * look the same everywhere.
29
+ *
30
+ * The keycaps are presentation. A control that has a shortcut announces it with
31
+ * `aria-keyshortcuts` on the control itself; mark a hint that repeats it `aria-hidden`.
32
+ *
33
+ * @example
34
+ * kbd('Mod+K'); // ⌘ K on macOS, Ctrl K elsewhere
35
+ * kbd(['g', 'h']); // a sequence written as two caps
36
+ * kbd('Enter', { size: 'sm' });
37
+ * @param {string|string[]} keys A chord (`'Mod+Shift+K'`) or the key labels, in order.
38
+ * @param {KbdOptions} [options]
39
+ * @returns {HTMLElement}
40
+ */
41
+ export declare function kbd(keys: string | string[], options?: KbdOptions): HTMLElement;
@@ -34,7 +34,8 @@ export type LauncherItem = {
34
34
  hint?: string | number;
35
35
  /**
36
36
  * Key labels drawn as
37
- * key caps (`['⌘', 'K']`), or Button's `{label, keys}` shape. Display only: the Launcher binds nothing.
37
+ * key caps with `kbd()` (`['⌘', 'K']`; a name such as `'Mod'` or `'Shift'` takes the platform's
38
+ * glyph), or Button's `{label, keys}` shape. Display only: the Launcher binds nothing.
38
39
  */
39
40
  shortcut?: string | string[] | {
40
41
  label: string | string[];
@@ -297,7 +298,8 @@ export type LauncherPageEntry = {
297
298
  * @property {string|number} [badge] Compact metadata.
298
299
  * @property {string|number} [hint] Muted text at the end of the row, such as a current value or a project.
299
300
  * @property {string|string[]|{label: string|string[], keys?: string}} [shortcut] Key labels drawn as
300
- * key caps (`['⌘', 'K']`), or Button's `{label, keys}` shape. Display only: the Launcher binds nothing.
301
+ * key caps with `kbd()` (`['⌘', 'K']`; a name such as `'Mod'` or `'Shift'` takes the platform's
302
+ * glyph), or Button's `{label, keys}` shape. Display only: the Launcher binds nothing.
301
303
  * @property {string} [keys] The same shortcut in `aria-keyshortcuts` syntax (`'Meta+K'`), exposed on
302
304
  * the option for assistive technology.
303
305
  * @property {'application'|'record'|'action'} [kind='action'] Tile or row presentation.
@@ -0,0 +1,69 @@
1
+ export type ProseAnchorsOptions = {
2
+ /**
3
+ * The headings that get a link, inside a
4
+ * `.zx-prose` under the root. A heading without an `id` has nothing to link to and is skipped.
5
+ */
6
+ selector?: string;
7
+ /**
8
+ * The link's accessible name; `%1` is the heading.
9
+ */
10
+ label?: string;
11
+ /**
12
+ * The link's tooltip.
13
+ */
14
+ title?: string;
15
+ /**
16
+ * What the live region says after a copy.
17
+ */
18
+ feedback?: string;
19
+ /**
20
+ * Milliseconds the tick and the message stay.
21
+ */
22
+ feedbackDuration?: number;
23
+ /**
24
+ * The address copied for a heading id. Defaults to the
25
+ * current address with its hash replaced (`sectionHref(location.href, id)`).
26
+ */
27
+ href?: (id: string) => string;
28
+ /**
29
+ * Called with the address and whether
30
+ * the clipboard took it.
31
+ */
32
+ oncopy?: (url: string, copied: boolean) => void;
33
+ };
34
+ export type ProseAnchors = {
35
+ /**
36
+ * Links headings added since, re-attaches the live region if the
37
+ * content was replaced, and updates the address of every link. Call it after re-rendering.
38
+ */
39
+ refresh: () => void;
40
+ /**
41
+ * Removes every link, the live region, and the listener.
42
+ */
43
+ destroy: () => void;
44
+ };
45
+ /**
46
+ * The address of a section: `base` with its hash replaced by the heading's id. The query is kept,
47
+ * and the id is encoded as a fragment.
48
+ * @param {string} base Absolute address, usually `location.href`.
49
+ * @param {string} id Heading id.
50
+ * @returns {string}
51
+ */
52
+ export declare function sectionHref(base: string, id: string): string;
53
+ /**
54
+ * Gives every section heading of authored content a link to itself. Each `h2`–`h4` with an `id`
55
+ * inside a `.zx-prose` under `root` ends in a small link (`<a class="zx-prose__anchor" href="#id">`)
56
+ * that rests out of sight and shows while the heading is pointed at or the link has focus. A plain
57
+ * click copies the section's address and confirms in place, without moving the page or touching
58
+ * the location, so an application's own routing is left alone; a middle or modified click is left
59
+ * to the browser, which opens the address.
60
+ *
61
+ * The heading becomes the reveal host (`data-zx-reveal-host`), so the link is always visible on a
62
+ * touch screen and under a contrast preference, and it stays in the Tab order.
63
+ *
64
+ * @param {Element|string} root The content, or an element holding it; a selector is resolved in
65
+ * the document.
66
+ * @param {ProseAnchorsOptions} [options={}] Anchor options.
67
+ * @returns {ProseAnchors}
68
+ */
69
+ export declare function proseAnchors(root: Element | string, options?: ProseAnchorsOptions): ProseAnchors;
@@ -114,42 +114,6 @@ export type QuestionnaireCompleteDetail = {
114
114
  answers: Record<string, unknown>;
115
115
  path: string[];
116
116
  };
117
- /**
118
- * @typedef {Object} QuestionnaireOptions
119
- * @property {QuestionnaireItem[]} [items=[]] Ordered question definitions.
120
- * @property {Record<string, unknown>} [answers={}] Answers to start from. Together with `active`
121
- * this is the resume pair: hand back what a previous session collected.
122
- * @property {string|null} [active=null] Item to open, defaulting to the first visible one.
123
- * @property {boolean} [progress=true] Whether the progress bar and counter are shown.
124
- * @property {boolean} [review=false] Whether a summary of every answer is shown before submitting.
125
- * @property {QuestionnaireAdvance} [advance='manual'] `auto` moves on by itself once a
126
- * single-choice question is answered.
127
- * @property {boolean} [shortcuts=true] Whether `1`–`9` and `a`–`z` pick an answer.
128
- * @property {boolean} [allowBack=true] Whether the Back action is offered.
129
- * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
130
- * @property {(event: CustomEvent<QuestionnaireChangeDetail>) => void} [onchange] Answer listener.
131
- * @property {(event: CustomEvent<QuestionnaireNavigateDetail>) => void} [onnavigate] Navigation listener.
132
- * @property {(event: CustomEvent<QuestionnaireSkipDetail>) => void} [onskip] Skip listener.
133
- * @property {(event: CustomEvent<QuestionnaireInvalidDetail>) => void} [oninvalid] Validation listener.
134
- * @property {(event: CustomEvent<QuestionnaireSubmitDetail>) => void} [onsubmit] Submit listener.
135
- * @property {(event: CustomEvent<QuestionnaireCompleteDetail>) => void} [oncomplete] Completion listener.
136
- */
137
- /**
138
- * @typedef {Object} QuestionnaireChangeDetail
139
- * @property {string} name Item whose answer changed.
140
- * @property {unknown} value The new answer.
141
- * @property {Record<string, unknown>} answers Every visible answer after the change.
142
- */
143
- /**
144
- * @typedef {Object} QuestionnaireNavigateDetail
145
- * @property {string|null} from Item being left, or null.
146
- * @property {string|null} to Item being opened, or null when the review screen is being entered.
147
- * @property {'next'|'previous'|'skip'|'goto'|'review'} reason What triggered the move.
148
- */
149
- /** @typedef {{name: string}} QuestionnaireSkipDetail */
150
- /** @typedef {{name: string, message: string}} QuestionnaireInvalidDetail */
151
- /** @typedef {{answers: Record<string, unknown>, path: string[]}} QuestionnaireSubmitDetail */
152
- /** @typedef {{answers: Record<string, unknown>, path: string[]}} QuestionnaireCompleteDetail */
153
117
  /**
154
118
  * A guided, one-question-at-a-time flow: onboarding intake, a service-call checklist, an audit
155
119
  * form, a feedback survey. The questionnaire owns the ordered items, the active one, the answers,