@zeyos/zx 5.7.0 → 5.7.1

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/docs/api.json CHANGED
@@ -2934,6 +2934,18 @@
2934
2934
  "default": "false",
2935
2935
  "description": "Fallback initial checked state."
2936
2936
  },
2937
+ {
2938
+ "name": "label",
2939
+ "type": "string|null",
2940
+ "default": "null",
2941
+ "description": "Heading text, which is also the group's accessible name; null uses the `checklist.label` message."
2942
+ },
2943
+ {
2944
+ "name": "disabled",
2945
+ "type": "boolean",
2946
+ "default": "false",
2947
+ "description": "Whether the search field and every checkbox are disabled."
2948
+ },
2937
2949
  {
2938
2950
  "name": "hideLabel",
2939
2951
  "type": "boolean",
@@ -2972,6 +2984,30 @@
2972
2984
  "returns": "this",
2973
2985
  "description": "Replaces items and derives checked state from `checkedKey` and `defaultChecked`."
2974
2986
  },
2987
+ {
2988
+ "name": "setLabel",
2989
+ "signature": "setLabel(label)",
2990
+ "returns": "this",
2991
+ "description": "Replaces the heading text, which is also the group's accessible name."
2992
+ },
2993
+ {
2994
+ "name": "enable",
2995
+ "signature": "enable()",
2996
+ "returns": "this",
2997
+ "description": "Enables the search field and the checkboxes."
2998
+ },
2999
+ {
3000
+ "name": "disable",
3001
+ "signature": "disable()",
3002
+ "returns": "this",
3003
+ "description": "Disables the search field and the checkboxes; values can still be set programmatically."
3004
+ },
3005
+ {
3006
+ "name": "isDisabled",
3007
+ "signature": "isDisabled()",
3008
+ "returns": "boolean",
3009
+ "description": "Whether the checklist is disabled."
3010
+ },
2975
3011
  {
2976
3012
  "name": "getValues",
2977
3013
  "signature": "getValues()",
@@ -4357,7 +4393,7 @@
4357
4393
  },
4358
4394
  {
4359
4395
  "name": "cancel",
4360
- "payload": "Record<string, never>",
4396
+ "payload": "import('../modal/modal.js').ModalCancelDetail",
4361
4397
  "description": "Cancel event listener."
4362
4398
  }
4363
4399
  ],
@@ -7865,7 +7901,7 @@
7865
7901
  "name": "lightDismiss",
7866
7902
  "type": "boolean",
7867
7903
  "default": "false",
7868
- "description": "Whether a backdrop click closes the modal."
7904
+ "description": "Whether a backdrop click closes the modal. Like every dismissal by the reader, it raises a preventable `cancel` first."
7869
7905
  },
7870
7906
  {
7871
7907
  "name": "destroyOnClose",
@@ -7893,7 +7929,7 @@
7893
7929
  },
7894
7930
  {
7895
7931
  "name": "cancel",
7896
- "payload": "Record<string, never>",
7932
+ "payload": "{reason}",
7897
7933
  "description": "Cancel event listener."
7898
7934
  }
7899
7935
  ],
@@ -8371,6 +8407,12 @@
8371
8407
  "default": "null",
8372
8408
  "description": "Decimal places; derived from `step` when null."
8373
8409
  },
8410
+ {
8411
+ "name": "snap",
8412
+ "type": "boolean",
8413
+ "default": "true",
8414
+ "description": "Whether a typed or assigned value is moved onto the `step` grid. With `false` the value is kept exactly as entered — `step` is then only the increment of the buttons and arrow keys, and decimals are rounded only to an explicit `precision`. `min` and `max` still apply. Use it for values that are not multiples of anything: an identifier, a seed, a measurement."
8415
+ },
8374
8416
  {
8375
8417
  "name": "wrap",
8376
8418
  "type": "boolean",
@@ -8461,7 +8503,7 @@
8461
8503
  "name": "set",
8462
8504
  "signature": "set(next, [options])",
8463
8505
  "returns": "this",
8464
- "description": "Sets the value, snapping it to `step` and clamping it into `[min, max]`."
8506
+ "description": "Sets the value, clamping it into `[min, max]` and — unless `snap` is off — moving it onto the `step` grid."
8465
8507
  },
8466
8508
  {
8467
8509
  "name": "stepUp",
@@ -10597,7 +10639,7 @@
10597
10639
  },
10598
10640
  {
10599
10641
  "name": "cancel",
10600
- "payload": "Record<string, never>",
10642
+ "payload": "import('../modal/modal.js').ModalCancelDetail",
10601
10643
  "description": "Cancel event listener."
10602
10644
  },
10603
10645
  {
package/docs/llms.md CHANGED
@@ -768,7 +768,9 @@ accept.
768
768
  `--zx-color-accent-solid*` roles, so in dark it keeps the deep stop with white ink rather than a
769
769
  bright slab. A `ghost` button's icon is drawn in `--zx-color-text-subtle` until hovered. A button
770
770
  with `aria-pressed="true"` (a Toolbar item with `active`, a view toggle) is a mode, not a pick:
771
- it takes the neutral `--zx-color-bg-current` fill and the text colour, never the accent.
771
+ it stays neutral, never the accent, and is drawn with a stronger fill plus a frame in
772
+ `--zx-color-text-subtle` (3:1 against its neighbours in both themes), so a pressed segment of a
773
+ `buttonGroup` is told apart without relying on the fill alone.
772
774
  <!-- /doc -->
773
775
 
774
776
  <!-- doc:badge -->
@@ -827,8 +829,8 @@ a `MenuButton`, where choosing one activates the original control.
827
829
  in visual order under `dir="rtl"`; Home/End jump to the first and last control. A text field, select,
828
830
  or contenteditable item keeps its own keys: Home/End and the arrows move its caret, and an arrow
829
831
  moves on to the neighbouring control only once the caret is at that edge of the text.
830
- - **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes the neutral
831
- `--zx-color-bg-current` fill, never the accent.
832
+ - **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes Button's
833
+ neutral pressed fill and frame, never the accent.
832
834
  <!-- /doc -->
833
835
 
834
836
  <!-- doc:empty-state -->
@@ -1430,12 +1432,15 @@ from `Select`, with its themed popover and keyboard behavior.
1430
1432
  Searchable multi-check list with optional async loading.
1431
1433
 
1432
1434
  - **Options** — `items`, `valueKey: 'ID'`, `labelKey: 'name'`, `checkedKey: 'on'`, `search: true`,
1433
- `height: 280`, `defaultChecked: false`, `hideLabel: false` (leaves out the heading; the group
1434
- keeps its text as `aria-label`), `load: async ()=>items`.
1435
+ `height: 280`, `defaultChecked: false`, `label: null` (heading text and the group's accessible
1436
+ name; null uses the `checklist.label` message), `disabled: false`, `hideLabel: false` (leaves out
1437
+ the heading; the group keeps its text as `aria-label`), `load: async ()=>items`.
1435
1438
  - **In a Field** — field type `checklist` draws no heading of its own: the field's label names the
1436
1439
  group (`aria-labelledby`).
1437
1440
  - **Methods** — `setItems()`, `getValues()`, `setValues(ids)`, `checkAll()`/`uncheckAll()`,
1438
- `search(query)`, `reload()`.
1441
+ `search(query)`, `reload()`, `setLabel(text)`, `enable()`/`disable()`, `isDisabled()`. Disabled,
1442
+ the search field and every checkbox are disabled (`aria-disabled="true"` on the group) through
1443
+ searches, `setItems()` and reloads; values can still be set from code.
1439
1444
  - **Events** — `change {values}`, `loaded`.
1440
1445
  <!-- /doc -->
1441
1446
 
@@ -1447,7 +1452,8 @@ buttons are `tabindex="-1"`/`aria-hidden` pointer affordances — the input itse
1447
1452
  Field type: `number`.
1448
1453
 
1449
1454
  - **Options** — `value` (number|null), `min`, `max`, `step: 1`, `largeStep: 10` (PageUp/PageDown
1450
- multiplier), `precision` (decimals; derived from `step` when null), `wrap: false` (stepping past
1455
+ multiplier), `precision` (decimals; derived from `step` when null), `snap: true` (see
1456
+ **Snapping**), `wrap: false` (stepping past
1451
1457
  a bound jumps to the other one), `placeholder`, `unit` (suffix rendered inside the control),
1452
1458
  `group: false` (thousands separators while idle), `locale`, `disabled`, `readonly`, `required`,
1453
1459
  `name`.
@@ -1455,6 +1461,11 @@ Field type: `number`.
1455
1461
  the range; `''`/null clear it), `stepUp(n)`, `stepDown(n)`, `setRange(min, max)`,
1456
1462
  `setReadonly()`, `reset()`, `focus()`, `getInput()`, `enable()`/`disable()`.
1457
1463
  - **Events** — `change {value}` (committed), `input {value}` (per keystroke, possibly unsnapped).
1464
+ - **Snapping** — by default a typed or assigned value is moved onto the `step` grid (step 2 turns
1465
+ 123 into 124) and rounded to the step's decimals. That suits quantities; it is wrong for a value
1466
+ that is not a multiple of anything — an identifier, a seed, a measurement. `snap: false` keeps
1467
+ the value exactly as entered: `step` is then only what the buttons and arrow keys add, decimals
1468
+ are rounded only to an explicit `precision`, and `min`/`max` still clamp.
1458
1469
  - **Keyboard** — ↑/↓ one step, PageUp/PageDown `largeStep` steps, Home/End jump to `min`/`max` when
1459
1470
  set (otherwise they keep their caret meaning), Enter commits, wheel steps while focused.
1460
1471
  - **Also exported** — `parseNumber(raw)` (accepts `.` and `,` as the decimal separator, ignores
@@ -1688,7 +1699,14 @@ panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus retur
1688
1699
  scope is resolved again on every `open()`; a `scope` element not yet in the document leaves the
1689
1700
  dialog detached until then, rather than parking it on `<body>` outside the theme.
1690
1701
  - **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
1691
- - **Events** — `open`, `close {result}`, `cancel` (Esc; preventable with `event.preventDefault()`).
1702
+ - **Events** — `open`, `close {result}`, `cancel {reason}`.
1703
+ - **Dismissal** — everything the reader does to dismiss an overlay raises `cancel` first, with
1704
+ `reason` `'escape'`, `'close-button'` (Dialog/Sheet header ✕), `'button'` (a footer button whose
1705
+ action is `'cancel'`), `'backdrop'` (`lightDismiss`), `'outside'` or `'drag'` (Sheet).
1706
+ `event.preventDefault()` keeps it open, which is the place for an "unsaved changes" check.
1707
+ A programmatic `close()` raises no `cancel`. Escape is handled by Zx rather than by the browser's
1708
+ close request, so preventing it holds however often the key is pressed; a handler that calls
1709
+ `preventDefault()` on the Escape keydown (a popup inside the dialog, your own) keeps the key.
1692
1710
  <!-- /doc -->
1693
1711
 
1694
1712
  <!-- doc:dialog -->
@@ -1730,7 +1748,8 @@ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
1730
1748
  - **Methods** — `open()`, `close(result?)`, `setSide(side)`, `getSide()`, `setSize(size)`,
1731
1749
  `isModal()`, `isDocked()`, `isOpen()`, `getSize()`, `snapTo(target)`, plus Dialog's `setTitle()`, `setContent()`,
1732
1750
  `setButtons()`, `addView()`, `showView()`.
1733
- - **Events** — `open`, `close {result}`, `cancel` (preventable with `event.preventDefault()`),
1751
+ - **Events** — `open`, `close {result}`, `cancel {reason}` (preventable; raised by Escape, the ✕,
1752
+ a backdrop click or outside press, and a dismissing drag — see Modal's **Dismissal**),
1734
1753
  `resize {size, ratio}`, `dockchange {docked, dock}`.
1735
1754
  - **Docked** — a sheet has two lives, and it does not choose between them: `Dock.adopt(sheet)`
1736
1755
  makes it a track in that dock's flow instead of an overlay, and the dock then owns its side,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zeyos/zx",
3
- "version": "5.7.0",
3
+ "version": "5.7.1",
4
4
  "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -108,24 +108,32 @@
108
108
  color: var(--zx-color-text);
109
109
  }
110
110
 
111
- /* A pressed toggle (`aria-pressed="true"`, e.g. a Toolbar item with `active`) is a mode you are
112
- in, not a pick: the neutral current fill and the full text colour, never the accent. */
111
+ /* A pressed toggle (`aria-pressed="true"`, e.g. a Toolbar item with `active`, a segment of a
112
+ button group) is a mode you are in, not a pick: neutral, never the accent. Two cues carry it,
113
+ because a few percent of fill alone disappears beside an unpressed neighbour, in dark most of
114
+ all: a fill clearly stronger than hover, and a frame in the subtle ink, which holds 3:1 on every
115
+ surface. The raised highlight goes, so the control reads as pushed in. A ghost button gains the
116
+ frame too; it is the only edge its pressed state has. */
113
117
  .zx-btn[aria-pressed="true"] {
114
- border-color: var(--zx-color-border-control);
115
- background: var(--zx-color-bg-current);
118
+ border-color: var(--zx-color-text-subtle);
119
+ background: color-mix(in srgb, var(--zx-color-text) 14%, transparent);
116
120
  color: var(--zx-color-text);
117
- }
118
-
119
- .zx-btn[data-kind="ghost"][aria-pressed="true"] {
120
- border-color: transparent;
121
+ box-shadow: none;
121
122
  }
122
123
 
123
124
  .zx-btn[aria-pressed="true"] > .zx-icon {
124
125
  color: var(--zx-color-text);
125
126
  }
126
127
 
127
- .zx-btn[aria-pressed="true"]:hover:not(:disabled) {
128
- background: var(--zx-color-bg-current);
128
+ .zx-btn[aria-pressed="true"]:hover:not(:disabled),
129
+ .zx-btn[aria-pressed="true"]:active:not(:disabled),
130
+ .zx-btn[data-kind="ghost"][aria-pressed="true"][aria-expanded="true"]:not(:disabled) {
131
+ border-color: var(--zx-color-text-subtle);
132
+ background: color-mix(in srgb, var(--zx-color-text) 14%, transparent);
133
+ }
134
+
135
+ .zx-btn[aria-pressed="true"]:focus-visible {
136
+ box-shadow: var(--zx-focus-ring);
129
137
  }
130
138
 
131
139
  .zx-btn[data-size="sm"] {
@@ -180,10 +188,15 @@
180
188
  border-end-end-radius: 0;
181
189
  }
182
190
 
183
- .zx-btn-group > .zx-btn:focus-visible {
191
+ /* Neighbours overlap by their border; the pressed segment's frame stays on top of both. */
192
+ .zx-btn-group > .zx-btn[aria-pressed="true"] {
184
193
  z-index: 1;
185
194
  }
186
195
 
196
+ .zx-btn-group > .zx-btn:focus-visible {
197
+ z-index: 2;
198
+ }
199
+
187
200
  @media (prefers-reduced-transparency: reduce) {
188
201
  .zx-btn {
189
202
  background: var(--zx-color-bg-control);
@@ -41,7 +41,7 @@
41
41
  line-height: 1.35;
42
42
  }
43
43
 
44
- .zx-checklist__item:hover {
44
+ .zx-checklist:not([aria-disabled="true"]) .zx-checklist__item:hover {
45
45
  background: var(--zx-color-bg-hover);
46
46
  }
47
47
 
@@ -70,3 +70,11 @@
70
70
  .zx-checklist[data-state="loading"] .zx-checklist__list {
71
71
  color: var(--zx-color-text-muted);
72
72
  }
73
+
74
+ .zx-checklist[aria-disabled="true"] {
75
+ opacity: var(--zx-control-disabled-opacity);
76
+ }
77
+
78
+ .zx-checklist[aria-disabled="true"] .zx-checklist__item {
79
+ cursor: default;
80
+ }
@@ -13,6 +13,9 @@ import { matchItems } from '../select/filter.js';
13
13
  * @property {boolean} [search=true] Whether the search field is shown.
14
14
  * @property {number} [height=280] Maximum list height in pixels.
15
15
  * @property {boolean} [defaultChecked=false] Fallback initial checked state.
16
+ * @property {string|null} [label=null] Heading text, which is also the group's accessible name;
17
+ * null uses the `checklist.label` message.
18
+ * @property {boolean} [disabled=false] Whether the search field and every checkbox are disabled.
16
19
  * @property {boolean} [hideLabel=false] Whether the heading is left out. The group keeps the
17
20
  * heading text as its accessible name (`aria-label`); a Field labelling the checklist names it
18
21
  * instead, which is why the `checklist` field type sets this.
@@ -43,6 +46,8 @@ export class Checklist extends Component {
43
46
  search: true,
44
47
  height: 280,
45
48
  defaultChecked: false,
49
+ label: null,
50
+ disabled: false,
46
51
  hideLabel: false,
47
52
  load: null
48
53
  };
@@ -57,13 +62,15 @@ export class Checklist extends Component {
57
62
  const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
58
63
  this.el = root;
59
64
  if (!this._createdRoot) this._originalChildren = Array.from(root.childNodes);
60
- for (const name of ['role', 'aria-label', 'aria-labelledby', 'data-state']) {
65
+ this._disabled = Boolean(this.options.disabled);
66
+ for (const name of ['role', 'aria-label', 'aria-labelledby', 'aria-disabled', 'data-state']) {
61
67
  this._originalAttributes.set(name, root.getAttribute(name));
62
68
  }
63
69
 
64
- const labelText = this._message('checklist.label', 'Checklist');
70
+ const labelText = this._labelText(this.options.label);
65
71
  const labelId = uid('zx-checklist-label');
66
72
  const title = this.options.hideLabel ? null : h('div', {
73
+ ref: 'label',
67
74
  class: 'zx-checklist__label',
68
75
  id: labelId
69
76
  }, labelText);
@@ -74,7 +81,8 @@ export class Checklist extends Component {
74
81
  autocomplete: 'off',
75
82
  placeholder: this._message('checklist.search', 'Search'),
76
83
  ariaLabel: this._message('checklist.search', 'Search checklist'),
77
- hidden: !this.options.search
84
+ hidden: !this.options.search,
85
+ disabled: this._disabled
78
86
  });
79
87
  const list = h('div', {
80
88
  ref: 'list',
@@ -99,6 +107,7 @@ export class Checklist extends Component {
99
107
  });
100
108
 
101
109
  this._replaceItems(this.options.items);
110
+ this._syncDisabled();
102
111
  if (typeof this.options.load === 'function') {
103
112
  queueMicrotask(() => {
104
113
  if (this._active) void this.reload().catch(() => {});
@@ -117,6 +126,37 @@ export class Checklist extends Component {
117
126
  return this;
118
127
  }
119
128
 
129
+ /**
130
+ * Replaces the heading text, which is also the group's accessible name.
131
+ * @param {string|null} label New label; null restores the `checklist.label` message.
132
+ * @returns {this}
133
+ */
134
+ setLabel(label) {
135
+ const text = this._labelText(label);
136
+ if (this.refs.label) this.refs.label.textContent = text;
137
+ else this.el.setAttribute('aria-label', text);
138
+ return this;
139
+ }
140
+
141
+ /** Enables the search field and the checkboxes. @returns {this} */
142
+ enable() {
143
+ this._disabled = false;
144
+ this._syncDisabled();
145
+ return this;
146
+ }
147
+
148
+ /** Disables the search field and the checkboxes; values can still be set programmatically. @returns {this} */
149
+ disable() {
150
+ this._disabled = true;
151
+ this._syncDisabled();
152
+ return this;
153
+ }
154
+
155
+ /** Whether the checklist is disabled. @returns {boolean} */
156
+ isDisabled() {
157
+ return this._disabled;
158
+ }
159
+
120
160
  /** Returns checked IDs in item order. @returns {unknown[]} */
121
161
  getValues() {
122
162
  return this._items
@@ -223,6 +263,7 @@ export class Checklist extends Component {
223
263
  type: 'checkbox',
224
264
  id: checkboxId,
225
265
  checked: this._checked.has(this._itemValue(item)),
266
+ disabled: this._disabled,
226
267
  dataset: { index }
227
268
  });
228
269
  return h('label', {
@@ -239,6 +280,21 @@ export class Checklist extends Component {
239
280
  this.refs.list.replaceChildren(...rows);
240
281
  }
241
282
 
283
+ /** @returns {void} */
284
+ _syncDisabled() {
285
+ if (this._disabled) this.el.setAttribute('aria-disabled', 'true');
286
+ else this.el.removeAttribute('aria-disabled');
287
+ /** @type {HTMLInputElement} */ (this.refs.search).disabled = this._disabled;
288
+ for (const input of this.refs.list.querySelectorAll('input[type="checkbox"]')) {
289
+ /** @type {HTMLInputElement} */ (input).disabled = this._disabled;
290
+ }
291
+ }
292
+
293
+ /** @param {string|null|undefined} label @returns {string} */
294
+ _labelText(label) {
295
+ return label == null || label === '' ? this._message('checklist.label', 'Checklist') : String(label);
296
+ }
297
+
242
298
  /** @param {Set<unknown>} next @returns {void} */
243
299
  _replaceChecked(next) {
244
300
  if (setsEqual(this._checked, next)) return;
@@ -10,19 +10,11 @@ export function registerChecklistFieldAdapter() {
10
10
  // The Field's label names the list (`aria-labelledby`), so the checklist draws no heading of
11
11
  // its own under it.
12
12
  const checklist = field.own(new Checklist(null, { hideLabel: true, ...(options.props ?? {}) }));
13
- let disabled = false;
14
13
  let setting = false;
15
- const syncDisabled = () => {
16
- checklist.el.setAttribute('aria-disabled', String(disabled));
17
- for (const control of checklist.el.querySelectorAll('input, button, select, textarea')) {
18
- control.disabled = disabled;
19
- }
20
- };
21
14
  field.listen(checklist.el, 'change', (event) => event.stopImmediatePropagation());
22
15
  checklist.on('change', (event) => {
23
16
  if (!setting) field.emit('change', { value: event.detail.values });
24
17
  });
25
- checklist.on('loaded', syncDisabled);
26
18
  return {
27
19
  el: checklist.el,
28
20
  get: () => checklist.getValues(),
@@ -33,15 +25,14 @@ export function registerChecklistFieldAdapter() {
33
25
  } finally {
34
26
  setting = false;
35
27
  }
36
- syncDisabled();
37
28
  },
38
29
  focus: () => {
39
30
  const search = checklist.el.querySelector('.zx-checklist__search:not([hidden]):not([disabled])');
40
31
  (search ?? checklist.el.querySelector('input[type="checkbox"]:not([disabled])'))?.focus();
41
32
  },
42
33
  setDisabled: (value) => {
43
- disabled = Boolean(value);
44
- syncDisabled();
34
+ if (value) checklist.disable();
35
+ else checklist.enable();
45
36
  }
46
37
  };
47
38
  });
@@ -24,7 +24,7 @@ import { button } from '../button/button.js';
24
24
  * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
25
25
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
26
26
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
27
- * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
27
+ * @property {(event: CustomEvent<import('../modal/modal.js').ModalCancelDetail>) => void} [oncancel] Cancel event listener.
28
28
  */
29
29
  /**
30
30
  * @typedef {Object} DialogViewOptions
@@ -107,7 +107,7 @@ export class Dialog extends Modal {
107
107
  this.#renderButtons(this.#baseButtons);
108
108
  this.refs.close.hidden = !this.options.closable;
109
109
 
110
- this.listen(this.refs.close, 'click', () => this.close());
110
+ this.listen(this.refs.close, 'click', () => this._requestDismiss('close-button'));
111
111
  this.listen(this.refs.footer, 'click', (event) => {
112
112
  const button = event.target.closest?.('[data-dialog-button]');
113
113
  if (!button || !this.refs.footer.contains(button)) return;
@@ -473,8 +473,7 @@ export class Dialog extends Modal {
473
473
  if (action === 'close') {
474
474
  this.close();
475
475
  } else if (action === 'cancel') {
476
- const event = this.emit('cancel');
477
- if (!event.defaultPrevented) this.close();
476
+ this._requestDismiss('button');
478
477
  } else if (typeof action === 'function') {
479
478
  action(this);
480
479
  }
@@ -17,13 +17,21 @@ const FOCUSABLE_SELECTOR = [
17
17
  * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Modal content.
18
18
  * @property {string|number} [width='auto'] CSS width, or a pixel width when numeric.
19
19
  * @property {boolean} [closable=true] Whether Escape may close the modal.
20
- * @property {boolean} [lightDismiss=false] Whether a backdrop click closes the modal.
20
+ * @property {boolean} [lightDismiss=false] Whether a backdrop click closes the modal. Like every
21
+ * dismissal by the reader, it raises a preventable `cancel` first.
21
22
  * @property {boolean} [destroyOnClose=false] Whether to destroy the modal after it closes.
22
23
  * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
23
24
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
24
25
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
25
- * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
26
+ * @property {(event: CustomEvent<ModalCancelDetail>) => void} [oncancel] Cancel event listener.
26
27
  */
28
+ /**
29
+ * What the reader did to ask for dismissal: pressed Escape, used a header close button, chose a
30
+ * footer button whose action is `'cancel'`, clicked the backdrop, pressed outside a non-modal
31
+ * overlay, or dragged it away.
32
+ * @typedef {'escape'|'close-button'|'button'|'backdrop'|'outside'|'drag'} ModalDismissReason
33
+ */
34
+ /** @typedef {{reason: ModalDismissReason}} ModalCancelDetail */
27
35
 
28
36
  /**
29
37
  * Thin native-dialog overlay with lifecycle-safe content and dismissal behavior.
@@ -76,8 +84,35 @@ export class Modal extends Component {
76
84
  this.#setWidth(this.options.width);
77
85
  replaceContent(this.refs.content, this.options.content);
78
86
 
87
+ /*
88
+ * Escape on a modal presentation is answered here rather than by the browser's close request.
89
+ * A browser stops honouring a prevented `cancel` once close requests repeat without other
90
+ * interaction, which would let a third Escape through an "unsaved changes" guard; a cancelled
91
+ * keydown never becomes a close request at all. The listener sits on `window`, the last stop
92
+ * of the bubble, so everything that may use the key first has had it: a popup inside the
93
+ * dialog, the overlay stack, an application's own `document` handler. Whatever they prevented
94
+ * is not ours. Only the topmost modal answers, so a dialog opened above this one — the
95
+ * library's or the application's — keeps its key.
96
+ */
97
+ if (typeof window !== 'undefined') this.listen(window, 'keydown', (event) => {
98
+ const key = /** @type {KeyboardEvent} */ (event);
99
+ if (key.key !== 'Escape' || key.defaultPrevented || key.isComposing) return;
100
+ if (!this.isOpen() || !this.el.matches(':modal')) return;
101
+ const modals = document.querySelectorAll('dialog:modal');
102
+ if (modals[modals.length - 1] !== this.el) return;
103
+ // Reported before the key is cancelled: a `cancel` listener may ask whether something else
104
+ // had already claimed this keydown, and our own claim must not answer for it.
105
+ if (this.options.closable) this._requestDismiss('escape');
106
+ else this.emit('cancel', { reason: 'escape' });
107
+ key.preventDefault();
108
+ });
109
+ /*
110
+ * The platform's own close request, for what is not a keydown this class saw: a back gesture,
111
+ * an Escape pressed mid-composition, an assistive-technology dismiss. The browser may make
112
+ * such a request non-cancelable, and then the dialog closes whatever a listener says.
113
+ */
79
114
  this.listen(this.el, 'cancel', (event) => {
80
- const cancelEvent = this.emit('cancel');
115
+ const cancelEvent = this.emit('cancel', { reason: 'escape' });
81
116
  if (!this.options.closable || cancelEvent.defaultPrevented) event.preventDefault();
82
117
  });
83
118
  this.listen(this.el, 'close', () => {
@@ -85,7 +120,7 @@ export class Modal extends Component {
85
120
  });
86
121
  this.listen(this.el, 'click', (event) => {
87
122
  if (!this.options.lightDismiss || event.target !== this.el || !isBackdropClick(this.el, event)) return;
88
- this.close();
123
+ this._requestDismiss('backdrop');
89
124
  });
90
125
  /*
91
126
  * One listener for every close path, because `close` is the one event all four converge on:
@@ -168,8 +203,9 @@ export class Modal extends Component {
168
203
  * Describes the current presentation for the overlay stack, or returns null to stay off it.
169
204
  *
170
205
  * The kind is read from the platform like `aria-modal` is: a `showModal()` dialog is `modal`,
171
- * and its Escape and backdrop stay the browser's; anything else is `non-modal`, and a subclass
172
- * presenting that way adds the Escape and outside-press handling it wants.
206
+ * and the stack leaves its Escape alone (this class answers it, see the constructor); anything
207
+ * else is `non-modal`, and a subclass presenting that way adds the Escape and outside-press
208
+ * handling it wants.
173
209
  * @returns {import('../../core/overlay-stack.js').OverlayEntryOptions|null}
174
210
  * @protected
175
211
  */
@@ -182,6 +218,22 @@ export class Modal extends Component {
182
218
  };
183
219
  }
184
220
 
221
+ /**
222
+ * Asks to close on the reader's behalf: emits a preventable `cancel` naming what they did, and
223
+ * closes unless a listener prevented it. Every dismissal gesture goes through here; `close()`
224
+ * itself stays unconditional, for the application's own decisions.
225
+ * @param {ModalDismissReason} reason What the reader did.
226
+ * @returns {boolean} Whether the overlay is closing.
227
+ * @fires Modal#cancel
228
+ * @protected
229
+ */
230
+ _requestDismiss(reason) {
231
+ if (!this.isOpen()) return false;
232
+ if (this.emit('cancel', { reason }).defaultPrevented) return false;
233
+ this.close();
234
+ return true;
235
+ }
236
+
185
237
  /**
186
238
  * Re-registers the current presentation on the overlay stack: called after every presentation,
187
239
  * including a subclass's change of address that bypasses `open()`.
@@ -449,9 +501,11 @@ export class Modal extends Component {
449
501
  */
450
502
 
451
503
  /**
452
- * Fired when Escape requests cancellation. Preventing it keeps the modal open.
504
+ * Fired when the reader asks to dismiss the modal — Escape, a header close button, a `'cancel'`
505
+ * footer button, a backdrop click, a press outside a non-modal overlay, a drag — with the gesture
506
+ * in `detail.reason`. Preventing it keeps the modal open. A programmatic `close()` does not raise it.
453
507
  * @event Modal#cancel
454
- * @type {CustomEvent<Record<string, never>>}
508
+ * @type {CustomEvent<ModalCancelDetail>}
455
509
  */
456
510
 
457
511
  /**