@zeyos/zx 5.4.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 (113) hide show
  1. package/CHANGELOG.md +80 -0
  2. package/README.md +23 -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 +1225 -433
  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 +243 -37
  28. package/docs/llms.txt +2 -0
  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.js +2 -2
  71. package/src/components/module-bar/module-bar.css +11 -1
  72. package/src/components/multi-value-editor/multi-value-editor.js +4 -4
  73. package/src/components/navigation-bar/navigation-bar.css +3 -2
  74. package/src/components/pagination/pagination.js +2 -2
  75. package/src/components/panel/panel.js +2 -2
  76. package/src/components/prose/prose.css +53 -0
  77. package/src/components/prose/prose.js +152 -0
  78. package/src/components/questionnaire/questionnaire.css +7 -17
  79. package/src/components/questionnaire/questionnaire.js +16 -1
  80. package/src/components/rating/rating.css +3 -1
  81. package/src/components/search/search.js +2 -2
  82. package/src/components/select/glyphs.js +3 -3
  83. package/src/components/select/select.css +35 -7
  84. package/src/components/select/select.js +4 -4
  85. package/src/components/stat-tile/stat-tile.css +56 -2
  86. package/src/components/stat-tile/stat-tile.js +25 -2
  87. package/src/components/stepper/stepper.css +2 -1
  88. package/src/components/stepper/stepper.js +3 -3
  89. package/src/components/tabbox/tabbox.css +2 -2
  90. package/src/components/tabbox/tabbox.js +2 -2
  91. package/src/components/table/table.css +52 -16
  92. package/src/components/table/table.js +7 -5
  93. package/src/components/tag-picker/tag-picker.css +56 -43
  94. package/src/components/tag-picker/tag-picker.js +21 -16
  95. package/src/components/tree/tree.css +44 -0
  96. package/src/components/tree/tree.js +97 -9
  97. package/src/components/value-list/value-list.css +25 -4
  98. package/src/components/value-list/value-list.js +2 -1
  99. package/src/components/view/record-view.js +3 -3
  100. package/src/components/view-settings/view-settings.css +2 -1
  101. package/src/components/workspace-switcher/workspace-switcher.js +3 -3
  102. package/src/core/icons.js +34 -3
  103. package/src/elements/define.js +1 -0
  104. package/src/index.js +4 -2
  105. package/src/internal/app-rail.js +5 -1
  106. package/src/internal/row-actions.js +203 -0
  107. package/styles/base.css +26 -1
  108. package/styles/prose.css +306 -0
  109. package/styles/tokens/dark.css +97 -120
  110. package/styles/tokens/global.css +24 -9
  111. package/styles/tokens/semantic.css +464 -184
  112. package/styles/tokens/themes.css +9 -0
  113. package/styles/zx.css +3 -0
package/CHANGELOG.md CHANGED
@@ -8,6 +8,86 @@ 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
+
11
91
  ## 5.4.0 — 2026-10-29
12
92
 
13
93
  Glass rebuilt as a lit pane with a body under it, five more materials in the theme studio, and a
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. |
@@ -286,14 +287,21 @@ region of it — override those tokens rather than switching a mode:
286
287
  }
287
288
  ```
288
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
+
289
297
  A second attribute picks the **accent**, orthogonally to the theme:
290
298
 
291
299
  ```html
292
300
  <html data-zx-theme="dark" data-zx-preset="ocean">
293
301
  ```
294
302
 
295
- Six presets ship — `zx` (the ZeyOS green, and the default), `zeyos`, `ocean`, `violet`, `rose`,
296
- `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
297
305
  through, so a preset rethemes light, dark, and auto at once:
298
306
 
299
307
  ```css
@@ -320,18 +328,17 @@ brushed or glazed, no blur), or Flat. Each is a set of token overrides composed
320
328
  light and dark, and reduced-transparency, high-contrast and forced-colour settings restore solid
321
329
  surfaces on their own.
322
330
 
323
- Anything beyond the accent is a semantic token override, without reaching into component CSS:
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.
324
335
 
325
336
  ```css
326
- :root[data-zx-theme="acme"] {
327
- --zx-color-bg-page: #f4f1eb;
328
- --zx-color-bg-surface: #fffdf8;
329
- --zx-color-bg-control: #ffffff;
330
- --zx-color-border-control: #978e80;
331
- --zx-color-text: #26221d;
332
- --zx-color-text-muted: #655e54;
333
- --zx-color-accent: #176b52;
334
- --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);
335
342
  }
336
343
  ```
337
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,
@@ -4,6 +4,7 @@ export type StatTileFormat = StatTileFormatName | ((value: number | string | nul
4
4
  export type StatTileKind = 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
5
5
  export type StatTileDeltaKind = 'positive' | 'negative' | 'neutral';
6
6
  export type StatTileDirection = 'up' | 'down' | 'flat';
7
+ export type StatTileVariant = 'default' | 'plain';
7
8
  export type StatTileDelta = {
8
9
  /**
9
10
  * Which way the metric moved, read from the sign alone.
@@ -105,6 +106,19 @@ export type StatTileOptions = {
105
106
  * value, which stays at full text contrast whatever intent a record carries.
106
107
  */
107
108
  kind?: StatTileKind;
109
+ /**
110
+ * `'default'` is a framed tile on its own surface,
111
+ * for a figure that stands among other content (a dashboard). `'plain'` drops the frame, the fill
112
+ * and the padding and sets the figure a size smaller, for a row of figures on a page (a record's
113
+ * amounts under its title). Reflected as `data-variant` on the root.
114
+ */
115
+ variant?: StatTileVariant;
116
+ /**
117
+ * The figure leads its row: in a plain row it is set at the
118
+ * display size while the others stay smaller, on a framed tile one step above the display size.
119
+ * Give it to one tile per row. Reflected as `data-emphasis="true"`.
120
+ */
121
+ emphasis?: boolean;
108
122
  /**
109
123
  * Destination. A tile with an href is an `<a>`.
110
124
  */
@@ -238,6 +252,12 @@ export declare function statDelta(delta: number | string | null | undefined, opt
238
252
  locale?: string;
239
253
  currency?: string | null;
240
254
  }): StatTileDelta | null;
255
+ /**
256
+ * Resolves the `variant` option to one the stylesheet knows; anything else is the framed tile.
257
+ * @param {unknown} value Requested variant.
258
+ * @returns {StatTileVariant}
259
+ */
260
+ export declare function normalizeStatTileVariant(value: unknown): StatTileVariant;
241
261
  /**
242
262
  * Chooses the element a tile must be, from what the tile does.
243
263
  *
@@ -31,8 +31,9 @@ export type TagPickerOptions = {
31
31
  /**
32
32
  * Optional item tone property or reader: a categorical
33
33
  * tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`,
34
- * `violet`, `slate`). A toned tag takes the palette's fill and ink, as a Badge with that `tone`
35
- * does; a tone wins over a colour, and unknown names are ignored.
34
+ * `violet`, `slate`). Every tag is built by `badge()`, so a toned tag is the Badge with that `tone`
35
+ * — the same shape, size, fill and ink it has in a list row or a record header; a tone wins over a
36
+ * colour, and unknown names are ignored.
36
37
  */
37
38
  toneKey?: TagValueReader;
38
39
  /**
@@ -155,8 +156,9 @@ export type TagPickerOptions = {
155
156
  * or a token reference such as `var(--zx-color-tone-blue-fg)`.
156
157
  * @property {TagValueReader} [toneKey='tone'] Optional item tone property or reader: a categorical
157
158
  * tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`,
158
- * `violet`, `slate`). A toned tag takes the palette's fill and ink, as a Badge with that `tone`
159
- * does; a tone wins over a colour, and unknown names are ignored.
159
+ * `violet`, `slate`). Every tag is built by `badge()`, so a toned tag is the Badge with that `tone`
160
+ * — the same shape, size, fill and ink it has in a list row or a record header; a tone wins over a
161
+ * colour, and unknown names are ignored.
160
162
  * @property {Array<TagValueReader>|null} [searchKeys=null] Fields searched by local filtering.
161
163
  * @property {'local'|((query: string) => Promise<TagItem[]>|TagItem[])} [filter='local'] Filtering mode.
162
164
  * @property {number} [minQuery=0] Minimum async query length.
@@ -308,7 +310,11 @@ export declare class TagPicker extends Component<TagPickerOptions> {
308
310
  setReadonly(readonly: boolean): this;
309
311
  /** Cancels pending work and restores an enhanced target. @returns {void} */
310
312
  destroy(): void;
311
- /** @returns {void} */
313
+ /**
314
+ * Draws the selection. A tag is a Badge — `badge({ tone })` with the picker's own class — so it
315
+ * has one construction wherever a label appears, and only the remove button is the picker's.
316
+ * @returns {void}
317
+ */
312
318
  _renderTags(): void;
313
319
  /** @returns {void} */
314
320
  _renderOptions(): void;