@zeyos/zx 4.3.0 → 4.4.0

package/src/components/navigation-bar/navigation-bar.js

@@ -35,9 +35,29 @@ import { MenuButton } from '../menu-button/menu-button.js';
  * @property {NavigationItem[]} [items=[]] Navigation items.
  * @property {string|null} [active=null] Initially active item, or the first enabled item.
  * @property {NavigationAction[]} [actions=[]] Right-aligned action elements or descriptors.
+ * @property {boolean} [overflow=true] Whether items collapse into the overflow menu at all.
+ *   `false` keeps every item in the bar at every width and never shows the More button.
+ * @property {string|number|false} [overflowBelow='44rem'] Container inline size at or below which
+ *   items collapse, as a `px` or `rem` length (a number is read as `px`); `false` disables
+ *   collapsing exactly as `overflow: false` does. The default is the threshold the stylesheet's
+ *   own container query carries, and a bar that keeps it collapses in CSS without measuring
+ *   itself; any other value is watched with a `ResizeObserver`.
+ * @property {number} [minVisible=0] How many items, counted from the start, never collapse. The
+ *   default collapses all of them, which is right for a top app bar and wrong for a phone bottom
+ *   bar — `minVisible: 4` is what makes that bar usable.
  * @property {(event: CustomEvent<{name: string}>) => void} [onchange] Change callback.
  */
 
+/**
+ * The container width `navigation-bar.css` collapses at. A bar that keeps this exact threshold is
+ * served by the stylesheet's container query, so it needs no measurement and no script at all;
+ * anything else has to be watched. Keep it in step with the `@container` rule.
+ */
+export const OVERFLOW_BELOW = '44rem';
+
+/** The lengths a threshold may be written in — the two a `ResizeObserver` can resolve alone. */
+const OVERFLOW_LENGTH = /^\d+(?:\.\d+)?(?:px|rem)$/;
+
 /**
  * @typedef {Object} NavigationRecord
  * @property {NavigationItem} definition Normalized item definition.
@@ -60,7 +80,10 @@ export class NavigationBar extends Component {
     title: '',
     items: [],
     active: null,
-    actions: []
+    actions: [],
+    overflow: true,
+    overflowBelow: OVERFLOW_BELOW,
+    minVisible: 0
   };
 
   /**
@@ -85,6 +108,7 @@ export class NavigationBar extends Component {
       if (record.definition.href) globalThis.location?.assign(record.definition.href);
     });
     this._syncOverflow();
+    this._observeWidth();
   }
 
   /** @returns {HTMLElement} */
@@ -100,6 +124,8 @@ export class NavigationBar extends Component {
     this._activeName = null;
     this._tabMode = false;
     this._overflow = null;
+    this._observer = null;
+    this._frame = 0;
 
     const bar = h('header', { class: 'zx-navigation-bar__bar' },
       h('div', { class: 'zx-navigation-bar__brand', ref: 'title' }),
@@ -257,6 +283,10 @@ export class NavigationBar extends Component {
   destroy() {
     if (this._cleaned) return;
     this._cleaned = true;
+    if (this._frame && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this._frame);
+    this._frame = 0;
+    this._observer?.disconnect();
+    this._observer = null;
     this._overflow?.destroy();
     super.destroy();
     if (!this._createdRoot && this._original) restore(this.el, this._original);
@@ -382,11 +412,34 @@ export class NavigationBar extends Component {
     }
   }
 
-  /** @returns {void} */
+  /**
+   * Republishes the overflow state: which items may collapse, which mode the stylesheet should
+   * apply, and what the More menu contains. With the default `minVisible: 0` every item collapses
+   * and the menu lists them all, which is what it has always done.
+   * @returns {void}
+   */
   _syncOverflow() {
+    const below = resolveOverflowBelow(this.options);
+    const minVisible = below === null
+      ? this._items.length
+      : resolveMinVisible(this.options, this._items.length);
+    const collapsing = this._items.slice(minVisible);
+    const root = /** @type {HTMLElement} */ (this.el);
+
+    for (const [index, record] of this._items.entries()) {
+      record.item.dataset.collapsed = String(index >= minVisible);
+    }
+    root.dataset.overflow = below === null ? 'off' : (minVisible === 0 ? 'all' : 'partial');
+    /*
+     * The attribute is the stylesheet's own switch: present means "a threshold I do not know", so
+     * the container query stands down and the observer below drives `data-narrow` instead.
+     */
+    if (below === null || below === OVERFLOW_BELOW) delete root.dataset.overflowBelow;
+    else root.dataset.overflowBelow = below;
+
     if (!this._overflow) return;
-    this.refs.more.dataset.empty = this._items.length === 0 ? 'true' : 'false';
-    this._overflow.setItems(this._items.map((record) => ({
+    this.refs.more.dataset.empty = collapsing.length === 0 ? 'true' : 'false';
+    this._overflow.setItems(collapsing.map((record) => ({
       label: record.definition.badge === null ? record.definition.title :
         `${record.definition.title} (${record.definition.badge})`,
       value: record.definition.name,
@@ -394,6 +447,53 @@ export class NavigationBar extends Component {
     })));
   }
 
+  /**
+   * Watches the bar's own inline size when `overflowBelow` names a threshold the stylesheet cannot
+   * express. A bar on the default threshold installs nothing: its container query has already
+   * decided before the first frame of script, which is why the default path stays exactly as it
+   * was.
+   * @returns {void}
+   */
+  _observeWidth() {
+    const below = resolveOverflowBelow(this.options);
+    if (below === null || below === OVERFLOW_BELOW) return;
+    if (typeof ResizeObserver !== 'function') return;
+    const root = /** @type {HTMLElement} */ (this.el);
+
+    const measure = () => {
+      const width = root.getBoundingClientRect().width;
+      /*
+       * Zero is not a narrow bar, it is no measurement at all — what an element reports before it
+       * has been laid out. Recording it would latch the collapsed state and never notice the real
+       * width, which is the failure `src/core/breakpoint.js` documents.
+       */
+      if (!width) return;
+      const rootElement = globalThis.document?.documentElement;
+      const rootFontSize = rootElement
+        ? Number.parseFloat(globalThis.getComputedStyle(rootElement).fontSize)
+        : Number.NaN;
+      // `<=`, because the container query this replaces is a `max-width` and that is inclusive.
+      root.dataset.narrow = String(width <= lengthToPixels(below, rootFontSize));
+    };
+
+    this._observer = new ResizeObserver(() => {
+      /*
+       * Answered on the next frame rather than inside the callback: collapsing the bar resizes the
+       * very element being observed, which the browser reports as an undelivered-notification loop.
+       */
+      if (this._frame || typeof requestAnimationFrame !== 'function') {
+        if (typeof requestAnimationFrame !== 'function') measure();
+        return;
+      }
+      this._frame = requestAnimationFrame(() => {
+        this._frame = 0;
+        measure();
+      });
+    });
+    this._observer.observe(root);
+    measure();
+  }
+
   /** @param {NavigationRecord} record @returns {void} */
   _focusTab(record) {
     for (const item of this._items) item.item.tabIndex = item === record ? 0 : -1;
@@ -424,6 +524,73 @@ export class NavigationBar extends Component {
  * @type {CustomEvent<{name: string}>}
  */
 
+/**
+ * Resolves the container inline size at or below which items collapse into the overflow menu.
+ *
+ * Two options can switch collapsing off, because they answer two different questions: `overflow`
+ * is whether the bar has an overflow menu at all, and `overflowBelow` is where it starts using it.
+ * Either being `false` means the same thing to the stylesheet — nothing ever collapses — so both
+ * resolve to `null` here and the caller has one state to handle rather than two.
+ * @param {NavigationBarOptions} [options={}] Navigation options, whole or partial.
+ * @returns {string|null} A `px` or `rem` length, or `null` when nothing ever collapses.
+ */
+export function resolveOverflowBelow(options = {}) {
+  const enabled = options.overflow ?? true;
+  if (typeof enabled !== 'boolean') {
+    throw new TypeError('NavigationBar overflow must be a boolean');
+  }
+  const below = options.overflowBelow ?? OVERFLOW_BELOW;
+  if (!enabled || below === false) return null;
+  if (typeof below === 'number') {
+    if (!Number.isFinite(below) || below < 0) {
+      throw new RangeError(`NavigationBar overflowBelow must not be negative: ${below}`);
+    }
+    return `${below}px`;
+  }
+  if (typeof below !== 'string' || !OVERFLOW_LENGTH.test(below.trim())) {
+    throw new TypeError(
+      `NavigationBar overflowBelow must be a px or rem length, a number of pixels, or false: ${String(below)}`
+    );
+  }
+  return below.trim();
+}
+
+/**
+ * How many items, counted from the start, stay in the bar when it collapses.
+ *
+ * Clamping to the item count is the whole arithmetic: `minVisible: 4` on a three-item bar keeps
+ * three, so the overflow menu is empty rather than holding a phantom fourth entry, and the bar
+ * hides its More button instead of opening onto nothing.
+ * @param {NavigationBarOptions} [options={}] Navigation options, whole or partial.
+ * @param {number} [count=0] How many items the bar currently has.
+ * @returns {number} A count between 0 and `count`.
+ */
+export function resolveMinVisible(options = {}, count = 0) {
+  const requested = options.minVisible ?? 0;
+  if (!Number.isInteger(requested) || requested < 0) {
+    throw new TypeError(`NavigationBar minVisible must be a non-negative integer: ${String(requested)}`);
+  }
+  const total = Number.isInteger(count) && count > 0 ? count : 0;
+  return Math.min(requested, total);
+}
+
+/**
+ * Converts an overflow threshold to pixels, so a measured width can be compared with it.
+ * @param {string|number} length A `px` or `rem` length, or a number of pixels.
+ * @param {number} [rootFontSize=16] Computed root font size; anything unusable falls back to 16.
+ * @returns {number} The threshold in pixels.
+ */
+export function lengthToPixels(length, rootFontSize = 16) {
+  const value = typeof length === 'number' ? `${length}px` : String(length).trim();
+  if (!OVERFLOW_LENGTH.test(value)) {
+    throw new TypeError(`NavigationBar cannot measure the length "${String(length)}"`);
+  }
+  const size = Number.parseFloat(value);
+  if (!value.endsWith('rem')) return size;
+  const root = Number(rootFontSize);
+  return size * (Number.isFinite(root) && root > 0 ? root : 16);
+}
+
 /** @param {unknown} content @returns {content is NavigationPanelContent} */
 function isPanelContent(content) {
   if (typeof content === 'function' || content instanceof Component) return true;

package/src/components/panel/panel.js

@@ -103,7 +103,7 @@ export class Panel extends Component {
         class: 'zx-panel__buttons',
         ref: 'buttons',
         role: 'group',
-        ariaLabel: 'Panel actions'
+        ariaLabel: this._message('panel.actions', 'Panel actions')
       })
     );
     const content = h('div', {
@@ -125,7 +125,7 @@ export class Panel extends Component {
       class: 'zx-panel__footer-buttons',
       ref: 'footerButtons',
       role: 'group',
-      ariaLabel: 'Panel footer actions'
+      ariaLabel: this._message('panel.footerActions', 'Panel footer actions')
     }));
     root.replaceChildren(header, body, footer);
 
@@ -286,6 +286,17 @@ export class Panel extends Component {
       return element;
     });
   }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @param {string} key Message key.
+   * @param {string} fallback English default.
+   * @returns {string}
+   */
+  _message(key, fallback) {
+    const message = this.msg(key);
+    return message === key ? fallback : message;
+  }
 }
 
 /**

package/src/components/search/search.js

@@ -39,27 +39,28 @@ export class Search extends Component {
     this._original = created ? null : snapshot(root);
     this._inputTimer = null;
     root.setAttribute('role', 'search');
+    const clearLabel = this._message('search.clear', 'Clear search');
     const input = h('input', {
       class: 'zx-search__input',
       ref: 'input',
       type: 'search',
       placeholder: String(this.options.placeholder),
       value: String(this.options.value),
-      ariaLabel: String(this.options.placeholder || 'Search')
+      ariaLabel: String(this.options.placeholder || this._message('search.label', 'Search'))
     });
     const clear = this.options.clearable ? h('button', {
       class: 'zx-search__clear',
       ref: 'clear',
       type: 'button',
-      ariaLabel: 'Clear search',
-      title: 'Clear search'
+      ariaLabel: clearLabel,
+      title: clearLabel
     }, icon('x', { size: 15 })) : null;
     const submit = h('button', {
       class: 'zx-search__submit',
       ref: 'submit',
       type: root.localName === 'form' ? 'submit' : 'button',
-      ariaLabel: 'Submit search',
-      title: 'Search'
+      ariaLabel: this._message('search.submit', 'Submit search'),
+      title: this._message('search.submitTitle', 'Search')
     }, icon('search', { size: 16 }));
     root.replaceChildren(...[input, clear, submit].filter(Boolean));
     this._syncClear();
@@ -157,6 +158,17 @@ export class Search extends Component {
       /** @type {HTMLButtonElement} */ (this.refs.clear).hidden = this.get() === '';
     }
   }
+
+  /**
+   * Resolves a message through the host translator, falling back to the built-in English text.
+   * @param {string} key Message key.
+   * @param {string} fallback English default.
+   * @returns {string}
+   */
+  _message(key, fallback) {
+    const message = this.msg(key);
+    return message === key ? fallback : message;
+  }
 }
 
 /**

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

@@ -9,7 +9,10 @@ export function registerSelectFieldAdapter() {
   Field.register('zxselect', (field, options) => {
     const props = options.props ?? {};
     const preset = props.preset;
-    const selectOptions = { ...props, value: options.value };
+    const selectOptions = { ...props, value: options.value, label: options.label || props.label, placeholder: props.placeholder ?? options.placeholder };
+    field.listen(field.el, 'click', (event) => {
+      if (event.target.closest?.('.zx-field__label')) field.adapter.focus();
+    });
     delete selectOptions.preset;
     const select = field.own(preset === 'priority'
       ? Select.priority(null, selectOptions)

package/src/components/select/select.js

@@ -27,6 +27,7 @@ import { matchItems } from './filter.js';
  * @property {unknown} [value=null] Initially selected ID or item.
  * @property {boolean} [disabled=false] Whether interaction is disabled.
  * @property {string} [placeholder=''] Empty control text.
+ * @property {string} [label=''] Accessible combobox name; falls back to the placeholder.
  * @property {boolean} [clearable=false] Whether selection may be cleared.
  * @property {false|'local'|((query: string) => Promise<SelectItem[]>|SelectItem[])} [filter=false] Filtering mode.
  * @property {Array<SelectValueReader>|null} [searchKeys=null] Fields searched by local filtering.
@@ -109,6 +110,7 @@ export class Select extends Component {
     value: null,
     disabled: false,
     placeholder: '',
+    label: '',
     clearable: false,
     filter: false,
     searchKeys: null,
@@ -136,6 +138,7 @@ export class Select extends Component {
       class: 'zx-select__input',
       type: 'text',
       role: 'combobox',
+      ariaLabel: String(this.options.label || this.options.placeholder || 'Select'),
       autocomplete: 'off',
       spellcheck: false,
       ariaExpanded: 'false',

package/src/components/sort-control/sort-control.css

@@ -0,0 +1,17 @@
+.zx-sort-control {
+  display: inline-grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: center;
+  gap: var(--zx-space-1);
+  min-inline-size: 0;
+  inline-size: 100%;
+}
+
+.zx-sort-control__direction {
+  inline-size: var(--zx-control-height);
+  padding: 0;
+  border-radius: var(--zx-radius-full);
+}
+
+.zx-sort-control__direction:focus-visible { box-shadow: var(--zx-focus-ring); }
+.zx-sort-control .zx-select__control { background: var(--zx-color-bg-control); }

package/src/components/sort-control/sort-control.js

@@ -0,0 +1,140 @@
+import { Component } from '../../core/component.js';
+import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
+import { icon } from '../../core/icons.js';
+import { button } from '../button/button.js';
+import { Select } from '../select/select.js';
+
+/** @typedef {{id:string,label:string}} SortField */
+/** @typedef {{id:string,dir:'asc'|'desc'}} SortValue */
+/**
+ * @typedef {Object} SortControlOptions
+ * @property {SortField[]} [fields=[]] Available sort fields, in display order.
+ * @property {SortValue|null} [value=null] Initial sort; null chooses the first field ascending.
+ * @property {string} [label='Sort by'] Accessible field label and direction-name prefix.
+ * @property {{asc?:string,desc?:string}} [labels={}] Current/next direction labels, defaulting to Ascending/Descending.
+ * @property {boolean} [disabled=false] Whether interaction is disabled.
+ * @property {(event:CustomEvent<{value:SortValue}>)=>void} [onchange] Atomic field/direction change.
+ */
+
+/**
+ * A searchable field selector with an adjacent direction toggle and one shared sort value.
+ * @fires SortControl#change
+ * @extends {Component<SortControlOptions>}
+ */
+export class SortControl extends Component {
+  static cssName = 'sort-control';
+  /** @type {SortControlOptions} */
+  static defaults = { fields: [], value: null, label: 'Sort by', labels: {}, disabled: false };
+
+  /** @returns {HTMLElement} */
+  render() {
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this._createdRoot = this.el === null;
+    this._snapshot = this._createdRoot ? null : snapshotTarget(root);
+    this.el = root;
+    this._value = normalizeSortValue(this.options.value, this.options.fields);
+    this._disabled = Boolean(this.options.disabled || !this.options.fields.length);
+    this._direction = button({ kind: 'ghost', disabled: this._disabled });
+    this._direction.classList.add('zx-sort-control__direction');
+    this.listen(this._direction, 'click', () => {
+      if (this._disabled || !this._value) return;
+      this.setValue({ id: this._value.id, dir: this._value.dir === 'asc' ? 'desc' : 'asc' });
+    });
+    this._select = new Select(null, {
+      items: sortChoices(this.options.fields), valueKey: 'id', labelKey: 'label',
+      value: this._value?.id ?? null, label: this.options.label,
+      filter: 'local', disabled: this._disabled,
+      onchange: ({ detail }) => {
+        if (!detail.item) return;
+        this.setValue({ id: detail.item.id, dir: this._value?.dir ?? 'asc' });
+      }
+    });
+    // The owned Select's DOM event must not duplicate the composite's atomic event.
+    this.listen(this._select.el, 'zx-change', (event) => event.stopPropagation());
+    root.replaceChildren(this._direction, this._select.el);
+    this._syncDirection();
+    return root;
+  }
+
+  /** Returns a defensive copy of the current sort. @returns {SortValue|null} */
+  getValue() { return this._value ? { ...this._value } : null; }
+
+  /**
+   * Replaces the field and direction atomically; rejects unavailable fields and directions.
+   * @param {SortValue|null} value Sort state, or null for the first field ascending.
+   * @param {{silent?:boolean}} [options={}] Suppress change when silent.
+   * @returns {this}
+   */
+  setValue(value, { silent = false } = {}) {
+    const next = normalizeSortValue(value, this.options.fields);
+    const changed = sortKey(next) !== sortKey(this._value);
+    this._value = next;
+    this._select.set(next?.id ?? null, { silent: true });
+    this._syncDirection();
+    if (changed && !silent) this.emit('change', { value: this.getValue() });
+    return this;
+  }
+
+  /** Enables both controls when fields are available. @returns {this} */
+  enable() {
+    this._disabled = !this.options.fields.length;
+    if (!this._disabled) this._select.enable();
+    this._direction.disabled = this._disabled;
+    return this;
+  }
+  /** Disables both controls and closes the option panel. @returns {this} */
+  disable() {
+    this._disabled = true;
+    this._select.disable();
+    this._direction.disabled = true;
+    return this;
+  }
+
+  /** Updates the icon and accessible current/next direction text. @private @returns {void} */
+  _syncDirection() {
+    const dir = this._value?.dir ?? 'asc';
+    const next = dir === 'asc' ? 'desc' : 'asc';
+    const labels = { asc: 'Ascending', desc: 'Descending', ...this.options.labels };
+    this._direction.replaceChildren(icon(dir === 'asc' ? 'arrow-up-wide-short' : 'arrow-down-wide-short'));
+    this._direction.dataset.direction = dir;
+    this._direction.setAttribute('aria-label', `${this.options.label}: ${labels[dir]}`);
+    this._direction.title = `${labels[dir]} → ${labels[next]}`;
+  }
+
+  /** Focuses the searchable control. @returns {this} */
+  focus() { this._select.focus(); return this; }
+  /** Releases the owned Select and restores an enhanced target. @returns {void} */
+  destroy() {
+    this._select?.destroy();
+    super.destroy();
+    if (!this._createdRoot) restoreTarget(this.el, this._snapshot);
+  }
+}
+
+/**
+ * Validates a sort against available fields without retaining caller-owned state.
+ * @param {SortValue|null} value Requested sort.
+ * @param {SortField[]} fields Available fields.
+ * @returns {SortValue|null} Normalized sort, or null for an empty catalogue.
+ */
+export function normalizeSortValue(value, fields) {
+  if (!fields.length) return null;
+  if (value == null) return { id: String(fields[0].id), dir: 'asc' };
+  if (!fields.some((field) => String(field.id) === String(value.id))) throw new RangeError('Unknown sort field');
+  if (value.dir !== 'asc' && value.dir !== 'desc') throw new RangeError('Unknown sort direction');
+  return { id: String(value.id), dir: value.dir };
+}
+
+/**
+ * Builds one searchable record per field without retaining caller-owned objects.
+ * @param {SortField[]} fields Available fields.
+ * @returns {SortField[]} Choice records.
+ */
+export function sortChoices(fields) {
+  return fields.map((field) => ({ id: String(field.id), label: field.label }));
+}
+
+/** @param {SortValue|null} value Sort state. @returns {string} Stable choice key. */
+function sortKey(value) { return value ? JSON.stringify([value.id, value.dir]) : ''; }
+
+/** @event SortControl#change @type {CustomEvent<{value:SortValue}>} */