@zeyos/zx 5.7.1 → 5.8.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 +296 -0
- package/README.md +47 -9
- package/dist/types/components/activity-item/activity-item.d.ts +14 -3
- package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
- package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
- package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
- package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
- package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
- package/dist/types/components/approval-card/approval-card.d.ts +31 -2
- package/dist/types/components/aurora/aurora.d.ts +31 -5
- package/dist/types/components/calendar/calendar.d.ts +39 -26
- package/dist/types/components/chart/chart.d.ts +250 -20
- package/dist/types/components/chart/color.d.ts +66 -0
- package/dist/types/components/chart/svg-adapter.d.ts +103 -0
- package/dist/types/components/chart/svg-geometry.d.ts +203 -0
- package/dist/types/components/check-button/check-button.d.ts +1 -4
- package/dist/types/components/checklist/checklist.d.ts +19 -5
- package/dist/types/components/code-editor/code-editor.d.ts +55 -1
- package/dist/types/components/composer/composer.d.ts +41 -6
- package/dist/types/components/context-menu/context-menu.d.ts +36 -8
- package/dist/types/components/copy/copy-button.d.ts +6 -0
- package/dist/types/components/copy/copy-input.d.ts +1 -0
- package/dist/types/components/date-picker/date-picker.d.ts +14 -0
- package/dist/types/components/date-picker/time-picker.d.ts +26 -17
- package/dist/types/components/datebox/datebox.d.ts +8 -4
- package/dist/types/components/dialog/dialog.d.ts +13 -2
- package/dist/types/components/empty-state/empty-state.d.ts +10 -1
- package/dist/types/components/field/field.d.ts +4 -2
- package/dist/types/components/form/form.d.ts +2 -1
- package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
- package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
- package/dist/types/components/launcher/launcher.d.ts +26 -0
- package/dist/types/components/master-panel/master-panel.d.ts +9 -4
- package/dist/types/components/menu-button/menu-button.d.ts +29 -5
- package/dist/types/components/message/message.d.ts +308 -5
- package/dist/types/components/modal/modal.d.ts +11 -0
- package/dist/types/components/modal/native-dialog.d.ts +40 -0
- package/dist/types/components/module-bar/module-bar.d.ts +9 -2
- package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
- package/dist/types/components/number-field/number-field.d.ts +7 -0
- package/dist/types/components/pagination/pagination.d.ts +341 -19
- package/dist/types/components/run-status/run-status.d.ts +26 -0
- package/dist/types/components/run-trace/run-trace.d.ts +10 -6
- package/dist/types/components/search/search.d.ts +16 -4
- package/dist/types/components/select/select.d.ts +19 -1
- package/dist/types/components/sheet/sheet.d.ts +18 -4
- package/dist/types/components/slider/slider.d.ts +2 -1
- package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
- package/dist/types/components/stepper/stepper.d.ts +17 -4
- package/dist/types/components/surface/catalog.d.ts +61 -17
- package/dist/types/components/surface/surface.d.ts +6 -4
- package/dist/types/components/table/table.d.ts +207 -5
- package/dist/types/components/table/window.d.ts +25 -1
- package/dist/types/components/toggle/toggle.d.ts +38 -6
- package/dist/types/components/tooltip/tooltip.d.ts +5 -4
- package/dist/types/components/tree/tree.d.ts +43 -6
- package/dist/types/components/truncate/truncate.d.ts +4 -2
- package/dist/types/components/value-list/value-list.d.ts +9 -2
- package/dist/types/core/date.d.ts +2 -1
- package/dist/types/core/drag-axis.d.ts +10 -5
- package/dist/types/core/export.d.ts +2 -2
- package/dist/types/core/format.d.ts +3 -1
- package/dist/types/core/icons.d.ts +36 -3
- package/dist/types/core/keyboard.d.ts +7 -3
- package/dist/types/core/messages.d.ts +3 -0
- package/dist/types/core/storage.d.ts +4 -3
- package/dist/types/core/util.d.ts +3 -1
- package/dist/types/elements/define.d.ts +5 -2
- package/dist/types/index.d.ts +6 -4
- package/dist/types/internal/agent-model.d.ts +99 -0
- package/dist/types/internal/app-rail.d.ts +37 -2
- package/dist/types/internal/collections.d.ts +18 -0
- package/dist/types/internal/menu-items.d.ts +27 -0
- package/dist/types/internal/overlay-content.d.ts +23 -0
- package/dist/types/internal/presence-loop.d.ts +5 -2
- package/dist/types/locales/index.d.ts +3 -0
- package/dist/types/zeyos/calendar.d.ts +43 -7
- package/dist/types/zeyos/connect.d.ts +4 -0
- package/dist/types/zeyos/form.d.ts +13 -5
- package/dist/types/zeyos/select.d.ts +5 -2
- package/dist/types/zeyos/table.d.ts +16 -8
- package/dist/types/zeyos/view.d.ts +2 -1
- package/dist/zx-zeyos.esm.js +2998 -451
- package/dist/zx-zeyos.esm.min.js +4 -4
- package/dist/zx.core.css +4 -0
- package/dist/zx.core.min.css +1 -1
- package/dist/zx.css +948 -48
- package/dist/zx.esm.js +7432 -3408
- package/dist/zx.esm.min.js +26 -26
- package/dist/zx.global.js +7432 -3408
- package/dist/zx.global.min.js +26 -26
- package/dist/zx.layered.css +950 -48
- package/dist/zx.layered.min.css +1 -1
- package/dist/zx.min.css +1 -1
- package/docs/agent-catalog.json +159 -1
- package/docs/agent-surfaces.md +21 -21
- package/docs/api.json +3122 -528
- package/docs/components/account-menu.md +24 -0
- package/docs/components/activity-item.md +23 -0
- package/docs/components/activity-list.md +28 -0
- package/docs/components/agent-avatar.md +59 -0
- package/docs/components/agent-thread.md +275 -0
- package/docs/components/app-icon.md +36 -0
- package/docs/components/app-sidebar.md +92 -0
- package/docs/components/approval-card.md +71 -0
- package/docs/components/aurora.md +34 -0
- package/docs/components/avatar.md +37 -0
- package/docs/components/badge.md +36 -0
- package/docs/components/block-view.md +34 -0
- package/docs/components/breadcrumb.md +20 -0
- package/docs/components/button.md +23 -0
- package/docs/components/calendar.md +68 -0
- package/docs/components/card-view.md +73 -0
- package/docs/components/card.md +25 -0
- package/docs/components/chart.md +109 -0
- package/docs/components/check-button.md +16 -0
- package/docs/components/checklist.md +19 -0
- package/docs/components/code-editor.md +38 -0
- package/docs/components/composer.md +107 -0
- package/docs/components/context-menu.md +32 -0
- package/docs/components/copy.md +37 -0
- package/docs/components/data-filter.md +16 -0
- package/docs/components/date-picker.md +31 -0
- package/docs/components/date-range.md +21 -0
- package/docs/components/datebox.md +31 -0
- package/docs/components/dialog.md +25 -0
- package/docs/components/dock.md +57 -0
- package/docs/components/dropdown.md +39 -0
- package/docs/components/elements.md +63 -0
- package/docs/components/empty-state.md +17 -0
- package/docs/components/entity-ref.md +26 -0
- package/docs/components/field-upload.md +18 -0
- package/docs/components/file-item.md +27 -0
- package/docs/components/file-list.md +23 -0
- package/docs/components/filter-panel.md +45 -0
- package/docs/components/filter.md +47 -0
- package/docs/components/finder.md +25 -0
- package/docs/components/form-widgets.md +42 -0
- package/docs/components/form.md +80 -0
- package/docs/components/grid.md +26 -0
- package/docs/components/groupbox.md +11 -0
- package/docs/components/helpers.md +359 -0
- package/docs/components/icons.md +87 -0
- package/docs/components/index.md +99 -0
- package/docs/components/kanban-view.md +42 -0
- package/docs/components/kbd.md +23 -0
- package/docs/components/kernel.md +41 -0
- package/docs/components/launcher.md +66 -0
- package/docs/components/layout.md +33 -0
- package/docs/components/list-toolbar.md +38 -0
- package/docs/components/loading.md +48 -0
- package/docs/components/menu-button.md +47 -0
- package/docs/components/message.md +76 -0
- package/docs/components/modal.md +27 -0
- package/docs/components/module-bar.md +71 -0
- package/docs/components/multi-value-editor.md +16 -0
- package/docs/components/navigation-bar.md +22 -0
- package/docs/components/number-field.md +34 -0
- package/docs/components/pagination.md +73 -0
- package/docs/components/panel.md +28 -0
- package/docs/components/prompt-starters.md +40 -0
- package/docs/components/prose.md +38 -0
- package/docs/components/questionnaire.md +115 -0
- package/docs/components/rating.md +19 -0
- package/docs/components/run-status.md +50 -0
- package/docs/components/run-trace.md +72 -0
- package/docs/components/search.md +11 -0
- package/docs/components/select.md +129 -0
- package/docs/components/sheet-stack.md +39 -0
- package/docs/components/sheet.md +77 -0
- package/docs/components/skeleton.md +27 -0
- package/docs/components/slider.md +29 -0
- package/docs/components/sort-control.md +21 -0
- package/docs/components/source-list.md +30 -0
- package/docs/components/split-view.md +12 -0
- package/docs/components/stat-tile.md +49 -0
- package/docs/components/stepper.md +27 -0
- package/docs/components/surface.md +152 -0
- package/docs/components/tabbox.md +33 -0
- package/docs/components/table-view.md +43 -0
- package/docs/components/table.md +232 -0
- package/docs/components/tag-picker.md +39 -0
- package/docs/components/timebox.md +16 -0
- package/docs/components/toggle.md +21 -0
- package/docs/components/tokens.md +82 -0
- package/docs/components/toolbar.md +26 -0
- package/docs/components/tooltip.md +16 -0
- package/docs/components/tree.md +48 -0
- package/docs/components/truncate.md +21 -0
- package/docs/components/value-list.md +14 -0
- package/docs/components/view-settings.md +56 -0
- package/docs/components/workspace-switcher.md +42 -0
- package/docs/components/zeyos.md +196 -0
- package/docs/llms-small.txt +299 -0
- package/docs/llms.md +697 -100
- package/docs/llms.txt +46 -19
- package/package.json +9 -4
- package/src/components/activity-item/activity-item.js +21 -2
- package/src/components/agent-avatar/agent-avatar.css +195 -0
- package/src/components/agent-avatar/agent-avatar.js +333 -0
- package/src/components/agent-avatar/agent-face.js +292 -0
- package/src/components/agent-thread/ag-ui.js +44 -11
- package/src/components/agent-thread/agent-thread.js +103 -11
- package/src/components/agent-thread/ui-message-stream.js +3 -1
- package/src/components/app-rail/app-rail.css +5 -0
- package/src/components/app-sidebar/app-sidebar.css +3 -0
- package/src/components/app-sidebar/app-sidebar.js +4 -3
- package/src/components/approval-card/approval-card.css +6 -0
- package/src/components/approval-card/approval-card.js +55 -7
- package/src/components/aurora/aurora.css +149 -14
- package/src/components/aurora/aurora.js +49 -6
- package/src/components/calendar/calendar.css +6 -2
- package/src/components/calendar/calendar.js +127 -47
- package/src/components/card-view/card-view.js +5 -6
- package/src/components/chart/chart.css +159 -1
- package/src/components/chart/chart.js +450 -62
- package/src/components/chart/color.js +297 -0
- package/src/components/chart/svg-adapter.js +576 -0
- package/src/components/chart/svg-geometry.js +323 -0
- package/src/components/check-button/check-button.js +3 -18
- package/src/components/checklist/checklist.js +46 -17
- package/src/components/checklist/field-adapter.js +4 -1
- package/src/components/code-editor/code-editor.css +33 -0
- package/src/components/code-editor/code-editor.js +97 -8
- package/src/components/code-editor/field-adapter.js +3 -0
- package/src/components/composer/composer.css +3 -0
- package/src/components/composer/composer.js +100 -22
- package/src/components/context-menu/context-menu.js +41 -5
- package/src/components/copy/copy-button.js +9 -1
- package/src/components/copy/copy-input.js +5 -0
- package/src/components/data-filter/filter-core.js +0 -1
- package/src/components/date-picker/date-picker.css +8 -0
- package/src/components/date-picker/date-picker.js +47 -8
- package/src/components/date-picker/date-range-picker.js +1 -1
- package/src/components/date-picker/month-picker.js +19 -3
- package/src/components/date-picker/time-picker.js +54 -19
- package/src/components/datebox/date-range-box.js +7 -3
- package/src/components/datebox/datebox.js +32 -6
- package/src/components/dialog/dialog.css +6 -0
- package/src/components/dialog/dialog.js +22 -30
- package/src/components/dropdown/dropdown.js +1 -18
- package/src/components/empty-state/empty-state.js +21 -2
- package/src/components/field/field.js +19 -3
- package/src/components/fieldset/fieldset.js +3 -1
- package/src/components/filter/filter.js +9 -0
- package/src/components/form/form.js +19 -2
- package/src/components/kanban-view/kanban-card.js +15 -2
- package/src/components/kanban-view/kanban-view.css +21 -0
- package/src/components/kanban-view/kanban-view.js +29 -16
- package/src/components/launcher/launcher.css +14 -0
- package/src/components/launcher/launcher.js +54 -9
- package/src/components/master-panel/master-panel.js +24 -22
- package/src/components/menu-button/menu-button.js +26 -4
- package/src/components/message/message.css +228 -29
- package/src/components/message/message.js +664 -30
- package/src/components/modal/modal.js +70 -25
- package/src/components/modal/native-dialog.js +91 -0
- package/src/components/module-bar/module-bar.css +3 -0
- package/src/components/module-bar/module-bar.js +17 -4
- package/src/components/multi-value-editor/multi-value-editor.css +7 -2
- package/src/components/multi-value-editor/multi-value-editor.js +3 -2
- package/src/components/navigation-bar/navigation-bar.js +13 -1
- package/src/components/number-field/field-adapter.js +3 -0
- package/src/components/number-field/number-field.js +2 -1
- package/src/components/pagination/pagination.css +26 -2
- package/src/components/pagination/pagination.js +551 -65
- package/src/components/prose/prose.js +7 -1
- package/src/components/rating/field-adapter.js +3 -0
- package/src/components/run-status/run-status.js +43 -3
- package/src/components/run-trace/run-trace.js +15 -7
- package/src/components/search/search.js +3 -18
- package/src/components/select/field-adapter.js +8 -1
- package/src/components/select/select.js +68 -13
- package/src/components/sheet/sheet.js +27 -8
- package/src/components/slider/field-adapter.js +3 -0
- package/src/components/slider/slider.js +4 -6
- package/src/components/stat-tile/stat-tile.js +24 -9
- package/src/components/stepper/stepper.css +15 -0
- package/src/components/stepper/stepper.js +34 -2
- package/src/components/surface/catalog.js +185 -28
- package/src/components/surface/surface.js +10 -5
- package/src/components/tabbox/tabbox.js +13 -1
- package/src/components/table/table.css +160 -2
- package/src/components/table/table.js +479 -52
- package/src/components/table/window.js +46 -4
- package/src/components/table-view/table-view.js +1 -10
- package/src/components/tag-picker/field-adapter.js +3 -0
- package/src/components/tag-picker/tag-picker.js +2 -0
- package/src/components/timebox/field-adapter.js +3 -0
- package/src/components/toggle/toggle.js +51 -27
- package/src/components/tooltip/tooltip.js +21 -14
- package/src/components/tree/tree.js +87 -14
- package/src/components/truncate/truncate.js +21 -5
- package/src/components/value-list/value-list.js +37 -9
- package/src/components/view-settings/view-settings.js +1 -5
- package/src/core/component.js +34 -2
- package/src/core/date.js +5 -4
- package/src/core/drag-axis.js +24 -7
- package/src/core/export.js +4 -4
- package/src/core/fontawesome.js +34 -3
- package/src/core/format.js +3 -1
- package/src/core/http.js +23 -11
- package/src/core/icons.js +51 -10
- package/src/core/keyboard.js +83 -9
- package/src/core/messages.js +3 -0
- package/src/core/position.js +2 -2
- package/src/core/storage.js +80 -31
- package/src/core/util.js +16 -5
- package/src/elements/define.js +82 -47
- package/src/elements/kit.js +46 -35
- package/src/index.js +8 -4
- package/src/internal/agent-model.js +152 -0
- package/src/internal/app-rail.js +53 -2
- package/src/internal/collections.js +25 -0
- package/src/internal/menu-items.js +59 -0
- package/src/internal/overlay-content.js +35 -0
- package/src/internal/presence-loop.js +61 -14
- package/src/locales/de.js +3 -0
- package/src/zeyos/calendar.js +81 -19
- package/src/zeyos/connect.js +5 -1
- package/src/zeyos/form.js +29 -10
- package/src/zeyos/select.js +36 -12
- package/src/zeyos/table.js +43 -11
- package/src/zeyos/view.js +2 -1
- package/styles/tokens/semantic.css +7 -1
- package/styles/zx.css +1 -0
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# FilterPanel — typed filters from server metadata
|
|
2
|
+
|
|
3
|
+
The filter form a data-driven list needs: field metadata in, a query object out.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/filter-panel · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
The third filter component, and the one a data-driven application reaches for. `DataFilter`
|
|
8
|
+
filters a client-side row set; `Filter` builds a backend-neutral AST with groups and operators.
|
|
9
|
+
`FilterPanel` takes the `{key: {type, label, options, min, max}}` map a list endpoint already
|
|
10
|
+
publishes and gives back a query object — so the shape the server describes is the shape the
|
|
11
|
+
form renders, with no per-application translation layer in between.
|
|
12
|
+
|
|
13
|
+
- **Options** — `fields: Record<string, {type, label?, options?, min?, max?, step?, search?}>`,
|
|
14
|
+
`order` (display order; omitted uses object order), `value` (the applied filters, drafted
|
|
15
|
+
from), `mode: 'draft'|'live'`, `serialize: 'seconds'|'ms'|'iso'|(date, edge) => unknown`,
|
|
16
|
+
`timeZone` (IANA zone the days are counted in; null = the runtime's own), `emptyText`, `msg`.
|
|
17
|
+
- **Types** — `text`, `select`, `date`, `date:range`, `int`, `float`, `number`, and
|
|
18
|
+
`int:range` / `float:range` / `number:range`. An unrecognised type renders a visible,
|
|
19
|
+
labelled placeholder naming it and is excluded from the value — never dropped silently.
|
|
20
|
+
- **Methods** — `getValue()`, `setValue()`, `apply()`, `reset()`, `clear()`.
|
|
21
|
+
- **Events** — `apply {value}`, `change {value, field}`. Values read back from typed controls
|
|
22
|
+
include their normalization, such as integer rounding and numeric bounds.
|
|
23
|
+
|
|
24
|
+
Five behaviours are deliberate rather than incidental:
|
|
25
|
+
|
|
26
|
+
- **A select is multi-valued.** "Open or waiting" is the common request, and single choice turns
|
|
27
|
+
it into two visits. It composes `Checklist`, which brings its own search past eight options,
|
|
28
|
+
and the group is named after the filter rather than after the component.
|
|
29
|
+
- **Each end of a range carries its own accessible name.** One `<label for>` cannot name two
|
|
30
|
+
inputs, and a group label that names neither is worse than no group label.
|
|
31
|
+
- **`clear()` commits; `reset()` does not.** Clear is "no filters" and applies immediately —
|
|
32
|
+
emptying the controls while the list stays filtered is a panel that lies about what is on
|
|
33
|
+
screen. Reset restores the constructed value without committing, which is a host sheet's
|
|
34
|
+
Cancel.
|
|
35
|
+
- **An empty `fields` map is normal.** An instance that configures no filters for a settings
|
|
36
|
+
section is the ordinary case; the panel renders `emptyText`, never an error.
|
|
37
|
+
- **`0` is a value.** `''`, `null`, `[]` and `{from: null, to: null}` are not, and only active
|
|
38
|
+
constraints reach the emitted value.
|
|
39
|
+
|
|
40
|
+
`serialize` decides how a date leaves the component, because the answer is a wire-format
|
|
41
|
+
decision rather than an application one. A range's upper bound takes the **end** of its day, or
|
|
42
|
+
a one-day range matches nothing. `timeZone` decides *which* day: with the ZeyOS instance's zone
|
|
43
|
+
(`'Europe/Vienna'`), 15 January serializes from 23:00 UTC on the 14th wherever the browser is, and
|
|
44
|
+
an incoming Unix timestamp shows as the day it falls on there — the rule `zeyosForm()` and
|
|
45
|
+
`zeyosTable()` apply to date-only fields. An unknown zone throws a `RangeError`.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Filter — dynamic backend-neutral expressions
|
|
2
|
+
|
|
3
|
+
A backend-neutral, nested filter authoring component.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/filter · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
An authoring component for typed, nested filter expressions. It never evaluates application data
|
|
8
|
+
or interpolates query text: it emits a versioned, JSON-safe AST for an allowlisted application
|
|
9
|
+
adapter to compile into its own backend query language.
|
|
10
|
+
|
|
11
|
+
- **AST** — `{version: 1, root: {kind:'group', id, logic:'and'|'or', children}}`; children are
|
|
12
|
+
stable-ID groups or `{kind:'condition', id, field, operator, value}` records. Unknown field or
|
|
13
|
+
operator IDs survive parsing and render as unavailable/invalid instead of being silently lost.
|
|
14
|
+
- **Fields** — `{id,label,type,operators?,defaultOperator?,choices?,loadChoices?,editor?,minQuery?,
|
|
15
|
+
debounce?}`. Built-in types cover text, number/money, date/datetime, boolean, enum/status/
|
|
16
|
+
priority/country/currency/unit/entity, and tags. Compatible operators and their arity come from
|
|
17
|
+
the exported `filterOperators` matrix; applications may explicitly override/add operator IDs. The
|
|
18
|
+
labels in that matrix are English data. `Filter` shows a built-in operator through its
|
|
19
|
+
`filter.op.<id>` message, and an operator the `operators` option supplies through its own `label`.
|
|
20
|
+
- **Relative dates** — `withinLast` and `withinNext` take a span, not two dates: the editor is a
|
|
21
|
+
whole-number amount and a unit select, and the value is the pair `[amount, unit]` with `unit` one
|
|
22
|
+
of `RELATIVE_DATE_UNITS` (`'days'|'weeks'|'months'`), e.g. `[7, 'days']`. `validate()` requires a
|
|
23
|
+
positive whole amount and a known unit; `relativeDateValueError(value)` is the same check for an
|
|
24
|
+
adapter. A value that is not such a pair (two dates) shows as an empty amount.
|
|
25
|
+
- **Options** — `fields`, `value`, `operators`, `allowGroups: true`, `maxDepth: 3`,
|
|
26
|
+
`maxConditions: 50`, `autoApply: false`, `readonly`, `disabled`, `applyLabel`, `clearLabel`,
|
|
27
|
+
`searchable: false`, `layout: 'standard'|'compact'`, `rootLogic: null|'and'|'or'`,
|
|
28
|
+
`showApply: true`, `showRootActions: true`.
|
|
29
|
+
- **Searchable conditions** — opt in to local-search `Select` controls for fields, operators and
|
|
30
|
+
static single-choice/boolean values. Uncommitted search text never becomes a condition value.
|
|
31
|
+
Multi-choice, async and custom editors retain their existing contracts. Compact rows keep field,
|
|
32
|
+
operator, value and removal together, wrapping the value below on narrow containers.
|
|
33
|
+
- **Embedding** — hide internal Apply and duplicate root Add controls when the parent drawer owns
|
|
34
|
+
submission. `rootLogic` fixes the authored root logic; incompatible saved expressions remain
|
|
35
|
+
visible and invalid until corrected, never silently rewritten. Removing the last condition
|
|
36
|
+
returns keyboard focus to Add filter.
|
|
37
|
+
- **Methods** — `getValue()`, atomic `setValue()`, `addCondition()`, `addGroup()`, `update()`,
|
|
38
|
+
`remove()`, `move()`, `validate()`, `apply()`, `clear()`, `focus()`, `setReadonly()`,
|
|
39
|
+
`enable()`/`disable()`.
|
|
40
|
+
- **Events** — `change {value,valid,errors,reason,nodeId}`, `apply {value}`, `invalid {errors}`,
|
|
41
|
+
and abortable async-choice lifecycle `query`, `loaded`, `error`. `apply()` returns null and
|
|
42
|
+
focuses the first invalid condition when validation fails.
|
|
43
|
+
- **Pure exports** — `emptyFilterAst`, `filterCondition`, `filterGroup`, `parseFilterAst`,
|
|
44
|
+
`cloneFilterAst`, `cloneFilterValue`, `stringifyFilterAst`, and `validateFilterAst`.
|
|
45
|
+
- **Boundary** — keep the AST in saved views/audit state and compile it in a backend-specific
|
|
46
|
+
adapter with an allowlist and bound parameters. Do not put SQL, URL query fragments, functions,
|
|
47
|
+
DOM nodes, Dates, non-finite numbers, or other executable/non-JSON values into conditions.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Finder
|
|
2
|
+
|
|
3
|
+
A Miller-columns browser: every column lists the children of the row picked to its left, the way a file browser’s column view works.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/finder · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Miller-columns hierarchy browser: each column lists the children of the row selected in the column
|
|
8
|
+
to its left, like the macOS Finder's column view. The columns are linked listboxes sharing **one**
|
|
9
|
+
tab stop. The constructor applies `path` silently, so read `getNodes()` for the first paint of any
|
|
10
|
+
breadcrumb.
|
|
11
|
+
|
|
12
|
+
- **Options** — `items` (the same nested shape as `TreeView`), `valueKey`, `labelKey`,
|
|
13
|
+
`childrenKey`, `path: []` (initial selection, root first), `load: (node)=>Promise<children>`,
|
|
14
|
+
`preview: (node)=>Node|null` (renders a pane after the last column for a selected leaf),
|
|
15
|
+
`rootLabel`, `columnWidth: 220`, `height: 320`, `icons: true`, `renderItem`, `emptyText` (unset, the
|
|
16
|
+
`finder.noItems` message; `null` shows no text).
|
|
17
|
+
- **Methods** — `getPath()`, `getNodes()`, `getSelection()`, `setPath(ids, {silent, focus})`
|
|
18
|
+
(async — loads every branch along the way), `reveal(id)`, `setItems()`, `focus()`.
|
|
19
|
+
- **Events** — `change {path, nodes, node}`, `activate {node, id}`.
|
|
20
|
+
- **Keyboard** — ↑/↓ move within the active column, → steps into the selected branch and lands on
|
|
21
|
+
its first row, ← returns to the parent column and truncates the path, Home/End, Enter opens a
|
|
22
|
+
leaf, typing jumps to the next match.
|
|
23
|
+
- **Appearance** — the selected row of each column is the path you are on: the neutral
|
|
24
|
+
`--zx-color-bg-current` fill, the text colour and a semibold label, with subtle icons and
|
|
25
|
+
column dividers.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Field widget types
|
|
2
|
+
|
|
3
|
+
The field types backed by a whole Zx component rather than a native input — what turns a Form into a real record editor.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/form-widgets · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Beyond the built-in field types, these widget types wrap whole components, used as
|
|
8
|
+
`{ type, label, props: {…component options…} }`. They are registered by
|
|
9
|
+
`registerFieldAdapters()`, which `src/index.js` calls by default.
|
|
10
|
+
|
|
11
|
+
- `zxselect` (Select), `checklist` (Checklist), `tagpicker` (TagPicker), `number` (NumberField),
|
|
12
|
+
`rating` (Rating), `slider` (Slider).
|
|
13
|
+
- `date`/`month`/`datetime` (Datebox/MonthPicker — pass a `Date` value), `daterange`
|
|
14
|
+
(DateRangeBox — a `{start, end}` value), `time` (Timebox).
|
|
15
|
+
- `valuelist` (ValueList), `multivalueeditor` (MultiValueEditor), `upload` (FieldUpload),
|
|
16
|
+
`toggle` (Toggle), `code` (CodeEditor).
|
|
17
|
+
|
|
18
|
+
**Stylesheet names for `zx-css`.** A field type is registered at run time, so `zx-css` cannot
|
|
19
|
+
follow it from `form` to the component that draws it: name that component's stylesheet beside
|
|
20
|
+
`form`. Each line is field type — component — the name to pass, and the stylesheets that name
|
|
21
|
+
depends on come with it.
|
|
22
|
+
|
|
23
|
+
- `zxselect` — Select — `select`
|
|
24
|
+
- `checklist` — Checklist — `checklist`
|
|
25
|
+
- `tagpicker` — TagPicker — `tag-picker`
|
|
26
|
+
- `number` — NumberField — `number-field`
|
|
27
|
+
- `rating` — Rating — `rating`
|
|
28
|
+
- `slider` — Slider — `slider`
|
|
29
|
+
- `date` — Datebox — `datebox`
|
|
30
|
+
- `datetime` — DateTimeBox — `datebox`
|
|
31
|
+
- `month` — MonthPicker — `date-picker`
|
|
32
|
+
- `daterange` — DateRangeBox — `date-range-box`
|
|
33
|
+
- `time` — Timebox — `timebox`
|
|
34
|
+
- `valuelist` — ValueList — `value-list`
|
|
35
|
+
- `multivalueeditor` — MultiValueEditor — `multi-value-editor`
|
|
36
|
+
- `upload` — FieldUpload — `field-upload`
|
|
37
|
+
- `toggle` — Toggle — `toggle`
|
|
38
|
+
- `code` — CodeEditor — `code-editor`
|
|
39
|
+
|
|
40
|
+
The built-in types — `text`, `password`, `textarea`, `checkbox`, `int`, `float`, `select`,
|
|
41
|
+
`optionlist`, `hidden`, `html`, `custom` — are drawn by Field itself and need `form` alone. A form
|
|
42
|
+
with a Select and a date field is `npx zx-css form select datebox --out public/zx.css`.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Form / Fieldset / Field
|
|
2
|
+
|
|
3
|
+
Fieldsets of typed fields with one values object in and out — the schema-shaped way to build a record editor.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/form · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
## Form
|
|
8
|
+
|
|
9
|
+
- **Options** — `fieldsets: []`, `actions: [button descriptors]`, `novalidate: true`,
|
|
10
|
+
`idPrefix: null` (handed to the fieldsets it builds; a fieldset's own wins).
|
|
11
|
+
- **Methods** (proxied across the fieldsets) — `getValues()`, `setValues()`, `getField()`,
|
|
12
|
+
`setValue()`, `getValue()`, `reset()`, `setHighlights()`, `clearHighlights()`, `addFieldset()`,
|
|
13
|
+
`setActions()`, `submit()`.
|
|
14
|
+
- **Events** — `submit {values}` (preventable; required/int/float validation runs first),
|
|
15
|
+
`invalid {errors}`, `change {id, value}`.
|
|
16
|
+
|
|
17
|
+
## Fieldset
|
|
18
|
+
|
|
19
|
+
- **Options** — `title` (the legend: a quiet sentence-case caption, small, medium weight, muted —
|
|
20
|
+
the fields are the content), `columns: 1|2|3`, `fields: { id: Field-options }`,
|
|
21
|
+
`idPrefix: null`.
|
|
22
|
+
- **Keys and ids** — a field key names the value, not an element: it is the field's `name` (and
|
|
23
|
+
a native control's `name`) and its `data-field-id`, never a DOM id by itself. Control ids are
|
|
24
|
+
`<idPrefix>-<key>`, with a prefix generated per instance unless `idPrefix` is given, so a form
|
|
25
|
+
mounted twice repeats no id and a field `stage` never collides with a `#stage` elsewhere; the
|
|
26
|
+
label, description, and message ids derive from it (`<id>-label`). Radio groups are named after
|
|
27
|
+
the control id. An `id` in the field options that differs from the key is used as given.
|
|
28
|
+
- **Methods** — `addField(id, opts|Field|element|component)`, `getField`/`hasField`/`getFields`,
|
|
29
|
+
`getValues`/`setValues`/`getValue`/`setValue`, `reset`, `clear`, `focus(id)`,
|
|
30
|
+
`setHighlights`/`clearHighlights`.
|
|
31
|
+
- **Adopting a component** — `addField(id, component)` wraps any component (or element) that is
|
|
32
|
+
not a registered field type and drives it through its own API. Values: `getValue`/`setValue`,
|
|
33
|
+
`get`/`set`, `getValues`/`setValues`, `isChecked`/`setChecked`, or a `value` property, tried in
|
|
34
|
+
that order (a Toggle reads its on-value, as the `toggle` type does); an element is read through
|
|
35
|
+
`value`, or `checked` for a checkbox or radio. Disabled: `setDisabled(bool)`, then
|
|
36
|
+
`enable()`/`disable()`, then a `disabled` property; a plain wrapper gets `aria-disabled` and its
|
|
37
|
+
form controls disabled. Read-only: `setReadonly`/`setReadOnly` or the element's `readOnly`. The
|
|
38
|
+
component's own `change` becomes the field's `change`, once per edit. Writes keep the caller's
|
|
39
|
+
`silent`: `setValues(values)` lets the component emit its own `change` to its own listeners and
|
|
40
|
+
the field emit one `change`; `setValues(values, {silent: true})` and `reset()` stay quiet.
|
|
41
|
+
Removing the field puts the component back, unsubscribes from it, and undoes the disabled and
|
|
42
|
+
read-only state the field set.
|
|
43
|
+
|
|
44
|
+
## Field
|
|
45
|
+
|
|
46
|
+
- **Options** — `id` (the control's DOM id; generated when omitted), `name` (the field name and
|
|
47
|
+
native control `name`; defaults to `id` on a standalone field), `type: 'text'`, `label`,
|
|
48
|
+
`description`, `value`, `placeholder`, `required`, `disabled`, `readonly` (shown and focusable,
|
|
49
|
+
not editable; ignored by types whose control has no read-only state, such as `checkbox`,
|
|
50
|
+
`select`, `zxselect`, `date`, `time`), `options`, `layout: 'stack'|'inline'`, `props: {}`.
|
|
51
|
+
- **Properties** — `controlId` (the control's DOM id), `name`.
|
|
52
|
+
- **Built-in types** — `text`, `password`, `textarea`, `checkbox`, `int`, `float`, `select`,
|
|
53
|
+
`optionlist`, `hidden`, `html` (display content as text: no input frame, a control's height,
|
|
54
|
+
inset like the values around it in a quiet form).
|
|
55
|
+
- **Methods** — `getValue`/`setValue`, `focus`, `reset`, `setDisabled`, `setReadonly`,
|
|
56
|
+
`setHighlight(msg, kind)`, `clearHighlight`, `getInput`, `own(child)`, plus the statics
|
|
57
|
+
`Field.register(type, adapter)` and `Field.has(type)`.
|
|
58
|
+
- **Events** — `change {value}`, once per committed edit whatever the type (a typed value on
|
|
59
|
+
leaving the input, a slider on release, `code` when the editor loses focus after an edit);
|
|
60
|
+
`input {value}` for every keystroke or drag step from the types that tell the two apart
|
|
61
|
+
(`code`, `slider`); `invalid {message}`.
|
|
62
|
+
- **Adapters** — `Field.register(type, (field, options) => ({el, get, set, focus, setDisabled,
|
|
63
|
+
setReadonly?, destroy?, labelTarget?}))`. An adapter whose widget reports its own commits
|
|
64
|
+
forwards them with `field.emit('change', {value})` and stops the native `change` its inner
|
|
65
|
+
control bubbles (`field.listen(widget.el, 'change', (e) => e.stopImmediatePropagation())`), so
|
|
66
|
+
the Field does not report the same edit twice.
|
|
67
|
+
- **Labels** — small, medium weight, in the muted text colour: quieter than the values they name.
|
|
68
|
+
With `layout: 'inline'` the label lines up with the control's first line.
|
|
69
|
+
|
|
70
|
+
## Quiet fields
|
|
71
|
+
|
|
72
|
+
Inside any element with `data-zx-fields="quiet"` — an inspector, a property list, an inline record
|
|
73
|
+
— fields read as values rather than a wall of boxes. Native inputs, selects and textareas, and the
|
|
74
|
+
composite controls (`Select`, `TagPicker`, `NumberField`, `Datebox`, `DateRangeBox`, `Timebox`)
|
|
75
|
+
show no border, fill, chevron, stepper or calendar button until hovered (the hover fill and the
|
|
76
|
+
affordances come back) and their full field chrome and focus ring while focused or open. A
|
|
77
|
+
NumberField's value starts where a quiet text input's text starts, and `html` display content is
|
|
78
|
+
inset to match. Disabled
|
|
79
|
+
and read-only controls never light up; an invalid Datebox keeps its danger border. It is a context
|
|
80
|
+
attribute, not an option: set it on the container.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Grid and `Grid.BillingItems()`
|
|
2
|
+
|
|
3
|
+
A public Table specialization for domain presets; it inherits sorting, selection, hierarchy, typed formatting, and editing without forking them.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/grid · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
`Grid` is the public extension point for repeatable data-table presets. It subclasses `Table`
|
|
8
|
+
without forking its implementation, so sorting, selection, hierarchy, responsive stacking,
|
|
9
|
+
editable cells/rows, loading, events, and teardown keep the Table contract.
|
|
10
|
+
|
|
11
|
+
- **Constructor** — `new Grid(target, tableOptions)` accepts the complete `Table` API and defaults
|
|
12
|
+
editable cells to a single-click trigger. Pinned columns, header groups, `minWidth`,
|
|
13
|
+
`setExpanded()` and the rule that a click on a control inside a cell raises no `rowclick` are
|
|
14
|
+
Table's and apply unchanged.
|
|
15
|
+
- **Preset** — `Grid.BillingItems(target, options)` supplies an editable hierarchical billing
|
|
16
|
+
schema for item, quantity, unit, unit price, currency, and line total. It enables single-click
|
|
17
|
+
editing, hierarchy, row reorder handles, and the column visibility chooser. It returns a `Grid`.
|
|
18
|
+
- **Billing options** — `data`, `fields` key overrides, `units`, `currencies`, fallback `currency`,
|
|
19
|
+
`locale`, `decimals`, `columnOverrides`, complete `columns` replacement, `lineTotal(row, changes)`,
|
|
20
|
+
and `oneditcommit` in addition to ordinary Table options.
|
|
21
|
+
- **Rows** — default field names are `id`, `parent`, `kind`, `item`, `quantity`, `unit`,
|
|
22
|
+
`unitPrice`, `currency`, and `total`. `kind: 'group'|'subtotal'|'header'|'section'` is read-only;
|
|
23
|
+
other rows are editable. Parent references use Table's flat-data treegrid projection.
|
|
24
|
+
- **Calculation boundary** — the default line total is quantity × unit price. Applications own
|
|
25
|
+
taxes, discounts, rounding, subtotal/group recalculation, optimistic persistence, and server
|
|
26
|
+
validation; provide `lineTotal` or cancel `editcommit` when product policy differs.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Groupbox
|
|
2
|
+
|
|
3
|
+
A collapsible section built on native `<details>`, so the keyboard and find-in-page behaviour comes from the platform.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/groupbox · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Collapsible titled section built on the native `<details>` element.
|
|
8
|
+
|
|
9
|
+
- **Options** — `title`, `open: true`.
|
|
10
|
+
- **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `setTitle()`, `setContent()`.
|
|
11
|
+
- **Events** — `open`, `close`.
|
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
# Helper functions
|
|
2
|
+
|
|
3
|
+
The standalone function library that ships alongside the components: dates, formatting, escaping, small utilities, translation, and keyboard behaviours.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/helpers · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Standalone exports with no DOM ownership and no lifecycle, importable individually from the same
|
|
8
|
+
entry point as the components. See also the Kernel section for `Component`, `h`, `icon`, and
|
|
9
|
+
`position` — the substrate the components themselves are built on.
|
|
10
|
+
|
|
11
|
+
- **Dates** — `formatDate(date, fmt, {locale})`, `parseDate(str, fmt)` (returns `null` when the
|
|
12
|
+
string does not match, so it doubles as a validator), `clampDate(date, min, max)`,
|
|
13
|
+
`isSameDay(a, b)`, `addDays(date, n)`, `addMonths(date, n)`, `getWeekStart(lang?)` → `0` (Sunday)
|
|
14
|
+
or `1` (Monday). strftime-style tokens: `%d %m %Y %y %H %M %S %a %A %b %B %s`. Month and weekday
|
|
15
|
+
names come from `Intl` in a supported explicit `locale`, then `getLanguage()`, then English.
|
|
16
|
+
Regional English tags keep their own abbreviations and conventions. Explicit locale names take
|
|
17
|
+
precedence over host date-name translations; without an explicit locale those translations apply.
|
|
18
|
+
Short names use `Intl` unless a host supplies the corresponding short-name key.
|
|
19
|
+
- **Numbers, money and time** — `formatNumber(value, {locale, decimals, minDecimals, maxDecimals,
|
|
20
|
+
group=true})`, `formatCurrency(value, currency, {locale, decimals})`, `formatPercent(value,
|
|
21
|
+
{locale, decimals=0})` (takes a fraction, so `0.42` → `42%`), `formatFileSize(bytes, {locale,
|
|
22
|
+
decimals=1, standard='iec'})` (`'iec'` → KiB/MiB/GiB in steps of 1024, `'si'` → kB/MB/GB in steps
|
|
23
|
+
of 1000; `0` → `'0 B'`, trailing zeros dropped), `formatRelativeTime(date, {now=new Date(),
|
|
24
|
+
locale, numeric='auto'})` (picks the largest sensible unit from second to year; accepts a `Date`,
|
|
25
|
+
Unix seconds, or an ISO string). A supported explicit `locale` takes precedence over
|
|
26
|
+
`getLanguage()`, then English, so `setLanguage()` drives all five when no usable option is given.
|
|
27
|
+
Nothing throws: `null`, `undefined` and `NaN` all format as
|
|
28
|
+
`''`, an invalid currency code falls back to plain number formatting, and every `Intl` instance
|
|
29
|
+
is cached because tables call these once per cell.
|
|
30
|
+
- **Utilities** — `debounce(fn, ms)` (trailing edge, preserves `this`), `throttle(fn, ms,
|
|
31
|
+
{leading=true, trailing=true})` (its rate-limiting counterpart: runs at most once per interval
|
|
32
|
+
and replays the latest arguments on the trailing edge), `uid(prefix='zx')` (unique
|
|
33
|
+
per page load, safe as a DOM id), `deepMerge(a, b)` (never mutates either input; replaces arrays
|
|
34
|
+
rather than concatenating), `clamp(n, min, max)`, `toArray(value)` (null → `[]`, string → single
|
|
35
|
+
entry, iterable/array-like → array), `isElement(value)` (cross-realm safe).
|
|
36
|
+
- **Collections** — `groupBy(items, key)` → `Record<string, T[]>` ordered by first appearance;
|
|
37
|
+
`sortBy(items, ...keys)` returns a **new** array and never mutates its input, taking a property
|
|
38
|
+
name, a `'-name'` prefix or a `{key, dir}` object for descending, or an accessor function,
|
|
39
|
+
comparing digit runs numerically and always sorting `null`, `undefined` and `NaN` last in either
|
|
40
|
+
direction; `uniqueBy(items, key?)` keeps the first occurrence.
|
|
41
|
+
- **Escaping** — `h()` rejects `innerHTML`, `outerHTML`, and `srcdoc` properties regardless of
|
|
42
|
+
casing, and sanitizes `href` through `safeHref`. `htmlEscape(str)`, and `h.raw(html)` as the only
|
|
43
|
+
sanctioned `innerHTML` path, for
|
|
44
|
+
component-generated markup only. `escapeRegExp(value)` makes user input safe as a literal
|
|
45
|
+
pattern, and `highlightMatch(text, query, {className='zx-mark'})` → `DocumentFragment` wraps
|
|
46
|
+
every case-insensitive occurrence in a `<mark>` built from text nodes, with no `innerHTML`
|
|
47
|
+
involved — the pairing every filtering list wants.
|
|
48
|
+
- **Storage** — `storage(namespace, {area='local'})` → `{get, set, remove, keys, clear, migrateLegacy}`, a
|
|
49
|
+
namespaced JSON-encoded view of `localStorage` (or `sessionStorage` with `{area: 'session'}`).
|
|
50
|
+
Keys are written as `zx2:<namespace length>:<namespace>:<key>` (UTF-16 string length), so names
|
|
51
|
+
containing colons cannot overlap. `clear()` empties only its own namespace; `keys()` reports
|
|
52
|
+
namespace-relative names. To retain values from the earlier `zx:` format, call
|
|
53
|
+
`migrateLegacy(['known-key'])` before reading them. It copies only the exact keys you name, only
|
|
54
|
+
when they contain valid JSON and the current key is absent, and returns the names copied.
|
|
55
|
+
Legacy values are never deleted. Migration is recorded once per key, including missing keys;
|
|
56
|
+
removing or clearing a migrated value does not restore it on the next load. Invalid legacy JSON
|
|
57
|
+
remains retryable. Built-in persisted components migrate their own known keys automatically.
|
|
58
|
+
`get(key, fallback)` returns the fallback both for a missing key and for unparseable JSON, and
|
|
59
|
+
`set()` drops values JSON cannot represent rather than throwing. When the area is missing or
|
|
60
|
+
refuses a write — private browsing, a full quota, cookies disabled — the view degrades silently
|
|
61
|
+
to an in-memory map for the life of the page, so callers never need a `try`/`catch`.
|
|
62
|
+
- **Export** — `toCsv(rows, columns, {delimiter=',', header=true, newline='\r\n'})` serialises to
|
|
63
|
+
RFC 4180: fields containing the delimiter, a quote, CR or LF are quoted with inner quotes
|
|
64
|
+
doubled, `Date`s become ISO strings, `null`/`undefined` become empty fields, and text starting
|
|
65
|
+
with `=`, `+`, `-` or `@` is prefixed with a tab so spreadsheets treat it as text rather than a
|
|
66
|
+
formula (numbers are exempt, so negative amounts survive). `columns` accepts plain id strings or
|
|
67
|
+
`{id, label, value(row)}` descriptors. `downloadBlob(filename, data, {type})` saves through a
|
|
68
|
+
temporary object URL, prepending a UTF-8 BOM for `text/csv` so Excel reads it as UTF-8;
|
|
69
|
+
`copyToClipboard(text)` → `Promise<boolean>` uses the async Clipboard API and falls back to a
|
|
70
|
+
hidden textarea, never rejecting.
|
|
71
|
+
- **Translation** — `setTranslator(fn)`, `setLanguage(lang)`, `getLanguage()`,
|
|
72
|
+
`translate(key, args)`, `printf(str, args)` (`%1`, `%2`, … placeholders), `defaultMessages`.
|
|
73
|
+
Every component resolves its built-in strings through `msg()`, so one translator covers the
|
|
74
|
+
library: per-instance `msg` option → `setTranslator()` function → the component's built-in
|
|
75
|
+
defaults → the default English catalogue → the key. The translator answers one key at a time;
|
|
76
|
+
null, undefined, or the key itself means "not translated" and English shows, so an application
|
|
77
|
+
without a translator never sees a raw key. `defaultMessages` is that catalogue — copy it to
|
|
78
|
+
start a locale (`setTranslator((key) => de[key])`), or install the German one below.
|
|
79
|
+
`setLanguage()` also selects the language table of a `msg` option and drives locale-dependent
|
|
80
|
+
behaviour such as the first day of the week and the month and weekday names `formatDate()` writes.
|
|
81
|
+
`translatePlural(key, count, args, {locale}?)` and `component.msgPlural(key, count, ...args)`
|
|
82
|
+
select cardinal forms using `Intl.PluralRules`. Pass the finite numeric count separately from
|
|
83
|
+
display arguments: `translatePlural('items', 2, ['two'])`. At each message source, resolution
|
|
84
|
+
tries `items.<category>`, `items.other`, then `items` (including a legacy alias). Instance overrides
|
|
85
|
+
precede the host translator, inherited component messages, and English defaults. English fallback
|
|
86
|
+
selects its category using English rules. Existing unsuffixed overrides remain valid.
|
|
87
|
+
- **Keyboard** — `focusTrap(container)` → `{activate, deactivate}` confines Tab to a container;
|
|
88
|
+
an empty trap focuses its boundary, temporarily adding `tabindex="-1"` when needed and removing
|
|
89
|
+
it on deactivation. Deactivation restores the previous focus when it is still connected.
|
|
90
|
+
`rovingTabindex(container, itemSelector, {orientation, wrap, rtl: 'auto'})` → `{focusFirst,
|
|
91
|
+
focusLast, destroy}` keeps one tab stop in a group — horizontal arrows follow `dir="rtl"`, and a
|
|
92
|
+
text field, select, or contenteditable item keeps Home/End and its arrows (an arrow leaves a text
|
|
93
|
+
field only from the edge of its text); toggling a `<fieldset disabled>` around items inside the
|
|
94
|
+
container moves the tab stop off them. Removed items regain their original tabindex and are
|
|
95
|
+
released; reinserted items use their new baseline. `typeahead(getItems, onMatch)` →
|
|
96
|
+
`(event|string) => void` resolves buffered printable keystrokes to an item (500 ms buffer,
|
|
97
|
+
repeated-letter cycling).
|
|
98
|
+
|
|
99
|
+
## Locales
|
|
100
|
+
|
|
101
|
+
[Open the Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales).
|
|
102
|
+
|
|
103
|
+
Its [live language-switching example](https://zx.zeyos.com/docs.html#getting-started/locales/try-language-switching)
|
|
104
|
+
offers English, German, and an application-owned French catalogue. Edit the name, record, and
|
|
105
|
+
count to try positional/named variables, plural forms, and number formatting. Switching preserves
|
|
106
|
+
the input values and recreates the translated Select. French intentionally omits `table.empty`
|
|
107
|
+
to demonstrate English fallback. The embedded example has its own language state, and its running
|
|
108
|
+
source and catalogues are available under Code.
|
|
109
|
+
|
|
110
|
+
### Language, locale, and catalogue
|
|
111
|
+
|
|
112
|
+
Zx ships English and German interface messages. Other languages can be supplied by the application.
|
|
113
|
+
Locale tags such as `en-GB`, `de-AT`, and `fr-CA` describe language and regional conventions; adding a
|
|
114
|
+
tag to a picker does not install a translation.
|
|
115
|
+
|
|
116
|
+
- `setTranslator(fn)` supplies the words. The function receives a flat message key and returns its text.
|
|
117
|
+
- `setLanguage(tag)` selects the active language for plural rules, default formatting, and language-specific `msg` tables. It does not load a catalogue or change the page's HTML `lang` attribute.
|
|
118
|
+
- `locale` selects formatting on helpers and components that expose this option. It does not select translated interface messages.
|
|
119
|
+
- `displayLocale` controls the names shown by Select.locale() and Select.country(), independently of their selected value.
|
|
120
|
+
- `msg` overrides messages for one component. Application labels, record values, and server text remain application-owned.
|
|
121
|
+
|
|
122
|
+
### Enable a shipped language
|
|
123
|
+
|
|
124
|
+
Install the catalogue and language before creating components:
|
|
125
|
+
|
|
126
|
+
```js
|
|
127
|
+
import { setLanguage, setTranslator } from '@zeyos/zx';
|
|
128
|
+
import { de } from '@zeyos/zx/locales/de.js';
|
|
129
|
+
|
|
130
|
+
setTranslator((key) => de[key]);
|
|
131
|
+
setLanguage('de-AT');
|
|
132
|
+
document.documentElement.lang = 'de-AT';
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
This uses German messages with Austrian formatting conventions. `setTranslator(null)` restores
|
|
136
|
+
English message fallback; call `setLanguage('en')` as well to return formatting to English.
|
|
137
|
+
`en` from `@zeyos/zx/locales/en.js` is the frozen `defaultMessages` object. The optional
|
|
138
|
+
`@zeyos/zx/locales/index.js` exports `en`, `de`, and the frozen `locales` manifest. Importing that
|
|
139
|
+
manifest includes both catalogues; the main entry does not load German automatically.
|
|
140
|
+
|
|
141
|
+
### Add a new language
|
|
142
|
+
|
|
143
|
+
Create an application-owned module, for example `app/locales/fr.js`, served at `/app/locales/fr.js`.
|
|
144
|
+
This intentionally partial example translates two Select messages:
|
|
145
|
+
|
|
146
|
+
```js
|
|
147
|
+
export const fr = Object.freeze({
|
|
148
|
+
'select.none': 'Aucune sélection',
|
|
149
|
+
'select.empty': 'Aucun résultat'
|
|
150
|
+
});
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
```js
|
|
154
|
+
import { setLanguage, setTranslator } from '@zeyos/zx';
|
|
155
|
+
import { fr } from '/app/locales/fr.js';
|
|
156
|
+
|
|
157
|
+
setTranslator((key) => fr[key]);
|
|
158
|
+
setLanguage('fr-FR');
|
|
159
|
+
document.documentElement.lang = 'fr-FR';
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Use `defaultMessages` as the inventory of built-in keys to translate. Keep their placeholders,
|
|
163
|
+
including each plural form's placeholders, and test the controls and accessible labels that your
|
|
164
|
+
application uses. A partial catalogue should return `undefined` for untranslated keys so Zx can
|
|
165
|
+
apply its English fallback with English plural rules. Do not fill a partial non-English catalogue
|
|
166
|
+
by spreading `defaultMessages` into it. `null` and an echoed key also mean “no translation”; an
|
|
167
|
+
empty string is an intentional empty translation.
|
|
168
|
+
|
|
169
|
+
Application catalogues need no change to Zx or its shipped manifest. Keep a registry of the languages
|
|
170
|
+
your application actually supports, and pass those tags to Select.locale().
|
|
171
|
+
|
|
172
|
+
### Regional variants and catalogue lookup
|
|
173
|
+
|
|
174
|
+
The application chooses how a regional tag maps to a catalogue. Zx does not automatically search
|
|
175
|
+
`de-AT`, then `de`, inside your translator. Reuse a language catalogue, or create regional overrides:
|
|
176
|
+
|
|
177
|
+
```js
|
|
178
|
+
import { setLanguage, setTranslator } from '@zeyos/zx';
|
|
179
|
+
import { en, de } from '@zeyos/zx/locales/index.js';
|
|
180
|
+
|
|
181
|
+
const deAT = Object.freeze({ ...de, 'table.empty': 'Keine Einträge' });
|
|
182
|
+
const catalogues = { en, de, 'de-AT': deAT };
|
|
183
|
+
|
|
184
|
+
function applyLocale(tag) {
|
|
185
|
+
const locale = Intl.getCanonicalLocales(tag)[0];
|
|
186
|
+
const language = new Intl.Locale(locale).language;
|
|
187
|
+
const catalogue = catalogues[locale] ?? catalogues[language];
|
|
188
|
+
setTranslator(catalogue ? (key) => catalogue[key] : null);
|
|
189
|
+
setLanguage(locale);
|
|
190
|
+
document.documentElement.lang = locale;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
applyLocale('de-AT');
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Here `en-GB` reuses English messages, while `de-AT` keeps its regional override. This function expects
|
|
197
|
+
a valid BCP 47 tag; picker values are already canonical. General locale APIs use hyphenated tags.
|
|
198
|
+
|
|
199
|
+
### Message keys and interpolation variables
|
|
200
|
+
|
|
201
|
+
Use flat string keys for your own messages. A dotted key is a name, not a nested object path.
|
|
202
|
+
Positional placeholders are `%1`, `%2`, and so on; named placeholders use `%name%`:
|
|
203
|
+
|
|
204
|
+
```js
|
|
205
|
+
import { setLanguage, setTranslator, translate } from '@zeyos/zx';
|
|
206
|
+
import { de } from '@zeyos/zx/locales/de.js';
|
|
207
|
+
|
|
208
|
+
const messages = Object.freeze({
|
|
209
|
+
...de,
|
|
210
|
+
'app.welcome': 'Willkommen, %1!',
|
|
211
|
+
'app.assigned': '%person% bearbeitet %record%.'
|
|
212
|
+
});
|
|
213
|
+
setTranslator((key) => messages[key]);
|
|
214
|
+
setLanguage('de');
|
|
215
|
+
|
|
216
|
+
translate('app.welcome', ['Ada']);
|
|
217
|
+
translate('app.assigned', { person: 'Ada', record: 'INV-42' });
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
`component.msg(key, ...args)` takes positional arguments. For a named template, use
|
|
221
|
+
`translate(key, values)` or `printf(component.msg(key), values)`. Interpolation produces plain text;
|
|
222
|
+
render it with text nodes or `textContent`.
|
|
223
|
+
|
|
224
|
+
For a single component, pass `msg: { 'select.empty': 'Nothing found here' }`. Resolution is instance
|
|
225
|
+
messages, host translator, inherited component messages, English catalogue, then the key.
|
|
226
|
+
Language-specific tables such as `msg: { de: { 'select.empty': 'Nichts gefunden' } }` match the exact
|
|
227
|
+
active language identifier; provide a `de-AT` table or a flat entry when that is the active tag.
|
|
228
|
+
|
|
229
|
+
### Plural forms
|
|
230
|
+
|
|
231
|
+
Pass a numeric count separately from its displayed text. The selected cardinal category comes
|
|
232
|
+
from `Intl.PluralRules`; messages remain flat strings:
|
|
233
|
+
|
|
234
|
+
```js
|
|
235
|
+
import { formatNumber, setLanguage, setTranslator, translatePlural } from '@zeyos/zx';
|
|
236
|
+
import { de } from '@zeyos/zx/locales/de.js';
|
|
237
|
+
|
|
238
|
+
const messages = Object.freeze({
|
|
239
|
+
...de,
|
|
240
|
+
'app.results.one': '%1 Ergebnis',
|
|
241
|
+
'app.results.other': '%1 Ergebnisse'
|
|
242
|
+
});
|
|
243
|
+
setTranslator((key) => messages[key]);
|
|
244
|
+
setLanguage('de');
|
|
245
|
+
|
|
246
|
+
const count = 1200;
|
|
247
|
+
translatePlural('app.results', count, [formatNumber(count)]);
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Use `component.msgPlural(key, count, ...args)` inside a component. Supply `.other` and the categories
|
|
251
|
+
your language needs: `.zero`, `.one`, `.two`, `.few`, and `.many` are supported too. At each message
|
|
252
|
+
source, lookup tries the selected category, `.other`, then the unsuffixed key and any supported legacy
|
|
253
|
+
alias before moving to the next source. Existing flat overrides therefore keep their precedence.
|
|
254
|
+
English fallback uses English rules. Custom application keys need their own fallback text; they are
|
|
255
|
+
not part of the built-in English catalogue. Ordinary `translate()` and `msg()` never infer a count.
|
|
256
|
+
|
|
257
|
+
### Formatting and date-name overrides
|
|
258
|
+
|
|
259
|
+
Formatting uses a supported explicit locale, then the active language, then English. Support is
|
|
260
|
+
checked for the particular Intl service, since a language may support numbers but not plural rules.
|
|
261
|
+
Regional English tags retain their own conventions.
|
|
262
|
+
|
|
263
|
+
```js
|
|
264
|
+
import { formatCurrency, formatDate, formatNumber } from '@zeyos/zx';
|
|
265
|
+
|
|
266
|
+
formatNumber(1234.5, { locale: 'en-GB', decimals: 2 });
|
|
267
|
+
formatCurrency(1234.5, 'EUR', { locale: 'de-AT' });
|
|
268
|
+
formatDate(new Date(2026, 8, 1), '%b', { locale: 'en-GB' });
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Components with a `locale` option can use the same override. For NumberField, locale-aware display
|
|
272
|
+
and parsing apply with `group: true`; ungrouped fields retain their machine-format input behavior.
|
|
273
|
+
Currency, time zone, week start, and display patterns are separate settings where the API exposes
|
|
274
|
+
them; a locale tag alone does not choose them all.
|
|
275
|
+
|
|
276
|
+
`formatDate()` normally obtains month and weekday names from Intl. A host translator can override
|
|
277
|
+
`date.month.0` through `date.month.11` and `date.weekday.0` through `date.weekday.6` (Sunday is zero).
|
|
278
|
+
Use `date.month.short.0` and `date.weekday.short.0` for their short forms. Missing short names come
|
|
279
|
+
from Intl, not a shortened translated long name. These overrides apply when no explicit locale is
|
|
280
|
+
passed; an explicit `formatDate(..., { locale })` takes precedence. `locale: null` remains implicit.
|
|
281
|
+
|
|
282
|
+
### Use the Select-based pickers
|
|
283
|
+
|
|
284
|
+
Select.locale() and Select.country() return ordinary Select instances. They keep its popup, keyboard map, events, field
|
|
285
|
+
adapter, and `.zx-select` styling, adding item generation, names, flags, and value normalization.
|
|
286
|
+
A locale selection emits `change`; it does not install translations or change the application language.
|
|
287
|
+
|
|
288
|
+
Using `applyLocale()` from the regional-lookup example:
|
|
289
|
+
|
|
290
|
+
```js
|
|
291
|
+
import { getLanguage, Select } from '@zeyos/zx';
|
|
292
|
+
|
|
293
|
+
const picker = Select.locale(null, {
|
|
294
|
+
locales: ['en-GB', 'de-DE', 'de-AT'],
|
|
295
|
+
value: getLanguage(),
|
|
296
|
+
displayLocale: 'en-GB',
|
|
297
|
+
flags: 'code',
|
|
298
|
+
filter: 'local'
|
|
299
|
+
});
|
|
300
|
+
picker.on('change', ({ detail }) => {
|
|
301
|
+
if (detail.value) applyLocale(detail.value);
|
|
302
|
+
});
|
|
303
|
+
document.querySelector('#language').append(picker.toElement());
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
`displayLocale` changes the language names shown, while the selected value stays a locale tag.
|
|
307
|
+
Select.locale() filters automatically for lists longer than seven; `filter: 'local'` also enables
|
|
308
|
+
search for short lists. For a form, use the existing Select field preset:
|
|
309
|
+
|
|
310
|
+
```js
|
|
311
|
+
import { Field } from '@zeyos/zx';
|
|
312
|
+
|
|
313
|
+
const languageField = new Field(null, {
|
|
314
|
+
type: 'zxselect',
|
|
315
|
+
name: 'language',
|
|
316
|
+
label: 'Language',
|
|
317
|
+
value: 'de-AT',
|
|
318
|
+
props: { preset: 'locale', locales: ['en-GB', 'de-AT'], flags: 'code' }
|
|
319
|
+
});
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
Use `props.preset: 'country'` for the country factory. Preset names are Field adapter options;
|
|
323
|
+
for direct construction call `Select.locale()` or `Select.country()`.
|
|
324
|
+
|
|
325
|
+
### Switching language at runtime
|
|
326
|
+
|
|
327
|
+
Set the translator and active language together, then refresh your application UI. Zx does not
|
|
328
|
+
broadcast a language-change event or automatically relabel every mounted component. Preserve the
|
|
329
|
+
application's values, destroy affected instances, and recreate them with the new messages; merely
|
|
330
|
+
changing the picker value does not do this. Use each component's documented update methods where
|
|
331
|
+
they cover the text being changed, rather than calling its internal `render()` method.
|
|
332
|
+
|
|
333
|
+
Set the document or region's HTML `lang` for pronunciation, and set `dir="rtl"` when your application
|
|
334
|
+
selects a right-to-left language. Zx does not infer text direction from `setLanguage()`. Verify visible
|
|
335
|
+
labels, accessible names, plural counts, date/number entry, and layout after a switch.
|
|
336
|
+
|
|
337
|
+
### German catalogue glossary
|
|
338
|
+
|
|
339
|
+
- **Voice** — a business application. The reader is addressed formally ("Sie"), and preferably not
|
|
340
|
+
at all ("Änderungen speichern"). Buttons and menu items use the infinitive ("Speichern",
|
|
341
|
+
"Abbrechen").
|
|
342
|
+
- **Typography** — quotation marks „…“; the ellipsis character attached to its word ("Wird
|
|
343
|
+
geladen…"); a non-breaking space between a number and its unit ("Letzte 30 Tage").
|
|
344
|
+
- **Kept as they are** — Agent, Board, Code, Swimlanes, Tags, Token, Tool, Upload; also Dashboard,
|
|
345
|
+
Prompt, and Tab where a key needs them. A work-in-progress limit is a WIP-Limit.
|
|
346
|
+
- **Agents** — approve → genehmigen, approval → Genehmigung, reject → ablehnen, request → Anfrage,
|
|
347
|
+
run → Ausführung, working time → Laufzeit, step → Schritt, tool call → Tool-Aufruf, retry →
|
|
348
|
+
Wiederholung, stop → stoppen, conversation → Unterhaltung, source → Quelle, attachment → Anhang.
|
|
349
|
+
- **Records** — record → Datensatz, field → Feld, row → Zeile, column → Spalte, view → Ansicht,
|
|
350
|
+
group by → gruppieren nach, no records → Keine Datensätze.
|
|
351
|
+
- **Dates** — event → Termin, date range and period → Zeitraum, week number → Kalenderwoche.
|
|
352
|
+
- **Actions** — choose and select → auswählen, clear → zurücksetzen (a selection: aufheben), search
|
|
353
|
+
→ suchen, or durchsuchen with an object, expand → ausklappen, collapse → einklappen, hide →
|
|
354
|
+
ausblenden, remove → entfernen, no matches → Keine Treffer, no results → Keine Ergebnisse.
|
|
355
|
+
- **Parts of the interface** — message → Nachricht in a conversation and Meldung in a notice,
|
|
356
|
+
launcher → Schnellsuche, workspace → Arbeitsbereich, panel → Bereich, sheet → Seitenbereich,
|
|
357
|
+
breadcrumb → Pfadnavigation.
|
|
358
|
+
- **Keys** — arrow keys → Pfeiltasten, Space → Leertaste, Enter → Eingabetaste, Escape → Esc, Ctrl →
|
|
359
|
+
Strg, Delete → Entf.
|