@zeyos/zx 5.3.0 → 5.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +125 -0
- package/README.md +49 -16
- package/dist/types/components/app-sidebar/app-sidebar.d.ts +33 -0
- package/dist/types/components/badge/badge.d.ts +5 -4
- package/dist/types/components/datebox/date-range-box.d.ts +15 -2
- package/dist/types/components/datebox/datebox.d.ts +37 -3
- package/dist/types/components/kbd/kbd.d.ts +41 -0
- package/dist/types/components/launcher/launcher.d.ts +4 -2
- package/dist/types/components/prose/prose.d.ts +69 -0
- package/dist/types/components/questionnaire/questionnaire.d.ts +0 -36
- package/dist/types/components/stat-tile/stat-tile.d.ts +20 -0
- package/dist/types/components/tag-picker/tag-picker.d.ts +11 -5
- package/dist/types/components/tree/tree.d.ts +44 -3
- package/dist/types/core/icons.d.ts +22 -1
- package/dist/types/index.d.ts +4 -2
- package/dist/types/internal/app-rail.d.ts +10 -3
- package/dist/types/internal/row-actions.d.ts +151 -0
- package/dist/zx-zeyos.esm.js +264 -82
- package/dist/zx-zeyos.esm.min.js +4 -4
- package/dist/zx.css +1288 -439
- package/dist/zx.esm.js +952 -392
- package/dist/zx.esm.min.js +6 -6
- package/dist/zx.global.js +952 -392
- package/dist/zx.global.min.js +6 -6
- package/dist/zx.min.css +1 -1
- package/docs/api.json +112 -4
- package/docs/llms.md +433 -38
- package/docs/llms.txt +21 -1
- package/package.json +1 -1
- package/src/components/account-menu/account-menu.js +2 -2
- package/src/components/app-rail/app-rail.css +11 -11
- package/src/components/app-sidebar/app-sidebar.css +90 -17
- package/src/components/app-sidebar/app-sidebar.js +120 -12
- package/src/components/badge/badge.css +33 -20
- package/src/components/badge/badge.js +5 -4
- package/src/components/breadcrumb/breadcrumb.css +28 -3
- package/src/components/breadcrumb/breadcrumb.js +2 -2
- package/src/components/button/button.css +24 -13
- package/src/components/button/button.js +20 -2
- package/src/components/calendar/calendar.css +14 -4
- package/src/components/card-view/card-view.js +2 -2
- package/src/components/chart/chart.js +20 -5
- package/src/components/check-button/check-button.css +11 -3
- package/src/components/check-button/check-button.js +3 -3
- package/src/components/context-menu/context-menu.css +7 -1
- package/src/components/date-picker/date-picker.css +6 -0
- package/src/components/date-picker/date-picker.js +5 -5
- package/src/components/date-picker/date-range-picker.css +6 -0
- package/src/components/date-picker/date-range-picker.js +3 -3
- package/src/components/date-picker/month-picker.js +3 -3
- package/src/components/date-picker/time-picker.css +6 -0
- package/src/components/datebox/date-range-box.js +30 -6
- package/src/components/datebox/datebox.js +44 -7
- package/src/components/dialog/dialog.css +0 -1
- package/src/components/dialog/dialog.js +2 -1
- package/src/components/dock/dock.js +2 -2
- package/src/components/dropdown/dropdown.css +2 -1
- package/src/components/entity-ref/entity-ref.css +8 -1
- package/src/components/file-item/file-item.css +1 -1
- package/src/components/finder/finder.js +2 -2
- package/src/components/groupbox/groupbox.js +2 -2
- package/src/components/kanban-view/kanban-view.css +8 -4
- package/src/components/kanban-view/kanban-view.js +3 -3
- package/src/components/kbd/kbd.css +64 -0
- package/src/components/kbd/kbd.js +121 -0
- package/src/components/launcher/launcher.css +30 -25
- package/src/components/launcher/launcher.js +15 -21
- package/src/components/list-toolbar/list-toolbar.css +7 -1
- package/src/components/menu-button/menu-button.css +9 -2
- package/src/components/message/message.css +6 -2
- package/src/components/message/message.js +2 -2
- package/src/components/module-bar/module-bar.css +11 -1
- package/src/components/multi-value-editor/multi-value-editor.js +4 -4
- package/src/components/navigation-bar/navigation-bar.css +3 -2
- package/src/components/pagination/pagination.js +2 -2
- package/src/components/panel/panel.js +2 -2
- package/src/components/prose/prose.css +53 -0
- package/src/components/prose/prose.js +152 -0
- package/src/components/questionnaire/questionnaire.css +7 -17
- package/src/components/questionnaire/questionnaire.js +16 -1
- package/src/components/rating/rating.css +3 -1
- package/src/components/search/search.js +2 -2
- package/src/components/select/glyphs.js +3 -3
- package/src/components/select/select.css +35 -7
- package/src/components/select/select.js +4 -4
- package/src/components/stat-tile/stat-tile.css +56 -2
- package/src/components/stat-tile/stat-tile.js +25 -2
- package/src/components/stepper/stepper.css +2 -1
- package/src/components/stepper/stepper.js +3 -3
- package/src/components/tabbox/tabbox.css +2 -2
- package/src/components/tabbox/tabbox.js +2 -2
- package/src/components/table/table.css +52 -16
- package/src/components/table/table.js +7 -5
- package/src/components/tag-picker/tag-picker.css +56 -43
- package/src/components/tag-picker/tag-picker.js +21 -16
- package/src/components/tree/tree.css +44 -0
- package/src/components/tree/tree.js +97 -9
- package/src/components/value-list/value-list.css +25 -4
- package/src/components/value-list/value-list.js +2 -1
- package/src/components/view/record-view.js +3 -3
- package/src/components/view-settings/view-settings.css +2 -1
- package/src/components/workspace-switcher/workspace-switcher.js +3 -3
- package/src/core/icons.js +34 -3
- package/src/elements/define.js +1 -0
- package/src/index.js +4 -2
- package/src/internal/app-rail.js +5 -1
- package/src/internal/row-actions.js +203 -0
- package/styles/base.css +26 -1
- package/styles/prose.css +306 -0
- package/styles/tokens/dark.css +108 -103
- package/styles/tokens/global.css +24 -9
- package/styles/tokens/semantic.css +520 -198
- package/styles/tokens/themes.css +9 -0
- package/styles/zx.css +3 -0
|
@@ -4,6 +4,7 @@ export type StatTileFormat = StatTileFormatName | ((value: number | string | nul
|
|
|
4
4
|
export type StatTileKind = 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
|
|
5
5
|
export type StatTileDeltaKind = 'positive' | 'negative' | 'neutral';
|
|
6
6
|
export type StatTileDirection = 'up' | 'down' | 'flat';
|
|
7
|
+
export type StatTileVariant = 'default' | 'plain';
|
|
7
8
|
export type StatTileDelta = {
|
|
8
9
|
/**
|
|
9
10
|
* Which way the metric moved, read from the sign alone.
|
|
@@ -105,6 +106,19 @@ export type StatTileOptions = {
|
|
|
105
106
|
* value, which stays at full text contrast whatever intent a record carries.
|
|
106
107
|
*/
|
|
107
108
|
kind?: StatTileKind;
|
|
109
|
+
/**
|
|
110
|
+
* `'default'` is a framed tile on its own surface,
|
|
111
|
+
* for a figure that stands among other content (a dashboard). `'plain'` drops the frame, the fill
|
|
112
|
+
* and the padding and sets the figure a size smaller, for a row of figures on a page (a record's
|
|
113
|
+
* amounts under its title). Reflected as `data-variant` on the root.
|
|
114
|
+
*/
|
|
115
|
+
variant?: StatTileVariant;
|
|
116
|
+
/**
|
|
117
|
+
* The figure leads its row: in a plain row it is set at the
|
|
118
|
+
* display size while the others stay smaller, on a framed tile one step above the display size.
|
|
119
|
+
* Give it to one tile per row. Reflected as `data-emphasis="true"`.
|
|
120
|
+
*/
|
|
121
|
+
emphasis?: boolean;
|
|
108
122
|
/**
|
|
109
123
|
* Destination. A tile with an href is an `<a>`.
|
|
110
124
|
*/
|
|
@@ -238,6 +252,12 @@ export declare function statDelta(delta: number | string | null | undefined, opt
|
|
|
238
252
|
locale?: string;
|
|
239
253
|
currency?: string | null;
|
|
240
254
|
}): StatTileDelta | null;
|
|
255
|
+
/**
|
|
256
|
+
* Resolves the `variant` option to one the stylesheet knows; anything else is the framed tile.
|
|
257
|
+
* @param {unknown} value Requested variant.
|
|
258
|
+
* @returns {StatTileVariant}
|
|
259
|
+
*/
|
|
260
|
+
export declare function normalizeStatTileVariant(value: unknown): StatTileVariant;
|
|
241
261
|
/**
|
|
242
262
|
* Chooses the element a tile must be, from what the tile does.
|
|
243
263
|
*
|
|
@@ -31,8 +31,9 @@ export type TagPickerOptions = {
|
|
|
31
31
|
/**
|
|
32
32
|
* Optional item tone property or reader: a categorical
|
|
33
33
|
* tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`,
|
|
34
|
-
* `violet`, `slate`).
|
|
35
|
-
*
|
|
34
|
+
* `violet`, `slate`). Every tag is built by `badge()`, so a toned tag is the Badge with that `tone`
|
|
35
|
+
* — the same shape, size, fill and ink it has in a list row or a record header; a tone wins over a
|
|
36
|
+
* colour, and unknown names are ignored.
|
|
36
37
|
*/
|
|
37
38
|
toneKey?: TagValueReader;
|
|
38
39
|
/**
|
|
@@ -155,8 +156,9 @@ export type TagPickerOptions = {
|
|
|
155
156
|
* or a token reference such as `var(--zx-color-tone-blue-fg)`.
|
|
156
157
|
* @property {TagValueReader} [toneKey='tone'] Optional item tone property or reader: a categorical
|
|
157
158
|
* tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`,
|
|
158
|
-
* `violet`, `slate`).
|
|
159
|
-
*
|
|
159
|
+
* `violet`, `slate`). Every tag is built by `badge()`, so a toned tag is the Badge with that `tone`
|
|
160
|
+
* — the same shape, size, fill and ink it has in a list row or a record header; a tone wins over a
|
|
161
|
+
* colour, and unknown names are ignored.
|
|
160
162
|
* @property {Array<TagValueReader>|null} [searchKeys=null] Fields searched by local filtering.
|
|
161
163
|
* @property {'local'|((query: string) => Promise<TagItem[]>|TagItem[])} [filter='local'] Filtering mode.
|
|
162
164
|
* @property {number} [minQuery=0] Minimum async query length.
|
|
@@ -308,7 +310,11 @@ export declare class TagPicker extends Component<TagPickerOptions> {
|
|
|
308
310
|
setReadonly(readonly: boolean): this;
|
|
309
311
|
/** Cancels pending work and restores an enhanced target. @returns {void} */
|
|
310
312
|
destroy(): void;
|
|
311
|
-
/**
|
|
313
|
+
/**
|
|
314
|
+
* Draws the selection. A tag is a Badge — `badge({ tone })` with the picker's own class — so it
|
|
315
|
+
* has one construction wherever a label appears, and only the remove button is the picker's.
|
|
316
|
+
* @returns {void}
|
|
317
|
+
*/
|
|
312
318
|
_renderTags(): void;
|
|
313
319
|
/** @returns {void} */
|
|
314
320
|
_renderOptions(): void;
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { Component } from '../../core/component.js';
|
|
2
2
|
export type TreeNode = import('./hierarchy.js').TreeNode;
|
|
3
|
+
export type RowAction = import('../../internal/row-actions.js').RowAction;
|
|
3
4
|
export type TreeOptions = {
|
|
4
5
|
/**
|
|
5
6
|
* Nested nodes.
|
|
@@ -45,6 +46,19 @@ export type TreeOptions = {
|
|
|
45
46
|
* Label renderer.
|
|
46
47
|
*/
|
|
47
48
|
renderLabel?: ((node: TreeNode) => Node | string) | null;
|
|
49
|
+
/**
|
|
50
|
+
* A row's actions:
|
|
51
|
+
* `{icon, label, onSelect(node), disabled?, danger?}` descriptors, or nodes placed as given. They
|
|
52
|
+
* rest out of sight and show while the row is pointed at, focused or selected; one or two show
|
|
53
|
+
* as icon buttons, more fold after the first into a "More actions" menu. Every descriptor is also
|
|
54
|
+
* in the row's context menu, and the focused row's actions follow it in the Tab order.
|
|
55
|
+
*/
|
|
56
|
+
rowActions?: ((node: TreeNode) => Array<RowAction | Node>) | null;
|
|
57
|
+
/**
|
|
58
|
+
* Name of a row's overflow menu; every action name
|
|
59
|
+
* is followed by the row's name ("More actions: Q3 plan").
|
|
60
|
+
*/
|
|
61
|
+
moreLabel?: string;
|
|
48
62
|
/**
|
|
49
63
|
* Lazy child loader.
|
|
50
64
|
*/
|
|
@@ -115,6 +129,7 @@ export type TreeOptions = {
|
|
|
115
129
|
}>) => void;
|
|
116
130
|
};
|
|
117
131
|
/** @typedef {import('./hierarchy.js').TreeNode} TreeNode */
|
|
132
|
+
/** @typedef {import('../../internal/row-actions.js').RowAction} RowAction */
|
|
118
133
|
/**
|
|
119
134
|
* @typedef {Object} TreeOptions
|
|
120
135
|
* @property {TreeNode[]} [items=[]] Nested nodes.
|
|
@@ -128,6 +143,13 @@ export type TreeOptions = {
|
|
|
128
143
|
* @property {unknown[]} [checked=[]] Initially checked node IDs.
|
|
129
144
|
* @property {boolean} [icons=true] Whether to render folder and file icons.
|
|
130
145
|
* @property {((node: TreeNode) => Node|string)|null} [renderLabel=null] Label renderer.
|
|
146
|
+
* @property {((node: TreeNode) => Array<RowAction|Node>)|null} [rowActions=null] A row's actions:
|
|
147
|
+
* `{icon, label, onSelect(node), disabled?, danger?}` descriptors, or nodes placed as given. They
|
|
148
|
+
* rest out of sight and show while the row is pointed at, focused or selected; one or two show
|
|
149
|
+
* as icon buttons, more fold after the first into a "More actions" menu. Every descriptor is also
|
|
150
|
+
* in the row's context menu, and the focused row's actions follow it in the Tab order.
|
|
151
|
+
* @property {string} [moreLabel='More actions'] Name of a row's overflow menu; every action name
|
|
152
|
+
* is followed by the row's name ("More actions: Q3 plan").
|
|
131
153
|
* @property {((node: TreeNode) => Promise<TreeNode[]>|TreeNode[])|null} [load=null] Lazy child loader.
|
|
132
154
|
* @property {string} [filter=''] Label substring the tree is filtered by.
|
|
133
155
|
* @property {string} [label='Tree'] Accessible name of the tree.
|
|
@@ -173,6 +195,9 @@ export declare class TreeView extends Component<TreeOptions> {
|
|
|
173
195
|
_loading: Map<unknown, Promise<boolean>>;
|
|
174
196
|
_focusId: any;
|
|
175
197
|
_filter: string;
|
|
198
|
+
/** @type {Array<import('../../internal/row-actions.js').RowActionStrip|undefined>} Per visible row. */
|
|
199
|
+
_strips: Array<import('../../internal/row-actions.js').RowActionStrip | undefined>;
|
|
200
|
+
_rowMenu: import("../context-menu/context-menu.js").ContextMenu;
|
|
176
201
|
_createdRoot: boolean;
|
|
177
202
|
_snapshot: import("../../core/dom.js").TargetSnapshot;
|
|
178
203
|
_readers: import("./hierarchy.js").NodeReaders;
|
|
@@ -313,6 +338,7 @@ export declare class TreeView extends Component<TreeOptions> {
|
|
|
313
338
|
_renderRows(): void;
|
|
314
339
|
/**
|
|
315
340
|
* @param {{node: TreeNode, id: unknown, level: number, posinset: number, setsize: number}} row Row spec.
|
|
341
|
+
* @param {number} index Visible position.
|
|
316
342
|
* @returns {HTMLElement}
|
|
317
343
|
*/
|
|
318
344
|
_renderRow(row: {
|
|
@@ -321,7 +347,7 @@ export declare class TreeView extends Component<TreeOptions> {
|
|
|
321
347
|
level: number;
|
|
322
348
|
posinset: number;
|
|
323
349
|
setsize: number;
|
|
324
|
-
}): HTMLElement;
|
|
350
|
+
}, index: number): HTMLElement;
|
|
325
351
|
/** Applies expansion, selection, check, loading, and roving-tabindex state to every row. */
|
|
326
352
|
_syncRows(): void;
|
|
327
353
|
/** @param {MouseEvent} event @returns {void} */
|
|
@@ -368,8 +394,23 @@ export declare class TreeView extends Component<TreeOptions> {
|
|
|
368
394
|
node: TreeNode;
|
|
369
395
|
id: unknown;
|
|
370
396
|
}[];
|
|
371
|
-
/**
|
|
372
|
-
|
|
397
|
+
/**
|
|
398
|
+
* The action strip an event target sits in, if any.
|
|
399
|
+
* @param {EventTarget|null} target Event target.
|
|
400
|
+
* @returns {HTMLElement|null}
|
|
401
|
+
*/
|
|
402
|
+
_stripOf(target: EventTarget | null): HTMLElement | null;
|
|
403
|
+
/**
|
|
404
|
+
* What a row's actions receive: the node in the working tree, not a filtered copy.
|
|
405
|
+
* @param {{node: TreeNode, id: unknown}|undefined} row Visible row.
|
|
406
|
+
* @returns {TreeNode|null}
|
|
407
|
+
*/
|
|
408
|
+
_subject(row: {
|
|
409
|
+
node: TreeNode;
|
|
410
|
+
id: unknown;
|
|
411
|
+
} | undefined): TreeNode | null;
|
|
412
|
+
/** @param {Element|null} element @returns {number} */
|
|
413
|
+
_rowIndex(element: Element | null): number;
|
|
373
414
|
/** @param {unknown} id @returns {Element|null} */
|
|
374
415
|
_rowElement(id: unknown): Element | null;
|
|
375
416
|
/** @param {number} index @returns {void} */
|
|
@@ -9,9 +9,30 @@
|
|
|
9
9
|
* Both renderers put `zx-icon` on the element, so component CSS can style either.
|
|
10
10
|
* @module zx/core/icons
|
|
11
11
|
*/
|
|
12
|
+
/**
|
|
13
|
+
* Icon sizes in CSS pixels, named by the role an icon plays rather than by its measure, so a call
|
|
14
|
+
* site says what a glyph is for and every glyph in that role renders at one size:
|
|
15
|
+
*
|
|
16
|
+
* icon('chevron-down', { size: ICON_SIZE.chevron });
|
|
17
|
+
*
|
|
18
|
+
* Several roles share a value; they are named apart so one can change without a sweep. At 14px and
|
|
19
|
+
* below an outline glyph is drawn with a one-pixel line, so the roles that share 14 also share a
|
|
20
|
+
* stroke weight.
|
|
21
|
+
* @type {Readonly<{control: number, chevron: number, dismiss: number, check: number, sort: number,
|
|
22
|
+
* chip: number, marker: number}>}
|
|
23
|
+
*/
|
|
24
|
+
export declare const ICON_SIZE: Readonly<{
|
|
25
|
+
control: number;
|
|
26
|
+
chevron: number;
|
|
27
|
+
dismiss: number;
|
|
28
|
+
check: number;
|
|
29
|
+
sort: number;
|
|
30
|
+
chip: number;
|
|
31
|
+
marker: number;
|
|
32
|
+
}>;
|
|
12
33
|
export type IconOptions = {
|
|
13
34
|
/**
|
|
14
|
-
* Rendered width and height.
|
|
35
|
+
* Rendered width and height; `ICON_SIZE` names one per role.
|
|
15
36
|
*/
|
|
16
37
|
size?: number | string;
|
|
17
38
|
/**
|
package/dist/types/index.d.ts
CHANGED
|
@@ -16,7 +16,7 @@ export { Http, zeyosService, parseResult } from './core/http.js';
|
|
|
16
16
|
export { setTranslator, setLanguage, getLanguage, translate, printf, defaultMessages } from './core/i18n.js';
|
|
17
17
|
export { focusTrap, rovingTabindex, typeahead } from './core/keyboard.js';
|
|
18
18
|
export { formatDate, parseDate, clampDate, isSameDay, addDays, addMonths, getWeekStart } from './core/date.js';
|
|
19
|
-
export { icon, icons, iconNames, registerIcons, configureIcons, getIconConfig, useFontAwesome, useBuiltinIcons, loadFontAwesome } from './core/icons.js';
|
|
19
|
+
export { icon, icons, iconNames, registerIcons, ICON_SIZE, configureIcons, getIconConfig, useFontAwesome, useBuiltinIcons, loadFontAwesome } from './core/icons.js';
|
|
20
20
|
export { faStyles, faFamilies, faNames, faIconClasses, parseIconSpec, kitUrl, loadFontAwesomeKit } from './core/fontawesome.js';
|
|
21
21
|
export { debounce, throttle, uid, deepMerge, isElement, clamp, toArray, groupBy, sortBy, uniqueBy, escapeRegExp } from './core/util.js';
|
|
22
22
|
export { formatNumber, formatCurrency, formatPercent, formatFileSize, formatRelativeTime } from './core/format.js';
|
|
@@ -25,6 +25,7 @@ export { toCsv, downloadBlob, copyToClipboard } from './core/export.js';
|
|
|
25
25
|
export { defineElements } from './elements/define.js';
|
|
26
26
|
export { button, buttonGroup, setButtonBusy } from './components/button/button.js';
|
|
27
27
|
export { BADGE_TONES, badge, badgeGroup } from './components/badge/badge.js';
|
|
28
|
+
export { kbd, keyLabels } from './components/kbd/kbd.js';
|
|
28
29
|
export { CheckButton } from './components/check-button/check-button.js';
|
|
29
30
|
export { emptyState } from './components/empty-state/empty-state.js';
|
|
30
31
|
export { spinner } from './components/loading/spinner.js';
|
|
@@ -35,6 +36,7 @@ export { stack, grid, aspect } from './components/layout/layout.js';
|
|
|
35
36
|
export { truncate, isTruncated } from './components/truncate/truncate.js';
|
|
36
37
|
export { copyButton } from './components/copy/copy-button.js';
|
|
37
38
|
export { CopyInput } from './components/copy/copy-input.js';
|
|
39
|
+
export { proseAnchors, sectionHref } from './components/prose/prose.js';
|
|
38
40
|
export { CodeEditor, indentSelection, editorPosition } from './components/code-editor/code-editor.js';
|
|
39
41
|
export { Toolbar } from './components/toolbar/toolbar.js';
|
|
40
42
|
export { Toggle } from './components/toggle/toggle.js';
|
|
@@ -84,7 +86,7 @@ export { Slider, stepPrecision } from './components/slider/slider.js';
|
|
|
84
86
|
export { DatePicker } from './components/date-picker/date-picker.js';
|
|
85
87
|
export { MonthPicker } from './components/date-picker/month-picker.js';
|
|
86
88
|
export { TimePicker } from './components/date-picker/time-picker.js';
|
|
87
|
-
export { Datebox, DateTimeBox } from './components/datebox/datebox.js';
|
|
89
|
+
export { Datebox, DateTimeBox, dateboxFormats } from './components/datebox/datebox.js';
|
|
88
90
|
export { DateRangePicker, clampRange, defaultDateRangePresets, normalizeRange, rangeNights, rangeStateOf } from './components/date-picker/date-range-picker.js';
|
|
89
91
|
export { DateRangeBox, formatRangeText, parseRangeText } from './components/datebox/date-range-box.js';
|
|
90
92
|
export { Timebox, splitTime, joinTime } from './components/timebox/timebox.js';
|
|
@@ -49,11 +49,14 @@ export type AppNavItem = {
|
|
|
49
49
|
*/
|
|
50
50
|
section?: boolean;
|
|
51
51
|
/**
|
|
52
|
-
*
|
|
52
|
+
* On a section, trailing controls beside its heading, such as an add button, always shown. On a
|
|
53
|
+
* destination of AppSidebar's tree, the row's actions: `{icon, label, onSelect(item), disabled?,
|
|
54
|
+
* danger?}` descriptors or nodes, revealed with the row, in its context menu, and after its
|
|
55
|
+
* control in the Tab order while it holds focus. Minimized flyouts show destinations only.
|
|
53
56
|
*/
|
|
54
57
|
actions?: Node | {
|
|
55
58
|
toElement: () => Node | null;
|
|
56
|
-
}
|
|
59
|
+
} | Array<import('./row-actions.js').RowAction | Node>;
|
|
57
60
|
};
|
|
58
61
|
export type AppRailPresenterOptions = {
|
|
59
62
|
/**
|
|
@@ -142,7 +145,11 @@ export type RailFlyout = {
|
|
|
142
145
|
* @property {AppNavItem[]} [children] Child destinations/actions.
|
|
143
146
|
* @property {boolean} [section] Makes the item a section: a quiet heading over its `children`, which
|
|
144
147
|
* render at the same level. A section is never focused, selected, or collapsed, and needs no `id`.
|
|
145
|
-
* @property {Node|{toElement: () => Node|null}} [actions]
|
|
148
|
+
* @property {Node|{toElement: () => Node|null}|Array<import('./row-actions.js').RowAction|Node>} [actions]
|
|
149
|
+
* On a section, trailing controls beside its heading, such as an add button, always shown. On a
|
|
150
|
+
* destination of AppSidebar's tree, the row's actions: `{icon, label, onSelect(item), disabled?,
|
|
151
|
+
* danger?}` descriptors or nodes, revealed with the row, in its context menu, and after its
|
|
152
|
+
* control in the Tab order while it holds focus. Minimized flyouts show destinations only.
|
|
146
153
|
*/
|
|
147
154
|
/**
|
|
148
155
|
* @typedef {Object} AppRailPresenterOptions
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
import { ContextMenu } from '../components/context-menu/context-menu.js';
|
|
2
|
+
import { MenuButton } from '../components/menu-button/menu-button.js';
|
|
3
|
+
export type RowAction = {
|
|
4
|
+
/**
|
|
5
|
+
* What the action does; the tooltip, and with the row's name its
|
|
6
|
+
* accessible name.
|
|
7
|
+
*/
|
|
8
|
+
label: string;
|
|
9
|
+
/**
|
|
10
|
+
* Icon name. Inline actions show only the icon.
|
|
11
|
+
*/
|
|
12
|
+
icon?: string;
|
|
13
|
+
/**
|
|
14
|
+
* Runs the action for the row's node or item.
|
|
15
|
+
*/
|
|
16
|
+
onSelect: (subject: any) => void;
|
|
17
|
+
/**
|
|
18
|
+
* Whether the action is unavailable on this row.
|
|
19
|
+
*/
|
|
20
|
+
disabled?: boolean;
|
|
21
|
+
/**
|
|
22
|
+
* Whether the action destroys something; menus colour it.
|
|
23
|
+
*/
|
|
24
|
+
danger?: boolean;
|
|
25
|
+
};
|
|
26
|
+
export type RowActionEntry = RowAction | Node;
|
|
27
|
+
export type RowActionStrip = {
|
|
28
|
+
/**
|
|
29
|
+
* The strip, marked `data-zx-reveal`.
|
|
30
|
+
*/
|
|
31
|
+
element: HTMLElement;
|
|
32
|
+
/**
|
|
33
|
+
* Every descriptor of the row, inline and folded, in order — what
|
|
34
|
+
* the row's context menu lists. Inline buttons and menu items carry indexes into it.
|
|
35
|
+
*/
|
|
36
|
+
actions: RowAction[];
|
|
37
|
+
/**
|
|
38
|
+
* The overflow menu, when actions were folded.
|
|
39
|
+
*/
|
|
40
|
+
menu: MenuButton | null;
|
|
41
|
+
/**
|
|
42
|
+
* Destroys the overflow menu.
|
|
43
|
+
*/
|
|
44
|
+
destroy: () => void;
|
|
45
|
+
};
|
|
46
|
+
/**
|
|
47
|
+
* One action a row offers: a repeated, secondary command such as "Add sub-page" or "Rename".
|
|
48
|
+
* @typedef {Object} RowAction
|
|
49
|
+
* @property {string} label What the action does; the tooltip, and with the row's name its
|
|
50
|
+
* accessible name.
|
|
51
|
+
* @property {string} [icon] Icon name. Inline actions show only the icon.
|
|
52
|
+
* @property {(subject: any) => void} onSelect Runs the action for the row's node or item.
|
|
53
|
+
* @property {boolean} [disabled=false] Whether the action is unavailable on this row.
|
|
54
|
+
* @property {boolean} [danger=false] Whether the action destroys something; menus colour it.
|
|
55
|
+
*/
|
|
56
|
+
/** @typedef {RowAction|Node} RowActionEntry */
|
|
57
|
+
/**
|
|
58
|
+
* The controls built for one row.
|
|
59
|
+
* @typedef {Object} RowActionStrip
|
|
60
|
+
* @property {HTMLElement} element The strip, marked `data-zx-reveal`.
|
|
61
|
+
* @property {RowAction[]} actions Every descriptor of the row, inline and folded, in order — what
|
|
62
|
+
* the row's context menu lists. Inline buttons and menu items carry indexes into it.
|
|
63
|
+
* @property {MenuButton|null} menu The overflow menu, when actions were folded.
|
|
64
|
+
* @property {() => void} destroy Destroys the overflow menu.
|
|
65
|
+
*/
|
|
66
|
+
/** A row never carries more controls than this before the rest fold into a menu. */
|
|
67
|
+
export declare const ROW_ACTION_LIMIT = 2;
|
|
68
|
+
/**
|
|
69
|
+
* Whether an entry is a control of the application's own, placed in the row as given.
|
|
70
|
+
* @param {unknown} entry Candidate entry.
|
|
71
|
+
* @returns {entry is Node}
|
|
72
|
+
*/
|
|
73
|
+
export declare function isRowActionNode(entry: unknown): entry is Node;
|
|
74
|
+
/**
|
|
75
|
+
* Whether an entry is a usable action descriptor: a label and something to run.
|
|
76
|
+
* @param {unknown} entry Candidate entry.
|
|
77
|
+
* @returns {entry is RowAction}
|
|
78
|
+
*/
|
|
79
|
+
export declare function isRowAction(entry: unknown): entry is RowAction;
|
|
80
|
+
/**
|
|
81
|
+
* Decides which entries a row shows and which fold into its overflow menu. One or two entries all
|
|
82
|
+
* show; with more, the first shows and the descriptors after it fold, so a row carries at most two
|
|
83
|
+
* controls of its own. A node is the application's control and never folds.
|
|
84
|
+
* @param {unknown} entries What `rowActions` or `actions` returned.
|
|
85
|
+
* @returns {{inline: RowActionEntry[], overflow: RowAction[]}}
|
|
86
|
+
*/
|
|
87
|
+
export declare function planRowActions(entries: unknown): {
|
|
88
|
+
inline: RowActionEntry[];
|
|
89
|
+
overflow: RowAction[];
|
|
90
|
+
};
|
|
91
|
+
/**
|
|
92
|
+
* An action control's accessible name, which says which row it acts on: on a list of rows every
|
|
93
|
+
* "Rename" button is otherwise the same button. The action comes first, so a screen reader's
|
|
94
|
+
* list of buttons still sorts by what they do.
|
|
95
|
+
* @param {string} action Action label.
|
|
96
|
+
* @param {string} name The row's name.
|
|
97
|
+
* @returns {string}
|
|
98
|
+
*/
|
|
99
|
+
export declare function rowActionLabel(action: string, name: string): string;
|
|
100
|
+
/**
|
|
101
|
+
* Menu items for descriptors, valued by their index in `actions`.
|
|
102
|
+
* @param {RowAction[]} actions The row's descriptors.
|
|
103
|
+
* @param {RowAction[]} [only=actions] The descriptors to list.
|
|
104
|
+
* @returns {Array<{label: string, icon?: string, value: number, danger: boolean, disabled: boolean}>}
|
|
105
|
+
*/
|
|
106
|
+
export declare function menuEntries(actions: RowAction[], only?: RowAction[]): Array<{
|
|
107
|
+
label: string;
|
|
108
|
+
icon?: string;
|
|
109
|
+
value: number;
|
|
110
|
+
danger: boolean;
|
|
111
|
+
disabled: boolean;
|
|
112
|
+
}>;
|
|
113
|
+
/**
|
|
114
|
+
* Builds a row's action strip: an icon button per inline descriptor, the given nodes, and the
|
|
115
|
+
* overflow menu. Every control starts outside the Tab order; the host component makes the strip
|
|
116
|
+
* of the row holding focus tabbable. Inline buttons carry `data-row-action`, an index into
|
|
117
|
+
* `actions`, so the host runs them from its own delegated click listener.
|
|
118
|
+
* @param {unknown} entries Row actions.
|
|
119
|
+
* @param {{block: string, name: string, moreLabel?: string, run: (action: RowAction) => void}} options
|
|
120
|
+
* `block` names the parts (`zx-<block>__actions`, `zx-<block>__action`); `name` is the row's
|
|
121
|
+
* name; `moreLabel` names the overflow menu ("More actions"); `run` is called with a descriptor
|
|
122
|
+
* chosen from the overflow menu.
|
|
123
|
+
* @returns {RowActionStrip|null} Null when nothing usable was given.
|
|
124
|
+
*/
|
|
125
|
+
export declare function renderRowActions(entries: unknown, { block, name, moreLabel, run }: {
|
|
126
|
+
block: string;
|
|
127
|
+
name: string;
|
|
128
|
+
moreLabel?: string;
|
|
129
|
+
run: (action: RowAction) => void;
|
|
130
|
+
}): RowActionStrip | null;
|
|
131
|
+
/**
|
|
132
|
+
* Puts every control in a strip in or out of the Tab order.
|
|
133
|
+
* @param {Element|null|undefined} element A strip.
|
|
134
|
+
* @param {boolean} tabbable Whether its controls are Tab stops.
|
|
135
|
+
* @returns {void}
|
|
136
|
+
*/
|
|
137
|
+
export declare function setRowActionsTabbable(element: Element | null | undefined, tabbable: boolean): void;
|
|
138
|
+
/**
|
|
139
|
+
* The context menu of a component's rows: every descriptor of the row it opens on. Choosing an
|
|
140
|
+
* item closes the menu, which returns focus to the row, and only then runs the action — so a
|
|
141
|
+
* dialog the action opens records the row as the place to return to.
|
|
142
|
+
* @param {Element} target The element holding the rows.
|
|
143
|
+
* @param {string} selector The rows.
|
|
144
|
+
* @param {(row: Element) => {actions: RowAction[], subject: unknown}|null} resolve The row's
|
|
145
|
+
* descriptors and what their `onSelect` receives.
|
|
146
|
+
* @returns {ContextMenu}
|
|
147
|
+
*/
|
|
148
|
+
export declare function rowActionMenu(target: Element, selector: string, resolve: (row: Element) => {
|
|
149
|
+
actions: RowAction[];
|
|
150
|
+
subject: unknown;
|
|
151
|
+
} | null): ContextMenu;
|