@zeyos/zx 4.3.4 → 5.0.0

package/src/components/select/select.js

@@ -3,8 +3,12 @@ import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
 import { icon } from '../../core/icons.js';
 import { typeahead } from '../../core/keyboard.js';
 import { position } from '../../core/position.js';
-import { isCssColor, uid } from '../../core/util.js';
+import { uid } from '../../core/util.js';
+import { itemColor } from './color.js';
 import { matchItems } from './filter.js';
+import {
+  DEFAULT_STATUSES, STATUS_INDICATORS, STATUS_TONES, normalizePriorityLevel, priorityIcon, statusIcon
+} from './glyphs.js';
 
 /** @typedef {string|number|boolean|symbol|bigint|null|undefined} Primitive */
 /** @typedef {Record<string, any>|Primitive} SelectItem */
@@ -27,6 +31,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.
@@ -48,7 +53,9 @@ import { matchItems } from './filter.js';
  * @property {string} [recentLabel='Recent'] Heading above recent choices.
  * @property {boolean|SelectAction} [create=false] Optional create command at the bottom.
  * @property {string|((item: SelectItem)=>unknown)} [iconKey='icon'] Item icon reader.
- * @property {string|((item: SelectItem)=>unknown)} [colorKey='color'] Optional icon colour reader.
+ * @property {string|((item: SelectItem)=>unknown)} [colorKey='color'] Optional icon colour reader: a CSS
+ * colour or a token reference such as `var(--zx-color-tone-blue-fg)`. Without one the glyph is a
+ * neutral tile in muted ink.
  * @property {string|((item: SelectItem)=>unknown)} [subtitleKey='description'] Secondary-text reader.
  * @property {((item: SelectItem, context:{selected:boolean})=>Node|string|null)|null} [renderIcon=null] Entity icon renderer.
  */
@@ -68,18 +75,6 @@ const PRIORITY_KEYS = [
 ];
 const PRIORITY_FALLBACKS = ['Lowest', 'Low', 'Medium', 'High', 'Highest'];
 
-const DEFAULT_STATUSES = Object.freeze([
-  ['backlog', 'status.backlog', 'Backlog', 'dotted', 'muted'],
-  ['todo', 'status.todo', 'Todo', 'ring', 'neutral'],
-  ['in-progress', 'status.inProgress', 'In Progress', 'progress', 'warning'],
-  ['in-review', 'status.inReview', 'In Review', 'review', 'info'],
-  ['ready', 'status.ready', 'Ready to Merge', 'ready', 'accent'],
-  ['waiting', 'status.waiting', 'Waiting for feedback', 'waiting', 'warning'],
-  ['done', 'status.done', 'Done', 'done', 'info'],
-  ['canceled', 'status.canceled', 'Canceled', 'canceled', 'muted'],
-  ['duplicate', 'status.duplicate', 'Duplicate', 'duplicate', 'muted']
-]);
-
 /**
  * APG editable combobox with optional local or asynchronous filtering.
  *
@@ -109,6 +104,7 @@ export class Select extends Component {
     value: null,
     disabled: false,
     placeholder: '',
+    label: '',
     clearable: false,
     filter: false,
     searchKeys: null,
@@ -123,7 +119,7 @@ export class Select extends Component {
   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._fixedItems = []; this._visibleFixed = []; this._actions = []; this._selected = null; this._optionEntries = []; this._activeIndex = -1; this._open = false; this._disabled = false; this._loading = false; this._requestSequence = 0; this._queryTimer = null; this._position = null; this._createdRoot = false; this._root = null; this._snapshot = null;
+    this._items = []; this._visibleItems = []; this._fixedItems = []; this._visibleFixed = []; this._actions = []; this._selected = null; this._optionEntries = []; this._activeIndex = -1; this._open = false; this._disabled = false; this._loading = false; this._requestSequence = 0; this._queryTimer = null; this._position = null; this._createdRoot = false; this._root = null; this._snapshot = null; this._pointerModality = false;
     this._createdRoot = this.el === null;
     const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
     this.el = root;
@@ -136,6 +132,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',
@@ -206,7 +203,22 @@ export class Select extends Component {
 
     this.listen(input, 'click', () => this.open());
     this.listen(input, 'input', () => this._onInput());
-    this.listen(input, 'keydown', (event) => this._onKeydown(/** @type {KeyboardEvent} */ (event)));
+    this.listen(input, 'keydown', (event) => {
+      if (!isModifierKey(/** @type {KeyboardEvent} */ (event))) root.removeAttribute('data-focus-origin');
+      this._onKeydown(/** @type {KeyboardEvent} */ (event));
+    });
+    // A text input matches :focus-visible however it was focused, read-only or not, so a click on
+    // a read-only Select would draw the keyboard ring. Track how the user last interacted and mark
+    // a pointer focus; the ring then follows keyboard focus only, and returns on the first key.
+    this.listen(input, 'focus', () => {
+      if (this._pointerModality && /** @type {HTMLInputElement} */ (input).readOnly) {
+        root.setAttribute('data-focus-origin', 'pointer');
+      } else root.removeAttribute('data-focus-origin');
+    });
+    this.listen(input, 'blur', () => root.removeAttribute('data-focus-origin'));
+    this.listen(document, 'keydown', (event) => {
+      if (!isModifierKey(/** @type {KeyboardEvent} */ (event))) this._pointerModality = false;
+    }, { capture: true });
     this.listen(toggle, 'click', () => {
       this.focus();
       if (this._open) this.close();
@@ -219,6 +231,7 @@ export class Select extends Component {
     this.listen(panel, 'pointerdown', (event) => event.preventDefault());
     this.listen(panel, 'click', (event) => this._onOptionClick(event));
     this.listen(document, 'pointerdown', (event) => {
+      this._pointerModality = true;
       if (this._open && !root.contains(/** @type {Node} */ (event.target))) this.close();
     }, { capture: true });
 
@@ -378,26 +391,44 @@ export class Select extends Component {
   }
 
   /**
-   * Creates the five-level priority preset.
+   * Creates the five-level priority preset: values 0 (lowest) to 4 (highest), each drawn as grey
+   * signal bars filled to its level, except the highest, which is the one coloured level — a
+   * danger square with an exclamation mark. A "No priority" row (value null, a row of dashes)
+   * heads the list and labels the empty control; `clearable: false` removes it.
    * @param {Element|string|null} target Component target.
-   * @param {SelectOptions} [options={}] Select overrides other than fixed items and renderer.
+   * @param {SelectOptions} [options={}] Select overrides other than items and renderers.
+   *   `clearable` defaults to true here; `noneLabel` and `placeholder` default to the
+   *   `priority.none` message ("No priority").
    * @returns {Select}
    */
   static priority(target, options = {}) {
     const requestedValue = options.value ?? null;
-    const select = new Select(target, {
+    const clearable = options.clearable ?? true;
+    /** @type {Select|null} */
+    let select = null;
+    // The constructor renders the list once before `select` is assigned; the label is settled by
+    // the setItems() below, which renders it again.
+    const noneLabel = () => options.noneLabel
+      ?? (select ? select._message('priority.none', 'No priority') : 'No priority');
+    select = new Select(target, {
       ...options,
+      clearable,
       value: null,
       items: [],
       renderItem(item) {
         return priorityContent(item, true);
       },
+      renderNone: options.renderNone ?? (() => priorityContent({ level: null, name: noneLabel() }, true)),
       renderValueAdornment(item) { return priorityIndicator(item.level); }
     });
+    if (clearable && !options.placeholder) {
+      /** @type {HTMLInputElement} */ (select.refs.input).placeholder = noneLabel();
+    }
+    const preset = select;
     select.setItems(PRIORITY_KEYS.map((key, level) => {
-      let name = level === 2 ? select.msg('priority.medium') : key;
-      if (name === 'priority.medium') name = select._message(key, PRIORITY_FALLBACKS[level]);
-      else if (level !== 2) name = select._message(key, PRIORITY_FALLBACKS[level]);
+      let name = level === 2 ? preset.msg('priority.medium') : key;
+      if (name === 'priority.medium') name = preset._message(key, PRIORITY_FALLBACKS[level]);
+      else if (level !== 2) name = preset._message(key, PRIORITY_FALLBACKS[level]);
       return { ID: level, name, level };
     }));
     select.set(requestedValue, { silent: true });
@@ -450,10 +481,10 @@ export class Select extends Component {
       const value = readSelectItem(item, iconKey);
       if (value && typeof value === 'object' && typeof value.nodeType === 'number') return value.cloneNode(true);
       if (typeof value !== 'string' || !value) return null;
-      const color = readSelectItem(item, colorKey);
+      const color = itemColor(readSelectItem(item, colorKey));
       return h('span', {
         class: 'zx-select__entity-glyph',
-        style: isCssColor(color) ? { '--zx-select-entity-color': String(color) } : null,
+        style: color ? { '--zx-select-entity-color': color } : null,
         ariaHidden: 'true'
       }, icon(value, { size: 14 }));
     };
@@ -989,28 +1020,26 @@ function priorityContent(item, label) {
     label ? h('span', {}, String(item.name)) : null);
 }
 
-/** @param {unknown} level @returns {Node} */
+/**
+ * The priority glyph `priorityIcon()` draws, carrying the Select's own class as well so styles
+ * written against it keep applying.
+ * @param {unknown} level Priority level 0–4, or null for none.
+ * @returns {Node}
+ */
 function priorityIndicator(level) {
-  const normalized = Math.max(0, Math.min(4, Math.trunc(Number(level) || 0)));
-  return h('span', {
-    class: 'zx-select__priority-icon',
-    dataset: { level: normalized },
-    ariaHidden: 'true'
-  }, Array.from({ length: 5 }, (_, index) => h('span', {
-    dataset: { filled: String(index <= normalized) }
-  })));
+  const glyph = priorityIcon(/** @type {number|null} */ (normalizePriorityLevel(level)));
+  glyph.classList.add('zx-select__priority-icon');
+  return glyph;
 }
 
 /** @param {unknown} input @returns {Record<string, any>|null} */
 function normalizeStatusItem(input) {
   if (!input || typeof input !== 'object' || input.ID == null || input.name == null) return null;
-  const indicators = ['dotted', 'ring', 'progress', 'review', 'ready', 'waiting', 'done', 'canceled', 'duplicate'];
-  const tones = ['muted', 'neutral', 'warning', 'info', 'accent', 'success', 'danger'];
   return {
     ...input,
     name: String(input.name),
-    indicator: indicators.includes(String(input.indicator)) ? String(input.indicator) : 'ring',
-    tone: tones.includes(String(input.tone)) ? String(input.tone) : 'muted',
+    indicator: STATUS_INDICATORS.includes(String(input.indicator)) ? String(input.indicator) : 'ring',
+    tone: STATUS_TONES.includes(String(input.tone)) ? String(input.tone) : 'muted',
     description: input.description == null ? '' : String(input.description),
     shortcut: input.shortcut == null ? '' : String(input.shortcut)
   };
@@ -1026,17 +1055,16 @@ function statusContent(item) {
     item.shortcut ? h('kbd', { class: 'zx-select__status-shortcut' }, item.shortcut) : null);
 }
 
-/** @param {Record<string, any>} item @returns {Node} */
+/**
+ * The status glyph `statusIcon()` draws for a settled status item, carrying the Select's own class
+ * as well so styles written against it keep applying.
+ * @param {Record<string, any>} item Normalized status item.
+ * @returns {Node}
+ */
 function statusIndicator(item) {
-  const indicator = String(item.indicator ?? 'ring');
-  const marker = h('span', {
-    class: 'zx-select__status-indicator',
-    dataset: { indicator, tone: String(item.tone ?? 'muted') },
-    ariaHidden: 'true'
-  });
-  if (indicator === 'done') marker.append(icon('check', { size: 8 }));
-  if (indicator === 'canceled') marker.append(icon('x', { size: 7 }));
-  return marker;
+  const glyph = statusIcon({ indicator: item.indicator ?? 'ring', tone: item.tone ?? 'muted' });
+  glyph.classList.add('zx-select__status-indicator');
+  return glyph;
 }
 
 /** Change emitted when the selected value changes. @event Select#change @type {CustomEvent<SelectChangeDetail>} */
@@ -1058,6 +1086,17 @@ function readItem(item, reader) {
   return item[reader];
 }
 
+/**
+ * Reports a key press that says nothing about how the user is moving focus: a lone modifier, or a
+ * shortcut chord the page or the browser handles.
+ * @param {KeyboardEvent} event Key event.
+ * @returns {boolean}
+ */
+function isModifierKey(event) {
+  return ['Shift', 'Control', 'Alt', 'Meta', 'CapsLock'].includes(event.key)
+    || event.ctrlKey || event.metaKey;
+}
+
 /** @param {KeyboardEvent} event @returns {boolean} */
 function isPrintable(event) {
   return event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;

package/src/components/sheet/sheet.css

@@ -57,8 +57,8 @@
   inset-block-start: 0;
   inset-block-end: auto;
   border-block-end: 1px solid var(--zx-color-overlay-border);
-  border-end-start-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
-  border-end-end-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
+  border-end-start-radius: var(--zx-sheet-radius, var(--zx-radius-lg));
+  border-end-end-radius: var(--zx-sheet-radius, var(--zx-radius-lg));
   --zx-sheet-enter: 0 -100%;
 }
 
@@ -66,8 +66,8 @@
   inset-block-start: auto;
   inset-block-end: 0;
   border-block-start: 1px solid var(--zx-color-overlay-border);
-  border-start-start-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
-  border-start-end-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
+  border-start-start-radius: var(--zx-sheet-radius, var(--zx-radius-lg));
+  border-start-end-radius: var(--zx-sheet-radius, var(--zx-radius-lg));
   --zx-sheet-enter: 0 100%;
 }
 
@@ -105,11 +105,14 @@
  * `display: none` immediately — so `display` and `overlay` transition with `allow-discrete`, which
  * defers the discrete jump until the rest of the transition has finished. `@starting-style` gives
  * the entry its from-state. Where either is unsupported the sheet simply appears and disappears.
+ *
+ * The slide runs on the drawer curve — most of the distance at once, then a settle — while the
+ * fade keeps the ordinary ease, so the panel arrives decisively without flashing in.
  */
 @media (prefers-reduced-motion: no-preference) {
   .zx-sheet {
     transition:
-      translate var(--zx-dur-base) var(--zx-ease),
+      translate var(--zx-dur-base) var(--zx-ease-drawer),
       opacity var(--zx-dur-base) var(--zx-ease),
       display var(--zx-dur-base) allow-discrete,
       overlay var(--zx-dur-base) allow-discrete;
@@ -193,7 +196,7 @@
 @media (prefers-reduced-motion: no-preference) {
   .zx-sheet[data-docked] {
     transition:
-      flex-basis var(--zx-dur-base) var(--zx-ease),
+      flex-basis var(--zx-dur-base) var(--zx-ease-drawer),
       opacity var(--zx-dur-base) var(--zx-ease),
       display var(--zx-dur-base) allow-discrete,
       overlay var(--zx-dur-base) allow-discrete;
@@ -363,8 +366,8 @@
 @media (prefers-reduced-motion: no-preference) {
   .zx-sheet[data-stack] {
     transition:
-      transform var(--zx-dur-base) var(--zx-ease),
-      translate var(--zx-dur-base) var(--zx-ease),
+      transform var(--zx-dur-base) var(--zx-ease-drawer),
+      translate var(--zx-dur-base) var(--zx-ease-drawer),
       opacity var(--zx-dur-base) var(--zx-ease),
       display var(--zx-dur-base) allow-discrete,
       overlay var(--zx-dur-base) allow-discrete;

package/src/components/slider/slider.css

@@ -147,17 +147,31 @@
   font-variant-numeric: tabular-nums;
 }
 
+/*
+ * A mark sits under the thumb's centre at its value — half a thumb in from either end of the rail
+ * — and centres its label there, except that a label is never pushed past either end of the
+ * track: the outermost ones end flush with it instead of spilling out of the component.
+ * `--zx-slider-mark` is the value's position on the scale, from 0 to 1.
+ */
 .zx-slider__marks {
   position: relative;
+  inline-size: 100%;
   block-size: var(--zx-space-5);
   margin-block-start: var(--zx-space-1);
+  container-type: inline-size;
 }
 
 .zx-slider__mark {
+  --zx-slider-mark-at: calc(var(--zx-slider-thumb) / 2
+    + (100cqi - var(--zx-slider-thumb)) * var(--zx-slider-mark, 0));
   position: absolute;
   inset-block-start: 0;
-  inset-inline-start: var(--zx-slider-mark, 0%);
-  transform: translateX(-50%);
+  inset-inline-start: var(--zx-slider-mark-at);
+  transform: translateX(clamp(
+    -1 * var(--zx-slider-mark-at),
+    -50%,
+    100cqi - var(--zx-slider-mark-at) - 100%
+  ));
   color: var(--zx-color-text-muted);
   font-size: var(--zx-text-xs);
   white-space: nowrap;

package/src/components/slider/slider.js

@@ -279,7 +279,7 @@ export class Slider extends Component {
       const label = typeof mark === 'number' ? this._format(value) : String(mark.label ?? this._format(value));
       element.append(h('span', {
         class: 'zx-slider__mark',
-        style: { '--zx-slider-mark': `${this._ratio(value) * 100}%` }
+        style: { '--zx-slider-mark': String(this._ratio(value)) }
       }, label));
     }
     return element;

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

@@ -0,0 +1,20 @@
+.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-control-radius);
+}
+
+.zx-sort-control__direction:focus-visible { box-shadow: var(--zx-focus-ring); }
+/* The arrow is the current direction, not decoration, so it keeps the text colour a ghost glyph
+   would otherwise give up. */
+.zx-sort-control .zx-sort-control__direction > .zx-icon { color: var(--zx-color-text); }
+.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}>} */