@zeyos/zx 2.1.0 → 2.2.0

package/src/components/context-menu/context-menu.js

@@ -0,0 +1,334 @@
+import { Component } from '../../core/component.js';
+import { h, resolveElement } from '../../core/dom.js';
+import { icon } from '../../core/icons.js';
+import { rovingTabindex, typeahead } from '../../core/keyboard.js';
+import { Dropdown } from '../dropdown/dropdown.js';
+
+/** @typedef {import('../menu-button/menu-button.js').MenuItem} MenuItem */
+/** @typedef {MenuItem|'-'} ContextMenuEntry */
+
+/**
+ * @typedef {Object} ContextMenuOptions
+ * @property {ContextMenuEntry[]|((context: Element|null) => ContextMenuEntry[])} [items=[]] Menu
+ *   items and `'-'` separators, or a function returning them for the element the menu is opening
+ *   on — which is how a row menu disables the actions that row does not allow. Returning an empty
+ *   array cancels the opening.
+ * @property {string|null} [selector=null] Restricts the menu to descendants matching this
+ *   selector, and reports the matched element as the context of the selection. A table passes
+ *   `'tbody tr'` here to get a per-row menu from one listener.
+ * @property {(event: CustomEvent<{value: unknown, item: MenuItem, context: Element|null}>) => void} [onselect]
+ *   Selection listener.
+ * @property {(event: CustomEvent<{context: Element|null}>) => void} [onopen] Open listener.
+ * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close listener.
+ */
+
+const MENU_ITEM_SELECTOR = '[role="menuitem"]';
+
+/**
+ * Right-click menu for a region, implementing the APG menu pattern.
+ *
+ * Attaches to an existing element and never changes it: the menu itself lives in the top layer,
+ * anchored to a zero-sized element parked at the pointer. `selector` turns one instance into a
+ * per-row menu — the listener stays on the container, and the row that was clicked arrives with
+ * the selection as `context`.
+ *
+ * Reachable from the keyboard as the platform expects: the Menu key or Shift+F10 opens the menu at
+ * the focused element, and closing returns focus to where it came from. Pointer-only context
+ * menus are a common accessibility failure, so both routes are wired here rather than left to the
+ * application.
+ *
+ * Note that the component's root is the anchor, which lives on `<body>` — so the bubbling `zx-*`
+ * DOM events land there, not in the target's tree. Listen with `on('select')` or `onselect`.
+ *
+ * @fires ContextMenu#select
+ * @fires ContextMenu#open
+ * @fires ContextMenu#close
+ * @extends {Component<ContextMenuOptions>}
+ */
+export class ContextMenu extends Component {
+  /** @type {ContextMenuOptions} */
+  static defaults = {
+    items: [],
+    selector: null
+  };
+
+  /** @type {Element} */
+  #target;
+  /** @type {Dropdown} */
+  #dropdown;
+  /** @type {HTMLElement} */
+  #panel;
+  /** @type {ReturnType<typeof rovingTabindex>} */
+  #roving;
+  /** @type {(event: KeyboardEvent|string) => void} */
+  #typeahead;
+  /** @type {ContextMenuEntry[]} */
+  #items = [];
+  /** @type {Element|null} */
+  #context = null;
+  /** @type {Element|null} */
+  #returnFocus = null;
+  #destroyed = false;
+
+  /**
+   * Attaches a context menu to an existing element.
+   * @param {Element|string} target Element or selector the menu belongs to.
+   * @param {ContextMenuOptions} [options={}] Context-menu options.
+   */
+  constructor(target, options = {}) {
+    const resolved = resolveElement(target);
+    if (!resolved) throw new TypeError('ContextMenu target could not be resolved');
+    super(null, options);
+    this.#target = resolved;
+    document.body.append(this.el);
+
+    this.#dropdown = new Dropdown(this.el, { openOn: 'manual', placement: 'bottom-start' });
+    this.#panel = this.#dropdown.getPanel();
+    this.#panel.classList.add('zx-context-menu');
+    this.#panel.setAttribute('role', 'menu');
+
+    if (Array.isArray(this.options.items)) this.setItems(this.options.items);
+    this.#roving = rovingTabindex(this.#panel, MENU_ITEM_SELECTOR);
+    this.#typeahead = typeahead(() => this.#menuItems(), (item) => item.focus());
+
+    this.#dropdown.on('close', () => {
+      this.#context = null;
+      const restore = this.#returnFocus;
+      this.#returnFocus = null;
+      if (restore instanceof HTMLElement && restore.isConnected) restore.focus();
+      this.emit('close');
+    });
+
+    this.listen(this.#target, 'contextmenu', (event) => this.#onContextMenu(event));
+    this.listen(this.#target, 'keydown', (event) => this.#onTargetKeydown(event));
+    this.listen(this.#panel, 'click', (event) => {
+      const item = event.target.closest?.(MENU_ITEM_SELECTOR);
+      if (item && this.#panel.contains(item)) this.#select(item);
+    });
+    this.listen(this.#panel, 'keydown', (event) => this.#onMenuKeydown(event));
+  }
+
+  /**
+   * Creates the zero-sized element the menu is anchored to.
+   * @returns {HTMLElement}
+   */
+  render() {
+    return h('span', { class: 'zx-context-menu__anchor', ariaHidden: 'true' });
+  }
+
+  /**
+   * Replaces the menu items.
+   * @param {ContextMenuEntry[]} items Menu definitions.
+   * @returns {this}
+   */
+  setItems(items) {
+    this.#items = Array.isArray(items) ? items.slice() : [];
+    this.#panel.replaceChildren();
+    this.#items.forEach((item, index) => {
+      if (item === '-') {
+        this.#panel.append(h('div', { class: 'zx-context-menu__separator', role: 'separator' }));
+        return;
+      }
+      const children = [];
+      if (item.icon) children.push(h('span', { class: 'zx-context-menu__icon' }, icon(item.icon)));
+      children.push(h('span', { class: 'zx-context-menu__label' }, String(item.label ?? '')));
+      this.#panel.append(h('button', {
+        class: 'zx-context-menu__item',
+        type: 'button',
+        role: 'menuitem',
+        tabindex: '-1',
+        'data-menu-item': String(index),
+        'data-danger': item.danger ? 'true' : null,
+        ariaDisabled: item.disabled ? 'true' : null
+      }, children));
+    });
+    return this;
+  }
+
+  /**
+   * Opens the menu at a point in viewport coordinates.
+   * @param {number} x Client X.
+   * @param {number} y Client Y.
+   * @param {Element|null} [context=null] Element the menu applies to.
+   * @returns {this}
+   * @fires ContextMenu#open
+   */
+  openAt(x, y, context = null) {
+    if (!this.#prepare(context)) return this;
+    this.#openResolved(x, y, context);
+    return this;
+  }
+
+  /**
+   * Opens the menu against an element's box, which is where a keyboard invocation puts it.
+   * @param {Element} element Element to anchor to.
+   * @returns {this}
+   * @fires ContextMenu#open
+   */
+  openAtElement(element) {
+    const box = element.getBoundingClientRect();
+    return this.openAt(box.left, box.bottom, element);
+  }
+
+  /**
+   * Closes the menu.
+   * @returns {this}
+   */
+  close() {
+    this.#dropdown.close();
+    return this;
+  }
+
+  /**
+   * Reports whether the menu is open.
+   * @returns {boolean}
+   */
+  isOpen() {
+    return this.#dropdown.isOpen();
+  }
+
+  /**
+   * The element the open menu applies to — the `selector` match under the pointer, or the target.
+   * @returns {Element|null}
+   */
+  getContext() {
+    return this.#context;
+  }
+
+  /**
+   * Detaches the menu and removes its anchor.
+   * @returns {void}
+   */
+  destroy() {
+    if (this.#destroyed) return;
+    this.#destroyed = true;
+    this.#roving.destroy();
+    this.#dropdown.destroy();
+    super.destroy();
+  }
+
+  /**
+   * Resolves the items for this opening and reports whether it may proceed.
+   * @param {Element|null} context Element the menu applies to.
+   * @returns {boolean}
+   */
+  #prepare(context) {
+    const items = this.options.items;
+    if (typeof items === 'function') {
+      const resolved = items(context);
+      if (!Array.isArray(resolved) || resolved.length === 0) return false;
+      this.setItems(resolved);
+    }
+    return this.#items.length > 0;
+  }
+
+  /**
+   * Places the anchor and opens, with the items for this opening already resolved.
+   *
+   * `left`/`top` rather than the logical insets used everywhere else: these are viewport
+   * coordinates from a pointer event, which are physical whatever the writing direction is.
+   *
+   * @param {number} x Client X.
+   * @param {number} y Client Y.
+   * @param {Element|null} context Element the menu applies to.
+   * @returns {void}
+   */
+  #openResolved(x, y, context) {
+    const root = /** @type {HTMLElement} */ (this.el);
+    root.style.left = `${x}px`;
+    root.style.top = `${y}px`;
+    this.#context = context;
+    this.#returnFocus = document.activeElement;
+    this.#dropdown.open();
+    this.#roving.focusFirst();
+    this.emit('open', { context });
+  }
+
+  /** @param {Event} event @returns {void} */
+  #onContextMenu(event) {
+    const pointer = /** @type {PointerEvent & {target: Element}} */ (event);
+    const context = this.#contextFor(pointer.target);
+    // Only take over the platform menu once there is something of our own to show — and resolve
+    // the items once for the opening, not once to decide and again to open.
+    if (!context || !this.#prepare(context)) return;
+    event.preventDefault();
+    this.#openResolved(pointer.clientX, pointer.clientY, context);
+  }
+
+  /** @param {Event} event @returns {void} */
+  #onTargetKeydown(event) {
+    const key = /** @type {KeyboardEvent} */ (event);
+    if (key.key !== 'ContextMenu' && !(key.key === 'F10' && key.shiftKey)) return;
+    const context = this.#contextFor(/** @type {Element} */ (key.target));
+    if (!context || !this.#prepare(context)) return;
+    event.preventDefault();
+    const box = context.getBoundingClientRect();
+    this.#openResolved(box.left, box.bottom, context);
+  }
+
+  /**
+   * The element a pointer or key event applies to, honoring `selector`.
+   * @param {Element|null} from Event target.
+   * @returns {Element|null}
+   */
+  #contextFor(from) {
+    if (!this.options.selector) return this.#target;
+    const match = from?.closest?.(String(this.options.selector));
+    return match && this.#target.contains(match) ? match : null;
+  }
+
+  /** @param {Event} event @returns {void} */
+  #onMenuKeydown(event) {
+    const key = /** @type {KeyboardEvent} */ (event);
+    if (key.key === 'Escape' || key.key === 'Tab') {
+      event.preventDefault();
+      this.close();
+      return;
+    }
+    if (key.key === 'Enter' || key.key === ' ') {
+      const item = /** @type {Element} */ (key.target).closest?.(MENU_ITEM_SELECTOR);
+      if (!item || !this.#panel.contains(item)) return;
+      event.preventDefault();
+      this.#select(item);
+      return;
+    }
+    this.#typeahead(key);
+  }
+
+  /** @param {Element} element @returns {void} */
+  #select(element) {
+    const index = Number(element.getAttribute('data-menu-item'));
+    const item = this.#items[index];
+    if (!item || item === '-' || item.disabled) return;
+    const context = this.#context;
+    this.emit('select', { value: item.value, item, context });
+    try {
+      item.onselect?.(item.value, item, this);
+    } finally {
+      this.close();
+    }
+  }
+
+  /** @returns {HTMLElement[]} */
+  #menuItems() {
+    return Array.from(this.#panel.querySelectorAll(MENU_ITEM_SELECTOR));
+  }
+}
+
+/**
+ * Fired when an enabled item is activated. `context` is the element the menu was opened on.
+ * @event ContextMenu#select
+ * @type {CustomEvent<{value: unknown, item: MenuItem, context: Element|null}>}
+ */
+
+/**
+ * Fired when the menu opens.
+ * @event ContextMenu#open
+ * @type {CustomEvent<{context: Element|null}>}
+ */
+
+/**
+ * Fired when the menu closes.
+ * @event ContextMenu#close
+ * @type {CustomEvent<Record<string, never>>}
+ */

package/src/components/copy/copy-button.css

@@ -0,0 +1,27 @@
+.zx-copy-button {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+}
+
+.zx-copy-button__icon {
+  display: inline-flex;
+  flex: none;
+}
+
+.zx-copy-button[data-copied] {
+  color: var(--zx-color-success);
+}
+
+/*
+ * The confirmation is spoken, not drawn: the tick already carries it visually, and a live region
+ * that also took up space would move the layout every time someone copied something.
+ */
+.zx-copy-button__status {
+  position: absolute;
+  clip-path: inset(50%);
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  white-space: nowrap;
+}

package/src/components/copy/copy-button.js

@@ -0,0 +1,78 @@
+import { h } from '../../core/dom.js';
+import { copyToClipboard } from '../../core/export.js';
+import { icon as createIcon } from '../../core/icons.js';
+
+/**
+ * @typedef {Object} CopyButtonOptions
+ * @property {string|(() => string)} [text=''] Text to copy, or a function returning it — a
+ *   function is what a button beside a live value wants, so the copy is never stale.
+ * @property {string} [label=''] Visible label. Empty renders an icon-only ghost button.
+ * @property {string} [title='Copy'] Accessible name, and the native tooltip on the icon-only form.
+ * @property {string} [feedback='Copied'] Confirmation announced and shown after a copy.
+ * @property {number} [feedbackDuration=2000] Milliseconds the confirmation stays.
+ * @property {'md'|'sm'} [size='md'] Control size.
+ * @property {'default'|'primary'|'ghost'} [kind='ghost'] Visual intent.
+ * @property {(text: string, copied: boolean) => void} [oncopy] Called with the text and whether
+ *   the clipboard accepted it.
+ */
+
+/** @type {Readonly<CopyButtonOptions>} */
+const buttonDefaults = Object.freeze({
+  text: '',
+  label: '',
+  title: 'Copy',
+  feedback: 'Copied',
+  feedbackDuration: 2000,
+  size: 'md',
+  kind: 'ghost'
+});
+
+/**
+ * Creates a button that copies a string and confirms it in place.
+ *
+ * The confirmation is the point: a clipboard write is silent, so without it nobody knows whether
+ * the click worked. It swaps the glyph for a tick and speaks through a live region, then reverts.
+ * A failed write — no permission, an insecure context — leaves the button untouched and reports
+ * `false` to `oncopy`, rather than claiming a copy that did not happen.
+ *
+ * @param {CopyButtonOptions} [opts={}] Copy-button options.
+ * @returns {HTMLButtonElement}
+ */
+export function copyButton(opts = {}) {
+  const options = { ...buttonDefaults, ...opts };
+  const iconOnly = !options.label;
+  const element = /** @type {HTMLButtonElement} */ (h('button', {
+    class: ['zx-copy-button', iconOnly ? 'zx-icon-btn' : 'zx-btn'],
+    type: 'button',
+    dataset: { size: options.size === 'sm' ? 'sm' : 'md', kind: iconOnly ? null : options.kind },
+    title: iconOnly ? String(options.title) : null,
+    ariaLabel: iconOnly ? String(options.title) : null
+  }));
+
+  const glyph = h('span', { class: 'zx-copy-button__icon', ariaHidden: 'true' },
+    createIcon('copy', { size: options.size === 'sm' ? 12 : 14 }));
+  const status = h('span', { class: 'zx-copy-button__status', role: 'status' });
+  element.append(glyph);
+  if (!iconOnly) element.append(h('span', { class: 'zx-copy-button__label' }, String(options.label)));
+  element.append(status);
+
+  let timer = 0;
+  element.addEventListener('click', async () => {
+    const text = typeof options.text === 'function' ? String(options.text()) : String(options.text ?? '');
+    const copied = await copyToClipboard(text);
+    options.oncopy?.(text, copied);
+    if (!copied) return;
+
+    clearTimeout(timer);
+    element.dataset.copied = 'true';
+    glyph.replaceChildren(createIcon('check', { size: options.size === 'sm' ? 12 : 14 }));
+    status.textContent = String(options.feedback);
+    timer = setTimeout(() => {
+      if (!element.isConnected) return;
+      delete element.dataset.copied;
+      glyph.replaceChildren(createIcon('copy', { size: options.size === 'sm' ? 12 : 14 }));
+      status.textContent = '';
+    }, Math.max(0, Number(options.feedbackDuration) || 0));
+  });
+  return element;
+}

package/src/components/copy/copy-input.css

@@ -0,0 +1,59 @@
+.zx-copy-input {
+  display: flex;
+  flex-direction: column;
+  gap: var(--zx-space-1);
+  inline-size: 100%;
+}
+
+.zx-copy-input__label {
+  color: var(--zx-color-text);
+  font-size: var(--zx-control-font-size);
+  font-weight: 500;
+}
+
+.zx-copy-input[data-hide-label] .zx-copy-input__label {
+  position: absolute;
+  clip-path: inset(50%);
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.zx-copy-input__box {
+  display: flex;
+  align-items: center;
+  gap: var(--zx-space-1);
+  min-inline-size: 0;
+  padding-inline-end: var(--zx-space-1);
+  border: 1px solid var(--zx-color-border-control);
+  border-radius: var(--zx-control-radius);
+  background: var(--zx-color-bg-control);
+}
+
+.zx-copy-input__box:focus-within {
+  border-color: var(--zx-color-accent);
+  box-shadow: var(--zx-focus-ring);
+}
+
+/* The box draws the control chrome, so the field inside it carries none of its own. */
+.zx-copy-input__field {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+  border: 0;
+  border-radius: 0;
+  background: none;
+  font-family: var(--zx-font-mono);
+  font-size: var(--zx-text-sm);
+  text-overflow: ellipsis;
+}
+
+.zx-copy-input__field:focus-visible {
+  outline: 0;
+  box-shadow: none;
+}
+
+.zx-copy-input[data-size="sm"] .zx-copy-input__field {
+  min-block-size: calc(var(--zx-control-height) - 4px);
+  font-size: var(--zx-text-xs);
+}

package/src/components/copy/copy-input.js

@@ -0,0 +1,123 @@
+import { Component } from '../../core/component.js';
+import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { uid } from '../../core/util.js';
+import { copyButton } from './copy-button.js';
+
+/**
+ * @typedef {Object} CopyInputOptions
+ * @property {string} [value=''] Text shown and copied.
+ * @property {string} [label=''] Visible label above the box.
+ * @property {boolean} [hideLabel=false] Whether the label is kept for assistive technology only.
+ * @property {string} [feedback='Copied'] Confirmation shown after a copy.
+ * @property {string} [buttonTitle='Copy'] Accessible name of the copy button.
+ * @property {'md'|'sm'} [size='md'] Control size.
+ * @property {(event: CustomEvent<{value: string, copied: boolean}>) => void} [oncopy] Copy listener.
+ */
+
+/**
+ * A read-only box holding a value to be copied — an API endpoint, a document number, a share link
+ * — with the copy button attached.
+ *
+ * The field is `readonly` rather than `disabled` so the text stays selectable and reachable by
+ * keyboard; focusing it selects the whole value, which is what someone reaching for Ctrl+C
+ * expects.
+ *
+ * @fires CopyInput#copy
+ * @extends {Component<CopyInputOptions>}
+ */
+export class CopyInput extends Component {
+  static cssName = 'copy-input';
+
+  /** @type {CopyInputOptions} */
+  static defaults = {
+    value: '',
+    label: '',
+    hideLabel: false,
+    feedback: 'Copied',
+    buttonTitle: 'Copy',
+    size: 'md'
+  };
+
+  /** @returns {HTMLElement} */
+  render() {
+    // render() runs inside the base constructor, before class-field initializers would run.
+    this._createdRoot = this.el === null;
+    this._snapshot = this._createdRoot ? null : snapshotTarget(this.el);
+
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this.el = root;
+    const id = uid('zx-copy-input');
+
+    const input = /** @type {HTMLInputElement} */ (h('input', {
+      ref: 'input',
+      class: 'zx-copy-input__field',
+      type: 'text',
+      id,
+      readOnly: true,
+      value: String(this.options.value ?? '')
+    }));
+    const button = copyButton({
+      text: () => this.get(),
+      title: String(this.options.buttonTitle),
+      feedback: String(this.options.feedback),
+      size: this.options.size === 'sm' ? 'sm' : 'md',
+      oncopy: (value, copied) => this.emit('copy', { value, copied })
+    });
+
+    root.replaceChildren(
+      h('label', { ref: 'label', class: 'zx-copy-input__label', for: id },
+        String(this.options.label ?? '')),
+      h('div', { class: 'zx-copy-input__box' }, input, button)
+    );
+    root.dataset.size = this.options.size === 'sm' ? 'sm' : 'md';
+    root.toggleAttribute('data-hide-label', Boolean(this.options.hideLabel));
+
+    this.listen(input, 'focus', () => input.select());
+    return root;
+  }
+
+  /**
+   * Returns the current value.
+   * @returns {string}
+   */
+  get() {
+    return this.refs.input.value;
+  }
+
+  /**
+   * Replaces the value.
+   * @param {string} value Text to show and copy.
+   * @returns {this}
+   */
+  set(value) {
+    this.refs.input.value = String(value ?? '');
+    return this;
+  }
+
+  /**
+   * Focuses the box and selects its contents.
+   *
+   * The selection is made here as well as in the `focus` listener: the listener covers a click or
+   * a Tab, but a programmatic `focus()` fires no focus event when the document itself is not
+   * focused, and the value would then be left uncopied under the caret.
+   * @returns {this}
+   */
+  focus() {
+    this.refs.input.focus();
+    this.refs.input.select();
+    return this;
+  }
+
+  /** Restores an enhanced target to the markup it had before the takeover. @returns {void} */
+  destroy() {
+    const root = this.el;
+    super.destroy();
+    if (!this._createdRoot && root) restoreTarget(root, this._snapshot);
+  }
+}
+
+/**
+ * Fired after a copy attempt; `copied` is false when the clipboard refused the write.
+ * @event CopyInput#copy
+ * @type {CustomEvent<{value: string, copied: boolean}>}
+ */

package/src/components/data-filter/data-filter.css

@@ -0,0 +1,53 @@
+.zx-data-filter {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: end;
+  gap: var(--zx-space-3);
+  padding: var(--zx-space-3);
+  border: 1px solid var(--zx-color-border);
+  border-radius: var(--zx-radius-md);
+  background: var(--zx-color-bg-surface);
+}
+
+.zx-data-filter__controls {
+  display: contents;
+}
+
+.zx-data-filter__field {
+  display: grid;
+  flex: 1 1 180px;
+  gap: var(--zx-space-1);
+  min-inline-size: 150px;
+}
+
+.zx-data-filter__field > input:not([type="checkbox"]):not([type="radio"]),
+.zx-data-filter__field > select {
+  inline-size: 100%;
+}
+
+.zx-data-filter__label {
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+  font-weight: 650;
+}
+
+.zx-data-filter__badge {
+  align-self: center;
+  min-inline-size: var(--zx-control-height);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-bg-selected);
+  color: var(--zx-color-accent);
+  padding: var(--zx-space-1) var(--zx-space-2);
+  font-size: var(--zx-text-sm);
+  font-weight: 650;
+  text-align: center;
+}
+
+.zx-data-filter__clear {
+  align-self: end;
+}
+
+.zx-data-filter__badge[hidden],
+.zx-data-filter__clear[hidden] {
+  display: none;
+}