@zeyos/zx 3.0.0 → 4.1.0

package/src/components/select/select.js

@@ -1,23 +1,29 @@
 import { Component } from '../../core/component.js';
-import { h } from '../../core/dom.js';
+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 { uid } from '../../core/util.js';
+import { isCssColor, uid } from '../../core/util.js';
 import { matchItems } from './filter.js';
 
 /** @typedef {string|number|boolean|symbol|bigint|null|undefined} Primitive */
 /** @typedef {Record<string, any>|Primitive} SelectItem */
 /** @typedef {string|((item: SelectItem) => unknown)} SelectValueReader */
 /** @typedef {string|((item: SelectItem) => string)} SelectLabelReader */
+/** @typedef {{id: string|number, label: string, icon?: string|Node, description?: string, group?: string, invoke?: (detail: SelectActionDetail) => void}} SelectAction */
 /**
  * @typedef {Object} SelectOptions
  * @property {SelectItem[]} [items=[]] Available values.
  * @property {SelectItem[]} [fixedItems=[]] Choices pinned above the list, kept through filtering and async loads.
+ * @property {string|null} [fixedLabel=null] Optional heading above pinned choices.
  * @property {SelectValueReader} [valueKey='ID'] Item ID property or reader.
  * @property {SelectLabelReader} [labelKey='name'] Item label property or reader.
  * @property {((item: SelectItem) => Node|string)|null} [renderItem=null] Option renderer.
  * @property {((item: SelectItem) => string)|null} [renderValue=null] Selected-value renderer.
+ * @property {((item: SelectItem) => Node|string|null)|null} [renderValueAdornment=null] Decorative content before the selected text.
+ * @property {((label: string) => Node|string)|null} [renderNone=null] Clear-row renderer.
+ * @property {string|null} [noneLabel=null] Clear-row label independent from the input placeholder.
+ * @property {SelectAction[]} [actions=[]] Command rows that emit `action` without changing value.
  * @property {unknown} [value=null] Initially selected ID or item.
  * @property {boolean} [disabled=false] Whether interaction is disabled.
  * @property {string} [placeholder=''] Empty control text.
@@ -34,11 +40,23 @@ import { matchItems } from './filter.js';
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close listener.
  * @property {(event: CustomEvent<SelectQueryDetail>) => void} [onquery] Async-query listener.
  * @property {(event: CustomEvent<SelectLoadedDetail>) => void} [onloaded] Async-loaded listener.
+ * @property {(event: CustomEvent<SelectActionDetail>) => void} [onaction] Preventable command-row listener.
+ */
+/**
+ * @typedef {Object} EntitySelectOptions
+ * @property {SelectItem[]} [recent=[]] Choices pinned above ordinary results.
+ * @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)} [subtitleKey='description'] Secondary-text reader.
+ * @property {((item: SelectItem, context:{selected:boolean})=>Node|string|null)|null} [renderIcon=null] Entity icon renderer.
  */
 /** @typedef {{value: unknown, item: SelectItem|null}} SelectChangeDetail */
 /** @typedef {{query: string}} SelectQueryDetail */
 /** @typedef {{items: SelectItem[]}} SelectLoadedDetail */
-/** @typedef {{item: SelectItem|null, clear: boolean, element: HTMLElement}} SelectOptionEntry */
+/** @typedef {{id: string|number, action: SelectAction, query: string, select: Select}} SelectActionDetail */
+/** @typedef {{item: SelectItem|null, clear: boolean, action: SelectAction|null, element: HTMLElement}} SelectOptionEntry */
 /** @typedef {{silent?: boolean}} SelectSetOptions */
 
 const PRIORITY_KEYS = [
@@ -48,7 +66,19 @@ const PRIORITY_KEYS = [
   'priority.high',
   'priority.highest'
 ];
-const PRIORITY_FALLBACKS = ['Lowest', 'Low', 'Normal', 'High', 'Highest'];
+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.
@@ -67,10 +97,15 @@ export class Select extends Component {
   static defaults = {
     items: [],
     fixedItems: [],
+    fixedLabel: null,
     valueKey: 'ID',
     labelKey: 'name',
     renderItem: null,
     renderValue: null,
+    renderValueAdornment: null,
+    renderNone: null,
+    noneLabel: null,
+    actions: [],
     value: null,
     disabled: false,
     placeholder: '',
@@ -88,15 +123,12 @@ 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._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._originalChildren = []; this._originalAttributes = new Map();
+    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._createdRoot = this.el === null;
     const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
     this.el = root;
     this._root = root;
-    if (!this._createdRoot) this._originalChildren = Array.from(root.childNodes);
-    this._rememberAttribute(root, 'data-state');
-    this._rememberAttribute(root, 'data-loading');
-    this._rememberAttribute(root, 'aria-disabled');
+    this._snapshot = this._createdRoot ? null : snapshotTarget(root);
 
     const listId = uid('zx-select-list');
     const input = h('input', {
@@ -112,6 +144,12 @@ export class Select extends Component {
       placeholder: String(this.options.placeholder ?? ''),
       readOnly: !this.options.filter
     });
+    const valueAdornment = h('span', {
+      ref: 'valueAdornment',
+      class: 'zx-select__value-adornment',
+      ariaHidden: 'true',
+      hidden: true
+    });
     const clear = h('button', {
       ref: 'clear',
       class: 'zx-icon-btn zx-select__clear',
@@ -135,7 +173,7 @@ export class Select extends Component {
       ariaLabel: this._message('select.toggle', 'Toggle options')
     }, icon('chevron-down', { size: 16 }));
     const control = h('div', { ref: 'control', class: 'zx-select__control' },
-      input, clear, loading, toggle
+      valueAdornment, input, clear, loading, toggle
     );
     const list = h('div', {
       ref: 'list',
@@ -155,9 +193,11 @@ export class Select extends Component {
     this._visibleItems = this._items.slice();
     this._fixedItems = Array.isArray(this.options.fixedItems) ? this.options.fixedItems.slice() : [];
     this._visibleFixed = this._fixedItems.slice();
+    this._actions = normalizeSelectActions(this.options.actions);
     this._disabled = Boolean(this.options.disabled);
     this._handleTypeahead = typeahead(
-      () => this._optionEntries.filter((entry) => !entry.clear).map((entry) => entry.element),
+      () => this._optionEntries.filter((entry) => !entry.clear && !entry.action)
+        .map((entry) => entry.element),
       (_option, index) => {
         if (!this._open) this.open();
         this._setActive(this._itemEntryIndex(index));
@@ -255,6 +295,14 @@ export class Select extends Component {
     return this;
   }
 
+  /** Replaces command rows without changing the selected value. @param {SelectAction[]} actions @returns {this} */
+  setActions(actions) {
+    this._actions = normalizeSelectActions(actions);
+    this._renderOptions();
+    this._position?.update();
+    return this;
+  }
+
   /**
    * Restores the configured initial value.
    * @param {{silent?: boolean}} [options={}] Reset behavior.
@@ -342,25 +390,96 @@ export class Select extends Component {
       value: null,
       items: [],
       renderItem(item) {
-        return h('span', { class: 'zx-select__priority' },
-          h('span', {
-            class: 'zx-select__priority-icon',
-            dataset: { level: item.level },
-            ariaHidden: 'true'
-          }),
-          h('span', {}, String(item.name))
-        );
-      }
+        return priorityContent(item, true);
+      },
+      renderValueAdornment(item) { return priorityIndicator(item.level); }
     });
-    select.setItems(PRIORITY_KEYS.map((key, level) => ({
-      ID: level,
-      name: select._message(key, PRIORITY_FALLBACKS[level]),
-      level
-    })));
+    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]);
+      return { ID: level, name, level };
+    }));
     select.set(requestedValue, { silent: true });
     return select;
   }
 
+  /**
+   * Creates a status picker with shape- and color-distinct workflow indicators.
+   * @param {Element|string|null} target Component target.
+   * @param {SelectOptions & {items?: Array<Record<string, any>>}} [options={}] Select overrides and status items.
+   * @returns {Select}
+   */
+  static status(target, options = {}) {
+    const { items = null, value = null, ...rest } = options;
+    const select = new Select(target, {
+      ...rest,
+      value: null,
+      items: [],
+      renderItem(item) { return statusContent(item); },
+      renderValueAdornment(item) { return statusIndicator(item); }
+    });
+    const statuses = Array.isArray(items) ? items.map(normalizeStatusItem).filter(Boolean)
+      : DEFAULT_STATUSES.map(([ID, key, fallback, indicator, tone], index) => ({
+        ID,
+        name: select._message(key, fallback),
+        indicator,
+        tone,
+        shortcut: String(index + 1)
+      }));
+    select.setItems(statuses);
+    select.set(value, { silent: true });
+    return select;
+  }
+
+  /**
+   * Creates a rich entity picker with optional Recent choices and a create command.
+   * @param {Element|string|null} target Component target.
+   * @param {SelectOptions & EntitySelectOptions} [options={}] Entity-preset options.
+   * @returns {Select}
+   */
+  static entity(target, options = {}) {
+    const {
+      recent = [], recentLabel = 'Recent', create = false, iconKey = 'icon', colorKey = 'color',
+      subtitleKey = 'description', renderIcon = null,
+      fixedItems = [], actions = [], renderItem = null, renderValueAdornment = null,
+      ...rest
+    } = options;
+    const visual = (item, selected = false) => {
+      if (typeof renderIcon === 'function') return renderIcon(item, { selected });
+      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);
+      return h('span', {
+        class: 'zx-select__entity-glyph',
+        style: isCssColor(color) ? { '--zx-select-entity-color': String(color) } : null,
+        ariaHidden: 'true'
+      }, icon(value, { size: 14 }));
+    };
+    const createAction = create ? normalizeEntityCreateAction(create) : null;
+    const select = new Select(target, {
+      ...rest,
+      fixedItems: [...(Array.isArray(recent) ? recent : []), ...(Array.isArray(fixedItems) ? fixedItems : [])],
+      fixedLabel: Array.isArray(recent) && recent.length ? recentLabel : rest.fixedLabel ?? null,
+      actions: [...(Array.isArray(actions) ? actions : []), ...(createAction ? [createAction] : [])],
+      renderItem: renderItem ?? ((item) => {
+        const decoration = visual(item, false);
+        const subtitle = readSelectItem(item, subtitleKey);
+        const copy = h('span', { class: 'zx-select__entity-copy' },
+          h('span', { class: 'zx-select__entity-label' }, String(readSelectItem(item, rest.labelKey ?? 'name') ?? '')),
+          subtitle == null || subtitle === ''
+            ? null : h('span', { class: 'zx-select__entity-subtitle' }, String(subtitle)));
+        return h('span', { class: 'zx-select__entity' },
+          decoration ? h('span', { class: 'zx-select__entity-icon', ariaHidden: 'true' }, decoration) : null,
+          copy);
+      }),
+      renderValueAdornment: renderValueAdornment ?? ((item) => visual(item, true))
+    });
+    select.el.dataset.preset = 'entity';
+    return select;
+  }
+
   /**
    * Creates the record-permission picker: the fixed Private and Public choices above the groups a
    * record can be shared with. The value is the tri-state ZeyOS stores — `false` for private,
@@ -373,12 +492,16 @@ export class Select extends Component {
    * @returns {Select}
    */
   static permission(target, options = {}) {
-    const { groups = [], value = true, valueKey = 'ID', labelKey = 'name', ...rest } = options;
+    const {
+      groups = [], value = true, valueKey = 'ID', labelKey = 'name', filter = 'local', ...rest
+    } = options;
     const loader = typeof groups === 'function' ? groups : null;
     const shareable = loader ? [] : groups;
     const choices = [{ ID: false, name: 'Private' }, { ID: true, name: 'Public' }];
     const select = new Select(target, {
-      filter: loader ?? 'local',
+      // An async group loader is the data source and cannot be disconnected by an incidental
+      // `filter` override. Array-backed groups still honor local/disabled filtering.
+      filter: loader ?? filter,
       ...rest,
       value: null,
       items: shareable,
@@ -401,19 +524,23 @@ export class Select extends Component {
     this._position?.destroy();
     this._position = null;
     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);
-      }
-    }
+    if (!this._createdRoot && root) restoreTarget(root, this._snapshot);
     super.destroy();
   }
 
   /** @param {KeyboardEvent} event @returns {void} */
   _onKeydown(event) {
     if (this._disabled) return;
+    if (this._open && isPrintable(event)) {
+      const shortcut = this._optionEntries.findIndex((entry) => !entry.clear && !entry.action
+        && String((/** @type {Record<string, any>|null} */ (entry.item))?.shortcut ?? '') === event.key);
+      if (shortcut >= 0) {
+        event.preventDefault();
+        this._setActive(shortcut);
+        this._chooseEntry(this._optionEntries[shortcut]);
+        return;
+      }
+    }
     if (event.key === 'ArrowDown') {
       event.preventDefault();
       if (!this._open) this.open();
@@ -459,6 +586,7 @@ export class Select extends Component {
   _onInput() {
     if (!this.options.filter) return;
     const query = /** @type {HTMLInputElement} */ (this.refs.input).value;
+    this._syncValueAdornment();
     if (!this._open) this.open();
     if (this.options.filter === 'local') {
       this._visibleFixed = this._matchFixed(query);
@@ -481,6 +609,19 @@ export class Select extends Component {
   /** @param {SelectOptionEntry|undefined} entry @returns {void} */
   _chooseEntry(entry) {
     if (!entry) return;
+    if (entry.action) {
+      const detail = {
+        id: entry.action.id,
+        action: entry.action,
+        query: /** @type {HTMLInputElement} */ (this.refs.input).value,
+        select: this
+      };
+      const action = this.emit('action', detail);
+      if (!action.defaultPrevented) entry.action.invoke?.(detail);
+      this.close();
+      this.focus();
+      return;
+    }
     this.set(entry.clear ? null : entry.item);
     this.close();
     this.focus();
@@ -516,16 +657,22 @@ export class Select extends Component {
     list.replaceChildren();
     this._optionEntries = [];
     let lastGroup = Symbol('initial-group');
+    const fixed = this._uniqueItems(this._visibleFixed);
+    const items = this._uniqueItems(this._visibleItems, fixed);
 
     if (this.options.clearable) {
-      this._appendOption(null, true, this.options.placeholder || this._message('select.none', 'No selection'));
+      this._appendOption(null, true, this.options.noneLabel
+        ?? this._message('select.none', 'No selection'));
+    }
+    if (fixed.length > 0 && this.options.fixedLabel) {
+      list.append(h('div', { class: 'zx-select__group', role: 'presentation' }, String(this.options.fixedLabel)));
     }
-    for (const item of this._visibleFixed) this._appendOption(item, false);
+    for (const item of fixed) this._appendOption(item, false);
     // A group heading already divides the two sections, and a rule right above one reads as a slip.
-    if (this._visibleFixed.length > 0 && this._visibleItems.length > 0 && !this.options.groupKey) {
+    if (fixed.length > 0 && items.length > 0 && !this.options.groupKey) {
       list.append(h('div', { class: 'zx-select__separator', role: 'presentation' }));
     }
-    for (const item of this._visibleItems) {
+    for (const item of items) {
       if (this.options.groupKey) {
         const group = this._read(item, this.options.groupKey);
         if (!Object.is(group, lastGroup)) {
@@ -538,7 +685,24 @@ export class Select extends Component {
       }
       this._appendOption(item, false);
     }
-    if (this._visibleItems.length === 0 && this._visibleFixed.length === 0 && !this._loading) {
+    if (this._actions.length > 0) {
+      if (fixed.length > 0 || items.length > 0 || this.options.clearable) {
+        list.append(h('div', { class: 'zx-select__separator', role: 'presentation' }));
+      }
+      let actionGroup = Symbol('initial-action-group');
+      for (const action of this._actions) {
+        if (action.group && action.group !== actionGroup) {
+          list.append(h('div', {
+            class: 'zx-select__group',
+            role: 'presentation'
+          }, action.group));
+          actionGroup = action.group;
+        }
+        this._appendAction(action);
+      }
+    }
+    if (items.length === 0 && fixed.length === 0
+      && this._actions.length === 0 && !this._loading) {
       list.append(h('div', {
         class: 'zx-select__empty',
         role: 'status'
@@ -552,7 +716,9 @@ export class Select extends Component {
     const selected = clear ? this._selected === null :
       this._selected !== null && Object.is(this._itemValue(item), this.value);
     const index = this._optionEntries.length;
-    const content = clear ? String(label ?? '') : this._renderItem(item);
+    const content = clear && typeof this.options.renderNone === 'function'
+      ? normalizeRenderedContent(this.options.renderNone(String(label ?? '')))
+      : clear ? String(label ?? '') : this._renderItem(item);
     const option = h('div', {
       class: 'zx-select__option',
       id: uid('zx-select-option'),
@@ -562,15 +728,33 @@ export class Select extends Component {
     }, h('span', { class: 'zx-select__option-content' }, content));
     if (selected) option.append(icon('check', { size: 15 }));
     this.refs.list.append(option);
-    this._optionEntries.push({ item, clear, element: option });
+    this._optionEntries.push({ item, clear, action: null, element: option });
+  }
+
+  /** @param {SelectAction} action @returns {void} */
+  _appendAction(action) {
+    const index = this._optionEntries.length;
+    const visual = selectActionIcon(action.icon);
+    const option = h('div', {
+      class: 'zx-select__option zx-select__action',
+      id: uid('zx-select-option'),
+      role: 'option',
+      ariaSelected: 'false',
+      dataset: { index, kind: 'action' }
+    }, h('span', { class: 'zx-select__option-content zx-select__action-content' },
+      visual ? h('span', { class: 'zx-select__action-icon', ariaHidden: 'true' }, visual) : null,
+      h('span', { class: 'zx-select__action-copy' },
+        h('span', { class: 'zx-select__action-label' }, action.label),
+        action.description ? h('span', { class: 'zx-select__action-description' }, action.description) : null)));
+    this.refs.list.append(option);
+    this._optionEntries.push({ item: null, clear: false, action, element: option });
   }
 
   /** @param {SelectItem|null} item @returns {Node|string} */
   _renderItem(item) {
     if (typeof this.options.renderItem === 'function') {
       const rendered = this.options.renderItem(item);
-      return rendered && typeof rendered === 'object' && 'nodeType' in rendered ?
-        /** @type {Node} */ (rendered) : String(rendered ?? '');
+      return normalizeRenderedContent(rendered);
     }
     return this._itemLabel(item);
   }
@@ -645,9 +829,30 @@ export class Select extends Component {
     input.value = this._selected === null ? '' :
       (typeof this.options.renderValue === 'function' ?
         String(this.options.renderValue(this._selected) ?? '') : this._itemLabel(this._selected));
+    this._syncValueAdornment();
     this.refs.clear.hidden = !this.options.clearable || this._selected === null;
   }
 
+  /** @returns {void} */
+  _syncValueAdornment() {
+    const host = this.refs.valueAdornment;
+    if (!host) return;
+    const selectedLabel = this._selected === null ? '' :
+      (typeof this.options.renderValue === 'function'
+        ? String(this.options.renderValue(this._selected) ?? '') : this._itemLabel(this._selected));
+    const query = String((/** @type {HTMLInputElement} */ (this.refs.input))?.value ?? '');
+    if (this._selected === null || typeof this.options.renderValueAdornment !== 'function'
+      || Boolean(this.options.filter && query !== selectedLabel)) {
+      host.replaceChildren();
+      host.hidden = true;
+      return;
+    }
+    const rendered = this.options.renderValueAdornment(this._selected);
+    const content = normalizeRenderedContent(rendered);
+    host.replaceChildren(content instanceof Node ? content : document.createTextNode(content));
+    host.hidden = rendered == null || (typeof content === 'string' && content === '');
+  }
+
   /** @returns {void} */
   _syncDisabled() {
     const input = /** @type {HTMLInputElement} */ (this.refs.input);
@@ -702,6 +907,17 @@ export class Select extends Component {
     return matchItems(this._fixedItems, query, this._searchKeys());
   }
 
+  /** De-duplicates choices by public value while preserving caller order. @param {SelectItem[]} items @param {SelectItem[]} [excluded=[]] @returns {SelectItem[]} */
+  _uniqueItems(items, excluded = []) {
+    const values = excluded.map((item) => this._itemValue(item));
+    return items.filter((item) => {
+      const value = this._itemValue(item);
+      if (values.some((candidate) => Object.is(candidate, value))) return false;
+      values.push(value);
+      return true;
+    });
+  }
+
   /** @returns {number} */
   _selectedEntryIndex() {
     if (this._selected === null) return this.options.clearable ? 0 : -1;
@@ -715,11 +931,6 @@ export class Select extends Component {
     return itemIndex + (this.options.clearable ? 1 : 0);
   }
 
-  /** @param {string} name @returns {void} */
-  _rememberAttribute(element, name) {
-    this._originalAttributes.set(name, element.getAttribute(name));
-  }
-
   /** @param {string} key @param {string} fallback @returns {string} */
   _message(key, fallback) {
     const message = this.msg(key);
@@ -727,11 +938,113 @@ export class Select extends Component {
   }
 }
 
+/** @param {SelectItem} item @param {unknown} reader @returns {unknown} */
+function readSelectItem(item, reader) {
+  if (typeof reader === 'function') return reader(item);
+  if (item !== null && typeof item === 'object' && typeof reader === 'string') return item[reader];
+  return null;
+}
+
+/** @param {boolean|SelectAction} value @returns {SelectAction} */
+function normalizeEntityCreateAction(value) {
+  const descriptor = value === true ? {} : value;
+  return {
+    id: descriptor.id ?? 'create', label: descriptor.label ?? 'Create new…',
+    description: descriptor.description, group: descriptor.group ?? 'New',
+    icon: descriptor.icon ?? 'plus', invoke: descriptor.invoke
+  };
+}
+
+/** @param {unknown} value @returns {boolean} */
+
+/** @param {unknown} rendered @returns {Node|string} */
+function normalizeRenderedContent(rendered) {
+  return rendered && typeof rendered === 'object' && 'nodeType' in rendered
+    ? /** @type {Node} */ (rendered) : String(rendered ?? '');
+}
+
+/** @param {unknown} actions @returns {SelectAction[]} */
+function normalizeSelectActions(actions) {
+  if (!Array.isArray(actions)) return [];
+  return actions.filter((action) => action && typeof action === 'object'
+    && action.id != null && action.label != null).map((action) => ({
+    ...action,
+    label: String(action.label),
+    description: action.description == null ? undefined : String(action.description),
+    group: action.group == null ? undefined : String(action.group)
+  }));
+}
+
+/** @param {unknown} visual @returns {Node|null} */
+function selectActionIcon(visual) {
+  if (typeof visual === 'string') return icon(visual);
+  if (visual instanceof Node) return visual.cloneNode(true);
+  return null;
+}
+
+/** @param {Record<string, any>} item @param {boolean} label @returns {Node} */
+function priorityContent(item, label) {
+  return h('span', { class: 'zx-select__priority' },
+    priorityIndicator(item.level),
+    label ? h('span', {}, String(item.name)) : null);
+}
+
+/** @param {unknown} level @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) }
+  })));
+}
+
+/** @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',
+    description: input.description == null ? '' : String(input.description),
+    shortcut: input.shortcut == null ? '' : String(input.shortcut)
+  };
+}
+
+/** @param {Record<string, any>} item @returns {Node} */
+function statusContent(item) {
+  return h('span', { class: 'zx-select__status' },
+    statusIndicator(item),
+    h('span', { class: 'zx-select__status-copy' },
+      h('span', { class: 'zx-select__status-label' }, String(item.name)),
+      item.description ? h('span', { class: 'zx-select__status-description' }, item.description) : null),
+    item.shortcut ? h('kbd', { class: 'zx-select__status-shortcut' }, item.shortcut) : null);
+}
+
+/** @param {Record<string, any>} 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;
+}
+
 /** Change emitted when the selected value changes. @event Select#change @type {CustomEvent<SelectChangeDetail>} */
 /** Panel-open notification. @event Select#open @type {CustomEvent<Record<string, never>>} */
 /** Panel-close notification. @event Select#close @type {CustomEvent<Record<string, never>>} */
 /** Async-query start notification. @event Select#query @type {CustomEvent<SelectQueryDetail>} */
 /** Async results notification. @event Select#loaded @type {CustomEvent<SelectLoadedDetail>} */
+/** Command-row activation; preventing it suppresses the action callback. @event Select#action @type {CustomEvent<SelectActionDetail>} */
 
 /**
  * Reads a value off an item through a property name or a reader function.