@zeyos/zx 2.1.0 → 2.2.1

package/src/components/breadcrumb/breadcrumb.css

@@ -0,0 +1,105 @@
+/*
+ * Breadcrumb — the ancestor trail above a record or a browsed hierarchy.
+ *
+ * Ancestors are quiet (muted, no chrome until hovered) and the current page is the only thing at
+ * full strength, so the trail reads as context rather than as a row of buttons. Separators are
+ * decorative and hidden from assistive technology.
+ */
+
+.zx-breadcrumb {
+  min-inline-size: 0;
+}
+
+.zx-breadcrumb__list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--zx-space-1);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  font-size: var(--zx-text-sm);
+}
+
+.zx-breadcrumb__item {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-1);
+  min-inline-size: 0;
+}
+
+.zx-breadcrumb__separator {
+  display: inline-flex;
+  align-items: center;
+  color: var(--zx-color-text-placeholder);
+}
+
+.zx-breadcrumb__link {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  min-inline-size: 0;
+  min-block-size: 0;
+  border: 0;
+  border-radius: var(--zx-radius-md);
+  background: none;
+  padding: var(--zx-space-1) var(--zx-space-2);
+  color: var(--zx-color-text-muted);
+  font: inherit;
+  font-size: inherit;
+  font-weight: 500;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.zx-breadcrumb__link:hover {
+  background: var(--zx-color-bg-hover);
+  color: var(--zx-color-text);
+}
+
+.zx-breadcrumb__link:focus-visible {
+  outline: 0;
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-breadcrumb__current {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-2);
+  min-inline-size: 0;
+  padding: var(--zx-space-1) var(--zx-space-2);
+  color: var(--zx-color-text);
+  font-weight: 600;
+}
+
+.zx-breadcrumb__label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.zx-breadcrumb__icon {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  color: var(--zx-color-text-muted);
+}
+
+/* The collapsed-levels trigger is a MenuButton, shrunk to sit on the trail's baseline. */
+.zx-breadcrumb__more.zx-btn {
+  min-block-size: 0;
+  border-radius: var(--zx-radius-md);
+  padding: var(--zx-space-1) var(--zx-space-2);
+  color: var(--zx-color-text-muted);
+}
+
+.zx-breadcrumb__more .zx-btn__label:empty {
+  display: none;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-breadcrumb__link {
+    transition: color var(--zx-dur-fast) var(--zx-ease),
+      background-color var(--zx-dur-fast) var(--zx-ease);
+  }
+}

package/src/components/breadcrumb/breadcrumb.js

@@ -0,0 +1,331 @@
+import { Component } from '../../core/component.js';
+import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { printf } from '../../core/i18n.js';
+import { icon } from '../../core/icons.js';
+import { MenuButton } from '../menu-button/menu-button.js';
+
+/** @typedef {'chevron'|'slash'} BreadcrumbSeparator */
+
+/**
+ * @typedef {Object} BreadcrumbItem
+ * @property {string} name Stable item name, unique within the trail.
+ * @property {string} label Visible label.
+ * @property {string} [icon] Icon name passed to `icon()`, rendered before the label.
+ * @property {string} [href] Link destination; items without one render as buttons.
+ */
+
+/**
+ * @typedef {Object} NormalizedBreadcrumbItem
+ * @property {string} name Stable item name.
+ * @property {string} label Visible label.
+ * @property {string|null} icon Icon name, or null.
+ * @property {string|null} href Link destination, or null.
+ */
+
+/**
+ * @typedef {Object} BreadcrumbOptions
+ * @property {BreadcrumbItem[]} [items=[]] Trail from the root to the current page.
+ * @property {number} [maxVisible=0] Number of items rendered inline; 0 renders all of them.
+ *   Anything in between collapses into an ellipsis menu, always keeping the first and last item.
+ *   Values below 2 behave as 2.
+ * @property {BreadcrumbSeparator} [separator='chevron'] Glyph drawn between items.
+ * @property {string|null} [rootIcon=null] Icon for the first item when it carries none itself.
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
+ * @property {(event: CustomEvent<BreadcrumbSelectDetail>) => void} [onselect] Selection listener.
+ */
+
+/**
+ * @typedef {Object} BreadcrumbSelectDetail
+ * @property {string} name Selected item name.
+ * @property {NormalizedBreadcrumbItem} item Copy of the selected item.
+ * @property {number} index Zero-based index in the full trail, collapsed items included.
+ */
+
+/** Separator glyphs. */
+const SEPARATORS = new Set(['chevron', 'slash']);
+
+/**
+ * The trail of ancestors above the current page. Pairs with {@link Finder} and {@link TreeView}:
+ * feed `setItems()` from a `change` event's `nodes`, and turn a `select` back into a path.
+ *
+ * The last item is the page you are on, so it is plain text marked `aria-current="page"` and never
+ * interactive. Every other item is a real `<a>` when it carries an `href` — its navigation is left
+ * alone — and a `<button>` otherwise, for trails an application resolves in JavaScript.
+ * @fires Breadcrumb#select
+ * @extends {Component<BreadcrumbOptions>}
+ */
+export class Breadcrumb extends Component {
+  static cssName = 'breadcrumb';
+
+  /** @type {Readonly<BreadcrumbOptions>} */
+  static defaults = {
+    items: [],
+    maxVisible: 0,
+    separator: 'chevron',
+    rootIcon: null
+  };
+
+  /**
+   * Creates or enhances a breadcrumb trail.
+   * @param {Element|string|null} target Existing container, selector, or null.
+   * @param {BreadcrumbOptions} [options={}] Breadcrumb options.
+   */
+  constructor(target, options = {}) {
+    super(target, options);
+  }
+
+  /**
+   * Builds the trail. Runs inside the base constructor, so instance state is initialized here.
+   * @returns {HTMLElement}
+   */
+  render() {
+    this._createdRoot = this.el === null;
+    this._snapshot = this._createdRoot ? null : snapshotTarget(this.el);
+    this._destroyed = false;
+    /** @type {NormalizedBreadcrumbItem[]} */
+    this._items = [];
+    /** @type {MenuButton|null} */
+    this._overflow = null;
+
+    if (!SEPARATORS.has(this.options.separator)) {
+      throw new RangeError(`Unknown breadcrumb separator: ${this.options.separator}`);
+    }
+
+    const root = /** @type {HTMLElement} */ (this.el ?? h('nav'));
+    this.el = root;
+    if (root.tagName !== 'NAV') root.setAttribute('role', 'navigation');
+    root.setAttribute('aria-label', this._message('breadcrumb.label', 'Breadcrumb'));
+
+    const list = h('ol', { class: 'zx-breadcrumb__list', ref: 'list' });
+    root.replaceChildren(list);
+    this.setItems(this.options.items);
+
+    this.listen(list, 'click', (event) => {
+      const control = /** @type {Element} */ (event.target).closest?.('[data-crumb]');
+      if (!control || !list.contains(control)) return;
+      // A crumb with an href is an ordinary link: report the selection and let the browser follow.
+      this._select(/** @type {HTMLElement} */ (control).dataset.crumb);
+    });
+    return root;
+  }
+
+  /**
+   * Replaces the whole trail.
+   * @param {BreadcrumbItem[]} list Items from the root to the current page.
+   * @returns {this}
+   * @throws {TypeError} When the list or an item is malformed.
+   * @throws {RangeError} When two items share a name.
+   */
+  setItems(list) {
+    if (!Array.isArray(list)) throw new TypeError('Breadcrumb items must be an array');
+    const names = new Set();
+    this._items = list.map((item) => {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) {
+        throw new TypeError('Breadcrumb item must be an object');
+      }
+      if (typeof item.name !== 'string' || item.name === '') {
+        throw new TypeError('Breadcrumb item name must be a non-empty string');
+      }
+      if (names.has(item.name)) throw new RangeError(`Breadcrumb item already exists: ${item.name}`);
+      names.add(item.name);
+      return {
+        name: item.name,
+        label: String(item.label ?? ''),
+        icon: item.icon ? String(item.icon) : null,
+        href: item.href == null ? null : String(item.href)
+      };
+    });
+    this._build();
+    return this;
+  }
+
+  /**
+   * Returns a copy of the trail.
+   * @returns {NormalizedBreadcrumbItem[]}
+   */
+  getItems() {
+    return this._items.map((item) => ({ ...item }));
+  }
+
+  /**
+   * Appends one level, which becomes the current page.
+   * @param {BreadcrumbItem} item Item to append.
+   * @returns {this}
+   */
+  push(item) {
+    return this.setItems([...this._items, item]);
+  }
+
+  /**
+   * Removes the deepest level.
+   * @returns {NormalizedBreadcrumbItem|null} The removed item, or null when the trail was empty.
+   */
+  pop() {
+    if (this._items.length === 0) return null;
+    const removed = this._items[this._items.length - 1];
+    this.setItems(this._items.slice(0, -1));
+    return removed;
+  }
+
+  /**
+   * Drops every level below a named item, making it the current page.
+   * @param {string} name Item name.
+   * @returns {this}
+   * @throws {RangeError} When no item carries that name.
+   */
+  truncateTo(name) {
+    const index = this._items.findIndex((item) => item.name === name);
+    if (index < 0) throw new RangeError(`Unknown breadcrumb item: ${name}`);
+    return this.setItems(this._items.slice(0, index + 1));
+  }
+
+  /**
+   * Destroys the overflow menu, aborts listeners, and restores an enhanced target.
+   * @returns {void}
+   */
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this._overflow?.destroy();
+    this._overflow = null;
+    const root = this.el;
+    super.destroy();
+    if (!this._createdRoot && root) restoreTarget(root, this._snapshot);
+  }
+
+  /* ------------------------------------------------------------------ internals -- */
+
+  /**
+   * Rebuilds the list from the current items.
+   * @returns {void}
+   */
+  _build() {
+    const { head, hidden, tail } = this._split();
+    const last = this._items[this._items.length - 1] ?? null;
+    /** @type {HTMLElement[]} */
+    const entries = [];
+
+    for (const item of head) entries.push(this._renderItem(item, item === last));
+    if (hidden.length > 0) entries.push(this._renderOverflow(hidden));
+    for (const item of tail) entries.push(this._renderItem(item, item === last));
+
+    this.refs.list.replaceChildren(...entries.map((content, index) => h('li', {
+      class: 'zx-breadcrumb__item'
+    }, index === 0 ? content : [this._renderSeparator(), content])));
+    if (hidden.length === 0) this._overflow?.toElement().remove();
+  }
+
+  /**
+   * Splits the trail into the inline head, the collapsed middle, and the inline tail.
+   * @returns {{head: NormalizedBreadcrumbItem[], hidden: NormalizedBreadcrumbItem[], tail: NormalizedBreadcrumbItem[]}}
+   */
+  _split() {
+    const items = this._items;
+    const max = Math.trunc(Number(this.options.maxVisible) || 0);
+    if (max <= 0 || items.length <= max) return { head: items, hidden: [], tail: [] };
+    // Collapsing needs at least the first and the last item to survive.
+    const visible = Math.max(2, max);
+    if (items.length <= visible) return { head: items, hidden: [], tail: [] };
+    const tailCount = visible - 1;
+    return {
+      head: items.slice(0, 1),
+      hidden: items.slice(1, items.length - tailCount),
+      tail: items.slice(items.length - tailCount)
+    };
+  }
+
+  /**
+   * @param {NormalizedBreadcrumbItem} item Item to render.
+   * @param {boolean} current Whether this is the page the user is on.
+   * @returns {HTMLElement}
+   */
+  _renderItem(item, current) {
+    const children = [];
+    const glyph = item.icon ?? (item === this._items[0] ? this.options.rootIcon : null);
+    if (glyph) {
+      children.push(h('span', { class: 'zx-breadcrumb__icon', ariaHidden: 'true' },
+        icon(String(glyph), { size: 13 })));
+    }
+    children.push(h('span', { class: 'zx-breadcrumb__label' }, item.label));
+
+    if (current) {
+      return h('span', { class: 'zx-breadcrumb__current', ariaCurrent: 'page' }, children);
+    }
+    if (item.href !== null) {
+      return h('a', {
+        class: 'zx-breadcrumb__link',
+        href: item.href,
+        dataset: { crumb: item.name }
+      }, children);
+    }
+    return h('button', {
+      class: 'zx-breadcrumb__link',
+      type: 'button',
+      dataset: { crumb: item.name }
+    }, children);
+  }
+
+  /**
+   * Renders (and, on first use, creates) the ellipsis menu holding the collapsed levels. The
+   * MenuButton is kept for the component's lifetime because its dropdown panel lives on
+   * `document.body`; rebuilding the trail only refills its items.
+   * @param {NormalizedBreadcrumbItem[]} hidden Collapsed items.
+   * @returns {HTMLElement}
+   */
+  _renderOverflow(hidden) {
+    if (!this._overflow) {
+      this._overflow = new MenuButton(null, {
+        label: '',
+        icon: 'dots',
+        kind: 'ghost',
+        placement: 'bottom-start'
+      });
+      const trigger = this._overflow.toElement();
+      trigger.classList.add('zx-breadcrumb__more');
+      trigger.setAttribute('aria-label', this._message('breadcrumb.more', 'Show hidden levels'));
+      this._overflow.on('select', (event) => this._select(String(event.detail.value)));
+    }
+    this._overflow.setItems(hidden.map((item) => ({
+      label: item.label,
+      value: item.name,
+      icon: item.icon ?? undefined
+    })));
+    return /** @type {HTMLElement} */ (this._overflow.toElement());
+  }
+
+  /** @returns {HTMLElement} */
+  _renderSeparator() {
+    return h('span', { class: 'zx-breadcrumb__separator', ariaHidden: 'true' },
+      this.options.separator === 'slash' ? '/' : icon('chevron-right', { size: 11 }));
+  }
+
+  /**
+   * @param {string|undefined} name Item name from a control's `data-crumb`.
+   * @returns {void}
+   * @fires Breadcrumb#select
+   */
+  _select(name) {
+    const index = this._items.findIndex((item) => item.name === name);
+    if (index < 0) return;
+    this.emit('select', { name: this._items[index].name, item: { ...this._items[index] }, index });
+  }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @param {string} key Message key.
+   * @param {string} fallback Built-in text, with `%1`-style placeholders.
+   * @param {...unknown} args Interpolation values.
+   * @returns {string}
+   */
+  _message(key, fallback, ...args) {
+    const message = this.msg(key, ...args);
+    return message === key ? printf(fallback, args) : message;
+  }
+}
+
+/**
+ * Fired when an interactive crumb is chosen, from the trail itself or from the overflow menu. A
+ * crumb with an `href` still navigates: the event reports the choice, it does not gate it.
+ * @event Breadcrumb#select
+ * @type {CustomEvent<BreadcrumbSelectDetail>}
+ */

package/src/components/button/button.css

@@ -0,0 +1,104 @@
+.zx-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--zx-space-2);
+  min-block-size: var(--zx-control-height);
+  border: 1px solid var(--zx-color-border-control);
+  border-radius: var(--zx-button-radius, var(--zx-control-radius));
+  background: var(--zx-color-bg-control);
+  color: var(--zx-color-text);
+  padding-inline: var(--zx-control-pad-x);
+  font: inherit;
+  font-size: var(--zx-control-font-size);
+  font-weight: var(--zx-control-font-weight);
+  line-height: 1;
+  cursor: pointer;
+  transition: color var(--zx-dur-fast) var(--zx-ease),
+    background-color var(--zx-dur-fast) var(--zx-ease),
+    border-color var(--zx-dur-fast) var(--zx-ease),
+    box-shadow var(--zx-dur-fast) var(--zx-ease);
+}
+
+.zx-btn:hover:not(:disabled) {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-btn:active:not(:disabled) {
+  border-color: var(--zx-color-border-strong);
+}
+
+.zx-btn:focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-btn:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.zx-btn[data-kind="primary"] {
+  border-color: var(--zx-color-accent);
+  background: var(--zx-color-accent);
+  color: var(--zx-color-on-accent);
+}
+
+.zx-btn[data-kind="primary"]:hover:not(:disabled) {
+  border-color: var(--zx-color-accent-hover);
+  background: var(--zx-color-accent-hover);
+}
+
+.zx-btn[data-kind="primary"]:active:not(:disabled) {
+  border-color: var(--zx-color-accent-active);
+  background: var(--zx-color-accent-active);
+}
+
+.zx-btn[data-kind="danger"] {
+  border-color: var(--zx-color-danger);
+  background: var(--zx-color-danger);
+  color: var(--zx-color-on-accent);
+}
+
+.zx-btn[data-kind="danger"]:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--zx-color-danger) 88%, var(--zx-color-text));
+}
+
+.zx-btn[data-kind="ghost"] {
+  border-color: transparent;
+  background: none;
+}
+
+.zx-btn[data-kind="ghost"]:hover:not(:disabled) {
+  border-color: transparent;
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-btn[data-size="sm"] {
+  min-block-size: calc(var(--zx-control-height) - var(--zx-space-1));
+  padding-inline: var(--zx-space-2);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-btn > svg,
+.zx-btn > .zx-icon {
+  flex: none;
+}
+
+.zx-btn-group {
+  display: inline-flex;
+}
+
+.zx-btn-group > .zx-btn:not(:first-child) {
+  margin-inline-start: -1px;
+  border-start-start-radius: 0;
+  border-end-start-radius: 0;
+}
+
+.zx-btn-group > .zx-btn:not(:last-child) {
+  border-start-end-radius: 0;
+  border-end-end-radius: 0;
+}
+
+.zx-btn-group > .zx-btn:focus-visible {
+  z-index: 1;
+}

package/src/components/button/button.js

@@ -0,0 +1,76 @@
+import { h } from '../../core/dom.js';
+import { icon as createIcon } from '../../core/icons.js';
+
+/**
+ * @typedef {Object} ButtonOptions
+ * @property {string} [label=''] Visible button label.
+ * @property {string|null} [icon=null] Icon name from `icons.js`.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Visual intent.
+ * @property {'md'|'sm'} [size='md'] Control size.
+ * @property {boolean} [disabled=false] Whether the button is disabled.
+ * @property {string} [title] Native title text.
+ * @property {(event: MouseEvent) => void} [onclick] Click callback.
+ */
+
+/** @type {Readonly<ButtonOptions>} */
+const defaults = Object.freeze({
+  label: '',
+  icon: null,
+  kind: 'default',
+  size: 'md',
+  disabled: false
+});
+
+/**
+ * Creates a styled native button.
+ * @param {ButtonOptions} [opts={}] Button options.
+ * @returns {HTMLButtonElement}
+ */
+export function button(opts = {}) {
+  const options = { ...defaults, ...opts };
+  const element = /** @type {HTMLButtonElement} */ (h('button', {
+    class: 'zx-btn',
+    type: 'button',
+    disabled: Boolean(options.disabled),
+    title: options.title,
+    dataset: {
+      kind: normalizeKind(options.kind),
+      size: normalizeSize(options.size)
+    }
+  }));
+
+  if (options.icon) {
+    element.append(createIcon(options.icon, { size: 16 }));
+  }
+  if (options.label !== '') {
+    element.append(h('span', { class: 'zx-btn__label' }, String(options.label)));
+  }
+  if (!options.label && options.title) element.setAttribute('aria-label', options.title);
+  if (typeof options.onclick === 'function') element.onclick = options.onclick;
+  return element;
+}
+
+/**
+ * Groups buttons into a joined control.
+ * @param {HTMLButtonElement[]} buttons Buttons to group.
+ * @returns {HTMLDivElement}
+ */
+export function buttonGroup(buttons) {
+  const group = /** @type {HTMLDivElement} */ (h('div', {
+    class: 'zx-btn-group',
+    role: 'group'
+  }));
+  group.append(...buttons);
+  return group;
+}
+
+/** @param {unknown} value @returns {'default'|'primary'|'danger'|'ghost'} */
+function normalizeKind(value) {
+  return ['primary', 'danger', 'ghost'].includes(String(value)) ?
+    /** @type {'primary'|'danger'|'ghost'} */ (value) : 'default';
+}
+
+/** @param {unknown} value @returns {'md'|'sm'} */
+function normalizeSize(value) {
+  return value === 'sm' ? 'sm' : 'md';
+}

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

@@ -0,0 +1,66 @@
+.zx-check-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--zx-space-2);
+  min-block-size: var(--zx-control-height);
+  border: 1px solid var(--zx-color-border-control);
+  border-radius: var(--zx-control-radius);
+  background: var(--zx-color-bg-control);
+  color: var(--zx-color-text);
+  padding-inline: var(--zx-control-pad-x);
+  font: inherit;
+  font-size: var(--zx-control-font-size);
+  cursor: pointer;
+}
+
+.zx-check-button:hover:not(:disabled) {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-check-button[aria-pressed="true"] {
+  border-color: var(--zx-color-accent);
+  background: var(--zx-color-bg-selected);
+  color: var(--zx-color-accent);
+}
+
+.zx-check-button:focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-check-button:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+/* Both glyphs occupy the same grid cell, so swapping them never shifts the label. */
+.zx-check-button__icon {
+  display: inline-grid;
+  flex: none;
+  grid-template-areas: "state";
+  place-items: center;
+}
+
+.zx-check-button__off,
+.zx-check-button__on {
+  display: inline-grid;
+  grid-area: state;
+  place-items: center;
+}
+
+.zx-check-button__off {
+  color: var(--zx-color-text-muted);
+}
+
+.zx-check-button__on,
+.zx-check-button[aria-pressed="true"] .zx-check-button__off {
+  visibility: hidden;
+}
+
+.zx-check-button[aria-pressed="true"] .zx-check-button__on {
+  visibility: visible;
+}
+
+.zx-check-button__icon .zx-icon {
+  display: block;
+}