@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.
- package/CHANGELOG.md +125 -0
- package/README.md +49 -16
- package/dist/types/components/app-sidebar/app-sidebar.d.ts +33 -0
- package/dist/types/components/badge/badge.d.ts +5 -4
- package/dist/types/components/datebox/date-range-box.d.ts +15 -2
- package/dist/types/components/datebox/datebox.d.ts +37 -3
- package/dist/types/components/kbd/kbd.d.ts +41 -0
- package/dist/types/components/launcher/launcher.d.ts +4 -2
- package/dist/types/components/prose/prose.d.ts +69 -0
- package/dist/types/components/questionnaire/questionnaire.d.ts +0 -36
- package/dist/types/components/stat-tile/stat-tile.d.ts +20 -0
- package/dist/types/components/tag-picker/tag-picker.d.ts +11 -5
- package/dist/types/components/tree/tree.d.ts +44 -3
- package/dist/types/core/icons.d.ts +22 -1
- package/dist/types/index.d.ts +4 -2
- package/dist/types/internal/app-rail.d.ts +10 -3
- package/dist/types/internal/row-actions.d.ts +151 -0
- package/dist/zx-zeyos.esm.js +264 -82
- package/dist/zx-zeyos.esm.min.js +4 -4
- package/dist/zx.css +1288 -439
- package/dist/zx.esm.js +952 -392
- package/dist/zx.esm.min.js +6 -6
- package/dist/zx.global.js +952 -392
- package/dist/zx.global.min.js +6 -6
- package/dist/zx.min.css +1 -1
- package/docs/api.json +112 -4
- package/docs/llms.md +433 -38
- package/docs/llms.txt +21 -1
- package/package.json +1 -1
- package/src/components/account-menu/account-menu.js +2 -2
- package/src/components/app-rail/app-rail.css +11 -11
- package/src/components/app-sidebar/app-sidebar.css +90 -17
- package/src/components/app-sidebar/app-sidebar.js +120 -12
- package/src/components/badge/badge.css +33 -20
- package/src/components/badge/badge.js +5 -4
- package/src/components/breadcrumb/breadcrumb.css +28 -3
- package/src/components/breadcrumb/breadcrumb.js +2 -2
- package/src/components/button/button.css +24 -13
- package/src/components/button/button.js +20 -2
- package/src/components/calendar/calendar.css +14 -4
- package/src/components/card-view/card-view.js +2 -2
- package/src/components/chart/chart.js +20 -5
- package/src/components/check-button/check-button.css +11 -3
- package/src/components/check-button/check-button.js +3 -3
- package/src/components/context-menu/context-menu.css +7 -1
- package/src/components/date-picker/date-picker.css +6 -0
- package/src/components/date-picker/date-picker.js +5 -5
- package/src/components/date-picker/date-range-picker.css +6 -0
- package/src/components/date-picker/date-range-picker.js +3 -3
- package/src/components/date-picker/month-picker.js +3 -3
- package/src/components/date-picker/time-picker.css +6 -0
- package/src/components/datebox/date-range-box.js +30 -6
- package/src/components/datebox/datebox.js +44 -7
- package/src/components/dialog/dialog.css +0 -1
- package/src/components/dialog/dialog.js +2 -1
- package/src/components/dock/dock.js +2 -2
- package/src/components/dropdown/dropdown.css +2 -1
- package/src/components/entity-ref/entity-ref.css +8 -1
- package/src/components/file-item/file-item.css +1 -1
- package/src/components/finder/finder.js +2 -2
- package/src/components/groupbox/groupbox.js +2 -2
- package/src/components/kanban-view/kanban-view.css +8 -4
- package/src/components/kanban-view/kanban-view.js +3 -3
- package/src/components/kbd/kbd.css +64 -0
- package/src/components/kbd/kbd.js +121 -0
- package/src/components/launcher/launcher.css +30 -25
- package/src/components/launcher/launcher.js +15 -21
- package/src/components/list-toolbar/list-toolbar.css +7 -1
- package/src/components/menu-button/menu-button.css +9 -2
- package/src/components/message/message.css +6 -2
- package/src/components/message/message.js +2 -2
- package/src/components/module-bar/module-bar.css +11 -1
- package/src/components/multi-value-editor/multi-value-editor.js +4 -4
- package/src/components/navigation-bar/navigation-bar.css +3 -2
- package/src/components/pagination/pagination.js +2 -2
- package/src/components/panel/panel.js +2 -2
- package/src/components/prose/prose.css +53 -0
- package/src/components/prose/prose.js +152 -0
- package/src/components/questionnaire/questionnaire.css +7 -17
- package/src/components/questionnaire/questionnaire.js +16 -1
- package/src/components/rating/rating.css +3 -1
- package/src/components/search/search.js +2 -2
- package/src/components/select/glyphs.js +3 -3
- package/src/components/select/select.css +35 -7
- package/src/components/select/select.js +4 -4
- package/src/components/stat-tile/stat-tile.css +56 -2
- package/src/components/stat-tile/stat-tile.js +25 -2
- package/src/components/stepper/stepper.css +2 -1
- package/src/components/stepper/stepper.js +3 -3
- package/src/components/tabbox/tabbox.css +2 -2
- package/src/components/tabbox/tabbox.js +2 -2
- package/src/components/table/table.css +52 -16
- package/src/components/table/table.js +7 -5
- package/src/components/tag-picker/tag-picker.css +56 -43
- package/src/components/tag-picker/tag-picker.js +21 -16
- package/src/components/tree/tree.css +44 -0
- package/src/components/tree/tree.js +97 -9
- package/src/components/value-list/value-list.css +25 -4
- package/src/components/value-list/value-list.js +2 -1
- package/src/components/view/record-view.js +3 -3
- package/src/components/view-settings/view-settings.css +2 -1
- package/src/components/workspace-switcher/workspace-switcher.js +3 -3
- package/src/core/icons.js +34 -3
- package/src/elements/define.js +1 -0
- package/src/index.js +4 -2
- package/src/internal/app-rail.js +5 -1
- package/src/internal/row-actions.js +203 -0
- package/styles/base.css +26 -1
- package/styles/prose.css +306 -0
- package/styles/tokens/dark.css +108 -103
- package/styles/tokens/global.css +24 -9
- package/styles/tokens/semantic.css +520 -198
- package/styles/tokens/themes.css +9 -0
- package/styles/zx.css +3 -0
package/docs/llms.md
CHANGED
|
@@ -3,7 +3,9 @@
|
|
|
3
3
|
> Xenon is a dependency-free design system for browser applications; Zx is its product-agnostic
|
|
4
4
|
> vanilla-JavaScript implementation. ES2022 modules, WAI-ARIA-accessible native controls, semantic `--zx-*` design
|
|
5
5
|
> tokens (light/dark, one token-driven geometry), and lifecycle-safe components. Zero runtime dependencies.
|
|
6
|
-
> This file is the single, complete reference a coding agent needs to build UI with Zx
|
|
6
|
+
> This file is the single, complete reference a coding agent needs to build UI with Zx. Read
|
|
7
|
+
> "Choosing what to build with" first: it maps every screen to a layout to start from, every job to
|
|
8
|
+
> its component, and lists the theme settings to decide. Each
|
|
7
9
|
> component below is wrapped in `<!-- doc:<name> -->` markers so tools can extract a single
|
|
8
10
|
> component's section (`website/docs.html` renders them as each component's Reference tab).
|
|
9
11
|
|
|
@@ -47,6 +49,186 @@ const t = new Table(target, options);
|
|
|
47
49
|
- Styles: load `/assets/zx.css` once.
|
|
48
50
|
- Build bundles with `npm run build` (esbuild). No build is needed to develop against `src/`.
|
|
49
51
|
|
|
52
|
+
## Choosing what to build with
|
|
53
|
+
|
|
54
|
+
Three decisions come before any code: which **layout** the screen is, which **component** does
|
|
55
|
+
each job, and which **theme settings** the application pins. The library already answers most of
|
|
56
|
+
them. A screen that invents its own shell, table, menu, or colour is the exception to justify,
|
|
57
|
+
never the default — it costs the accessibility, keyboard map, theming, and print behaviour the
|
|
58
|
+
standard parts already have.
|
|
59
|
+
|
|
60
|
+
### Start from a layout, not a blank page
|
|
61
|
+
|
|
62
|
+
Every layout in the gallery (<https://zx.zeyos.com/layouts>, `layouts.html#<id>` opens one,
|
|
63
|
+
`layout.html#<id>` shows it alone) is a complete, working screen on one shared application shell,
|
|
64
|
+
and its source is public: `https://zx.zeyos.com/layouts/<id>.layout.js` with `<id>.layout.css`
|
|
65
|
+
(in the repository, `website/layouts/`). Open the closest one, keep its anatomy — the columns,
|
|
66
|
+
the pane headers, the toolbar, the drawers, the states, the keyboard map — and change the data,
|
|
67
|
+
the fields, and the copy.
|
|
68
|
+
|
|
69
|
+
The helpers a layout imports are public too, and meant to be copied beside application code
|
|
70
|
+
(they are documentation-site modules, not package exports; import them relatively):
|
|
71
|
+
|
|
72
|
+
- `layouts/kit.js` + `kit.css` — the shell: `.shell` and its columns, `paneHeader()`,
|
|
73
|
+
`propList()`, `.list-row`, `.surface`, `suiteNav()` (module strip + module menu, with a
|
|
74
|
+
`workspace` switcher), `adaptiveShell()` (every column stays reachable at any width),
|
|
75
|
+
`shortcuts()` and `shortcutSheet()` (`?`), `toast()`, `loadChartJs()`.
|
|
76
|
+
- `layouts/overview.js` + `overview.css` — `createOverview()`: one toolbar over one record set
|
|
77
|
+
shown as table, list, cards, gallery, or board; search; filters as editable chips with a Filters
|
|
78
|
+
drawer; a View settings drawer; grouping, sorting, paging, selection and bulk actions; a base
|
|
79
|
+
filter for tabs and scopes; split empty states. The record collection, CRM, and issue tracker
|
|
80
|
+
are all this one composition.
|
|
81
|
+
|
|
82
|
+
Which layout a screen is:
|
|
83
|
+
|
|
84
|
+
| The screen | Start from | Not from |
|
|
85
|
+
| --- | --- | --- |
|
|
86
|
+
| A list of records of one type (companies, tickets, orders, files) | **Record collection** (`record-collection`) — the toolbar, chips, drawers and pager come with it | a bare `Table` under a heading |
|
|
87
|
+
| A list beside the record being edited | **Master–detail** (`master-detail`) | two unrelated panes |
|
|
88
|
+
| One record on its own page | **Record page** (`record-page`) | a form |
|
|
89
|
+
| Figures, charts, a period switch | **Dashboard** (`dashboard`) | cards of big numbers |
|
|
90
|
+
| Settings in sections | **Settings workspace** (`settings-workspace`) | one long form |
|
|
91
|
+
| Creating something in steps | **Record wizard** (`record-wizard`, vertical steps) or **Checkout wizard** (`checkout-wizard`, horizontal) | tabs |
|
|
92
|
+
| Conversations, triage | **Inbox** (`inbox`) or the **Mail** template | — |
|
|
93
|
+
| An assistant | **Agent chat** (`agent-chat`, one run with tools and approvals) or the **AI chat** template | a chat bubble list |
|
|
94
|
+
| Empty, loading, error, offline, confirmation | **System states** (`system-states`) — every screen needs these; copy them | ad-hoc messages |
|
|
95
|
+
| A whole application | the closest **template** below; they share one shell | a new shell |
|
|
96
|
+
|
|
97
|
+
Templates — complete applications with navigation, lists, records, and editors together:
|
|
98
|
+
|
|
99
|
+
| id | Screen | Use it for |
|
|
100
|
+
| --- | --- | --- |
|
|
101
|
+
| `mail` | Mail | a keyboard-first inbox: split streams, one-key triage, snooze, inline reply |
|
|
102
|
+
| `issue-tracker` | Issue tracker | work items grouped by status or on a board, chips, sub-items, activity, properties edited in place |
|
|
103
|
+
| `wiki` | Knowledge base | nested pages in spaces, a reading column with a live outline, comments, Markdown editing |
|
|
104
|
+
| `ai-chat` | AI chat | chat with an assistant: tool steps, sources, artifacts with versions, per-chat settings |
|
|
105
|
+
| `agent-workspace` | Agent workspace | a team of agents: roster with presence, plans and logs, approvals, a palette, a terminal |
|
|
106
|
+
| `invoice-editor` | Invoice editor | a document edited beside its live page, totals per rate, a send step that locks it |
|
|
107
|
+
| `item-inventory` | Item & inventory | one master-data record: levels per location, linked documents, tabbed settings, a log |
|
|
108
|
+
| `workflows` | Workflows | recurring processes as step flows: built, run, measured |
|
|
109
|
+
| `infrastructure` | Infrastructure | monitoring: health, alerts, traffic, drill-down to the unit |
|
|
110
|
+
| `crm` | CRM | companies, people, deals: editable collections with saved views, record pages, a stage board |
|
|
111
|
+
|
|
112
|
+
Patterns — single screens that recur in every application:
|
|
113
|
+
|
|
114
|
+
| id | Screen | What it shows |
|
|
115
|
+
| --- | --- | --- |
|
|
116
|
+
| `master-detail` | Master–detail | a filterable list beside the record being edited; save, revert, unsaved-change checks |
|
|
117
|
+
| `record-collection` | Record collection | one record type as table, list, cards, gallery, and board under one toolbar; filter chips and drawers |
|
|
118
|
+
| `dashboard` | Dashboard | figures, a chart, tabbed detail, one period switch redrawing all of it |
|
|
119
|
+
| `inbox` | Inbox | three panes: folders, conversations, the open thread with a reply |
|
|
120
|
+
| `record-page` | Record page | one record: summary header, tabs for lines, files and history, editable details |
|
|
121
|
+
| `agent-chat` | Agent chat | one agent run: plan, tool calls, an approval that holds it, a streamed answer with sources |
|
|
122
|
+
| `record-wizard` | Record wizard | creation in validated vertical steps with a running total and a review |
|
|
123
|
+
| `checkout-wizard` | Checkout wizard | a focused horizontal flow beside a live summary |
|
|
124
|
+
| `settings-workspace` | Settings workspace | personal settings in sections, saved together |
|
|
125
|
+
| `system-states` | System states | every empty, loading, error, and confirmation state, with an offline switch |
|
|
126
|
+
| `zeyos-invoices` | ZeyOS invoices | a table and a form generated from the ZeyOS schema, beside the ZeyOS module navigation |
|
|
127
|
+
|
|
128
|
+
Every application shares one shell: `AppSidebar` (or `ModuleBar` for the module level) with
|
|
129
|
+
`AccountMenu`, a `WorkspaceSwitcher` where users have several workspaces, a `Launcher` as the
|
|
130
|
+
command palette, `?` for the shortcut sheet, and `data-zx-theme` honoured throughout. Do not design
|
|
131
|
+
a second navigation.
|
|
132
|
+
|
|
133
|
+
### The component for the job
|
|
134
|
+
|
|
135
|
+
| Job | Use | Rather than |
|
|
136
|
+
| --- | --- | --- |
|
|
137
|
+
| Records the user scans, sorts, selects | `Table`; `TableView` when the same records also appear as cards or a board | a styled `<table>`, a list of `<div>`s |
|
|
138
|
+
| Records as cards or a gallery | `CardView` (`keyboard: 'roving'`, `groupBy`, `collapsibleGroups`) | `Card`s in a CSS grid |
|
|
139
|
+
| Records by stage, dragged between columns | `KanbanView` | — |
|
|
140
|
+
| One record set, several presentations, one state | `RecordView` family + `ListToolbar` + `ViewSettings` + `Pagination` — `createOverview()` wires them | three components with three states |
|
|
141
|
+
| The bar above a record view | `ListToolbar` (search, live count, view switch, badged tools) | a row of buttons |
|
|
142
|
+
| Sorting outside a header | `SortControl` | two selects |
|
|
143
|
+
| Paging | `Pagination` (`paginationRange()` for the numbers) | — |
|
|
144
|
+
| Filters, quick and client-side | `DataFilter` | — |
|
|
145
|
+
| Filters typed from a server's field metadata | `FilterPanel` (`mode: 'draft'|'live'`) | — |
|
|
146
|
+
| Filters the user composes, nested, serialisable | `Filter` (an AST; `parseFilterAst()`/`stringifyFilterAst()`) | — |
|
|
147
|
+
| A spreadsheet-like editable grid (lines, positions) | `Grid` (`Grid.BillingItems()`) | `Table` with `editMode` — that is for occasional cell edits |
|
|
148
|
+
| A tree | `TreeView` (one column) or `Finder` (Miller columns) | nested `<ul>`s |
|
|
149
|
+
| Events over time | `Calendar` (agenda, day, week, month, year) | — |
|
|
150
|
+
| One number with context | `StatTile` (delta, sparkline, loading; plain and one leading for a record's figures) | a card with a big figure |
|
|
151
|
+
| A chart | `Chart` with `ChartJsAdapter` (Chart.js injected, never bundled) | — |
|
|
152
|
+
| A linked record inline | `EntityRef` | a link |
|
|
153
|
+
| Files | `FileItem` / `FileList`; uploading: `FieldUpload` | — |
|
|
154
|
+
| History, comments, a feed | `ActivityItem` / `ActivityList` | — |
|
|
155
|
+
| Choose one of many | `Select` (`filter: 'local'` or async for long lists; `Select.entity()` for records; `Select.priority()` / `Select.status()` presets); native radios for a handful of visible options | a custom dropdown |
|
|
156
|
+
| Choose many | `TagPicker` (identity, colour, icons), `Checklist` (a plain list) | — |
|
|
157
|
+
| On or off | `Toggle` (takes effect at once), `CheckButton` (a mode in a toolbar), a native checkbox inside a form | — |
|
|
158
|
+
| Search | `Search` | an input with an icon |
|
|
159
|
+
| Number, date, time, range | `NumberField`, `Datebox` / `DateTimeBox`, `Timebox`, `DateRangeBox`, `Slider`, `Rating` | plain inputs |
|
|
160
|
+
| A form | `Form` → `Fieldset` → `Field` (the type registry); `Questionnaire` for one question at a time | hand-laid inputs |
|
|
161
|
+
| Structured text, code | `CodeEditor` | a textarea |
|
|
162
|
+
| Repeating values | `ValueList`, `MultiValueEditor` | — |
|
|
163
|
+
| Confirm, alert, prompt | `Dialog.confirm()` / `Dialog.alert()` / `Dialog.prompt()` (Promises) | `window.confirm` |
|
|
164
|
+
| A task in a window | `Dialog` (header, footer, buttons); `Modal` is the bare surface | — |
|
|
165
|
+
| Edit without leaving the list | `Sheet` (`side: 'end'`); drill-down: `SheetStack`; a persistent pane: `Dock` | a dialog |
|
|
166
|
+
| Transient status | `Message.success()` / `.info()` / `.warning()` / `.error()` (toasts); inline `Message` for a region | an alert bar built by hand |
|
|
167
|
+
| Actions on a thing | `MenuButton`; `ContextMenu` (right-click and Shift+F10; one instance per table via `selector`) | a floating `<div>` |
|
|
168
|
+
| Anchored content, hints | `Dropdown`; `tooltip()` / `describe()` | `title` attributes alone |
|
|
169
|
+
| A row of actions | `Toolbar` (overflow menu, one Tab stop) | a flex row of buttons |
|
|
170
|
+
| Navigation | `AppSidebar` (tree, sections, `layout: 'modules'`), `ModuleBar`, `NavigationBar`, `Tabbox` (in-page), `Breadcrumb` (where am I), `Stepper` (a sequence) | — |
|
|
171
|
+
| Commands by keyboard | `Launcher` | — |
|
|
172
|
+
| Account and workspace | `AccountMenu`, `WorkspaceSwitcher` | — |
|
|
173
|
+
| Grouping content | `Card`, `Panel` (actions in the header or footer), `Groupbox`, `MasterPanel`, `SplitView`, `stack()` / `grid()` / `aspect()` | ad-hoc wrappers |
|
|
174
|
+
| Identity and status marks | `Avatar`, `AppIcon`, `badge()` (`kind` says how it is doing, `tone` what it is) | coloured spans |
|
|
175
|
+
| Nothing yet, loading, failed | `emptyState()`, `skeleton()` / `skeletonText()` / `skeletonTable()`, `InlineLoading`, `spinner()`, `ProgressBar` | a blank area |
|
|
176
|
+
| Ambient colour behind a hero, a login, a launcher | `Aurora` | CSS gradients |
|
|
177
|
+
| Icons | `icon(name)` — the bundled set or Font Awesome, whichever the application opted into | inline SVG |
|
|
178
|
+
|
|
179
|
+
### Theming decisions
|
|
180
|
+
|
|
181
|
+
Decide these once per application, in this order, and express each as the attribute or token
|
|
182
|
+
the library already reads — never as component CSS:
|
|
183
|
+
|
|
184
|
+
1. **Theme** — `data-zx-theme="auto"` unless the product pins `light` or `dark`. Both must work; a
|
|
185
|
+
region may differ from the page.
|
|
186
|
+
2. **Accent** — a preset (`data-zx-preset="zx|zeyos|ocean|violet|rose|slate|folio"`) or a five-stop
|
|
187
|
+
`--zx-accent-300…700` ramp built in the theme studio (<https://zx.zeyos.com/theme.html>), which
|
|
188
|
+
exports the CSS. Never a one-off colour on a button.
|
|
189
|
+
3. **Geometry** — the rhythm is three tokens on `:root` (or on a dense region): `--zx-space-unit`,
|
|
190
|
+
`--zx-control-height`, `--zx-radius`. Dense data tools sit around 3.5px / 28px; comfortable
|
|
191
|
+
products around 4.5px / 32–34px. Never a per-component size. Data rows follow the control
|
|
192
|
+
height through `--zx-row-height`; set it only to make rows tighter or more relaxed than that.
|
|
193
|
+
4. **Material** — how surfaces answer light, exported from the studio as token overrides (there
|
|
194
|
+
is no attribute). `Glass` (the default: a thin lit pane), `Deep glass` (a thick one), `Frost`
|
|
195
|
+
(milk glass for reading surfaces), `Smoke` (tinted glass that darkens the scene; dark-first
|
|
196
|
+
products), `Paper`, `Satin` and `Enamel` (opaque: matte, brushed or glazed; no blur, so they
|
|
197
|
+
render cheaply and never depend on what is behind them), or `Flat`. `Aurora` supplies the light glass responds to. Reduced-transparency,
|
|
198
|
+
high-contrast, forced-colour and unsupported-filter environments fall back to solid surfaces on
|
|
199
|
+
their own.
|
|
200
|
+
5. **Motion** — `data-zx-motion="reduced"` is the only switch; own transitions use `--zx-dur-*`,
|
|
201
|
+
`--zx-ease`, `--zx-ease-spring`, `--zx-ease-drawer`.
|
|
202
|
+
6. **Colour roles** — `--zx-color-tone-*` for categories (tags, modules, avatars),
|
|
203
|
+
`--zx-color-danger|warning|success|info` for status, `--zx-color-bg-current` for "you are here"
|
|
204
|
+
and `--zx-color-bg-selected` for "what you picked", `--zx-color-bg-chrome` for navigation and
|
|
205
|
+
inspector columns. A module's colour is its `tone` on `ModuleBar`. A product's own colour is a
|
|
206
|
+
role overridden once on `:root`, `light-dark(<light>, <dark>)` where the appearances differ —
|
|
207
|
+
never per theme attribute (see **Override once**).
|
|
208
|
+
7. **Type** — two registers. Interface type is `--zx-font-sans`, `--zx-font-mono` and
|
|
209
|
+
`--zx-text-base` (every `--zx-text-*` step derives from it). Reading type is a second, separate
|
|
210
|
+
decision for authored content in `.zx-prose`: `--zx-font-prose` (a serif here leaves the
|
|
211
|
+
interface alone), `--zx-prose-size`, `--zx-prose-measure`.
|
|
212
|
+
8. **Content** — wrap authored text (a document, notes, a message body, an assistant's answer) in
|
|
213
|
+
`.zx-prose`; set emphasis apart with `.zx-callout` (neutral unless it is a status or a
|
|
214
|
+
category). Never style headings and paragraphs per screen.
|
|
215
|
+
9. **Fields** — `data-zx-fields="quiet"` on property panels (no border or fill until hovered or
|
|
216
|
+
focused).
|
|
217
|
+
10. **Print** — works without work; keep status badges, hide chrome. Nothing to add.
|
|
218
|
+
11. **Markup-first pages** — `defineElements()` for `<zx-*>` custom elements where templates are
|
|
219
|
+
authored as HTML.
|
|
220
|
+
|
|
221
|
+
### Never
|
|
222
|
+
|
|
223
|
+
- No raw colours (`#hex`, `rgb()`, named), no tier-1 tokens (`--zx-gray-*`, `--zx-emerald-*`,
|
|
224
|
+
`--zx-tone-*`), no hard-coded sizes the geometry tokens cover.
|
|
225
|
+
- No application CSS on component internals (`.zx-<component>__<part>` selectors); override a
|
|
226
|
+
token, or use a published hook.
|
|
227
|
+
- No hand-built dropdowns, menus, dialogs, tooltips, tables, date pickers, or toasts.
|
|
228
|
+
- No `innerHTML` with data; `h()` and text nodes.
|
|
229
|
+
- No state classes; state is ARIA and `data-state`, which the stylesheets already match.
|
|
230
|
+
- No second shell, second navigation, or second keyboard convention inside one application.
|
|
231
|
+
|
|
50
232
|
## Theming
|
|
51
233
|
|
|
52
234
|
Load `zx.css`, then set the theme on any ancestor (usually `<html>`):
|
|
@@ -60,18 +242,53 @@ Themes: `light` | `dark` | `auto` (follows OS).
|
|
|
60
242
|
**One geometry.** Spacing steps are multiples of one unit
|
|
61
243
|
(`--zx-space-unit`, 4px: `--zx-space-1…8` = 4/8/12/16/20/24/32/40px), radius steps are fractions of
|
|
62
244
|
one base (`--zx-radius`, 4px: `-sm/-md/-lg/-xl` = 2/3/4/6px; `-full` only for shapes whose roundness
|
|
63
|
-
is the meaning —
|
|
245
|
+
is the meaning — status pills, avatars, toggles; a tag takes `-md`; `-panel` is the corner of a panel that holds rounded
|
|
246
|
+
items, a menu or a listbox, concentric with them: the item corner plus the inset between them, 6px
|
|
247
|
+
at the default and square when the base is 0), and controls are `--zx-control-height` (30px) tall.
|
|
248
|
+
A data row — a table row, a single-line list row — is `--zx-row-height`, derived from the control
|
|
249
|
+
height (36px at the default), so every list on a screen shares one rhythm and a tighter product is
|
|
250
|
+
still one decision. Type is one base: `--zx-text-base` (14px) with every `--zx-text-*` step derived
|
|
251
|
+
from it (12 / 13 / 14 / 16 / 18 / 24 / 30px at the default), so changing the base keeps the
|
|
252
|
+
hierarchy; setting `--zx-text-md` alone still moves only the control size.
|
|
64
253
|
To tighten or loosen an application, override those tokens on `:root` or on any region. The
|
|
65
254
|
geometry and material tokens (control size, radius, spacing, blur and glass filters, durations,
|
|
66
|
-
easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]`
|
|
67
|
-
override on `:root` reaches nested light and dark regions alike
|
|
255
|
+
easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]` element, so an
|
|
256
|
+
override on `:root` reaches nested light and dark regions alike — and colours work the same way
|
|
257
|
+
(see **Override once**):
|
|
68
258
|
|
|
69
259
|
```css
|
|
70
260
|
:root { --zx-space-unit: 3.5px; --zx-control-height: 28px; }
|
|
71
261
|
```
|
|
72
262
|
|
|
263
|
+
**Override once.** Every colour role is declared once, on `:root`; a theme element sets only
|
|
264
|
+
`color-scheme`, which picks the half of each `light-dark()` pair it reads. So a colour override
|
|
265
|
+
belongs on `:root` as well, written as `light-dark(<light>, <dark>)` where the two appearances
|
|
266
|
+
differ, and it reaches light, dark, auto and every nested region alike — together with everything
|
|
267
|
+
derived from it (hover, current, the glass and overlay tiers, and the tone tints follow
|
|
268
|
+
`--zx-color-text` and `--zx-color-bg-surface`) and every material the theme studio exports:
|
|
269
|
+
|
|
270
|
+
```css
|
|
271
|
+
:root {
|
|
272
|
+
--zx-color-bg-page: light-dark(#f7f8fa, #14161b);
|
|
273
|
+
--zx-color-text-muted: light-dark(#5b6170, #a3a9b6);
|
|
274
|
+
}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
A value without `light-dark()` applies to both appearances. The accent is a ramp, not a role: set
|
|
278
|
+
`--zx-accent-300…700` (or use a preset) and each appearance takes its own stop. A nested
|
|
279
|
+
`data-zx-preset` region restates the roles that read that ramp (`--zx-color-accent*`,
|
|
280
|
+
`--zx-color-bg-selected`, `--zx-color-ring`, `--zx-focus-ring`, `--zx-color-overlay-selected`, the
|
|
281
|
+
overlay images), so an override of one of those meant to reach such a region too is written
|
|
282
|
+
`:root, [data-zx-preset] { … }`. Never register a colour role with `@property`: a registered colour
|
|
283
|
+
resolves where it is declared and stops following the region. Script that needs a role's value
|
|
284
|
+
reads a probe element's computed `color`, not the property's text, which may be a `light-dark()`
|
|
285
|
+
pair that a canvas cannot parse. `light-dark()` needs a 2024 browser; older ones read Xenon's own
|
|
286
|
+
per-theme fallback, where a `:root` override stops at a nested theme region, so an application that
|
|
287
|
+
supports them puts its own `light-dark()` overrides inside `@supports (color: light-dark(#000,
|
|
288
|
+
#fff))`.
|
|
289
|
+
|
|
73
290
|
**Accent presets.** A second, orthogonal attribute picks the accent ramp:
|
|
74
|
-
`data-zx-preset="zx" | "zeyos" | "ocean" | "violet" | "rose" | "slate"` (`zx` is the default and
|
|
291
|
+
`data-zx-preset="zx" | "zeyos" | "ocean" | "violet" | "rose" | "slate" | "folio"` (`zx` is the default and
|
|
75
292
|
need not be set). A preset repoints five tier-1 tokens — `--zx-accent-300` … `--zx-accent-700` —
|
|
76
293
|
and the semantic tier takes its own stop per polarity (600/700 on light surfaces, 300/400/500 on
|
|
77
294
|
dark), so one five-line block rethemes light, dark, and auto together. Status colours are not part
|
|
@@ -90,24 +307,45 @@ Keep the 600 stop at 4.5:1 or better against white and the 400 stop at 4.5:1 aga
|
|
|
90
307
|
|
|
91
308
|
The theme studio treats those stable IDs as complete recipes: selecting a preset also changes its
|
|
92
309
|
spacing unit, neutral tint, radius, control height, base text size, font stack, and material strength.
|
|
93
|
-
Its **Material** control is CSS-first
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
310
|
+
Its **Material** control is CSS-first: eight materials, each a set of token overrides (there is no
|
|
311
|
+
attribute), composed from six per-theme *ingredients* the stylesheet declares —
|
|
312
|
+
`--zx-color-glass-rim` and `-ring` (the lit top edge and the hairline inner ring), `-lift` (white
|
|
313
|
+
laid on a pane from its top edge, which makes it read as lit rather than tinted), `-shade` (the
|
|
314
|
+
pane's own body: a veil over the scene, white in light and black in dark, that bounds what the
|
|
315
|
+
scene can do to text contrast), `-edge` (the cut outer line a pane needs against a dark scene) and
|
|
316
|
+
`-tint` (smoked glass) — plus `--zx-glass-grain`, a faint grey tooth. One recipe therefore
|
|
317
|
+
serves light and dark alike. **Glass**, the stylesheet default, is a thin lit pane: its light sits
|
|
318
|
+
on the edge, never as a wash on its face, and the filter saturates so colour behind survives the
|
|
319
|
+
blur. **Deep glass** is a thick pane — a double rim with an inner glow, one narrow specular band,
|
|
320
|
+
more refraction, a fine grain. **Frost** is milk glass: heavy diffusion, almost no reflection, text
|
|
321
|
+
as on paper. **Smoke** is tinted glass that darkens what is behind it (sunglass glass in dark).
|
|
322
|
+
**Paper** is opaque and matte, depth from a contact shadow and a modest cast; **Satin** is opaque
|
|
323
|
+
and brushed, a soft sheen across raised surfaces and a bright rim on controls; **Enamel** is an
|
|
324
|
+
opaque body under a glossy coat, a narrow highlight along the top edge and a darker foot, for
|
|
325
|
+
terminals and consoles where text backing must be certain. None of the three filters anything,
|
|
326
|
+
so they render cheaply and survive every fallback unchanged. **Flat** is the opaque semantic
|
|
327
|
+
surfaces. Aurora is
|
|
328
|
+
the independent ambient canvas layer; material is how surfaces respond to that light. The shared
|
|
329
|
+
recipe applies to AppIcons, ordinary controls, persistent chrome, raised cards, and every transient
|
|
330
|
+
overlay: Dropdown, ContextMenu, MenuButton, AccountMenu, AppRail flyouts, Select, TagPicker, date
|
|
331
|
+
pickers, tooltips, column menus, and toasts use `--zx-color-overlay-surface`; Launcher, Modal,
|
|
332
|
+
Dialog, and overlay Sheets use the calmer `--zx-color-overlay-panel`. The modal backdrop is a
|
|
100
333
|
separate material token so it does not erase the light the panel should refract. A docked Sheet is
|
|
101
|
-
layout rather than an overlay and becomes opaque, as do dense data surfaces.
|
|
102
|
-
progressively raise translucency, blur, highlights, and elevation; reduced-transparency,
|
|
334
|
+
layout rather than an overlay and becomes opaque, as do dense data surfaces. Reduced-transparency,
|
|
103
335
|
increased-contrast, forced-colour, and unsupported-filter environments restore solid surfaces.
|
|
104
336
|
Top-layer components remain DOM children of their nearest Zx theme scope, so a theme or material
|
|
105
337
|
set on an application region continues to inherit through its menus, dialogs, tooltips, and toasts.
|
|
106
338
|
|
|
107
|
-
Define a product theme
|
|
339
|
+
Define a product theme as an accent ramp (a preset) plus **semantic** token overrides, each declared
|
|
340
|
+
once on `:root` as above — not under a `[data-zx-theme="name"]` selector, which would stop at the
|
|
341
|
+
first nested region:
|
|
108
342
|
`--zx-color-bg-page/surface/raised/control/muted/hover/selected`, `--zx-color-bg-current` (the
|
|
109
343
|
neutral "you are here" fill of the current nav item, row, tab, or pressed toggle — never the
|
|
110
344
|
accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off the canvas),
|
|
345
|
+
`--zx-color-text-chrome` (navigation labels at rest, one ink step under the content and above 7:1;
|
|
346
|
+
hover, focus and the current item take the full text colour), `--zx-color-border-chrome` (the line
|
|
347
|
+
where a chrome column meets the canvas: none in light, where the tone step separates them; a
|
|
348
|
+
hairline in dark, under `prefers-contrast: more`, and in forced colours),
|
|
111
349
|
`--zx-color-glass-chrome/surface`,
|
|
112
350
|
`--zx-color-overlay-surface/panel/backdrop/border/hover/selected/divider/scrim`,
|
|
113
351
|
`--zx-overlay-surface-image/toast-image/panel-image`,
|
|
@@ -120,12 +358,29 @@ accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off
|
|
|
120
358
|
tiles, avatars — neither the accent nor a status) and `-solid` (a solid identity fill, such as a
|
|
121
359
|
module tile, that the white icon glyph reads on at 3:1 in both themes), the chart series
|
|
122
360
|
`--zx-color-chart-1…8`,
|
|
123
|
-
`--zx-
|
|
361
|
+
`--zx-color-ring` with `--zx-focus-ring` (keyboard focus; see **Focus** below),
|
|
362
|
+
`--zx-control-height/-radius`, `--zx-space-*`, `--zx-radius-*`, `--zx-text-*`
|
|
124
363
|
(`-3xl` for document titles), `--zx-weight-medium/-semibold`, `--zx-tracking-tight/-title`. Never
|
|
125
364
|
use tier-1 palette tokens (`--zx-gray-*`, `--zx-green-*`, `--zx-emerald-*`, `--zx-tone-*`) or raw
|
|
126
365
|
color literals in application/component CSS. Prefer the least-specific override that works (global
|
|
127
366
|
token → then, if needed, a component style).
|
|
128
367
|
|
|
368
|
+
**Focus.** Keyboard focus is one quiet line: `--zx-focus-ring` is a single 2px spread shadow in
|
|
369
|
+
`--zx-color-ring` (the accent, at the stop each theme reads as text), opaque, so it clears the 3:1
|
|
370
|
+
a focus indicator needs against everything it sits on — the page, the chrome, a card, a raised
|
|
371
|
+
panel, a current row and a selected row — in both themes, under every preset and tint, and for any
|
|
372
|
+
custom ramp that keeps the promise above. Being one shadow, it works both ways round:
|
|
373
|
+
`box-shadow: var(--zx-focus-ring)` draws it around a control, `box-shadow: inset
|
|
374
|
+
var(--zx-focus-ring)` inside a row, a tab, or a cell. Combine it by listing it after the
|
|
375
|
+
element's own shadows (`var(--zx-focus-ring), var(--zx-drag-shadow)`), with any `inset` layer
|
|
376
|
+
first, since `inset` belongs to one shadow of a list rather than to the list. Where the focused
|
|
377
|
+
element is itself an accent fill — a primary button, a chosen day — the ring would only make it
|
|
378
|
+
look larger, so lead with a 1px line in the fill's ink: `box-shadow: inset 0 0 0 1px
|
|
379
|
+
var(--zx-color-on-accent-solid), var(--zx-focus-ring)` (`--zx-color-on-accent` on a
|
|
380
|
+
`--zx-color-accent` fill). Leave the outline transparent rather than removing it: forced colours
|
|
381
|
+
drop every shadow and paint that outline in the system highlight instead. A product that restyles
|
|
382
|
+
the ring keeps it one shadow, at least 2px, and at 3:1; to recolour it, set `--zx-color-ring`.
|
|
383
|
+
|
|
129
384
|
**Print.** `zx.css` imports `styles/print.css` last. It releases sticky headers and scroll
|
|
130
385
|
containers, drops fills, shadows, zebra striping and focus rings, hides overlays and navigation
|
|
131
386
|
chrome, repeats table headers across pages, keeps cards and rows from breaking, and prints link
|
|
@@ -370,6 +625,65 @@ reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-butt
|
|
|
370
625
|
Each component is `new Component(target, options)`. Events are the component-level names (also
|
|
371
626
|
dispatched as bubbling `zx-<name>` on the root). Detail is always an object.
|
|
372
627
|
|
|
628
|
+
<!-- doc:prose -->
|
|
629
|
+
### Prose — `.zx-prose` and `.zx-callout`
|
|
630
|
+
|
|
631
|
+
The reading register: a class, not a component, that sets authored content — a document, a
|
|
632
|
+
record's notes, a message body, an assistant's answer — in the reading tokens rather than the
|
|
633
|
+
interface ones. Write plain HTML inside it: `h1`–`h4`, `p`, `ul`/`ol`, `blockquote`, `hr`, links,
|
|
634
|
+
inline `code`, `pre`, `kbd`, `mark`, tables, `figure`/`figcaption`, `img`.
|
|
635
|
+
|
|
636
|
+
- **Tokens** — `--zx-font-prose` (the interface stack by default; a serif here leaves the interface
|
|
637
|
+
alone), `--zx-prose-size` (16px, `--zx-text-lg`), `--zx-prose-leading` (1.7), `--zx-prose-measure`
|
|
638
|
+
(62ch, the reading width). Headings scale with the reading size and read `--zx-weight-title`.
|
|
639
|
+
- **Attributes** — `data-size="sm"` sets prose at the interface size, for comments, previews, and
|
|
640
|
+
panels; `data-zx-measure="full"` drops the measure where the column already sets the width.
|
|
641
|
+
- **Rhythm** — one gap between blocks, more above a heading and less below it; links in the body
|
|
642
|
+
colour over a quiet underline, accent on hover; tables without a frame, a muted header over
|
|
643
|
+
hairline rows, `data-align="end"` cells in tabular figures.
|
|
644
|
+
- **Content colour** — a bare `mark` highlights in the amber tone; `mark[data-tone]` in any of the
|
|
645
|
+
nine tones; a bare `span[data-tone]` colours its text, and `data-fill` highlights it as well.
|
|
646
|
+
- **Callout** — `.zx-callout` with an optional `.zx-callout__icon` and a `.zx-callout__body`
|
|
647
|
+
(`.zx-callout__title` for a bold first line): a tinted fill, no frame, at the interface size.
|
|
648
|
+
Neutral by default, because most callouts are emphasis; `data-kind="info|success|warning|danger"`
|
|
649
|
+
makes it a status and `data-tone` a category. Works inside or outside prose.
|
|
650
|
+
- **Specificity** — every rule is `.zx-prose` plus `:where()`, and the stylesheet loads before the
|
|
651
|
+
components, so a badge, an entity reference, or a table placed in prose keeps its own styles,
|
|
652
|
+
while an application's bare element reset cannot undo the rhythm.
|
|
653
|
+
- **Section links** — `proseAnchors(root, options)` ends every `h2`–`h4` with an `id` inside a
|
|
654
|
+
`.zx-prose` under `root` with a small link to itself (`a.zx-prose__anchor`, "Copy link to …").
|
|
655
|
+
It shows while the heading is pointed at or the link has focus (and always on a touch screen or
|
|
656
|
+
under a contrast preference). A click copies the address with the section's hash — the current
|
|
657
|
+
address by default, `href(id)` to build another — and confirms with a tick and a polite "Link
|
|
658
|
+
copied"; it never changes the location, and a middle or modified click is left to the browser.
|
|
659
|
+
Options: `selector`, `label` (`%1` is the heading), `title`, `feedback`, `feedbackDuration`,
|
|
660
|
+
`href`, `oncopy(url, copied)`. It returns `{refresh(), destroy()}`: call `refresh()` after
|
|
661
|
+
re-rendering the content. Headings without an id are skipped — give the ones worth linking a
|
|
662
|
+
stable id. `sectionHref(base, id)` builds the address.
|
|
663
|
+
<!-- /doc -->
|
|
664
|
+
|
|
665
|
+
<!-- doc:kbd -->
|
|
666
|
+
### Kbd — `kbd(keys, options)`
|
|
667
|
+
|
|
668
|
+
A factory (not a class) returning keycaps: one `<kbd class="zx-kbd">` holding a nested
|
|
669
|
+
`<kbd class="zx-kbd__key">` per key, which is how HTML marks up a combination. Button shortcuts,
|
|
670
|
+
the launcher's hints, and shortcut references all use it, so a key looks the same everywhere.
|
|
671
|
+
|
|
672
|
+
- **Signature** — `kbd(keys, { size, tone })` → `HTMLElement`. `keys` is a chord written like
|
|
673
|
+
`aria-keyshortcuts` (`'Mod+Shift+K'`; a literal plus as `'Mod++'`) or an array of keys for a
|
|
674
|
+
sequence (`['g', 'i']`). `size: 'md'|'sm'` (`sm` inside buttons and menu rows); `tone:
|
|
675
|
+
'neutral'|'inherit'` (`inherit` draws the caps in the surrounding ink, for a solid button or a
|
|
676
|
+
dark toast). `keyLabels(keys, { apple })` returns the labels without building DOM.
|
|
677
|
+
- **Labels** — `Mod` is ⌘ on Apple platforms and Ctrl elsewhere; `Alt`, `Shift`, `Ctrl`,
|
|
678
|
+
`Backspace`, `Delete`, `Tab` become ⌥ ⇧ ⌃ ⌫ ⌦ ⇥ on Apple platforms and words elsewhere; `Enter`,
|
|
679
|
+
`Escape` and the arrows become ↵, Esc, ↑ ↓ ← →; single letters are upper-cased.
|
|
680
|
+
- **Look** — a surface fill, one hairline and a 1px foot, the label at the small size and medium
|
|
681
|
+
weight, centred on its capital height; a single key is square. Retint it with `--zx-kbd-ink`,
|
|
682
|
+
`--zx-kbd-fill` and `--zx-kbd-line` on any ancestor.
|
|
683
|
+
- **Accessibility** — the caps are presentation. Announce a control's shortcut with
|
|
684
|
+
`aria-keyshortcuts` on the control and mark a hint that repeats it `aria-hidden`.
|
|
685
|
+
<!-- /doc -->
|
|
686
|
+
|
|
373
687
|
<!-- doc:button -->
|
|
374
688
|
### Button — `button(options)` / `buttonGroup(buttons)`
|
|
375
689
|
|
|
@@ -393,9 +707,9 @@ accept.
|
|
|
393
707
|
<!-- doc:badge -->
|
|
394
708
|
### Badge — `badge(options)` / `badgeGroup(badges)`
|
|
395
709
|
|
|
396
|
-
Factories (not classes) returning a
|
|
397
|
-
|
|
398
|
-
record-header metadata. A badge with no label but a `title` is named for assistive technology
|
|
710
|
+
Factories (not classes) returning a chip: a small, non-interactive `<span>` carrying a semantic
|
|
711
|
+
colour — a status — or, with `tone`, a categorical one — a tag — used for stages, counts, labels,
|
|
712
|
+
and record-header metadata. A badge with no label but a `title` is named for assistive technology
|
|
399
713
|
through `role="img"`; everything else is plain text and needs no ARIA.
|
|
400
714
|
|
|
401
715
|
- **Options** — `label`, `icon` (an icon name, rendered before the label), `kind:
|
|
@@ -408,11 +722,18 @@ through `role="img"`; everything else is plain text and needs no ARIA.
|
|
|
408
722
|
accent nor the status set, so a project tagged red never reads as an error. When `tone` is set it
|
|
409
723
|
decides the colour and `kind` is ignored for it; every `variant` still applies (soft: tinted,
|
|
410
724
|
borderless; solid: filled with the tone's ink; outline). The badge carries `data-tone`. Badges
|
|
411
|
-
are
|
|
725
|
+
are sentence case.
|
|
726
|
+
- **Two shapes, one construction** — a status is a pill (`--zx-radius-full`); give a workflow state
|
|
727
|
+
`dot: true`, a 6px dot centred in the pill's round end. A tag (any badge with a `tone`) has small
|
|
728
|
+
corners (`--zx-radius-md`). Both are one fill and no line, 12px at weight 500 at either size,
|
|
729
|
+
and their height follows the row they sit in: about five ninths of `--zx-row-height` for `md`
|
|
730
|
+
and half of it for `sm` (20px and 18px in the default row), never below a line of their own text,
|
|
731
|
+
so a chip follows the row height setting without making a row taller. `TagPicker` builds its tags with
|
|
732
|
+
`badge()`, so a label reads the same in a list row, a record header and the field that edits it.
|
|
412
733
|
- **Neutral and small** — the neutral soft fill is a wash of the text colour, not an opaque surface
|
|
413
734
|
step, so it stays visible on raised surfaces in the dark theme. `size: 'sm'` fits table cells
|
|
414
|
-
and board cards;
|
|
415
|
-
|
|
735
|
+
and board cards; it is shorter and tighter, never smaller type. Under `prefers-contrast: more` a
|
|
736
|
+
soft badge gets its edge back, and under forced colours every badge does.
|
|
416
737
|
- **Methods** — none. `badge(options)` → `HTMLSpanElement`, `badgeGroup([badge(…), …])` → a wrapping
|
|
417
738
|
inline row with its own spacing; you own both elements.
|
|
418
739
|
- **Events** — none; a badge is not interactive.
|
|
@@ -1116,9 +1437,19 @@ Text date input with a calendar popover. `DateTimeBox(target, opts)` is a Datebo
|
|
|
1116
1437
|
`time: true`, which also brings the TimePicker (and its clock face) into the popover. Format
|
|
1117
1438
|
tokens are the date-utility ones: `%d %m %Y %H %M`.
|
|
1118
1439
|
|
|
1119
|
-
- **Options** — `value: Date | number(unix) | string`, `format: '%d.%m.%Y'`, `
|
|
1120
|
-
`max`, `placeholder`, `clearable: true` (the clear button shows while
|
|
1121
|
-
box is enabled; without `clearable` the input keeps no room for it),
|
|
1440
|
+
- **Options** — `value: Date | number(unix) | string`, `format: '%d.%m.%Y'`, `displayFormat: null`,
|
|
1441
|
+
`time: false`, `min`, `max`, `placeholder`, `clearable: true` (the clear button shows while
|
|
1442
|
+
there is a value and the box is enabled; without `clearable` the input keeps no room for it),
|
|
1443
|
+
`disabled`.
|
|
1444
|
+
- **Two formats** — `format` is what the reader types, and what the field shows while it has
|
|
1445
|
+
focus; it is parsed, so it takes numeric tokens only. `displayFormat` is what the field shows at
|
|
1446
|
+
rest, so a date field reads the way the rest of the screen writes dates (`'%e %b %Y'` → "2 Nov
|
|
1447
|
+
2026" beside a header that says "Created 19 Jul 2026"). It is never parsed, so month and weekday
|
|
1448
|
+
names (`%b %B %a %A`) are fine; `null` shows `format`. Focus switches the text to the typing
|
|
1449
|
+
format, a valid commit on blur or Enter switches it back, and text that failed to parse stays as
|
|
1450
|
+
typed. With `time`, a format without `%H`/`%M` gets ` %H:%M` appended, the display format too.
|
|
1451
|
+
The placeholder still describes `format`, and string values passed to `set()` are parsed with it.
|
|
1452
|
+
`dateboxFormats({format, displayFormat, time})` → `{format, display}` resolves both the same way.
|
|
1122
1453
|
- **In a Field** — field types `date`/`datetime` (and `daterange`) fill the control column like a
|
|
1123
1454
|
text input and give way in a narrow two-column row; standalone, the box keeps its own width.
|
|
1124
1455
|
- **Methods** — `get(unit='date')` (`'seconds'` → unix), `set(value, {silent})` (accepts a Date;
|
|
@@ -1144,7 +1475,7 @@ An inline two-month calendar for picking a start and an end day, plus the form-u
|
|
|
1144
1475
|
|
|
1145
1476
|
#### DateRangeBox
|
|
1146
1477
|
|
|
1147
|
-
- **Options** — everything DateRangePicker takes, plus `format: '%d.%m.%Y'`, `separator: ' – '`, `placeholder: null` (derived from the format when null), `clearable: true` (no clear button while disabled, and no room kept for one without it). Typed text is parsed as `"<start><separator><end>"`; a lone date reads as a one-day range and a trailing separator keeps the range half open.
|
|
1478
|
+
- **Options** — everything DateRangePicker takes, plus `format: '%d.%m.%Y'`, `displayFormat: null`, `separator: ' – '`, `placeholder: null` (derived from the format when null), `clearable: true` (no clear button while disabled, and no room kept for one without it). Typed text is parsed as `"<start><separator><end>"`; a lone date reads as a one-day range and a trailing separator keeps the range half open. `displayFormat` is the endpoints' format at rest, as on Datebox (`'%e %b %Y'` → "3 Aug 2026 – 9 Aug 2026"); focus switches to `format`, and text left untouched while the calendar holds focus goes back to the display format.
|
|
1148
1479
|
- **Methods** — `get(unit = 'date')` (`'seconds'` returns `{start, end}` as Unix seconds), `set(range, {silent})` accepting `{start, end}` of Dates, Unix-seconds numbers, or formatted strings, `clear({silent})`, `open()`, `close()`, `enable()`, `disable()`, `focus()`, `destroy()`.
|
|
1149
1480
|
- **Events** — `change {start, end}`, `invalid {text}` when the typed value cannot be parsed (the text stays editable and the field takes `data-state="invalid"` plus `aria-invalid`), `open`, `close`.
|
|
1150
1481
|
<!-- /doc -->
|
|
@@ -2032,7 +2363,17 @@ mutate the caller's data.
|
|
|
2032
2363
|
- **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
|
|
2033
2364
|
`expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
|
|
2034
2365
|
(tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
|
|
2035
|
-
(lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height
|
|
2366
|
+
(lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height`,
|
|
2367
|
+
`rowActions: (node) => actions`, `moreLabel: 'More actions'`.
|
|
2368
|
+
- **Row actions** — `rowActions(node)` returns the row's commands: `{icon, label, onSelect(node),
|
|
2369
|
+
disabled?, danger?}` descriptors, or nodes of your own placed as given. One or two show as icon
|
|
2370
|
+
buttons at the row's end; with more, the first shows and the rest fold into a "More actions"
|
|
2371
|
+
menu (a node never folds). They rest out of sight and keep their room, and show while the row is
|
|
2372
|
+
pointed at, focused or selected, while its menu is open, and always on a touch screen, under a
|
|
2373
|
+
contrast preference and in forced colours — the `data-zx-reveal` utility. Every descriptor is
|
|
2374
|
+
also in the row's context menu (right-click, Shift+F10, the Menu key), and each control is named
|
|
2375
|
+
after its action and its row ("Add sub-page: Onboarding"); the row's own name stays its label.
|
|
2376
|
+
Use them only for repeated, secondary commands that are reachable another way too.
|
|
2036
2377
|
- **Methods** — `setItems()`, `getItems()`, `getNode(id)`, `getPath(id)`, `setFilter(query)` (keeps
|
|
2037
2378
|
matching nodes' ancestors and opens the surviving branches),
|
|
2038
2379
|
`expand(id)`/`collapse(id)`/`toggle(id)` (async — they await the loader),
|
|
@@ -2045,6 +2386,9 @@ mutate the caller's data.
|
|
|
2045
2386
|
activates, Space selects or toggles the checkbox, `*` expands every sibling, typing jumps to the
|
|
2046
2387
|
next match. A typed character's default action is prevented, so find-as-you-type and page
|
|
2047
2388
|
shortcuts do not act on it too; typing into a control inside a row is left to that control.
|
|
2389
|
+
With row actions, Tab from the focused row walks that row's actions and then leaves the tree
|
|
2390
|
+
(Shift+Tab comes back); keys pressed on an action belong to it, and clicking one neither selects
|
|
2391
|
+
nor focuses the row.
|
|
2048
2392
|
- **Appearance** — the selected node of a single-selection tree is where you are: the neutral
|
|
2049
2393
|
`--zx-color-bg-current` fill, the text colour, a semibold label. A `selection: 'multi'` tree is a
|
|
2050
2394
|
set of picks and keeps the accent tint. Icons, folders included, are drawn in
|
|
@@ -2314,12 +2658,16 @@ yet. Field type: `tagpicker`.
|
|
|
2314
2658
|
`filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
|
|
2315
2659
|
`max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
|
|
2316
2660
|
`placeholder`, `listHeight: 260`, `disabled`, `readonly`, `renderItem`, `renderTag`.
|
|
2661
|
+
- **Tags are Badges** — every selected tag is built by `badge()` (`.zx-badge.zx-tag-picker__tag`):
|
|
2662
|
+
the Badge's height from the row, 12px medium type, padding and one fill, with the tag shape's
|
|
2663
|
+
small corners. `toneKey` names a categorical tone from the Badge palette (`blue`, `teal`,
|
|
2664
|
+
`green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`), so a toned tag is exactly the
|
|
2665
|
+
`badge({ tone })` a list row or record header shows for the same item; a tone wins over a colour.
|
|
2666
|
+
An untoned tag keeps the text ink, because in a field it is the value.
|
|
2317
2667
|
- **Tag identity** — icon values accept a bundled icon name or Node; colors (a CSS colour or a token
|
|
2318
2668
|
reference such as `var(--zx-color-tone-blue-fg)`) are scoped to the tag and its option through
|
|
2319
|
-
`--zx-tag-color`.
|
|
2320
|
-
|
|
2321
|
-
toned Badge does (`data-tone`), and a tone wins over a colour. Custom `renderItem`/`renderTag`
|
|
2322
|
-
remain authoritative.
|
|
2669
|
+
`--zx-tag-color`. An option shows its icon on a tile of its colour; inside a tag the icon is a bare
|
|
2670
|
+
glyph, since the tag is already the fill. Custom `renderItem`/`renderTag` remain authoritative.
|
|
2323
2671
|
- **Read-only** — `readonly` (or `setReadonly(true)`) shows only the tags: no input, chevron, or
|
|
2324
2672
|
remove buttons, so a full row of tags never wraps onto an empty line.
|
|
2325
2673
|
- **Methods** — `getValues()`, `getItems()`, `setValues(values, {silent})`, `addValue()`,
|
|
@@ -2378,13 +2726,21 @@ returns the component, the way `tooltip()` does; call `.toElement()` for the nod
|
|
|
2378
2726
|
|
|
2379
2727
|
- **Options** — `label`, `value`, `format: 'number'|'currency'|'percent'|'fileSize'|null|fn`,
|
|
2380
2728
|
`currency`, `locale`, `caption`, `delta`, `deltaKind: 'positive'|'negative'|'neutral'`,
|
|
2381
|
-
`deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `
|
|
2382
|
-
`msg`.
|
|
2729
|
+
`deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `variant: 'default'|'plain'`,
|
|
2730
|
+
`emphasis`, `href`, `clickable`, `loading`, `msg`.
|
|
2383
2731
|
- **Appearance** — the label is a sentence-case muted line (13px, medium); the value is the loud
|
|
2384
2732
|
part (24px, weight 650, tabular figures); `caption` is one muted context line under it ("of
|
|
2385
2733
|
13,184"). `icon` is a muted glyph beside the label, never a coloured chip; `kind` tints only the
|
|
2386
2734
|
sparkline. The tile is a column with the sparkline at its foot, so tiles in a row are the same
|
|
2387
2735
|
height and line up whether or not each has a caption, a delta or a trend.
|
|
2736
|
+
- **Framed or plain** — the default is a framed tile on its own surface: use it where a figure
|
|
2737
|
+
stands among other content, as on a dashboard. `variant: 'plain'` drops the frame, the fill and
|
|
2738
|
+
the padding, for a record's own figures under its title: its text sits on the content edge,
|
|
2739
|
+
space alone separates it from the next, and the figure steps down to 16px. Do not draw boxes
|
|
2740
|
+
around plain figures in the layout either. Reflected as `data-variant`.
|
|
2741
|
+
- **One figure leads** — `emphasis: true` sets one figure per row above the others: 24px in a
|
|
2742
|
+
plain row (the record title's size, never above it), 30px on a framed tile. Reflected as
|
|
2743
|
+
`data-emphasis`. The size is `--zx-stat-tile-value-size`, which the loading skeleton reads too.
|
|
2388
2744
|
- **Methods** — `update(options)`, `getAccessibleName()`.
|
|
2389
2745
|
- **Events** — `click {event}`.
|
|
2390
2746
|
|
|
@@ -2782,8 +3138,18 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
|
|
|
2782
3138
|
`side: 'left'|'right'|'top'|'bottom'`, `layout: 'tree'|'modules'`, `module`, `moduleBar`
|
|
2783
3139
|
(`{appearance, labels: 'auto'|'beside'|'below'|'hidden', allModules, label}` for the module
|
|
2784
3140
|
strip), `label`,
|
|
2785
|
-
`header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
|
|
2786
|
-
`renderIcon(item, context)`. Icon values may also be names,
|
|
3141
|
+
`header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
|
|
3142
|
+
`moreLabel: 'More actions'`, and `renderIcon(item, context)`. Icon values may also be names,
|
|
3143
|
+
nodes, components, or factories.
|
|
3144
|
+
- **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
|
|
3145
|
+
disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
|
|
3146
|
+
rest in a "More actions" menu). They rest out of sight over the end of the row, which keeps room
|
|
3147
|
+
for them, and show while the row is pointed at, holds focus, is the current page or has its menu
|
|
3148
|
+
open — always on a touch screen, under a contrast preference and in forced colours. Each is named
|
|
3149
|
+
after its action and the destination ("Rename: Customers"). Only the actions of the destination
|
|
3150
|
+
holding focus are Tab stops, right after it; a right-click or Shift+F10 on the destination lists
|
|
3151
|
+
them all. The expanded tree and the modules layout's panel draw them; minimized flyouts show the
|
|
3152
|
+
destinations only.
|
|
2787
3153
|
- **Sections** — an item with `section: true` is a quiet heading over its `children`, which stay
|
|
2788
3154
|
at its own level: never indented, collapsed, focused, or selected, and it needs no `id`.
|
|
2789
3155
|
`actions` (a node) adds trailing controls such as an add button. Sections replace stacking
|
|
@@ -2930,8 +3296,8 @@ bar.setBadge('mail', 8);
|
|
|
2930
3296
|
newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
|
|
2931
3297
|
triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
|
|
2932
3298
|
these functions globally or compose them into their own UI and routing layer.
|
|
2933
|
-
- **Icons** — `icon(name, {size, label})` and `
|
|
2934
|
-
by default, Font Awesome after an opt-in.
|
|
3299
|
+
- **Icons** — `icon(name, {size, label})`, `icons`, and `ICON_SIZE` (one size per role); see the
|
|
3300
|
+
Icons section — bundled inline SVG by default, Font Awesome after an opt-in.
|
|
2935
3301
|
- **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
|
|
2936
3302
|
`{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
|
|
2937
3303
|
supports it and a scroll/resize-tracked fallback where it does not. Options are resolved once,
|
|
@@ -3004,6 +3370,26 @@ old `RangeError`, at a call site that can afford to fail: a test, or a build-tim
|
|
|
3004
3370
|
Font Awesome elements are sized with `font-size` and occupy 1em; bundled SVGs use width/height
|
|
3005
3371
|
attributes (default 16). Both honour `label` (`null` ⇒ `aria-hidden`, otherwise `role="img"` +
|
|
3006
3372
|
`aria-label`).
|
|
3373
|
+
|
|
3374
|
+
**Size an icon by its role.** `ICON_SIZE` names one pixel size per role, so every chevron, every
|
|
3375
|
+
dismiss ×, and every check renders alike wherever it appears, and a call site says what a glyph is
|
|
3376
|
+
for rather than how big it is: `icon('chevron-down', { size: ICON_SIZE.chevron })`. The components
|
|
3377
|
+
use it throughout; use it in application code too, and never write a number for one of these roles.
|
|
3378
|
+
|
|
3379
|
+
- `ICON_SIZE.control` (16) — the default: an icon that is a control's content or leads its label.
|
|
3380
|
+
- `ICON_SIZE.chevron` (14) — dropdown, disclosure, and reorder chevrons; calendar and pager
|
|
3381
|
+
arrows; breadcrumb separators.
|
|
3382
|
+
- `ICON_SIZE.dismiss` (14) — the × that clears a field, closes a tab, dialog, or message, or
|
|
3383
|
+
removes a row.
|
|
3384
|
+
- `ICON_SIZE.check` (14) — the check of a selected option, a pressed toggle button, or a completed
|
|
3385
|
+
step.
|
|
3386
|
+
- `ICON_SIZE.sort` (14) — the sort-direction arrow beside a column heading.
|
|
3387
|
+
- `ICON_SIZE.chip` (12) — any glyph inside a chip or token, its remove × included.
|
|
3388
|
+
- `ICON_SIZE.marker` (8) — a glyph drawn inside a small status marker.
|
|
3389
|
+
|
|
3390
|
+
Several roles share a value and are named apart so one can change on its own. At 14px and below an
|
|
3391
|
+
outline is drawn with a one-pixel line, so the indicator roles also share a stroke weight. A text
|
|
3392
|
+
character is never a stand-in for an icon: draw "×", "✓", or an arrow with `icon()`.
|
|
3007
3393
|
<!-- /doc -->
|
|
3008
3394
|
|
|
3009
3395
|
<!-- doc:helpers -->
|
|
@@ -3109,7 +3495,8 @@ destroys its component.
|
|
|
3109
3495
|
|
|
3110
3496
|
Registered elements: `<zx-toggle>`, `<zx-check-button>`, `<zx-select items='[…]' required>`,
|
|
3111
3497
|
`<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
|
|
3112
|
-
`<zx-table>`, `<zx-dialog>`.
|
|
3498
|
+
`<zx-table>`, `<zx-dialog>`. `<zx-datebox>` takes `display-format` beside `format`, as the
|
|
3499
|
+
Datebox options `displayFormat` and `format`.
|
|
3113
3500
|
<!-- /doc -->
|
|
3114
3501
|
|
|
3115
3502
|
<!-- doc:tokens -->
|
|
@@ -3180,4 +3567,12 @@ record: native inputs, selects, and textareas inside it drop their border and fi
|
|
|
3180
3567
|
(`--zx-color-bg-hover`) or focus (the normal border, the control fill, and the focus ring), so values
|
|
3181
3568
|
read as text rather than as a wall of boxes. Read-only and disabled fields stay quiet. The rules have
|
|
3182
3569
|
zero specificity, so a component's own input styling still wins.
|
|
3570
|
+
|
|
3571
|
+
**Revealed actions.** Mark a row or a section heading `data-zx-reveal-host` and a secondary action
|
|
3572
|
+
inside it `data-zx-reveal`: the action rests invisible and appears while the host is pointed at,
|
|
3573
|
+
holds focus, is current or selected, or has a menu open. It keeps its space, so nothing shifts, and
|
|
3574
|
+
stays in the tab order, so focusing it shows it. On touch screens, under `prefers-contrast: more`
|
|
3575
|
+
and in forced colours it is always visible. Use it only for repeated, secondary per-row actions
|
|
3576
|
+
that are reachable another way (a context menu, a keyboard shortcut); a primary action stays
|
|
3577
|
+
visible. Hosts do not nest.
|
|
3183
3578
|
<!-- /doc -->
|