@zeyos/zx 5.6.0 → 5.7.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 +154 -0
- package/README.md +73 -7
- package/bin/zx-css.js +328 -0
- package/dist/types/components/account-menu/account-menu.d.ts +4 -2
- package/dist/types/components/activity-list/activity-list.d.ts +14 -8
- package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
- package/dist/types/components/agent-thread/agent-thread.d.ts +142 -14
- package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
- package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
- package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
- package/dist/types/components/calendar/calendar-model.d.ts +9 -2
- package/dist/types/components/calendar/calendar.d.ts +12 -4
- package/dist/types/components/chart/chart.d.ts +25 -13
- package/dist/types/components/code-editor/code-editor.d.ts +7 -2
- package/dist/types/components/composer/composer.d.ts +206 -4
- package/dist/types/components/composer/queue.d.ts +76 -0
- package/dist/types/components/copy/copy-button.d.ts +6 -4
- package/dist/types/components/copy/copy-input.d.ts +10 -6
- package/dist/types/components/datebox/date-range-box.d.ts +33 -0
- package/dist/types/components/datebox/placeholder.d.ts +7 -0
- package/dist/types/components/dock/dock.d.ts +12 -3
- package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
- package/dist/types/components/field-upload/field-upload.d.ts +3 -2
- package/dist/types/components/file-item/file-item.d.ts +3 -2
- package/dist/types/components/file-list/file-list.d.ts +14 -8
- package/dist/types/components/filter/filter-model.d.ts +31 -1
- package/dist/types/components/filter/filter.d.ts +20 -2
- package/dist/types/components/finder/finder.d.ts +14 -6
- package/dist/types/components/flag/flag.d.ts +99 -0
- package/dist/types/components/grid/grid.d.ts +1 -1
- package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
- package/dist/types/components/launcher/launcher.d.ts +2 -0
- package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
- package/dist/types/components/number-field/number-field.d.ts +17 -6
- package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
- package/dist/types/components/prose/prose.d.ts +9 -6
- package/dist/types/components/questionnaire/conditions.d.ts +270 -0
- package/dist/types/components/questionnaire/items.d.ts +52 -30
- package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
- package/dist/types/components/rating/rating.d.ts +5 -3
- package/dist/types/components/select/country.d.ts +106 -0
- package/dist/types/components/select/field-adapter.d.ts +2 -1
- package/dist/types/components/select/locale.d.ts +102 -0
- package/dist/types/components/select/select.d.ts +41 -2
- package/dist/types/components/slider/slider.d.ts +1 -0
- package/dist/types/components/sort-control/sort-control.d.ts +7 -3
- package/dist/types/components/source-list/source-list.d.ts +7 -5
- package/dist/types/components/split-view/split-view.d.ts +5 -3
- package/dist/types/components/surface/catalog.d.ts +260 -0
- package/dist/types/components/surface/elicit.d.ts +81 -0
- package/dist/types/components/surface/mcp.d.ts +165 -0
- package/dist/types/components/surface/schema.d.ts +314 -0
- package/dist/types/components/surface/stream.d.ts +118 -0
- package/dist/types/components/surface/surface.d.ts +718 -0
- package/dist/types/components/surface/text.d.ts +277 -0
- package/dist/types/components/surface/validate.d.ts +339 -0
- package/dist/types/components/table/table.d.ts +55 -3
- package/dist/types/components/table/window.d.ts +203 -0
- package/dist/types/components/toolbar/toolbar.d.ts +10 -6
- package/dist/types/components/tooltip/tooltip.d.ts +2 -2
- package/dist/types/components/tree/tree.d.ts +20 -13
- package/dist/types/core/component.d.ts +10 -0
- package/dist/types/core/date.d.ts +8 -1
- package/dist/types/core/dom.d.ts +1 -0
- package/dist/types/core/http.d.ts +10 -0
- package/dist/types/core/i18n.d.ts +38 -0
- package/dist/types/core/messages.d.ts +344 -1
- package/dist/types/core/storage.d.ts +7 -2
- package/dist/types/elements/define.d.ts +21 -46
- package/dist/types/elements/definitions.d.ts +147 -0
- package/dist/types/elements/kit.d.ts +7 -0
- package/dist/types/elements/reflect.d.ts +6 -3
- package/dist/types/index.d.ts +10 -1
- package/dist/types/internal/date-locale.d.ts +7 -0
- package/dist/types/internal/json-patch.d.ts +146 -0
- package/dist/types/locales/de.d.ts +13 -0
- package/dist/types/locales/en.d.ts +2 -0
- package/dist/types/locales/index.d.ts +823 -0
- package/dist/types/zeyos/view.d.ts +8 -1
- package/dist/zx-zeyos.esm.js +16802 -15180
- package/dist/zx-zeyos.esm.min.js +5 -5
- package/dist/zx.core.css +1276 -0
- package/dist/zx.core.min.css +1 -0
- package/dist/zx.css +498 -134
- package/dist/zx.esm.js +40778 -29654
- package/dist/zx.esm.min.js +36 -23
- package/dist/zx.global.js +40778 -29654
- package/dist/zx.global.min.js +36 -23
- package/dist/zx.layered.css +17302 -0
- package/dist/zx.layered.min.css +1 -0
- package/dist/zx.min.css +1 -1
- package/docs/agent-catalog.json +12501 -0
- package/docs/agent-surfaces.md +340 -0
- package/docs/api.json +851 -121
- package/docs/llms.md +1018 -71
- package/docs/llms.txt +30 -9
- package/package.json +29 -6
- package/src/components/account-menu/account-menu.js +6 -3
- package/src/components/activity-item/activity-item.js +2 -1
- package/src/components/activity-list/activity-list.js +16 -10
- package/src/components/agent-thread/ag-ui.js +1439 -0
- package/src/components/agent-thread/agent-thread.js +359 -54
- package/src/components/agent-thread/ui-message-stream.js +1281 -0
- package/src/components/app-sidebar/app-sidebar.js +18 -8
- package/src/components/approval-card/approval-card.js +3 -2
- package/src/components/block-view/block-view.js +7 -6
- package/src/components/breadcrumb/breadcrumb.js +8 -5
- package/src/components/calendar/calendar-model.js +8 -2
- package/src/components/calendar/calendar.js +53 -18
- package/src/components/chart/chart.js +54 -23
- package/src/components/code-editor/code-editor.js +45 -8
- package/src/components/code-editor/field-adapter.js +1 -1
- package/src/components/composer/composer.css +80 -1
- package/src/components/composer/composer.js +390 -16
- package/src/components/composer/queue.js +78 -0
- package/src/components/context-menu/context-menu.js +12 -1
- package/src/components/copy/copy-button.js +9 -7
- package/src/components/copy/copy-input.js +10 -6
- package/src/components/date-picker/date-picker.js +2 -1
- package/src/components/date-picker/date-range-picker.js +8 -7
- package/src/components/datebox/date-range-box.js +3 -9
- package/src/components/datebox/datebox.js +18 -21
- package/src/components/datebox/placeholder.js +18 -0
- package/src/components/dialog/dialog.js +1 -1
- package/src/components/dock/dock.js +34 -13
- package/src/components/entity-ref/entity-ref.js +16 -5
- package/src/components/field-upload/field-upload.js +81 -38
- package/src/components/file-item/file-item.js +70 -40
- package/src/components/file-list/file-list.js +15 -9
- package/src/components/filter/filter-model.js +46 -8
- package/src/components/filter/filter.css +3 -3
- package/src/components/filter/filter.js +29 -10
- package/src/components/filter-panel/filter-panel.js +13 -5
- package/src/components/finder/finder.js +50 -26
- package/src/components/flag/flag.css +40 -0
- package/src/components/flag/flag.js +177 -0
- package/src/components/form/form.js +1 -1
- package/src/components/grid/grid.js +22 -8
- package/src/components/kanban-view/kanban-view.js +51 -81
- package/src/components/launcher/launcher.js +17 -2
- package/src/components/list-toolbar/list-toolbar.js +2 -1
- package/src/components/master-panel/master-panel.js +1 -1
- package/src/components/menu-button/menu-button.js +4 -0
- package/src/components/message/message.js +3 -0
- package/src/components/multi-value-editor/multi-value-editor.js +10 -9
- package/src/components/navigation-bar/navigation-bar.js +3 -3
- package/src/components/number-field/number-field.js +29 -13
- package/src/components/prompt-starters/prompt-starters.css +91 -0
- package/src/components/prompt-starters/prompt-starters.js +206 -0
- package/src/components/prose/prose.js +14 -10
- package/src/components/questionnaire/conditions.js +666 -0
- package/src/components/questionnaire/items.js +150 -41
- package/src/components/questionnaire/questionnaire.js +126 -32
- package/src/components/rating/rating.js +5 -4
- package/src/components/run-status/run-status.js +2 -2
- package/src/components/select/country.js +136 -0
- package/src/components/select/field-adapter.js +7 -2
- package/src/components/select/locale.js +219 -0
- package/src/components/select/select.css +20 -22
- package/src/components/select/select.js +94 -12
- package/src/components/sheet/sheet-stack.js +10 -1
- package/src/components/slider/slider.js +7 -2
- package/src/components/sort-control/sort-control.js +15 -5
- package/src/components/source-list/source-list.js +7 -4
- package/src/components/split-view/split-view.js +5 -3
- package/src/components/surface/catalog.js +1334 -0
- package/src/components/surface/elicit.js +107 -0
- package/src/components/surface/mcp.js +243 -0
- package/src/components/surface/schema.js +644 -0
- package/src/components/surface/stream.js +245 -0
- package/src/components/surface/surface.css +308 -0
- package/src/components/surface/surface.js +2291 -0
- package/src/components/surface/text.js +513 -0
- package/src/components/surface/validate.js +2218 -0
- package/src/components/tabbox/tabbox.js +9 -0
- package/src/components/table/table.css +63 -3
- package/src/components/table/table.js +167 -28
- package/src/components/table/window.js +317 -0
- package/src/components/toolbar/toolbar.js +12 -7
- package/src/components/tooltip/tooltip.css +2 -3
- package/src/components/tooltip/tooltip.js +32 -5
- package/src/components/tree/tree.js +53 -23
- package/src/core/component.js +25 -1
- package/src/core/date.js +62 -16
- package/src/core/dom.js +22 -2
- package/src/core/format.js +15 -13
- package/src/core/http.js +29 -20
- package/src/core/i18n.js +83 -10
- package/src/core/keyboard.js +79 -8
- package/src/core/messages.js +376 -2
- package/src/core/overlay-host.js +1 -0
- package/src/core/storage.js +59 -6
- package/src/elements/define.js +178 -130
- package/src/elements/definitions.js +229 -0
- package/src/elements/kit.js +444 -0
- package/src/elements/reflect.js +8 -3
- package/src/index.js +10 -1
- package/src/internal/date-locale.js +11 -0
- package/src/internal/json-patch.js +405 -0
- package/src/locales/de.js +911 -0
- package/src/locales/en.js +2 -0
- package/src/locales/index.js +7 -0
- package/src/zeyos/calendar.js +2 -1
- package/src/zeyos/form.js +2 -1
- package/src/zeyos/launcher.js +7 -6
- package/src/zeyos/module-bar.js +2 -1
- package/src/zeyos/schema.js +37 -23
- package/src/zeyos/select.js +4 -3
- package/src/zeyos/table.js +2 -13
- package/src/zeyos/view.js +57 -17
- package/styles/core.css +11 -0
- package/styles/tokens/semantic.css +1 -0
- package/styles/zeyos.css +2 -0
- package/styles/zx.css +4 -8
- package/styles/zx.layered.css +1 -0
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,160 @@ and friends remain the complete record.
|
|
|
8
8
|
|
|
9
9
|
## Unreleased
|
|
10
10
|
|
|
11
|
+
## 5.7.0 — 2026-11-09
|
|
12
|
+
|
|
13
|
+
Locale and country Select presets, complete English/German catalogues and plural messages,
|
|
14
|
+
agent surfaces and protocol adapters, and fixes across forms, data views and overlays.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- `translatePlural(key, count, args, {locale}?)` and `Component.msgPlural(key, count, ...args)`
|
|
19
|
+
select cardinal forms with an explicit numeric count, preserving existing message overrides.
|
|
20
|
+
- English catalogue export and an opt-in English/German manifest at `@zeyos/zx/locales/en.js`
|
|
21
|
+
and `@zeyos/zx/locales/index.js`.
|
|
22
|
+
- Optional ZeyOS module palette at `@zeyos/zx/styles/zeyos.css`.
|
|
23
|
+
- Explicit legacy storage migration with `storage(namespace).migrateLegacy(['known-key'])`.
|
|
24
|
+
- **`Select.locale()`** and **`Select.country()`** — Select presets over a list of locales or ISO 3166-1
|
|
25
|
+
countries, named by `Intl.DisplayNames` with no translation table. A locale shows its native name
|
|
26
|
+
with the interface's name beneath; the value is the canonical BCP 47 tag or the upper-case
|
|
27
|
+
alpha-2 code. Both take `preferred` choices pinned above the list, `displayLocale`, and a `flags`
|
|
28
|
+
mode, and return ordinary Select instances. `Select.localeItems()` and `Select.countryItems()`
|
|
29
|
+
expose the item builders, and `canonicalLocale()` normalizes locale tags. Field type `zxselect`
|
|
30
|
+
supports `preset: 'locale'` or `'country'`.
|
|
31
|
+
- **Locales guide** — adding languages and message keys, positional and named variables, plural
|
|
32
|
+
forms, regional formatting, and switching language at runtime. Its live example switches between
|
|
33
|
+
English, German and a custom French catalogue, with editable variables and counts.
|
|
34
|
+
- **`flag()`** — draws a country flag as the platform's emoji, a muted code chip where the platform
|
|
35
|
+
has no flag glyphs, or an image from a flag set the application serves (`src: '/flags/{code}.svg'`).
|
|
36
|
+
`flagEmoji()`, `supportsFlagEmoji()` and `COUNTRY_CODES` go with it.
|
|
37
|
+
- **Surface** — an agent composes an answer or a dialog as JSON, whole or streamed, and Zx validates
|
|
38
|
+
and draws it with library components: `show`, `ask`, `choose`, `confirm`, `review` and
|
|
39
|
+
`questionnaire` intents, tables, charts, conditional fields and a review of proposed changes.
|
|
40
|
+
Model output is data, never code or markup. No URL from a model is loaded. The application's
|
|
41
|
+
`policy()` decides how each action is confirmed, and nothing in a surface can lower that. Every
|
|
42
|
+
surface ends in exactly one reply, which carries the application's `token`, and stays as a
|
|
43
|
+
read-only receipt. `openSurface()`, `elicit()` and `surfaceText()` go with it, and AgentThread
|
|
44
|
+
draws `surface` items (`thread.surface(id)`, the `reply` event).
|
|
45
|
+
- **`narrowCatalog()`, `surfaceSchema()`, `surfaceTools()` and `surfacePrompt()`** — generate a
|
|
46
|
+
model's prompt, schema and tool definitions at runtime, from all of the catalog or a narrowed
|
|
47
|
+
part of it. `catalog.js` imports without a DOM, so a server can use it. Model output reaches a
|
|
48
|
+
surface as operation lines, as a tool call's arguments, or in a fence in the answer text, split
|
|
49
|
+
out by `inlineSplitter()`.
|
|
50
|
+
- **`connectAgUi(thread, options)`** and `AG_UI_VERSION` — draw an AG-UI 1.0 event stream in an
|
|
51
|
+
AgentThread: run status, answers, trace steps, approvals, the application's own tiles, surfaces
|
|
52
|
+
and JSON Patch state, with reasoning kept private. The application keeps the transport.
|
|
53
|
+
- **`elicitationHandler()`** and `MCP_ELICITATION_VERSION` — MCP elicitation 2026-07-28, also
|
|
54
|
+
accepting 2025-11-25. Form mode goes through `elicit()`; URL mode asks first, naming the host.
|
|
55
|
+
- **Questionnaire** `when`, `next` and `validate` accept plain-JSON forms beside functions:
|
|
56
|
+
conditions with `all`, `any` and `not`, first-match `next` with `$review` and `$submit`, and rule
|
|
57
|
+
lists.
|
|
58
|
+
- **AgentThread** `upsert(item, {after})` places a new item after another.
|
|
59
|
+
- **Custom elements for the agent kit and the data views** — `<zx-agent-thread>`,
|
|
60
|
+
`<zx-composer>`, `<zx-block-view>`, `<zx-run-trace>`, `<zx-approval-card>`, `<zx-source-list>`,
|
|
61
|
+
`<zx-run-status>`, `<zx-card-view>`, `<zx-kanban-view>`, `<zx-tree>` and `<zx-chart>`. Data options
|
|
62
|
+
are properties and are never written back to attributes; methods are forwarded to the component,
|
|
63
|
+
and calls made before it exists are queued; events reach the host under their plain names as well
|
|
64
|
+
as `zx-<type>`.
|
|
65
|
+
- **`connectUiMessageStream(thread, options)`** and `UI_MESSAGE_STREAM_VERSION` — draw an AI SDK UI
|
|
66
|
+
message stream (`v1`) in an AgentThread: text, private reasoning, tool steps, approvals, sources,
|
|
67
|
+
files, data parts and application tiles. The application keeps the transport. `replay(messageId)`
|
|
68
|
+
rebuilds a response fed again after a reconnect, so its text is not doubled.
|
|
69
|
+
- **PromptStarters** — conversation starters for an empty conversation, with `items`, `label`,
|
|
70
|
+
`columns`, `headingLevel`, `setItems()` and a `pick` event. A pick is reported and never sent.
|
|
71
|
+
- **Queued messages in Composer** — `queue` and `queueLimit`, `getQueue()`, `clearQueue()`,
|
|
72
|
+
`removeQueued(id)`, and `queue` and `dequeue` events. A queued message goes out as a normal `send`
|
|
73
|
+
with `queued: true`, one each time busy ends.
|
|
74
|
+
- **Table `virtual: true`** — windowed rendering: only the rows in view and one viewport of overscan
|
|
75
|
+
above and below are in the DOM, and the table stays one grid over all its rows. Off by default.
|
|
76
|
+
`reveal(id)` scrolls a row into view, drawing it first in a windowed table.
|
|
77
|
+
- **`zx-css`** — `npx zx-css select table --out public/zx.css` writes one stylesheet with the core
|
|
78
|
+
sheet and everything those components reach, in `zx.css` order, with `--min`, `--layer` and
|
|
79
|
+
`--list`.
|
|
80
|
+
- **`zx.core.css` and `zx.layered.css`** — the core sheet on its own, and an opt-in build with the
|
|
81
|
+
whole library in `@layer zx`, so unlayered application rules win. `./src/components/*.css` exports
|
|
82
|
+
one component's own rules.
|
|
83
|
+
- **`@zeyos/zx/locales/de.js`** — a complete German message catalogue, installed with
|
|
84
|
+
`setTranslator((key) => de[key])` and `setLanguage('de')`. A test keeps it complete, and the
|
|
85
|
+
reference lists its glossary.
|
|
86
|
+
|
|
87
|
+
### Changed
|
|
88
|
+
|
|
89
|
+
- Storage keys use length-prefixed namespaces, preventing collisions when names contain colons.
|
|
90
|
+
Built-in persisted components migrate known legacy keys once, preserving the originals. Applications
|
|
91
|
+
using `storage()` directly should call `migrateLegacy()` for their own known keys before reading.
|
|
92
|
+
- Generic stylesheets exclude the ZeyOS module palette; import `styles/zeyos.css` to retain those colours.
|
|
93
|
+
- Locale-aware formatting preserves regional English conventions and follows a usable explicit locale,
|
|
94
|
+
then the active language, then English. Explicit date locales take precedence over host date names.
|
|
95
|
+
- Built-in counts and ZeyOS control defaults use the message catalogue. Caller and server labels remain
|
|
96
|
+
unchanged. Short date names use locale abbreviations unless explicitly translated.
|
|
97
|
+
- The package includes the Surface guide and catalogue; documented ESM entries preserve field-adapter
|
|
98
|
+
registration when bundled with tree-shaking. Development tools are pinned to the lockfile versions.
|
|
99
|
+
- The documentation's ZeyOS client asset has a reproducible build command and a verified source manifest.
|
|
100
|
+
- Component documentation explains host-provided integrations: Chart needs a rendering adapter
|
|
101
|
+
(`ChartJsAdapter` uses Chart.js), Font Awesome modes need their icon assets, and ZeyOS data
|
|
102
|
+
bindings need a compatible client. The library has no runtime package dependencies.
|
|
103
|
+
- Theme Studio groups specimens into named sections, with a responsive grid, sticky section
|
|
104
|
+
navigation and colour swatches grouped by semantic role. Website navigation adds icons for
|
|
105
|
+
Docs, Layouts and Theme Studio.
|
|
106
|
+
- Composer mention suggestions use the floating overlay material, including glass and
|
|
107
|
+
forced-colour treatment where supported.
|
|
108
|
+
- The `agent-chat` layout includes an interactive credit-note question built with Surface and
|
|
109
|
+
uses the submitted values in the answer.
|
|
110
|
+
- The `ai-chat` layout's empty state uses PromptStarters, and focus moves to the composer after a
|
|
111
|
+
pick.
|
|
112
|
+
- The library's remaining text, in Select, Table, Datebox, Filter and the rest, now goes through the
|
|
113
|
+
message catalogue, so a translator reaches it. English remains the fallback, with singular and
|
|
114
|
+
plural forms selected from explicit counts.
|
|
115
|
+
- Month and weekday names, and dates in Calendar, ActivityItem, AgentThread and Surface, follow
|
|
116
|
+
`setLanguage()`. With no language set, nothing changes.
|
|
117
|
+
- Text options whose default moved to the catalogue no longer hold that English text, so
|
|
118
|
+
`component.options.label`, `treeEl.label` and `chartEl.emptyText` read `null` or `undefined` until
|
|
119
|
+
set. Read the text with `component.msg('tree.label')`.
|
|
120
|
+
- `null` in a text option that used to print the word "null" now shows nothing.
|
|
121
|
+
- PageUp, PageDown and Ctrl+Home/End inside a control in a thread item stay with the control.
|
|
122
|
+
- An answer finishing no longer drowns out "needs your approval" or "needs your answer".
|
|
123
|
+
|
|
124
|
+
### Removed
|
|
125
|
+
|
|
126
|
+
- The `filter.choosePart` message, so a host override of it stops applying. Use
|
|
127
|
+
`filter.choosePart.field`, `.operator` and `.value`.
|
|
128
|
+
|
|
129
|
+
### Fixed
|
|
130
|
+
|
|
131
|
+
- Country Select presets search custom descriptions. Blurring an unchanged Datebox preserves hidden time fields
|
|
132
|
+
and emits no change. Disabled AppSidebar items remain inert under keyboard activation.
|
|
133
|
+
- Empty focus traps focus their boundary and restore its attributes on release. AgentThread follows its
|
|
134
|
+
current scroll container after reparenting and releases listeners from the previous one.
|
|
135
|
+
- AG-UI durations are omitted when event timestamps use different clocks or move backwards.
|
|
136
|
+
- Filter empty-state markup and Select reset, spinner, disabled and overlay styling follow semantic
|
|
137
|
+
tokens and logical layout. CSS checks cover SVG data-URL paint and shared layout styles.
|
|
138
|
+
- Questionnaire ignores stale asynchronous validation, validates the final answer once, refreshes
|
|
139
|
+
replaced field definitions, and includes earlier applicable answers in native form data.
|
|
140
|
+
- Slider number-box commits, locale-aware NumberField stepping, normalized FilterPanel values,
|
|
141
|
+
Select typing and async item replacement, locale extension labels, and nested Datebox dismissal.
|
|
142
|
+
- NumberField preserves localized digits and minus signs while editing and committing grouped values.
|
|
143
|
+
- Persistent messages retain their duration. Tabbox restores a tab stop; MenuButton preserves Tab
|
|
144
|
+
navigation; Breadcrumb overflow keeps links and cancellation; ContextMenu restores invoking focus.
|
|
145
|
+
- Launcher ignores stale close events, Dock restores lazy content and destroys hosted sheets,
|
|
146
|
+
SheetStack raises native dialogs correctly, Dialog respects IME composition, and Tooltip remains
|
|
147
|
+
visible while the pointer moves onto its bubble.
|
|
148
|
+
- Calendar positions events by local clock time on daylight-saving transitions, retains keyboard
|
|
149
|
+
focus across periods, and rejects invalid resize steps. CodeEditor indentation participates in
|
|
150
|
+
native undo where supported and commits once on blur.
|
|
151
|
+
- Tree and Finder ignore stale lazy loads after replacement or destruction. Kanban recomputes its
|
|
152
|
+
drop target during stationary-pointer auto-scroll and on release.
|
|
153
|
+
- Http honors cancellation and multipart names, distinguishes timeouts, and accepts legacy
|
|
154
|
+
false-valued success envelopes. FieldUpload with Http retains upload progress and client defaults.
|
|
155
|
+
- AgentThread metadata patches preserve streamed blocks. The DOM builder rejects raw HTML sinks
|
|
156
|
+
and unsafe links; roving focus releases removed nodes, and repeated-letter typeahead cycles.
|
|
157
|
+
- Landing-page modules and styles load from the same asset revision.
|
|
158
|
+
- ZeyOS views can opt into `savedViewFallback: 'baseline'` to browse records when the saved-view
|
|
159
|
+
registry cannot be read, preserving the document and reporting the failure until recovery.
|
|
160
|
+
- `printf()` fills every placeholder in one pass, so a value holding `%word%` stays as written.
|
|
161
|
+
- `AgentThread.remove()` gives the next item its byline back when it now starts a turn, and moves
|
|
162
|
+
focus to a neighbour when the removed item held it.
|
|
163
|
+
- A destroyed AgentThread takes no more items.
|
|
164
|
+
|
|
11
165
|
## 5.6.0 — 2026-11-03
|
|
12
166
|
|
|
13
167
|
Agents: a conversation with AI agents drawn from plain JSON — streamed answers, the steps a run
|
package/README.md
CHANGED
|
@@ -44,9 +44,9 @@ Import a component source module directly when a bundler needs the narrowest pos
|
|
|
44
44
|
import { Slider } from '@zeyos/zx/src/components/slider/slider.js';
|
|
45
45
|
```
|
|
46
46
|
|
|
47
|
-
The package also exposes the bundled ESM entry for ordinary named imports.
|
|
48
|
-
|
|
49
|
-
|
|
47
|
+
The package also exposes the bundled ESM entry for ordinary named imports. JavaScript can be
|
|
48
|
+
tree-shaken or imported component by component either way, and [`zx-css`](#installing) does the
|
|
49
|
+
same for the stylesheet.
|
|
50
50
|
|
|
51
51
|
TypeScript definitions ship with the package. They are generated from the JSDoc that documents
|
|
52
52
|
every option, method, and event, so `new Slider(null, { … })` is checked against `SliderOptions`
|
|
@@ -57,6 +57,18 @@ Components accept an existing element or selector as their first argument. Passi
|
|
|
57
57
|
the component create and own its root. Call `destroy()` when a component is no longer needed; an
|
|
58
58
|
owned root is removed, while an enhanced target is restored.
|
|
59
59
|
|
|
60
|
+
## Optional integration requirements
|
|
61
|
+
|
|
62
|
+
Zx has no package runtime dependencies and its source modules import no external runtime packages.
|
|
63
|
+
Optional integrations still need application-provided assets or clients. `Chart` requires an injected
|
|
64
|
+
renderer; the only supplied renderer, `ChartJsAdapter`, requires Chart.js 4 supplied by the host.
|
|
65
|
+
There is no built-in chart renderer. Chart.js 4.5.1 is pinned as a development dependency and copied
|
|
66
|
+
to the documentation site's self-hosted vendor assets during its build; it is not bundled into Zx.
|
|
67
|
+
Core icons use bundled SVG by default. Opting into Font Awesome requires host-loaded CSS or a kit.
|
|
68
|
+
ZeyOS `moduleIcon()`, `moduleChip()`, and `zeyosAppIcon()` default to glyphs from the external custom
|
|
69
|
+
ZeyOS Font Awesome kit; `standard: true` still needs stock Font Awesome assets. `ZeyOS.connect()`
|
|
70
|
+
requires an injected compatible client and never imports the client package.
|
|
71
|
+
|
|
60
72
|
## Component index
|
|
61
73
|
|
|
62
74
|
The groups match the demo sidebar.
|
|
@@ -100,7 +112,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
|
|
|
100
112
|
| `CheckButton` | Two-state pressed button with optional state-specific labels. |
|
|
101
113
|
| `Toggle` | Native-button switch with a separate submitted value. |
|
|
102
114
|
| `Search` | Search input with debounced input, submit, and clear events. |
|
|
103
|
-
| `Select` | APG combobox with local or async filtering, pinned items, priority/status/permission presets, and an optional ZeyOS entity picker. |
|
|
115
|
+
| `Select` | APG combobox with local or async filtering, pinned items, locale/country/priority/status/permission presets, and an optional ZeyOS entity picker. `Select.locale()` and `Select.country()` return ordinary Select instances; `Select.localeItems()` and `Select.countryItems()` generate rows without DOM. |
|
|
104
116
|
| `Checklist` | Searchable checkbox group with optional async loading. |
|
|
105
117
|
| `TagPicker` | Multi-select combobox that keeps its selection as removable tags. |
|
|
106
118
|
| `NumberField` | APG spinbutton with step buttons, ranges, units, and wrapping. |
|
|
@@ -126,6 +138,7 @@ ZeyOS binding — see `src/zeyos/modules.js`.
|
|
|
126
138
|
| `Dropdown` | Generic anchored popover with placement fallback. |
|
|
127
139
|
| `MenuButton` | APG menu button built on `Dropdown`. |
|
|
128
140
|
| `ContextMenu` | APG right-click menu for a region or, via `selector`, per row. |
|
|
141
|
+
| `Sheet` | Dockable panel that can float as a modal or nonmodal dialog. |
|
|
129
142
|
| `Tooltip`, `tooltip()`, `describe()` | Hover/focus description bubble anchored with `position()`. |
|
|
130
143
|
|
|
131
144
|
### Data
|
|
@@ -136,14 +149,18 @@ ZeyOS binding — see `src/zeyos/modules.js`.
|
|
|
136
149
|
| `FileItem`, `FileList` | Durable and transient file presentation with MIME/size metadata, status, progress, downloads, and collection states. |
|
|
137
150
|
| `ActivityItem`, `ActivityList` | Chronological activity entries and grouped collections with actor, time, attachment, action, loading, and empty slots. |
|
|
138
151
|
| `Table` | Sortable/selectable table with typed transaction columns, flat-data hierarchy/treegrid projection, and opt-in cell/row editing. |
|
|
152
|
+
| `RecordView` | Shared record collection state for table, card, and Kanban views. |
|
|
139
153
|
| `TableView` | Record-oriented Table composition with shared fields, portable state, column visibility/order, sorting, and selection. |
|
|
140
154
|
| `CardView` | Responsive record cards with configurable fields, safe preview media, grouping, actions, sorting, and selection. |
|
|
141
155
|
| `KanbanView` | Record board with configurable columns, swim lanes, WIP guidance, and cancelable pointer/keyboard movement. |
|
|
142
156
|
| `Grid`, `Grid.BillingItems()` | Table-compatible preset surface with editable currencies, units, totals, and sub-items. |
|
|
143
|
-
| `Chart`, `ChartJsAdapter` | Accessible
|
|
157
|
+
| `Chart`, `ChartJsAdapter` | Accessible chart host requiring an injected renderer; the supplied adapter requires host-provided Chart.js 4. |
|
|
144
158
|
| `Calendar` | Agenda/day/week/month/year scheduling with timed collisions, spanning events, range selection, and configurable optimistic drag/resize editing. |
|
|
159
|
+
| `Filter` | Nested, backend-neutral filter expression editor. |
|
|
145
160
|
| `DataFilter` | Declarative select, text, and custom filters for client-side row sets. |
|
|
146
161
|
| `FilterPanel` | Typed filter form built from a server's own field metadata, drafted then applied. |
|
|
162
|
+
| `SortControl` | Searchable sort field and direction control. |
|
|
163
|
+
| `ViewSettings` | Portable field visibility, order, grouping, and view settings. |
|
|
147
164
|
| `ListToolbar` | Search, result count, view switch, and badged tools above a record view. |
|
|
148
165
|
| `TreeView` | APG tree with lazy children, filtering, tri-state checkboxes, and hover-revealed `rowActions`. |
|
|
149
166
|
| `Finder` | Miller-columns hierarchy browser with an optional preview pane. |
|
|
@@ -181,6 +198,8 @@ ZeyOS binding — see `src/zeyos/modules.js`.
|
|
|
181
198
|
| `AppSidebar` | Expanded or minimized vertical application navigation plus horizontal rails; descendants are inline only while expanded. Sections group a tree; `layout: 'modules'` puts a module strip beside one module's menu. |
|
|
182
199
|
| `ModuleBar` | Colour-coded module tiles in a strip or bar: flyout menus, live badges, one Tab stop, and an "All modules" catalogue for what does not fit. |
|
|
183
200
|
| `Toolbar` | APG toolbar: one tab stop, arrow-key movement, and overflow into a menu. |
|
|
201
|
+
| `Dock` | Resizable, collapsible pane layout with tabs and hosted Sheets. |
|
|
202
|
+
| `WorkspaceSwitcher` | Workspace identity and switching menu. |
|
|
184
203
|
| `SplitView` | Resizable two-pane split with a keyboard-operable separator. |
|
|
185
204
|
| `Stepper` | Linear multi-step progress with completed, active, and error states. |
|
|
186
205
|
| `Breadcrumb` | Hierarchy trail with middle-collapse, pairing with `Finder` and `TreeView`. |
|
|
@@ -192,6 +211,23 @@ ZeyOS binding — see `src/zeyos/modules.js`.
|
|
|
192
211
|
| `skeleton()`, `skeletonText()`, `skeletonTable()` | Placeholders shaped like the content that is coming. |
|
|
193
212
|
| `truncate()` | Clamps text to a number of lines, with the full value on hover. |
|
|
194
213
|
|
|
214
|
+
### Agents
|
|
215
|
+
|
|
216
|
+
| API | Description |
|
|
217
|
+
| --- | --- |
|
|
218
|
+
| `AgentThread` | Accessible conversation feed with streamed answers, versions, and actions. |
|
|
219
|
+
| `BlockView`, `renderBlocks()` | Safe structured answer content with incremental streaming. |
|
|
220
|
+
| `Composer` | Message input with attachments, mentions, commands, context, and queued messages. |
|
|
221
|
+
| `RunTrace` | Tool calls, reasoning summaries, retries, and handoffs within a run. |
|
|
222
|
+
| `RunStatus` | Run state, steps, elapsed work, tokens, and cost. |
|
|
223
|
+
| `ApprovalCard` | Application-controlled approval, editing, rejection, and typed confirmation. |
|
|
224
|
+
| `SourceList` | Citations and source metadata without loading remote content. |
|
|
225
|
+
| `PromptStarters` | Suggested conversation starters that report a selection. |
|
|
226
|
+
| `Surface` | Validated agent-authored forms, tables, choices, and reviews with one reply. |
|
|
227
|
+
|
|
228
|
+
See the [Surface guide](docs/agent-surfaces.md) and [component catalogue](docs/agent-catalog.json)
|
|
229
|
+
for supported schemas and streaming helpers. Both ship in the package.
|
|
230
|
+
|
|
195
231
|
## Start from a layout
|
|
196
232
|
|
|
197
233
|
The [layout gallery](https://zx.zeyos.com/layouts) holds complete, working screens on one shared
|
|
@@ -372,7 +408,7 @@ JavaScript positioning fallback.
|
|
|
372
408
|
Install the development toolchain and start the no-build demo server:
|
|
373
409
|
|
|
374
410
|
```sh
|
|
375
|
-
npm
|
|
411
|
+
npm ci
|
|
376
412
|
npm run serve
|
|
377
413
|
```
|
|
378
414
|
|
|
@@ -389,6 +425,15 @@ npm run build:site # assembles the deployable documentation site into site/
|
|
|
389
425
|
npm run serve:site # serves site/ exactly as it will be deployed
|
|
390
426
|
```
|
|
391
427
|
|
|
428
|
+
Browser checks use an already-installed Chrome. Set `ZX_BROWSER_CHANNEL` to another installed
|
|
429
|
+
Playwright browser channel, or `ZX_BROWSER_EXECUTABLE_PATH` to an executable path; use one option
|
|
430
|
+
at a time. No browser is downloaded by the checks.
|
|
431
|
+
|
|
432
|
+
The checked-in ZeyOS client asset has a source and checksum manifest. To refresh it from a local
|
|
433
|
+
client checkout, run `node tools/build-client-vendor.js --source /path/to/client`; verify it with
|
|
434
|
+
`node tools/build-client-vendor.js --check`. Ordinary site builds verify the asset without needing
|
|
435
|
+
that checkout or a network connection.
|
|
436
|
+
|
|
392
437
|
## Installing
|
|
393
438
|
|
|
394
439
|
```sh
|
|
@@ -400,7 +445,28 @@ import { Table, Message } from '@zeyos/zx';
|
|
|
400
445
|
import '@zeyos/zx/zx.css';
|
|
401
446
|
```
|
|
402
447
|
|
|
448
|
+
`zx.css` is the whole library. To load only what an application uses, `zx-css` writes one stylesheet
|
|
449
|
+
for the components named: the tokens and base rules, then those components and everything they
|
|
450
|
+
depend on, resolved from the source.
|
|
451
|
+
|
|
452
|
+
```sh
|
|
453
|
+
npx zx-css select table --out public/zx.css --min
|
|
454
|
+
npx zx-css select table --list # the files it contains, in order
|
|
455
|
+
```
|
|
456
|
+
|
|
403
457
|
Additional entry points: `@zeyos/zx/zeyos` (the schema-driven ZeyOS binding) and
|
|
404
|
-
`@zeyos/zx/global` for classic script tags.
|
|
458
|
+
`@zeyos/zx/global` for classic script tags. For styles, `@zeyos/zx/zx.core.css` is the tokens, base
|
|
459
|
+
rules, icons and reading type, `@zeyos/zx/src/components/select/select.css` is one component's own
|
|
460
|
+
rules, and `@zeyos/zx/zx.layered.css` puts the whole library in `@layer zx`, so that unlayered
|
|
461
|
+
application rules win without a specificity fight, and so do unlayered resets and third-party
|
|
462
|
+
stylesheets: `docs/llms.md` covers when to choose it.
|
|
463
|
+
|
|
464
|
+
ZeyOS module colours are optional: import `@zeyos/zx/styles/zeyos.css` when using the ZeyOS binding.
|
|
465
|
+
The generic core and full-library stylesheets do not include that product palette.
|
|
466
|
+
|
|
467
|
+
The [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales) covers the shipped
|
|
468
|
+
English/German catalogues, adding application languages and regional variants, custom messages and
|
|
469
|
+
variables, plural forms, formatting, and runtime language switching. `Select.locale()` and `Select.country()`
|
|
470
|
+
return ordinary Select instances; selecting a locale is separate from installing its translations.
|
|
405
471
|
|
|
406
472
|
Documentation lives at <https://zx.zeyos.com>.
|
package/bin/zx-css.js
ADDED
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Writes a stylesheet holding only the components an application uses.
|
|
4
|
+
*
|
|
5
|
+
* A subset is resolved from the source, not listed by hand. A component's subset is its own
|
|
6
|
+
* stylesheet plus the stylesheet of every block it reaches: every component module in its static
|
|
7
|
+
* import graph, and every `zx-<block>` class named by a module in that graph, because a component
|
|
8
|
+
* may draw another's markup without importing it. The result keeps the order of `styles/zx.css`,
|
|
9
|
+
* holds each file once, and starts with the core sheet.
|
|
10
|
+
*
|
|
11
|
+
* Runs on Node alone: the package has no runtime dependencies and this is part of the package.
|
|
12
|
+
*/
|
|
13
|
+
import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
|
|
14
|
+
import { dirname, posix, resolve } from 'node:path';
|
|
15
|
+
import { fileURLToPath } from 'node:url';
|
|
16
|
+
import { parseArgs } from 'node:util';
|
|
17
|
+
|
|
18
|
+
const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
19
|
+
const ENTRY_SHEET = 'styles/zx.css';
|
|
20
|
+
const CORE_SHEET = 'styles/core.css';
|
|
21
|
+
const COMPONENT_SHEETS = 'src/components/';
|
|
22
|
+
|
|
23
|
+
const USAGE = `Usage:
|
|
24
|
+
zx-css <component...> --out <file> [--min] [--layer]
|
|
25
|
+
zx-css <component...> --list
|
|
26
|
+
|
|
27
|
+
--out <file> write the stylesheet to this file
|
|
28
|
+
--min strip comments and whitespace
|
|
29
|
+
--layer put everything in @layer zx, so unlayered application rules win
|
|
30
|
+
--list print the files the subset contains, in order, without writing`;
|
|
31
|
+
|
|
32
|
+
const SHEET_IMPORT = /@import url\("([^"]+)"\);/g;
|
|
33
|
+
const MODULE_IMPORT = /^[ \t]*(?:import\s+|(?:import|export)\b[^'"`;]*?\bfrom\s+)['"](\.{1,2}\/[^'"]+)['"]/gm;
|
|
34
|
+
// A preceding `-` rules out `--zx-*` properties and `data-zx-*` attributes.
|
|
35
|
+
const CLASS_NAME = /(?<![\w$-])zx-([a-z0-9-]+)/g;
|
|
36
|
+
// The class `Component` puts on a root from `static cssName`, which the source never spells out.
|
|
37
|
+
const ROOT_CLASS_NAME = /\bstatic cssName = '([a-z0-9-]+)'/g;
|
|
38
|
+
const CSS_CLASS = /\.zx-([a-z0-9-]+)/;
|
|
39
|
+
// `zx-<type>` also names the DOM event a component dispatches, and hearing one draws nothing.
|
|
40
|
+
const EVENT_NAMES = /\bfor \(const type of \[[^\]]*\]\)|\w*[Ll]isten\w*\([^,()]*,\s*'zx-[a-z-]+'/g;
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* @typedef {Object} SubsetOptions
|
|
44
|
+
* @property {string} [root] Package root holding `styles/` and `src/`. Defaults to this package.
|
|
45
|
+
*/
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* @typedef {Object} BuildOptions
|
|
49
|
+
* @property {string} [root] Package root holding `styles/` and `src/`. Defaults to this package.
|
|
50
|
+
* @property {boolean} [min=false] Strip comments and whitespace.
|
|
51
|
+
* @property {boolean} [layer=false] Put the stylesheet in `@layer zx`.
|
|
52
|
+
*/
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* @param {string} root Package root.
|
|
56
|
+
* @param {string} file File path relative to the root.
|
|
57
|
+
* @returns {string} File contents.
|
|
58
|
+
*/
|
|
59
|
+
function read(root, file) {
|
|
60
|
+
return readFileSync(resolve(root, file), 'utf8');
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* @param {string} root Package root.
|
|
65
|
+
* @param {string} sheet Stylesheet path relative to the root.
|
|
66
|
+
* @returns {string[]} The sheets it imports, relative to the root, in order.
|
|
67
|
+
*/
|
|
68
|
+
function importsOf(root, sheet) {
|
|
69
|
+
return [...read(root, sheet).matchAll(SHEET_IMPORT)]
|
|
70
|
+
.map((match) => posix.join(posix.dirname(sheet), match[1]));
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* @param {string} root Package root.
|
|
75
|
+
* @returns {string[]} The component stylesheets, in `zx.css` order.
|
|
76
|
+
*/
|
|
77
|
+
function componentSheets(root) {
|
|
78
|
+
const imports = importsOf(root, ENTRY_SHEET);
|
|
79
|
+
if (imports[0] !== CORE_SHEET) throw new Error(`${ENTRY_SHEET} must import ${CORE_SHEET} first`);
|
|
80
|
+
return imports.filter((sheet) => sheet.startsWith(COMPONENT_SHEETS));
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* @param {string} sheet Stylesheet path.
|
|
85
|
+
* @returns {string} The component name, which is the file's name.
|
|
86
|
+
*/
|
|
87
|
+
function nameOf(sheet) {
|
|
88
|
+
return posix.basename(sheet, '.css');
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Lists the names `resolveSubset` accepts: one for each component stylesheet in `styles/zx.css`.
|
|
93
|
+
* @param {SubsetOptions} [options] Package root.
|
|
94
|
+
* @returns {string[]} Component names, sorted.
|
|
95
|
+
*/
|
|
96
|
+
export function componentNames({ root = PACKAGE_ROOT } = {}) {
|
|
97
|
+
return componentSheets(root).map(nameOf).sort();
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* @param {string} root Package root.
|
|
102
|
+
* @param {string} sheet Stylesheet path relative to the root.
|
|
103
|
+
* @returns {string} Stylesheet source without comments.
|
|
104
|
+
*/
|
|
105
|
+
function rulesOf(root, sheet) {
|
|
106
|
+
return read(root, sheet).replace(/\/\*[\s\S]*?\*\//g, '');
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Finds the block that opens each selector of a stylesheet.
|
|
111
|
+
* @param {string} css Stylesheet source without comments.
|
|
112
|
+
* @returns {Set<string>} Block names.
|
|
113
|
+
*/
|
|
114
|
+
function leadingBlocks(css) {
|
|
115
|
+
const blocks = new Set();
|
|
116
|
+
const tokens = css.split(/([{};])/);
|
|
117
|
+
for (let index = 1; index < tokens.length; index += 2) {
|
|
118
|
+
if (tokens[index] !== '{' || tokens[index - 1].trimStart().startsWith('@')) continue;
|
|
119
|
+
for (const selector of tokens[index - 1].split(',')) {
|
|
120
|
+
const block = CSS_CLASS.exec(selector)?.[1];
|
|
121
|
+
if (block) blocks.add(block);
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
return blocks;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Maps each block to the component stylesheets that define it. A sheet named after a block is that
|
|
129
|
+
* block's home; `.zx-grid` is the exception, since `grid.css` styles the Grid component and never
|
|
130
|
+
* the class, which is why the sheet has to name the block to claim it. Any other block, such as
|
|
131
|
+
* `.zx-btn` in `button.css`, belongs to the sheets whose selectors open with it, unless the core
|
|
132
|
+
* sheet defines it, in which case every subset already has it. Sheets that only style a block in
|
|
133
|
+
* context, like `.zx-field .zx-select`, do not claim it.
|
|
134
|
+
* @param {string} root Package root.
|
|
135
|
+
* @param {string[]} sheets Component stylesheets.
|
|
136
|
+
* @returns {Map<string, string[]>} Block name to stylesheets.
|
|
137
|
+
*/
|
|
138
|
+
function blockHomes(root, sheets) {
|
|
139
|
+
const core = new Set(importsOf(root, CORE_SHEET)
|
|
140
|
+
.flatMap((sheet) => [...leadingBlocks(rulesOf(root, sheet))]));
|
|
141
|
+
/** @type {Map<string, string[]>} */
|
|
142
|
+
const homes = new Map();
|
|
143
|
+
const sources = sheets.map((sheet) => ({ sheet, css: rulesOf(root, sheet) }));
|
|
144
|
+
for (const { sheet, css } of sources) {
|
|
145
|
+
const ownClass = new RegExp(`\\.zx-${nameOf(sheet)}(?![a-z0-9-])`);
|
|
146
|
+
if (ownClass.test(css)) homes.set(nameOf(sheet), [sheet]);
|
|
147
|
+
}
|
|
148
|
+
const named = new Set(homes.keys());
|
|
149
|
+
for (const { sheet, css } of sources) {
|
|
150
|
+
for (const block of leadingBlocks(css)) {
|
|
151
|
+
if (named.has(block) || core.has(block)) continue;
|
|
152
|
+
homes.set(block, [...(homes.get(block) ?? []), sheet]);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
return homes;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* @param {string} source Module source.
|
|
160
|
+
* @returns {string} The source without its comment lines, which describe other blocks as often as
|
|
161
|
+
* they name this one's. Trailing comments stay: reaching too far costs bytes, not correctness.
|
|
162
|
+
*/
|
|
163
|
+
function withoutCommentLines(source) {
|
|
164
|
+
return source.replace(/^\s*(?:\/\*|\*|\/\/).*$/gm, '');
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Walks the static import graph.
|
|
169
|
+
* @param {string} root Package root.
|
|
170
|
+
* @param {string[]} entries Entry modules.
|
|
171
|
+
* @returns {Map<string, string>} Every module reached, with its source.
|
|
172
|
+
*/
|
|
173
|
+
function moduleGraph(root, entries) {
|
|
174
|
+
const modules = new Map();
|
|
175
|
+
const queue = [...entries];
|
|
176
|
+
for (const module of queue) {
|
|
177
|
+
if (modules.has(module)) continue;
|
|
178
|
+
const source = withoutCommentLines(read(root, module));
|
|
179
|
+
modules.set(module, source);
|
|
180
|
+
for (const [, specifier] of source.matchAll(MODULE_IMPORT)) {
|
|
181
|
+
const target = posix.join(posix.dirname(module), specifier);
|
|
182
|
+
if (existsSync(resolve(root, target))) queue.push(target);
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
return modules;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* @param {string} root Package root.
|
|
190
|
+
* @param {string} sheet Component stylesheet.
|
|
191
|
+
* @returns {string|null} Its module: the file beside it, or the presenter of the same name that
|
|
192
|
+
* several components share from `src/internal/`.
|
|
193
|
+
*/
|
|
194
|
+
function moduleOf(root, sheet) {
|
|
195
|
+
const candidates = [sheet.replace(/\.css$/, '.js'), `src/internal/${nameOf(sheet)}.js`];
|
|
196
|
+
return candidates.find((file) => existsSync(resolve(root, file))) ?? null;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Resolves the stylesheets a set of components needs.
|
|
201
|
+
* @param {string[]} names Component names, see `componentNames()`.
|
|
202
|
+
* @param {SubsetOptions} [options] Package root.
|
|
203
|
+
* @returns {string[]} Stylesheets relative to the root: the core sheet, then the components in
|
|
204
|
+
* `zx.css` order, each once.
|
|
205
|
+
* @throws {Error} When a name is not a component, listing the ones that are.
|
|
206
|
+
*/
|
|
207
|
+
export function resolveSubset(names, { root = PACKAGE_ROOT } = {}) {
|
|
208
|
+
const sheets = componentSheets(root);
|
|
209
|
+
const sheetOf = new Map(sheets.map((sheet) => [nameOf(sheet), sheet]));
|
|
210
|
+
const unknown = names.filter((name) => !sheetOf.has(name));
|
|
211
|
+
if (unknown.length) {
|
|
212
|
+
throw new Error(`Unknown component: ${unknown.join(', ')}\n`
|
|
213
|
+
+ `Known components: ${componentNames({ root }).join(', ')}`);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
const requested = names.map((name) => /** @type {string} */ (sheetOf.get(name)));
|
|
217
|
+
const reached = new Set(requested);
|
|
218
|
+
const homes = blockHomes(root, sheets);
|
|
219
|
+
const entries = requested.map((sheet) => moduleOf(root, sheet)).filter((module) => module !== null);
|
|
220
|
+
for (const [module, source] of moduleGraph(root, entries)) {
|
|
221
|
+
const own = module.replace(/\.js$/, '.css');
|
|
222
|
+
if (sheets.includes(own)) reached.add(own);
|
|
223
|
+
const code = source.replace(EVENT_NAMES, '');
|
|
224
|
+
for (const pattern of [CLASS_NAME, ROOT_CLASS_NAME]) {
|
|
225
|
+
for (const [, token] of code.matchAll(pattern)) {
|
|
226
|
+
for (const sheet of homes.get(token.replace(/-+$/, '')) ?? []) reached.add(sheet);
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
return [CORE_SHEET, ...sheets.filter((sheet) => reached.has(sheet))];
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* Inlines a stylesheet's imports.
|
|
235
|
+
* @param {string} root Package root.
|
|
236
|
+
* @param {string} sheet Stylesheet path relative to the root.
|
|
237
|
+
* @returns {string} Stylesheet with no `@import` left.
|
|
238
|
+
*/
|
|
239
|
+
function inlineSheet(root, sheet) {
|
|
240
|
+
return read(root, sheet).replace(SHEET_IMPORT, (statement, href) => (
|
|
241
|
+
inlineSheet(root, posix.join(posix.dirname(sheet), href))
|
|
242
|
+
));
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* Strips comments and the whitespace that means nothing, leaving strings as they are. Whitespace
|
|
247
|
+
* inside a selector or value can be a combinator or a separator, so it collapses but stays.
|
|
248
|
+
* @param {string} css Stylesheet.
|
|
249
|
+
* @returns {string} Minified stylesheet.
|
|
250
|
+
*/
|
|
251
|
+
function minify(css) {
|
|
252
|
+
let output = '';
|
|
253
|
+
let space = false;
|
|
254
|
+
for (let index = 0; index < css.length;) {
|
|
255
|
+
const char = css[index];
|
|
256
|
+
if (css.startsWith('/*', index)) {
|
|
257
|
+
const end = css.indexOf('*/', index + 2);
|
|
258
|
+
index = end < 0 ? css.length : end + 2;
|
|
259
|
+
space = true;
|
|
260
|
+
} else if (/\s/.test(char)) {
|
|
261
|
+
index += 1;
|
|
262
|
+
space = true;
|
|
263
|
+
} else {
|
|
264
|
+
let end = index + 1;
|
|
265
|
+
if (char === '"' || char === "'") {
|
|
266
|
+
while (end < css.length && css[end] !== char) end += css[end] === '\\' ? 2 : 1;
|
|
267
|
+
end += 1;
|
|
268
|
+
}
|
|
269
|
+
if (space && output && !'{};,'.includes(output.at(-1)) && !'{};,'.includes(char)) output += ' ';
|
|
270
|
+
if (char === '}' && output.endsWith(';')) output = output.slice(0, -1);
|
|
271
|
+
output += css.slice(index, end);
|
|
272
|
+
index = end;
|
|
273
|
+
space = false;
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
return output;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* Builds the stylesheet for a set of components.
|
|
281
|
+
* @param {string[]} names Component names.
|
|
282
|
+
* @param {BuildOptions} [options] Package root and output form.
|
|
283
|
+
* @returns {string} Stylesheet with no `@import` left.
|
|
284
|
+
* @throws {Error} When a name is not a component.
|
|
285
|
+
*/
|
|
286
|
+
export function buildSubset(names, { root = PACKAGE_ROOT, min = false, layer = false } = {}) {
|
|
287
|
+
const css = resolveSubset(names, { root }).map((sheet) => inlineSheet(root, sheet)).join('\n');
|
|
288
|
+
const output = layer ? `@layer zx {\n${css}\n}\n` : css;
|
|
289
|
+
return min ? minify(output) : output;
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
/**
|
|
293
|
+
* Runs the command line.
|
|
294
|
+
* @param {string[]} args Arguments after the program name.
|
|
295
|
+
* @returns {number} Exit code.
|
|
296
|
+
*/
|
|
297
|
+
function main(args) {
|
|
298
|
+
try {
|
|
299
|
+
const { values, positionals } = parseArgs({
|
|
300
|
+
args,
|
|
301
|
+
allowPositionals: true,
|
|
302
|
+
options: {
|
|
303
|
+
out: { type: 'string' },
|
|
304
|
+
min: { type: 'boolean' },
|
|
305
|
+
layer: { type: 'boolean' },
|
|
306
|
+
list: { type: 'boolean' }
|
|
307
|
+
}
|
|
308
|
+
});
|
|
309
|
+
if (!positionals.length || (!values.out && !values.list)) throw new Error(USAGE);
|
|
310
|
+
if (values.list) {
|
|
311
|
+
console.log(resolveSubset(positionals).join('\n'));
|
|
312
|
+
return 0;
|
|
313
|
+
}
|
|
314
|
+
const out = resolve(/** @type {string} */ (values.out));
|
|
315
|
+
const css = buildSubset(positionals, { min: values.min, layer: values.layer });
|
|
316
|
+
mkdirSync(dirname(out), { recursive: true });
|
|
317
|
+
writeFileSync(out, css);
|
|
318
|
+
console.log(`${values.out}: ${positionals.join(', ')} (${(Buffer.byteLength(css) / 1000).toFixed(1)} kB)`);
|
|
319
|
+
return 0;
|
|
320
|
+
} catch (error) {
|
|
321
|
+
console.error(error instanceof Error ? error.message : String(error));
|
|
322
|
+
return 1;
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
327
|
+
process.exitCode = main(process.argv.slice(2));
|
|
328
|
+
}
|
|
@@ -42,7 +42,8 @@ export type AccountMenuOptions = {
|
|
|
42
42
|
*/
|
|
43
43
|
compact?: boolean;
|
|
44
44
|
/**
|
|
45
|
-
* Trigger label;
|
|
45
|
+
* Trigger label; null reads the `accountMenu.labelFor` message
|
|
46
|
+
* ("Account menu for <name>"), or `accountMenu.label` without a name.
|
|
46
47
|
*/
|
|
47
48
|
label?: string | null;
|
|
48
49
|
/**
|
|
@@ -80,7 +81,8 @@ export type AccountMenuOptions = {
|
|
|
80
81
|
* @property {AccountIdentity} [account={}] Account presentation supplied by the application.
|
|
81
82
|
* @property {MenuButtonItem[]} [items=[]] Account actions and `'-'` separators.
|
|
82
83
|
* @property {boolean} [compact=false] Whether only the avatar is visually shown in the trigger.
|
|
83
|
-
* @property {string|null} [label=null] Trigger label;
|
|
84
|
+
* @property {string|null} [label=null] Trigger label; null reads the `accountMenu.labelFor` message
|
|
85
|
+
* ("Account menu for <name>"), or `accountMenu.label` without a name.
|
|
84
86
|
* @property {'bottom-start'|'bottom-end'|'top-start'|'top-end'|'bottom'|'top'|'right-start'|'right-end'|'left-start'|'left-end'|'right'|'left'} [placement='top-start'] Popup placement.
|
|
85
87
|
* @property {(event: CustomEvent<{value: unknown, item: object}>) => void} [onselect] Preventable action listener.
|
|
86
88
|
* @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open listener.
|