@zeyos/zx 5.2.0 → 5.4.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 +79 -0
- package/README.md +26 -0
- package/dist/types/components/card-view/card-view.d.ts +236 -0
- package/dist/zx.css +177 -64
- package/dist/zx.esm.js +453 -30
- package/dist/zx.esm.min.js +6 -6
- package/dist/zx.global.js +453 -30
- package/dist/zx.global.min.js +6 -6
- package/dist/zx.min.css +1 -1
- package/docs/api.json +41 -0
- package/docs/llms.md +229 -12
- package/docs/llms.txt +19 -1
- package/package.json +1 -1
- package/src/components/card-view/card-view.css +71 -0
- package/src/components/card-view/card-view.js +505 -15
- package/src/components/message/message.css +6 -2
- package/src/components/search/search.css +2 -0
- package/styles/tokens/dark.css +28 -0
- package/styles/tokens/semantic.css +101 -59
package/docs/api.json
CHANGED
|
@@ -1914,6 +1914,30 @@
|
|
|
1914
1914
|
"type": "string|null",
|
|
1915
1915
|
"default": "null",
|
|
1916
1916
|
"description": "Accessible collection label; null resolves message `cardView.label`, \"Card view\"."
|
|
1917
|
+
},
|
|
1918
|
+
{
|
|
1919
|
+
"name": "keyboard",
|
|
1920
|
+
"type": "'tabs'|'roving'",
|
|
1921
|
+
"default": "'tabs'",
|
|
1922
|
+
"description": "Keyboard model. `'tabs'` makes every card, title link, checkbox, and action its own Tab stop. `'roving'` — recommended for lists — follows the APG Grid pattern with row focus: the collection is one Tab stop, the arrow keys, Home/End, and PageUp/PageDown move between cards, Enter activates, Space selects, and the controls inside a card stay pointer targets with `tabindex=\"-1\"`."
|
|
1923
|
+
},
|
|
1924
|
+
{
|
|
1925
|
+
"name": "collapsibleGroups",
|
|
1926
|
+
"type": "boolean",
|
|
1927
|
+
"default": "false",
|
|
1928
|
+
"description": "Whether group headings carry a toggle that hides and shows the group's cards."
|
|
1929
|
+
},
|
|
1930
|
+
{
|
|
1931
|
+
"name": "collapsedGroups",
|
|
1932
|
+
"type": "unknown[]",
|
|
1933
|
+
"default": "[]",
|
|
1934
|
+
"description": "Group ids that start collapsed."
|
|
1935
|
+
},
|
|
1936
|
+
{
|
|
1937
|
+
"name": "renderGroupHeading",
|
|
1938
|
+
"type": "((context:CardGroupHeadingContext)=>Node|string|null|undefined)|null",
|
|
1939
|
+
"default": "null",
|
|
1940
|
+
"description": "Content of a group heading in place of its label. With `collapsibleGroups` it is placed inside the toggle button, so it must not contain interactive elements."
|
|
1917
1941
|
}
|
|
1918
1942
|
],
|
|
1919
1943
|
"events": [
|
|
@@ -1921,6 +1945,11 @@
|
|
|
1921
1945
|
"name": "recordaction",
|
|
1922
1946
|
"payload": "Record<string,unknown>",
|
|
1923
1947
|
"description": ""
|
|
1948
|
+
},
|
|
1949
|
+
{
|
|
1950
|
+
"name": "groupcollapse",
|
|
1951
|
+
"payload": "{id:string,collapsed:boolean,collapsedGroups:string[]}",
|
|
1952
|
+
"description": ""
|
|
1924
1953
|
}
|
|
1925
1954
|
],
|
|
1926
1955
|
"methods": [
|
|
@@ -1936,6 +1965,18 @@
|
|
|
1936
1965
|
"returns": "this",
|
|
1937
1966
|
"description": "Restores shared and CardView configuration. Unknown shared fields reconcile in RecordView."
|
|
1938
1967
|
},
|
|
1968
|
+
{
|
|
1969
|
+
"name": "setGroupCollapsed",
|
|
1970
|
+
"signature": "setGroupCollapsed(id, [collapsed], [options])",
|
|
1971
|
+
"returns": "this",
|
|
1972
|
+
"description": "Collapses or expands one group. A collapsed group keeps its heading and hides its cards."
|
|
1973
|
+
},
|
|
1974
|
+
{
|
|
1975
|
+
"name": "getCollapsedGroups",
|
|
1976
|
+
"signature": "getCollapsedGroups()",
|
|
1977
|
+
"returns": "string[]",
|
|
1978
|
+
"description": "Returns the collapsed group ids."
|
|
1979
|
+
},
|
|
1939
1980
|
{
|
|
1940
1981
|
"name": "destroy",
|
|
1941
1982
|
"signature": "destroy()",
|
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,178 @@ 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) | 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"`) 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.
|
|
192
|
+
4. **Material** — how surfaces answer light, exported from the studio as token overrides (there
|
|
193
|
+
is no attribute). `Glass` (the default: a thin lit pane), `Deep glass` (a thick one), `Frost`
|
|
194
|
+
(milk glass for reading surfaces), `Smoke` (tinted glass that darkens the scene; dark-first
|
|
195
|
+
products), `Paper`, `Satin` and `Enamel` (opaque: matte, brushed or glazed; no blur, so they
|
|
196
|
+
render cheaply and never depend on what is behind them), or `Flat`. `Aurora` supplies the light glass responds to. Reduced-transparency,
|
|
197
|
+
high-contrast, forced-colour and unsupported-filter environments fall back to solid surfaces on
|
|
198
|
+
their own.
|
|
199
|
+
5. **Motion** — `data-zx-motion="reduced"` is the only switch; own transitions use `--zx-dur-*`,
|
|
200
|
+
`--zx-ease`, `--zx-ease-spring`, `--zx-ease-drawer`.
|
|
201
|
+
6. **Colour roles** — `--zx-color-tone-*` for categories (tags, modules, avatars),
|
|
202
|
+
`--zx-color-danger|warning|success|info` for status, `--zx-color-bg-current` for "you are here"
|
|
203
|
+
and `--zx-color-bg-selected` for "what you picked", `--zx-color-bg-chrome` for navigation and
|
|
204
|
+
inspector columns. A module's colour is its `tone` on `ModuleBar`.
|
|
205
|
+
7. **Type** — `--zx-font-sans`, `--zx-font-mono`, `--zx-text-md` (the control size); the steps
|
|
206
|
+
follow.
|
|
207
|
+
8. **Fields** — `data-zx-fields="quiet"` on property panels (no border or fill until hovered or
|
|
208
|
+
focused).
|
|
209
|
+
9. **Print** — works without work; keep status badges, hide chrome. Nothing to add.
|
|
210
|
+
10. **Markup-first pages** — `defineElements()` for `<zx-*>` custom elements where templates are
|
|
211
|
+
authored as HTML.
|
|
212
|
+
|
|
213
|
+
### Never
|
|
214
|
+
|
|
215
|
+
- No raw colours (`#hex`, `rgb()`, named), no tier-1 tokens (`--zx-gray-*`, `--zx-emerald-*`,
|
|
216
|
+
`--zx-tone-*`), no hard-coded sizes the geometry tokens cover.
|
|
217
|
+
- No application CSS on component internals (`.zx-<component>__<part>` selectors); override a
|
|
218
|
+
token, or use a published hook.
|
|
219
|
+
- No hand-built dropdowns, menus, dialogs, tooltips, tables, date pickers, or toasts.
|
|
220
|
+
- No `innerHTML` with data; `h()` and text nodes.
|
|
221
|
+
- No state classes; state is ARIA and `data-state`, which the stylesheets already match.
|
|
222
|
+
- No second shell, second navigation, or second keyboard convention inside one application.
|
|
223
|
+
|
|
50
224
|
## Theming
|
|
51
225
|
|
|
52
226
|
Load `zx.css`, then set the theme on any ancestor (usually `<html>`):
|
|
@@ -90,16 +264,31 @@ Keep the 600 stop at 4.5:1 or better against white and the 400 stop at 4.5:1 aga
|
|
|
90
264
|
|
|
91
265
|
The theme studio treats those stable IDs as complete recipes: selecting a preset also changes its
|
|
92
266
|
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
|
-
|
|
267
|
+
Its **Material** control is CSS-first: eight materials, each a set of token overrides (there is no
|
|
268
|
+
attribute), composed from six per-theme *ingredients* the stylesheet declares —
|
|
269
|
+
`--zx-color-glass-rim` and `-ring` (the lit top edge and the hairline inner ring), `-lift` (white
|
|
270
|
+
laid on a pane from its top edge, which makes it read as lit rather than tinted), `-shade` (the
|
|
271
|
+
pane's own body: a veil over the scene, white in light and black in dark, that bounds what the
|
|
272
|
+
scene can do to text contrast), `-edge` (the cut outer line a pane needs against a dark scene) and
|
|
273
|
+
`-tint` (smoked glass) — plus `--zx-glass-grain`, a faint grey tooth. One recipe therefore
|
|
274
|
+
serves light and dark alike. **Glass**, the stylesheet default, is a thin lit pane: its light sits
|
|
275
|
+
on the edge, never as a wash on its face, and the filter saturates so colour behind survives the
|
|
276
|
+
blur. **Deep glass** is a thick pane — a double rim with an inner glow, one narrow specular band,
|
|
277
|
+
more refraction, a fine grain. **Frost** is milk glass: heavy diffusion, almost no reflection, text
|
|
278
|
+
as on paper. **Smoke** is tinted glass that darkens what is behind it (sunglass glass in dark).
|
|
279
|
+
**Paper** is opaque and matte, depth from a contact shadow and a modest cast; **Satin** is opaque
|
|
280
|
+
and brushed, a soft sheen across raised surfaces and a bright rim on controls; **Enamel** is an
|
|
281
|
+
opaque body under a glossy coat, a narrow highlight along the top edge and a darker foot, for
|
|
282
|
+
terminals and consoles where text backing must be certain. None of the three filters anything,
|
|
283
|
+
so they render cheaply and survive every fallback unchanged. **Flat** is the opaque semantic
|
|
284
|
+
surfaces. Aurora is
|
|
285
|
+
the independent ambient canvas layer; material is how surfaces respond to that light. The shared
|
|
286
|
+
recipe applies to AppIcons, ordinary controls, persistent chrome, raised cards, and every transient
|
|
287
|
+
overlay: Dropdown, ContextMenu, MenuButton, AccountMenu, AppRail flyouts, Select, TagPicker, date
|
|
288
|
+
pickers, tooltips, column menus, and toasts use `--zx-color-overlay-surface`; Launcher, Modal,
|
|
289
|
+
Dialog, and overlay Sheets use the calmer `--zx-color-overlay-panel`. The modal backdrop is a
|
|
100
290
|
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,
|
|
291
|
+
layout rather than an overlay and becomes opaque, as do dense data surfaces. Reduced-transparency,
|
|
103
292
|
increased-contrast, forced-colour, and unsupported-filter environments restore solid surfaces.
|
|
104
293
|
Top-layer components remain DOM children of their nearest Zx theme scope, so a theme or material
|
|
105
294
|
set on an application region continues to inherit through its menus, dialogs, tooltips, and toasts.
|
|
@@ -1700,8 +1889,13 @@ portable state as TableView and KanbanView.
|
|
|
1700
1889
|
|
|
1701
1890
|
- **Options** — the shared RecordView options plus `titleField`, `subtitleField`, `preview`,
|
|
1702
1891
|
`previewAlt`, `link`, `actions`, `groupBy`, `groupOrder`, `minCardWidth`, `maxColumns`,
|
|
1703
|
-
`variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`,
|
|
1704
|
-
resolves message `cardView.label`, "Card view")
|
|
1892
|
+
`variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`, `label` (null
|
|
1893
|
+
resolves message `cardView.label`, "Card view"), `keyboard: 'tabs'|'roving'` (default `'tabs'`),
|
|
1894
|
+
`collapsibleGroups`, `collapsedGroups`, and `renderGroupHeading`.
|
|
1895
|
+
- **Methods** — the shared RecordView methods plus `setGroupCollapsed(id, collapsed, {silent})` and
|
|
1896
|
+
`getCollapsedGroups()`. **Events** — the shared set plus `recordaction` and
|
|
1897
|
+
`groupcollapse {id, collapsed, collapsedGroups}` (also a `statechange` with reason
|
|
1898
|
+
`'groupcollapse'`). The view state carries `collapsedGroups`.
|
|
1705
1899
|
- **Messages** — `cardView.label`, `cardView.sort`, `cardView.sortCards`, `cardView.unsorted`,
|
|
1706
1900
|
`cardView.sortAscending`/`cardView.sortDescending` (`%1` the field), `cardView.ungrouped`
|
|
1707
1901
|
("Ungrouped"), `cardView.groupEmpty` ("No records in this group."), `table.empty` for the empty
|
|
@@ -1728,6 +1922,29 @@ portable state as TableView and KanbanView.
|
|
|
1728
1922
|
a stable fallback. Title/action links are normalized; `_blank` links receive `noopener`.
|
|
1729
1923
|
- **Grouping and layout** — `groupBy` is a field ID or callback; `groupOrder` may deliberately show
|
|
1730
1924
|
empty groups. Cards reflow through container queries and may cap columns without viewport logic.
|
|
1925
|
+
- **Keyboard model** — `keyboard: 'roving'` is the recommended setting for lists; `'tabs'` stays the
|
|
1926
|
+
default for compatibility, and makes every card, title link, checkbox, and action its own Tab
|
|
1927
|
+
stop (44 stops for 22 selectable cards). `'roving'` follows the WAI-ARIA APG **Grid** pattern with
|
|
1928
|
+
row focus, the same model as `Table`: the content is `role="grid"` (`aria-multiselectable` for
|
|
1929
|
+
`multi`), each card a `row` with `aria-selected` when selectable, and the collection is one Tab
|
|
1930
|
+
stop. Grid rather than listbox because a card holds a link and buttons, which a listbox option
|
|
1931
|
+
would flatten. ArrowUp/ArrowDown move to the card above or below — columns are measured from the
|
|
1932
|
+
rendered positions, and the column you travel in is remembered — ArrowLeft/ArrowRight within a
|
|
1933
|
+
row, Home/End to the first or last card, PageUp/PageDown by a visible page. Enter activates
|
|
1934
|
+
(`recordclick`), Space toggles selection in `selectable` modes (activates otherwise),
|
|
1935
|
+
Shift+movement extends a `multi` selection, Ctrl/Cmd+A selects every rendered card. Title links,
|
|
1936
|
+
checkboxes, and actions get `tabindex="-1"`: they still work with the pointer, and Enter on the
|
|
1937
|
+
card is the keyboard route. The current card is kept by record id across `setData`, sorting,
|
|
1938
|
+
grouping, and collapsing, and focus is restored with `preventScroll`. Focus shows as an inset
|
|
1939
|
+
`--zx-focus-ring` with a transparent outline for forced-colors mode.
|
|
1940
|
+
- **Group headings** — `renderGroupHeading({id, label, count, records, collapsed, toggle})` returns
|
|
1941
|
+
the heading content in place of the label. `collapsibleGroups: true` makes each heading an APG
|
|
1942
|
+
disclosure: a button with `aria-expanded` and `aria-controls` pointing at the group's list, which
|
|
1943
|
+
holds the label (and so the custom content, which must then not contain interactive elements).
|
|
1944
|
+
A collapsed group keeps its heading and renders no cards; `collapsedGroups` sets the initial
|
|
1945
|
+
ones. In the roving model a collapsible heading is a row in the arrow-key order: Enter or Space
|
|
1946
|
+
toggles it, ArrowLeft collapses, ArrowRight expands, and collapsing the group of the focused card
|
|
1947
|
+
moves focus to its heading.
|
|
1731
1948
|
- **Interaction** — By default Enter activates a focused card; Space toggles selection. With
|
|
1732
1949
|
`selectionTrigger:'card'`, Enter also toggles selection. Links, actions,
|
|
1733
1950
|
selection controls, and selected text do not also activate the card. `recordaction` adds the
|
package/docs/llms.txt
CHANGED
|
@@ -18,6 +18,24 @@ exports and as `window.zx.*`.
|
|
|
18
18
|
- [API reference](llms.md): per-component constructor options, methods, and events for all public components plus the core helpers.
|
|
19
19
|
- [Changelog](../CHANGELOG.md): what changed in each release, including behaviour changes an upgrade has to account for.
|
|
20
20
|
|
|
21
|
+
## Start here: choosing
|
|
22
|
+
- Start every screen from the closest **layout**, never from a blank page. Gallery:
|
|
23
|
+
https://zx.zeyos.com/layouts (`layouts.html#<id>` opens one); source
|
|
24
|
+
`https://zx.zeyos.com/layouts/<id>.layout.js` + `<id>.layout.css`; the shell helpers
|
|
25
|
+
`layouts/kit.js` + `kit.css`, and `layouts/overview.js` + `overview.css` (`createOverview()`,
|
|
26
|
+
the toolbar-chips-drawers-pager composition every record screen uses). They are site modules,
|
|
27
|
+
not package exports: copy them beside the application.
|
|
28
|
+
- Templates (complete applications on one shell): `mail`, `issue-tracker`, `wiki`, `ai-chat`,
|
|
29
|
+
`agent-workspace`, `invoice-editor`, `item-inventory`, `workflows`, `infrastructure`, `crm`.
|
|
30
|
+
Patterns (single screens): `master-detail`, `record-collection` (any list of records),
|
|
31
|
+
`dashboard`, `inbox`, `record-page`, `agent-chat`, `record-wizard`, `checkout-wizard`,
|
|
32
|
+
`settings-workspace`, `system-states` (every empty, loading, error, and confirmation state),
|
|
33
|
+
`zeyos-invoices`.
|
|
34
|
+
- The agent reference's **"Choosing what to build with"** section maps each screen to its layout
|
|
35
|
+
and each job to its component, lists the theming decisions (theme, accent preset, geometry
|
|
36
|
+
tokens, material, motion, colour roles), and what never to build by hand. Read it before
|
|
37
|
+
building anything.
|
|
38
|
+
|
|
21
39
|
## Components
|
|
22
40
|
- Inputs: `button()`, `buttonGroup()`, `badge()`/`badgeGroup()`, `CheckButton`,
|
|
23
41
|
`Toggle`, `Search`,
|
|
@@ -60,7 +78,7 @@ exports and as `window.zx.*`.
|
|
|
60
78
|
- Helpers: `formatNumber`/`formatCurrency`/`formatPercent`/`formatFileSize`/`formatRelativeTime` (locale-aware, cached `Intl`), `debounce`/`throttle`, `groupBy`/`sortBy`/`uniqueBy`, `escapeRegExp`/`highlightMatch`, `storage()` (namespaced JSON, degrades to memory), `toCsv`/`downloadBlob`/`copyToClipboard`, `truncate()`/`isTruncated()` (line clamp with the full value on hover).
|
|
61
79
|
|
|
62
80
|
## Theming
|
|
63
|
-
Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) on any ancestor. There is one geometry: spacing steps are multiples of `--zx-space-unit` (4px), radius steps are fractions of `--zx-radius` (4px: 2/3/4/6px), and controls are `--zx-control-height` (30px) tall — override those to tighten or loosen an application. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, spacing, font, type size, radius, control height, and CSS-first glass
|
|
81
|
+
Load `zx.css` once; set `data-zx-theme` (`light`|`dark`|`auto`) on any ancestor. There is one geometry: spacing steps are multiples of `--zx-space-unit` (4px), radius steps are fractions of `--zx-radius` (4px: 2/3/4/6px), and controls are `--zx-control-height` (30px) tall — override those to tighten or loosen an application. Define a product theme by overriding semantic `--zx-color-*` / `--zx-control-*` tokens under `[data-zx-theme="name"]`. The theme studio controls accent, neutral tint, spacing, font, type size, radius, control height, and the CSS-first material: Glass (the default, a thin lit pane), Deep glass, Frost (milk glass), Smoke (tinted), Paper, Satin and Enamel (opaque, no blur), or Flat — each a token-override recipe composed from the theme's glass ingredients (`--zx-color-glass-rim/-ring/-lift/-shade/-edge/-tint`). Compact menus, pickers, tooltips, column menus, and toasts share responsive compact glass; Launcher, Modal, Dialog, and floating Sheets share a calmer reading panel. Both preserve scoped theme inheritance and refract Aurora/page content; docked Sheets and dense data surfaces remain opaque. Never use tier-1 palette tokens or raw color literals in application CSS.
|
|
64
82
|
|
|
65
83
|
## Talking to ZeyOS
|
|
66
84
|
Use the dedicated ZeyOS client library **`@zeyos/client`** (`npm install @zeyos/client`) for ZeyOS business data: `createZeyosClient({ platform, auth })`, typed `client.api.list/get/create/update<Resource>` over the full OpenAPI surface, and `normalizeListResult`. Zx accepts the client by injection and does not bundle it. See the `website/layouts/zeyos-invoices.layout.js` layout for a Zx-components-on-@zeyos/client reference. Zx also ships a minimal `Http`/`zeyosService` for ad-hoc in-app `remotecall`, but `@zeyos/client` is the recommended default.
|
package/package.json
CHANGED
|
@@ -59,6 +59,77 @@
|
|
|
59
59
|
line-height: 1.3;
|
|
60
60
|
}
|
|
61
61
|
|
|
62
|
+
/* The heading row: a plain wrapper in the tab model, a grid row in the roving one. */
|
|
63
|
+
.zx-card-view__group-header {
|
|
64
|
+
border-radius: var(--zx-radius-sm);
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
.zx-card-view__group-header:focus-visible {
|
|
68
|
+
outline: 2px solid transparent;
|
|
69
|
+
box-shadow: inset var(--zx-focus-ring);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/* A collapsible heading is an APG disclosure: the button carries the label, the chevron turns. */
|
|
73
|
+
.zx-card-view__group-toggle {
|
|
74
|
+
display: inline-flex;
|
|
75
|
+
align-items: center;
|
|
76
|
+
gap: var(--zx-space-1);
|
|
77
|
+
min-block-size: 0;
|
|
78
|
+
margin-inline-start: calc(-1 * var(--zx-space-1));
|
|
79
|
+
padding: var(--zx-space-1);
|
|
80
|
+
border: 0;
|
|
81
|
+
border-radius: var(--zx-radius-sm);
|
|
82
|
+
background: none;
|
|
83
|
+
color: inherit;
|
|
84
|
+
font: inherit;
|
|
85
|
+
cursor: pointer;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
.zx-card-view__group-toggle:hover {
|
|
89
|
+
background: var(--zx-color-bg-hover);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
.zx-card-view__group-toggle:focus-visible {
|
|
93
|
+
outline: 2px solid transparent;
|
|
94
|
+
box-shadow: var(--zx-focus-ring);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
.zx-card-view__group-toggle > .zx-icon {
|
|
98
|
+
flex: none;
|
|
99
|
+
color: var(--zx-color-text-subtle);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
.zx-card-view__group-toggle[aria-expanded="false"] > .zx-icon {
|
|
103
|
+
transform: rotate(-90deg);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
.zx-card-view__group[data-collapsed="true"] .zx-card-view__group-heading {
|
|
107
|
+
margin-block-end: 0;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
.zx-card-view__list[hidden] {
|
|
111
|
+
display: none;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/* Roving focus sits inside the card, so a host that restyles cards into flush rows still shows
|
|
115
|
+
it; the transparent outline is what forced-colors mode paints. */
|
|
116
|
+
.zx-card-view[data-keyboard="roving"] .zx-record-card:focus-visible {
|
|
117
|
+
outline: 2px solid transparent;
|
|
118
|
+
outline-offset: -2px;
|
|
119
|
+
box-shadow: inset var(--zx-focus-ring);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
.zx-card-view__content[data-empty-focus]:focus-visible {
|
|
123
|
+
outline: 2px solid transparent;
|
|
124
|
+
box-shadow: inset var(--zx-focus-ring);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
@media (prefers-reduced-motion: no-preference) {
|
|
128
|
+
.zx-card-view__group-toggle > .zx-icon {
|
|
129
|
+
transition: transform var(--zx-dur-fast) var(--zx-ease);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
62
133
|
.zx-card-view__list {
|
|
63
134
|
display: grid;
|
|
64
135
|
grid-template-columns: repeat(auto-fill,
|