@zeyos/zx 2.1.0 → 2.2.0

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

@@ -0,0 +1,167 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+import { icon } from '../../core/icons.js';
+
+/**
+ * @typedef {Object} CheckButtonOptions
+ * @property {string|[string, string]} [label=''] A shared label or `[onLabel, offLabel]`.
+ * @property {boolean} [checked=false] Initial pressed state.
+ * @property {boolean} [icon=true] Whether to show the check indicator.
+ * @property {boolean} [disabled=false] Initial disabled state.
+ * @property {(event: CustomEvent<{checked: boolean}>) => void} [onchange] Change callback.
+ */
+
+/**
+ * Two-state native press button.
+ * @fires CheckButton#change
+ * @extends {Component<CheckButtonOptions>}
+ */
+export class CheckButton extends Component {
+  static cssName = 'check-button';
+
+  /** @type {Readonly<CheckButtonOptions>} */
+  static defaults = {
+    label: '',
+    checked: false,
+    icon: true,
+    disabled: false
+  };
+
+  /** @returns {HTMLButtonElement} */
+  render() {
+    const created = !this.el;
+    const root = /** @type {HTMLButtonElement} */ (this.el ?? h('button'));
+    this.el = root;
+    if (root.localName !== 'button') {
+      throw new TypeError('CheckButton target must be a button element');
+    }
+
+    this._createdRoot = created;
+    this._original = created ? null : snapshot(root);
+    this._checked = Boolean(this.options.checked);
+    this._disabled = Boolean(this.options.disabled);
+    this._labels = normalizeLabels(this.options.label);
+    root.type = 'button';
+    const children = [];
+    if (this.options.icon) {
+      // Both states carry a glyph — an empty box when off, a check when on — so the control still
+      // reads as a two-state control while pressed, unpressed, or disabled.
+      children.push(h('span', { class: 'zx-check-button__icon', ariaHidden: 'true' },
+        h('span', { class: 'zx-check-button__off' }, icon('square', { size: 15 })),
+        h('span', { class: 'zx-check-button__on' }, icon('check', { size: 15 }))));
+    }
+    children.push(h('span', { class: 'zx-check-button__label', ref: 'label' }));
+    root.replaceChildren(...children);
+    this._sync();
+    this.listen(root, 'click', () => this.toggle());
+    return root;
+  }
+
+  /**
+   * Returns the current pressed state.
+   * @returns {boolean}
+   */
+  get() {
+    return this._checked;
+  }
+
+  /**
+   * Sets the pressed state.
+   * @param {boolean} checked Next state.
+   * @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
+   * @returns {this}
+   * @fires CheckButton#change
+   */
+  set(checked, { silent = false } = {}) {
+    const next = Boolean(checked);
+    if (next === this._checked) return this;
+    this._checked = next;
+    this._sync();
+    if (!silent) this.emit('change', { checked: this._checked });
+    return this;
+  }
+
+  /**
+   * Toggles the pressed state.
+   * @returns {this}
+   * @fires CheckButton#change
+   */
+  toggle() {
+    return this.set(!this._checked);
+  }
+
+  /**
+   * Replaces the state labels.
+   * @param {string|[string, string]} label A shared label or `[onLabel, offLabel]`.
+   * @returns {this}
+   */
+  setLabel(label) {
+    this._labels = normalizeLabels(label);
+    this._sync();
+    return this;
+  }
+
+  /**
+   * Enables user interaction.
+   * @returns {this}
+   */
+  enable() {
+    this._disabled = false;
+    this.el.removeAttribute('disabled');
+    return this;
+  }
+
+  /**
+   * Disables user interaction.
+   * @returns {this}
+   */
+  disable() {
+    this._disabled = true;
+    this.el.setAttribute('disabled', '');
+    return this;
+  }
+
+  /** @returns {void} */
+  destroy() {
+    if (this._cleaned) return;
+    this._cleaned = true;
+    super.destroy();
+    if (!this._createdRoot && this._original) restore(this.el, this._original);
+  }
+
+  /** @returns {void} */
+  _sync() {
+    this.el.setAttribute('aria-pressed', String(this._checked));
+    this.el.toggleAttribute('disabled', this._disabled);
+    this.refs.label.textContent = this._checked ? this._labels.on : this._labels.off;
+  }
+}
+
+/**
+ * Change emitted after a real state transition.
+ * @event CheckButton#change
+ * @type {CustomEvent<{checked: boolean}>}
+ */
+
+/** @param {string|[string, string]} label @returns {{on: string, off: string}} */
+function normalizeLabels(label) {
+  if (Array.isArray(label)) {
+    return { on: String(label[0] ?? ''), off: String(label[1] ?? '') };
+  }
+  return { on: String(label ?? ''), off: String(label ?? '') };
+}
+
+/** @param {Element} element @returns {{attributes: [string, string][], children: Node[]}} */
+function snapshot(element) {
+  return {
+    attributes: Array.from(element.attributes, (attribute) => [attribute.name, attribute.value]),
+    children: Array.from(element.childNodes)
+  };
+}
+
+/** @param {Element} element @param {{attributes: [string, string][], children: Node[]}} state */
+function restore(element, state) {
+  for (const attribute of Array.from(element.attributes)) element.removeAttribute(attribute.name);
+  for (const [name, value] of state.attributes) element.setAttribute(name, value);
+  element.replaceChildren(...state.children);
+}

package/src/components/checklist/checklist.css

@@ -0,0 +1,65 @@
+.zx-checklist {
+  display: grid;
+  gap: var(--zx-space-2);
+  min-inline-size: 0;
+  color: var(--zx-color-text);
+  font-size: var(--zx-control-font-size);
+}
+
+.zx-checklist__label {
+  font-weight: 650;
+}
+
+.zx-checklist__search {
+  inline-size: 100%;
+}
+
+.zx-checklist__search[hidden] {
+  display: none;
+}
+
+.zx-checklist__list {
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  border: 1px solid var(--zx-color-border);
+  border-radius: var(--zx-radius-md);
+  background: var(--zx-color-bg-surface);
+  padding: var(--zx-space-1);
+}
+
+.zx-checklist__item {
+  display: flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  min-block-size: var(--zx-control-height);
+  border-radius: var(--zx-radius-sm);
+  cursor: pointer;
+  padding: var(--zx-space-1) var(--zx-space-2);
+}
+
+.zx-checklist__item:hover {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-checklist__item:has(input:checked) {
+  background: var(--zx-color-bg-selected);
+}
+
+.zx-checklist__item input {
+  flex: none;
+  accent-color: var(--zx-color-accent);
+}
+
+.zx-checklist__item:has(input:focus-visible) {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-checklist__empty {
+  color: var(--zx-color-text-muted);
+  padding: var(--zx-space-3);
+  text-align: center;
+}
+
+.zx-checklist[data-state="loading"] .zx-checklist__list {
+  color: var(--zx-color-text-muted);
+}

package/src/components/checklist/checklist.js

@@ -0,0 +1,282 @@
+import { Component } from '../../core/component.js';
+import { h } from '../../core/dom.js';
+import { uid } from '../../core/util.js';
+import { matchItems } from '../select/filter.js';
+
+/** @typedef {Record<string, any>|string|number|boolean|symbol|bigint|null|undefined} ChecklistItem */
+/**
+ * @typedef {Object} ChecklistOptions
+ * @property {ChecklistItem[]} [items=[]] Available checkbox items.
+ * @property {string|((item: ChecklistItem) => unknown)} [valueKey='ID'] Item ID property or reader.
+ * @property {string|((item: ChecklistItem) => string)} [labelKey='name'] Item label property or reader.
+ * @property {string|((item: ChecklistItem) => unknown)} [checkedKey='on'] Initial checked-state property or reader.
+ * @property {boolean} [search=true] Whether the search field is shown.
+ * @property {number} [height=280] Maximum list height in pixels.
+ * @property {boolean} [defaultChecked=false] Fallback initial checked state.
+ * @property {(() => Promise<ChecklistItem[]>|ChecklistItem[])|null} [load=null] Async item loader.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<ChecklistChangeDetail>) => void} [onchange] Change listener.
+ * @property {(event: CustomEvent<ChecklistLoadedDetail>) => void} [onloaded] Loaded listener.
+ */
+/** @typedef {{values: unknown[]}} ChecklistChangeDetail */
+/** @typedef {{items: ChecklistItem[]}} ChecklistLoadedDetail */
+
+/**
+ * Searchable native-checkbox group.
+ *
+ * @fires Checklist#change
+ * @fires Checklist#loaded
+ * @extends {Component<ChecklistOptions>}
+ */
+export class Checklist extends Component {
+  static cssName = 'checklist';
+
+  /** @type {ChecklistOptions} */
+  static defaults = {
+    items: [],
+    valueKey: 'ID',
+    labelKey: 'name',
+    checkedKey: 'on',
+    search: true,
+    height: 280,
+    defaultChecked: false,
+    load: null
+  };
+
+
+  /** @returns {HTMLElement} */
+  render() {
+    // Instance state initialized here because render() runs inside the base
+    // constructor, before class-field initializers would run (and clobber it).
+    this._items = []; this._visibleItems = []; this._checked = new Set(); this._query = ''; this._loadSequence = 0; this._createdRoot = false; this._active = true; this._originalChildren = []; this._originalAttributes = new Map();
+    this._createdRoot = this.el === null;
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this.el = root;
+    if (!this._createdRoot) this._originalChildren = Array.from(root.childNodes);
+    for (const name of ['role', 'aria-labelledby', 'data-state']) {
+      this._originalAttributes.set(name, root.getAttribute(name));
+    }
+
+    const labelId = uid('zx-checklist-label');
+    const title = h('div', {
+      class: 'zx-checklist__label',
+      id: labelId
+    }, this._message('checklist.label', 'Checklist'));
+    const search = h('input', {
+      ref: 'search',
+      class: 'zx-checklist__search',
+      type: 'search',
+      autocomplete: 'off',
+      placeholder: this._message('checklist.search', 'Search'),
+      ariaLabel: this._message('checklist.search', 'Search checklist'),
+      hidden: !this.options.search
+    });
+    const list = h('div', {
+      ref: 'list',
+      class: 'zx-checklist__list'
+    });
+    list.style.maxBlockSize = `${Math.max(0, Number(this.options.height) || 0)}px`;
+    root.replaceChildren(title, search, list);
+    root.setAttribute('role', 'group');
+    root.setAttribute('aria-labelledby', labelId);
+
+    this.listen(search, 'input', () => this.search(/** @type {HTMLInputElement} */ (search).value));
+    this.listen(list, 'change', (event) => {
+      const input = /** @type {HTMLInputElement|null} */ (event.target);
+      if (!input?.matches?.('input[type="checkbox"][data-index]')) return;
+      const item = this._visibleItems[Number(input.dataset.index)];
+      if (item === undefined) return;
+      const value = this._itemValue(item);
+      if (input.checked) this._checked.add(value);
+      else this._checked.delete(value);
+      this.emit('change', { values: this.getValues() });
+    });
+
+    this._replaceItems(this.options.items);
+    if (typeof this.options.load === 'function') {
+      queueMicrotask(() => {
+        if (this._active) void this.reload().catch(() => {});
+      });
+    }
+    return root;
+  }
+
+  /**
+   * Replaces items and derives checked state from `checkedKey` and `defaultChecked`.
+   * @param {ChecklistItem[]} items New items.
+   * @returns {this}
+   */
+  setItems(items) {
+    this._replaceItems(items);
+    return this;
+  }
+
+  /** Returns checked IDs in item order. @returns {unknown[]} */
+  getValues() {
+    return this._items
+      .map((item) => this._itemValue(item))
+      .filter((value) => this._checked.has(value));
+  }
+
+  /**
+   * Replaces the checked IDs.
+   * @param {Iterable<unknown>|unknown[]} ids Checked item IDs.
+   * @returns {this}
+   * @fires Checklist#change
+   */
+  setValues(ids) {
+    const requested = new Set(ids == null ? [] : Array.from(ids));
+    const next = new Set(this._items
+      .map((item) => this._itemValue(item))
+      .filter((value) => requested.has(value)));
+    this._replaceChecked(next);
+    return this;
+  }
+
+  /** Checks every item. @returns {this} @fires Checklist#change */
+  checkAll() {
+    this._replaceChecked(new Set(this._items.map((item) => this._itemValue(item))));
+    return this;
+  }
+
+  /** Unchecks every item. @returns {this} @fires Checklist#change */
+  uncheckAll() {
+    this._replaceChecked(new Set());
+    return this;
+  }
+
+  /**
+   * Filters visible items by label.
+   * @param {string} query Search text.
+   * @returns {this}
+   */
+  search(query) {
+    this._query = String(query ?? '');
+    const input = /** @type {HTMLInputElement} */ (this.refs.search);
+    if (input.value !== this._query) input.value = this._query;
+    this._visibleItems = matchItems(this._items, this._query, [this.options.labelKey]);
+    this._renderItems();
+    return this;
+  }
+
+  /**
+   * Reloads items through the configured async loader.
+   * @returns {Promise<this>}
+   * @fires Checklist#loaded
+   */
+  async reload() {
+    if (!this._active || typeof this.options.load !== 'function') return this;
+    const sequence = ++this._loadSequence;
+    this.el.setAttribute('data-state', 'loading');
+    this.refs.list.setAttribute('aria-busy', 'true');
+    try {
+      const items = await this.options.load();
+      if (sequence !== this._loadSequence) return this;
+      this._replaceItems(items);
+      this.emit('loaded', { items: this._items.slice() });
+    } finally {
+      if (sequence === this._loadSequence) {
+        this.el.removeAttribute('data-state');
+        this.refs.list.setAttribute('aria-busy', 'false');
+      }
+    }
+    return this;
+  }
+
+  /** Restores an enhanced target and invalidates pending loads. @returns {void} */
+  destroy() {
+    this._active = false;
+    this._loadSequence += 1;
+    const root = /** @type {HTMLElement} */ (this.el);
+    if (!this._createdRoot && root) {
+      root.replaceChildren(...this._originalChildren);
+      for (const [name, value] of this._originalAttributes) {
+        if (value === null) root.removeAttribute(name);
+        else root.setAttribute(name, value);
+      }
+    }
+    super.destroy();
+  }
+
+  /** @param {ChecklistItem[]} items @returns {void} */
+  _replaceItems(items) {
+    this._items = Array.isArray(items) ? items.slice() : [];
+    this._checked = new Set(this._items
+      .filter((item) => Boolean(this._initialChecked(item)))
+      .map((item) => this._itemValue(item)));
+    this._visibleItems = matchItems(this._items, this._query, [this.options.labelKey]);
+    this._renderItems();
+  }
+
+  /** @returns {void} */
+  _renderItems() {
+    if (!this.refs.list) return;
+    const rows = this._visibleItems.map((item, index) => {
+      const checkboxId = uid('zx-checklist-item');
+      const input = h('input', {
+        type: 'checkbox',
+        id: checkboxId,
+        checked: this._checked.has(this._itemValue(item)),
+        dataset: { index }
+      });
+      return h('label', {
+        class: 'zx-checklist__item',
+        for: checkboxId
+      }, input, h('span', {}, this._itemLabel(item)));
+    });
+    if (rows.length === 0) {
+      rows.push(h('div', {
+        class: 'zx-checklist__empty',
+        role: 'status'
+      }, this._message('checklist.empty', 'No matches')));
+    }
+    this.refs.list.replaceChildren(...rows);
+  }
+
+  /** @param {Set<unknown>} next @returns {void} */
+  _replaceChecked(next) {
+    if (setsEqual(this._checked, next)) return;
+    this._checked = next;
+    this._renderItems();
+    this.emit('change', { values: this.getValues() });
+  }
+
+  /** @param {ChecklistItem} item @returns {unknown} */
+  _itemValue(item) {
+    return this._read(item, this.options.valueKey);
+  }
+
+  /** @param {ChecklistItem} item @returns {string} */
+  _itemLabel(item) {
+    return String(this._read(item, this.options.labelKey) ?? '');
+  }
+
+  /** @param {ChecklistItem} item @returns {unknown} */
+  _initialChecked(item) {
+    let value;
+    if (typeof this.options.checkedKey === 'function') value = this.options.checkedKey(item);
+    else if (item !== null && typeof item === 'object') value = item[this.options.checkedKey];
+    return value == null ? this.options.defaultChecked : value;
+  }
+
+  /** @param {ChecklistItem} item @param {string|((item: ChecklistItem) => unknown)} reader @returns {unknown} */
+  _read(item, reader) {
+    if (typeof reader === 'function') return reader(item);
+    if (item === null || typeof item !== 'object') return item;
+    return item[reader];
+  }
+
+  /** @param {string} key @param {string} fallback @returns {string} */
+  _message(key, fallback) {
+    const message = this.msg(key);
+    return message === key ? fallback : message;
+  }
+}
+
+/** Checked-value change. @event Checklist#change @type {CustomEvent<ChecklistChangeDetail>} */
+/** Async-load completion. @event Checklist#loaded @type {CustomEvent<ChecklistLoadedDetail>} */
+
+/** @param {Set<unknown>} left @param {Set<unknown>} right @returns {boolean} */
+function setsEqual(left, right) {
+  return left.size === right.size && Array.from(left).every((value) => right.has(value));
+}

package/src/components/checklist/field-adapter.js

@@ -0,0 +1,46 @@
+import { Field } from '../field/field.js';
+import { Checklist } from './checklist.js';
+
+/**
+ * Registers the Checklist-backed `checklist` field type.
+ * @returns {void}
+ */
+export function registerChecklistFieldAdapter() {
+  Field.register('checklist', (field, options) => {
+    const checklist = field.own(new Checklist(null, { ...(options.props ?? {}) }));
+    let disabled = false;
+    let setting = false;
+    const syncDisabled = () => {
+      checklist.el.setAttribute('aria-disabled', String(disabled));
+      for (const control of checklist.el.querySelectorAll('input, button, select, textarea')) {
+        control.disabled = disabled;
+      }
+    };
+    field.listen(checklist.el, 'change', (event) => event.stopImmediatePropagation());
+    checklist.on('change', (event) => {
+      if (!setting) field.emit('change', { value: event.detail.values });
+    });
+    checklist.on('loaded', syncDisabled);
+    return {
+      el: checklist.el,
+      get: () => checklist.getValues(),
+      set: (value) => {
+        setting = true;
+        try {
+          checklist.setValues(Array.isArray(value) ? value : []);
+        } finally {
+          setting = false;
+        }
+        syncDisabled();
+      },
+      focus: () => {
+        const search = checklist.el.querySelector('.zx-checklist__search:not([hidden]):not([disabled])');
+        (search ?? checklist.el.querySelector('input[type="checkbox"]:not([disabled])'))?.focus();
+      },
+      setDisabled: (value) => {
+        disabled = Boolean(value);
+        syncDisabled();
+      }
+    };
+  });
+}

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

@@ -0,0 +1,54 @@
+/*
+ * The anchor is a zero-sized element parked at the pointer, not a visible part of the menu: the
+ * panel positions against it exactly as a Dropdown positions against its trigger, so a menu opened
+ * at the pointer flips near a viewport edge like every other floating panel in the library.
+ */
+.zx-context-menu__anchor {
+  position: fixed;
+  inline-size: 0;
+  block-size: 0;
+  pointer-events: none;
+}
+
+.zx-context-menu {
+  min-inline-size: 180px;
+  padding: var(--zx-space-1);
+}
+
+.zx-context-menu__item {
+  display: flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  inline-size: 100%;
+  min-block-size: var(--zx-control-height);
+  border-color: var(--zx-color-bg-raised);
+  background: var(--zx-color-bg-raised);
+  padding-inline: var(--zx-control-pad-x);
+  text-align: start;
+}
+
+.zx-context-menu__item:hover,
+.zx-context-menu__item:focus-visible {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-context-menu__item[data-danger="true"] {
+  color: var(--zx-color-danger);
+}
+
+.zx-context-menu__item[aria-disabled="true"] {
+  color: var(--zx-color-text-muted);
+  cursor: not-allowed;
+  opacity: 0.65;
+}
+
+.zx-context-menu__icon {
+  display: inline-flex;
+  flex: none;
+}
+
+.zx-context-menu__separator {
+  block-size: 1px;
+  margin: var(--zx-space-1) var(--zx-space-2);
+  background: var(--zx-color-border);
+}