@zeyos/zx 5.0.0 → 5.2.0

package/src/components/dropdown/dropdown.js

@@ -1,11 +1,16 @@
 import { Component } from '../../core/component.js';
 import { h, resolveElement } from '../../core/dom.js';
-import { connectedOverlayHost, overlayHost } from '../../core/overlay-host.js';
+import { connectedOverlayHost, openDialogOf, overlayHost, overlayScope } from '../../core/overlay-host.js';
+import { pushOverlay } from '../../core/overlay-stack.js';
 import { position } from '../../core/position.js';
 import { uid } from '../../core/util.js';
 
-const HANDLE_POINTER_DISMISS = Symbol('zxDropdownPointerDismiss');
-const HANDLE_ESCAPE_DISMISS = Symbol('zxDropdownEscapeDismiss');
+/** What Tab may land on inside a panel: the controls a reader reaches in sequence. */
+const TABBABLE_SELECTOR = [
+  'a[href]', 'button:not([disabled])', 'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])', 'textarea:not([disabled])', 'iframe', '[contenteditable="true"]',
+  '[tabindex]'
+].map((selector) => `${selector}:not([tabindex^="-"])`).join(',');
 
 /**
  * @typedef {Object} DropdownOptions
@@ -22,6 +27,16 @@ const HANDLE_ESCAPE_DISMISS = Symbol('zxDropdownEscapeDismiss');
 
 /**
  * Generic anchored floating panel using the browser popover top layer.
+ *
+ * Open, the panel is one entry on the overlay stack (`core/overlay-stack.js`): Escape closes it
+ * only while it is the topmost layer that takes Escape, a press outside it and every overlay opened
+ * from it closes it, and it closes with the overlay its anchor sits in. Inside an open dialog the
+ * panel is hosted by that dialog, so `showModal()` does not make it inert.
+ *
+ * The panel follows its trigger in the Tab order: Tab on the anchor of an open panel moves into
+ * the panel's first focusable control (or onto the panel itself when it carries a `tabindex`),
+ * Tab past the panel's last control continues after the anchor, and Shift+Tab from the first goes
+ * back to the anchor. Closing while focus is inside returns it to the anchor.
  * @fires Dropdown#open
  * @fires Dropdown#close
  * @extends {Component<DropdownOptions>}
@@ -46,6 +61,12 @@ export class Dropdown extends Component {
   #position = null;
   /** @type {Map<string, string|null>} */
   #anchorAttributes = new Map();
+  /** @type {import('../../core/overlay-stack.js').OverlayHandle|null} */
+  #overlay = null;
+  /** @type {((event: KeyboardEvent) => void)|null} Escape behaviour a composing component supplies. */
+  #escapeHandler = null;
+  /** Whether the panel joins the Tab order after its anchor; menus and rail flyouts opt out. */
+  #tabReach = true;
   #destroyed = false;
 
   /**
@@ -59,8 +80,9 @@ export class Dropdown extends Component {
     super(null, options);
     this.#anchor = resolved;
     // An anchor that is not in the document yet has no theme scope to read; the panel then waits
-    // detached and finds its host on the first open, instead of settling on <body>.
-    connectedOverlayHost(this.options.scope ?? resolved)?.append(this.el);
+    // detached and finds its host on the first open, instead of settling on <body>. A closed panel
+    // rests in the theme scope even when the anchor is in a dialog; it moves in only while open.
+    connectedOverlayHost(this.options.scope ?? resolved, { dialog: false })?.append(this.el);
     this.#rememberAnchorAttribute('aria-expanded');
     this.#rememberAnchorAttribute('aria-controls');
     this.#anchor.setAttribute('aria-expanded', 'false');
@@ -73,6 +95,8 @@ export class Dropdown extends Component {
     this.listen(this.el, 'click', () => {
       if (this.options.closeOnSelect) this.close();
     });
+    this.listen(this.#anchor, 'keydown', (event) => this.#onAnchorKeydown(/** @type {KeyboardEvent} */ (event)));
+    this.listen(this.el, 'keydown', (event) => this.#onPanelKeydown(/** @type {KeyboardEvent} */ (event)));
   }
 
   /**
@@ -95,7 +119,7 @@ export class Dropdown extends Component {
    */
   open() {
     if (this.isOpen() || this.#destroyed) return this;
-    const host = overlayHost(this.options.scope ?? this.#anchor);
+    const host = this.#host();
     if (this.el.parentElement !== host) host.append(this.el);
     this.#position = position(this.#anchor, this.el, {
       placement: this.options.placement,
@@ -103,9 +127,18 @@ export class Dropdown extends Component {
       matchWidth: Boolean(this.options.matchWidth)
     });
     this.el.dataset.state = 'open';
-    this.el.dataset.zxOverlayOrder = String(nextOverlayOrder());
+    this.#overlay = pushOverlay({
+      kind: 'popup',
+      root: this.el,
+      owner: this,
+      anchor: [this.#anchor, resolveElement(this.options.scope)],
+      inside: [this.#anchor],
+      onEscape: (event) => this.#onEscape(event),
+      onOutsidePointer: () => this.close(),
+      onParentClose: () => this.close()
+    });
+    this.el.dataset.zxOverlayOrder = String(this.#overlay.order);
     this.#anchor.setAttribute('aria-expanded', 'true');
-    ensureDismissManager();
     this.emit('open');
     return this;
   }
@@ -117,13 +150,24 @@ export class Dropdown extends Component {
    */
   close() {
     if (!this.isOpen()) return this;
+    const hadFocus = this.el.contains(document.activeElement);
     this.#position?.destroy();
     this.#position = null;
     this.el.dataset.state = 'closed';
     delete this.el.dataset.zxOverlayOrder;
+    const overlay = this.#overlay;
+    this.#overlay = null;
     this.#anchor.setAttribute('aria-expanded', 'false');
+    // A panel that took the Tab order hands focus back rather than dropping it on <body>. Menus and
+    // flyouts decide where their own focus goes.
+    if (hadFocus && this.#tabReach && this.#anchor instanceof HTMLElement) this.#anchor.focus();
+    // Back to the theme scope: a closed panel left inside a dialog would sit in that dialog's
+    // focus search and go with it when the dialog is removed.
+    if (openDialogOf(this.el.parentElement) && this.el.parentElement?.isConnected) {
+      overlayScope(this.options.scope ?? this.#anchor).append(this.el);
+    }
+    overlay?.release();
     this.emit('close');
-    destroyUnusedDismissManager();
     return this;
   }
 
@@ -174,50 +218,78 @@ export class Dropdown extends Component {
     super.destroy();
   }
 
-  /** @param {PointerEvent} event @returns {void} */
-  [HANDLE_POINTER_DISMISS](event) {
-    if (!this.isOpen()) return;
-    const path = event.composedPath();
-    if (path.includes(this.el) || path.includes(this.#anchor)) return;
-    this.close();
+  /**
+   * Internal seam for components built on a Dropdown (MenuButton, ContextMenu, the app rail):
+   * replaces what Escape does when the overlay stack routes it to this panel, and takes the panel
+   * out of the anchor's Tab order — a menu is reached with the arrow keys, not Tab.
+   * @param {{onEscape?: ((event: KeyboardEvent) => void)|null, tabReach?: boolean}} settings
+   * @returns {this}
+   * @internal
+   */
+  _configure(settings) {
+    if ('onEscape' in settings) this.#escapeHandler = settings.onEscape ?? null;
+    if ('tabReach' in settings) this.#tabReach = Boolean(settings.tabReach);
+    return this;
+  }
+
+  /** @returns {Element} Where the panel lives while open. */
+  #host() {
+    const dialog = openDialogOf(this.#anchor) ?? openDialogOf(resolveElement(this.options.scope));
+    return dialog ?? overlayHost(this.options.scope ?? this.#anchor);
   }
 
   /** @param {KeyboardEvent} event @returns {void} */
-  [HANDLE_ESCAPE_DISMISS](event) {
-    if (event.defaultPrevented || event.key !== 'Escape' || !this.isOpen()) return;
-    event.preventDefault();
+  #onEscape(event) {
+    if (this.#escapeHandler) {
+      this.#escapeHandler(event);
+      return;
+    }
     const restoreFocus = this.el.contains(document.activeElement);
     this.close();
     if (restoreFocus && this.#anchor instanceof HTMLElement) this.#anchor.focus();
   }
 
-  /** @param {string} name @returns {void} */
-  #rememberAnchorAttribute(name) {
-    this.#anchorAttributes.set(name, this.#anchor.getAttribute(name));
+  /** @param {KeyboardEvent} event @returns {void} */
+  #onAnchorKeydown(event) {
+    if (event.key !== 'Tab' || event.shiftKey || event.defaultPrevented || !this.#tabReach || !this.isOpen()) return;
+    const target = tabbables(this.el)[0] ?? (this.el.hasAttribute('tabindex') ? this.el : null);
+    if (!(target instanceof HTMLElement)) return;
+    event.preventDefault();
+    target.focus();
   }
-}
 
-/** Shared document-level light-dismiss listener owned only while a dropdown is open. */
-class DropdownDismissManager extends Component {
-  /** Creates the transient listener owner. */
-  constructor() {
-    super(null);
-    this.listen(document, 'pointerdown', (event) => {
-      const component = topmostOverlayComponent();
-      if (component instanceof Dropdown) component[HANDLE_POINTER_DISMISS](event);
-    });
-    this.listen(document, 'keydown', (event) => {
-      if (event.defaultPrevented || event.key !== 'Escape') return;
-      const component = topmostOverlayComponent();
-      if (component instanceof Dropdown) component[HANDLE_ESCAPE_DISMISS](event);
-    });
+  /** @param {KeyboardEvent} event @returns {void} */
+  #onPanelKeydown(event) {
+    if (event.key !== 'Tab' || event.defaultPrevented || !this.#tabReach || !this.isOpen()) return;
+    const items = tabbables(this.el);
+    const active = document.activeElement;
+    /*
+     * Judged by position, not identity: focus may rest on something Tab itself would never stop
+     * at — a composite's `tabindex="-1"` part, a roving item — and what matters is whether any
+     * real stop is left in the panel on the side Tab is moving to.
+     */
+    const ahead = active && active !== this.el
+      ? items.filter((item) => !item.contains(active) && (event.shiftKey
+        ? Boolean(active.compareDocumentPosition(item) & Node.DOCUMENT_POSITION_PRECEDING)
+        : Boolean(active.compareDocumentPosition(item) & Node.DOCUMENT_POSITION_FOLLOWING)
+          && !active.contains(item)))
+      : (event.shiftKey ? [] : items);
+    if (ahead.length > 0) return;
+    if (event.shiftKey) {
+      if (!(this.#anchor instanceof HTMLElement)) return;
+      event.preventDefault();
+      this.#anchor.focus();
+      return;
+    }
+    const next = followingTabbable(this.#anchor, this.el);
+    if (!next) return;
+    event.preventDefault();
+    next.focus();
   }
 
-  /** @returns {HTMLElement} */
-  render() {
-    const marker = h('span', { hidden: true, 'data-zx-dropdown-dismiss-manager': '' });
-    document.body.append(marker);
-    return marker;
+  /** @param {string} name @returns {void} */
+  #rememberAnchorAttribute(name) {
+    this.#anchorAttributes.set(name, this.#anchor.getAttribute(name));
   }
 }
 
@@ -251,41 +323,54 @@ function replaceContent(target, content) {
   }
 }
 
-/** @returns {Component|null} */
-function topmostOverlayComponent() {
-  let topmost = null;
-  let highest = -1;
-  for (const candidate of document.querySelectorAll('[data-zx-overlay-order]')) {
-    const order = Number(candidate.getAttribute('data-zx-overlay-order')) || 0;
-    if (order > highest) {
-      highest = order;
-      topmost = candidate;
-    }
-  }
-  return topmost ? Component.from(topmost) : null;
-}
-
-/** @returns {number} */
-function nextOverlayOrder() {
-  const orders = Array.from(document.querySelectorAll('[data-zx-overlay-order]'), (element) =>
-    Number(element.getAttribute('data-zx-overlay-order')) || 0
-  );
-  return Math.max(0, ...orders) + 1;
+/**
+ * The controls inside a container Tab would visit, in document order.
+ * @param {Element} container
+ * @returns {HTMLElement[]}
+ */
+function tabbables(container) {
+  return /** @type {HTMLElement[]} */ (Array.from(container.querySelectorAll(TABBABLE_SELECTOR))
+    .filter((element) => isTabbable(element)));
 }
 
-/** @returns {DropdownDismissManager} */
-function ensureDismissManager() {
-  const marker = document.querySelector('[data-zx-dropdown-dismiss-manager]');
-  const existing = marker ? Component.from(marker) : null;
-  return existing instanceof DropdownDismissManager ? existing : new DropdownDismissManager();
+/**
+ * The control Tab reaches after `anchor`, skipping the panel that follows it.
+ * @param {Element} anchor
+ * @param {Element} panel
+ * @returns {HTMLElement|null}
+ */
+function followingTabbable(anchor, panel) {
+  // Inside a modal dialog nothing beyond it can take focus, so the search stays within it.
+  const scope = openDialogOf(anchor) ?? anchor.ownerDocument.body ?? anchor.ownerDocument.documentElement;
+  const all = tabbables(scope).filter((element) => !panel.contains(element));
+  const index = all.findIndex((element) => element === anchor || anchor.contains(element));
+  if (index < 0) return null;
+  let next = index + 1;
+  while (next < all.length && anchor.contains(all[next])) next += 1;
+  return all[next] ?? null;
 }
 
-/** @returns {void} */
-function destroyUnusedDismissManager() {
-  if (document.querySelector('.zx-dropdown[data-state="open"]')) return;
-  const marker = document.querySelector('[data-zx-dropdown-dismiss-manager]');
-  const manager = marker ? Component.from(marker) : null;
-  if (manager instanceof DropdownDismissManager) manager.destroy();
+/**
+ * Whether sequential navigation stops at an element: focusable, a non-negative tab index, not
+ * disabled, hidden, inert or `aria-hidden`, rendered, and — for a radio — the one stop its group
+ * offers (the checked radio, or the first when none is checked).
+ * @param {Element} element
+ * @returns {boolean}
+ */
+function isTabbable(element) {
+  const html = /** @type {HTMLElement} */ (element);
+  if (typeof html.focus !== 'function' || html.tabIndex < 0) return false;
+  if (/** @type {HTMLButtonElement} */ (html).disabled) return false;
+  if (element.closest('[inert], [hidden], [aria-hidden="true"], fieldset[disabled]')) return false;
+  if (html instanceof HTMLInputElement && html.type === 'radio' && html.name && !html.checked) {
+    const scope = html.form ?? html.getRootNode();
+    const group = /** @type {HTMLInputElement[]} */ (Array.from(
+      /** @type {ParentNode} */ (scope).querySelectorAll?.('input[type="radio"]') ?? []
+    )).filter((radio) => radio.name === html.name && (radio.form ?? radio.getRootNode()) === scope);
+    if (group.some((radio) => radio.checked) || group[0] !== html) return false;
+  }
+  if (typeof html.checkVisibility === 'function') return html.checkVisibility({ visibilityProperty: true });
+  return html.getClientRects().length > 0;
 }
 
 /** @param {Element} element @param {string} name @param {string|null} value @returns {void} */

package/src/components/field/field.js

@@ -15,6 +15,9 @@ import { uid } from '../../core/util.js';
  * @property {string} [placeholder=''] Control placeholder.
  * @property {boolean} [required=false] Whether a value is required.
  * @property {boolean} [disabled=false] Whether the control is disabled.
+ * @property {boolean} [readonly=false] Whether the value is read-only: shown and focusable, not
+ *   editable. Types whose control has no read-only state (`checkbox`, `select`, `optionlist`,
+ *   `zxselect`, `date`, `time`, …) ignore it.
  * @property {string[]|Record<string, string>|null} [options=null] Select or option-list values.
  * @property {'stack'|'inline'} [layout='stack'] Label/control layout.
  * @property {Record<string, unknown>} [props={}] Adapter-specific control properties.
@@ -30,6 +33,8 @@ import { uid } from '../../core/util.js';
  * @property {(value: unknown, options?: {silent?: boolean}) => void} set Set the current value.
  * @property {() => void} focus Focus the control.
  * @property {(disabled: boolean) => void} setDisabled Set disabled state.
+ * @property {(readonly: boolean) => void} [setReadonly] Set read-only state; left out when the
+ *   control has none.
  * @property {() => void} [destroy] Release adapter-owned resources.
  * @property {Element} [labelTarget] The element the field's label, description, and validity
  *   belong to when it is not `el` — the text input inside a composite control. Left out, a
@@ -42,6 +47,7 @@ import { uid } from '../../core/util.js';
 /**
  * One labelled form control backed by a registered adapter.
  * @fires Field#change
+ * @fires Field#input
  * @fires Field#invalid
  * @extends {Component<FieldOptions>}
  */
@@ -59,6 +65,7 @@ export class Field extends Component {
     placeholder: '',
     required: false,
     disabled: false,
+    readonly: false,
     options: null,
     layout: 'stack',
     props: {},
@@ -108,7 +115,7 @@ export class Field extends Component {
     const layout = this.options.layout === 'inline' ? 'inline' : 'stack';
     this._ownedComponents = new Set();
     this._ownedNodes = [];
-    this._rootAttributes = rememberAttributes(root, ['data-layout', 'data-field-type', 'data-disabled', 'data-state']);
+    this._rootAttributes = rememberAttributes(root, ['data-layout', 'data-field-type', 'data-disabled', 'data-readonly', 'data-state']);
     root.dataset.layout = layout;
     root.dataset.fieldType = type;
 
@@ -175,6 +182,8 @@ export class Field extends Component {
     this.initialValue = initialValue(type, this.options.value);
     this.adapter.set(this.initialValue, { silent: true });
     this.setDisabled(Boolean(this.options.disabled));
+    if (this.options.readonly) this.setReadonly(true);
+    // Adapters whose widget reports its own commits stop the native `change` before this sees it.
     this.listen(control, 'change', () => {
       this.emit('change', { value: this.getValue() });
     });
@@ -233,6 +242,19 @@ export class Field extends Component {
     return this;
   }
 
+  /**
+   * Makes the value read-only or editable again, where the control has a read-only state (see
+   * the `readonly` option); reflected as `data-readonly` on the root either way.
+   * @param {boolean} readonly Read-only state.
+   * @returns {this}
+   */
+  setReadonly(readonly) {
+    const value = Boolean(readonly);
+    this.adapter.setReadonly?.(value);
+    this.el.dataset.readonly = String(value);
+    return this;
+  }
+
   /**
    * Displays a validation or status message.
    * @param {string} message Message text.
@@ -470,7 +492,7 @@ function textAdapter(tag, type) {
       required: options.required,
       disabled: options.disabled
     }));
-    return elementValueAdapter(el);
+    return { ...elementValueAdapter(el), setReadonly: (readonly) => { el.readOnly = readonly; } };
   };
 }
 
@@ -507,7 +529,8 @@ function numericAdapter(kind) {
     });
     return {
       ...elementValueAdapter(input),
-      get: () => coerce(input.value).value
+      get: () => coerce(input.value).value,
+      setReadonly: (readonly) => { input.readOnly = readonly; }
     };
   };
 }
@@ -642,6 +665,13 @@ Field.register('custom', customAdapter);
  * @type {CustomEvent<{value: unknown}>}
  */
 
+/**
+ * Live edit before it is committed, from the types whose widget tells the two apart (`code`,
+ * `slider`): every keystroke or drag step, where `change` follows only on commit.
+ * @event Field#input
+ * @type {CustomEvent<{value: unknown}>}
+ */
+
 /**
  * Field validation failure event.
  * @event Field#invalid