@zeyos/zx 4.4.0 → 5.0.0

package/src/components/message/message.js

@@ -1,15 +1,32 @@
 import { Component } from '../../core/component.js';
-import { h } from '../../core/dom.js';
+import { h, resolveElement } from '../../core/dom.js';
 import { icon } from '../../core/icons.js';
 import { overlayHost } from '../../core/overlay-host.js';
+import { button } from '../button/button.js';
 
 /** @typedef {'info'|'success'|'warning'|'error'} MessageKind */
 
+/**
+ * The one command a message may carry, drawn as a small button beside its text.
+ * @typedef {Object} MessageAction
+ * @property {string} label Button text: a verb naming what happens ("Undo", "Approve", "Retry").
+ * @property {(event: MouseEvent) => void} [onclick] Runs when the button is activated, by pointer
+ *   or keyboard; the message closes right after it.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Button kind; the default is the
+ *   secondary button.
+ */
+
 /**
  * @typedef {Object} MessageShowOptions
  * @property {MessageKind|'danger'} [kind='info'] Message intent (`danger` aliases `error`).
- * @property {number} [timeout=4000] Auto-dismiss delay in milliseconds; zero persists.
+ * @property {number} [timeout=4000] Auto-dismiss delay in milliseconds; zero persists. A message
+ *   with an `action` stays at least 8000ms.
  * @property {boolean} [closable=true] Whether to render a close button.
+ * @property {MessageAction|null} [action=null] A command button inside the message. The message
+ *   never times out while the pointer is over it or focus is inside it.
+ * @property {Node|{toElement: () => Node|null}|null} [leading=null] Visual shown in place of the
+ *   kind icon, such as an Avatar's element. It is decorative — the message text must say what it
+ *   shows.
  * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns a floating toast.
  */
 
@@ -21,7 +38,15 @@ import { overlayHost } from '../../core/overlay-host.js';
  * @property {number} [maxVisible=5] Maximum number of visible messages.
  */
 
-/** @typedef {{close: () => void}} MessageHandle */
+/**
+ * Returned by every `show()`: closes that message early. Closing one that already closed, or one
+ * still waiting in the queue, is safe.
+ * @typedef {Object} MessageHandle
+ * @property {() => void} close Closes the message.
+ */
+
+/** The shortest time a message that carries an action stays, in milliseconds. */
+export const MESSAGE_ACTION_MIN_TIMEOUT = 8000;
 
 /**
  * @typedef {Object} ProgressHandle
@@ -135,7 +160,7 @@ export class Message extends Component {
     maxVisible: 5
   };
 
-  /** @type {WeakMap<Element, Message>} */
+  /** @type {WeakMap<Element, Message>} Floating region per overlay host. */
   static #floating = new WeakMap();
 
   /** @returns {HTMLElement} */
@@ -145,6 +170,8 @@ export class Message extends Component {
     this._createdRoot = created;
     this._original = created ? null : snapshot(root);
     this._entries = new Set();
+    /** @type {Element|null} The overlay host this instance is the floating region of; null when inline. */
+    this._floatingHost = null;
     this._queue = new MessageQueue(normalizeLimit(this.options.maxVisible), (entry) => {
       this._activate(entry);
     });
@@ -161,10 +188,13 @@ export class Message extends Component {
    * @returns {MessageHandle}
    */
   show(msg, options = {}) {
+    const action = normalizeMessageAction(options.action);
     const settings = {
       kind: normalizeKind(options.kind ?? this.options.kind),
-      timeout: normalizeTimeout(options.timeout ?? this.options.timeout),
-      closable: options.closable ?? Boolean(this.options.closable)
+      timeout: messageTimeout(options.timeout ?? this.options.timeout, action !== null),
+      closable: options.closable ?? Boolean(this.options.closable),
+      action,
+      leading: resolveLeading(options.leading)
     };
     const entry = this._createEntry(msg, settings);
     this._entries.add(entry);
@@ -232,10 +262,33 @@ export class Message extends Component {
     return this.#floatingRegion(options.scope)._progress(text);
   }
 
+  /**
+   * Removes a floating region at once, toasts and all, without waiting for them to time out.
+   *
+   * A region already removes itself when its last toast closes, and one whose host has left the
+   * document is replaced on the next toast, so this is only for a host being torn down while
+   * toasts are still showing — an application view unmounting its themed shell, say.
+   * @param {Element|string} scope Element or selector whose nearest Zx theme scope owns the region,
+   *   as passed to `show()`.
+   * @returns {boolean} Whether there was a region to remove.
+   */
+  static disposeRegion(scope) {
+    if (scope == null) return false;
+    const context = resolveElement(scope);
+    if (!context) return false;
+    const host = overlayHost(context);
+    const region = Message.#floating.get(host);
+    if (!region) return false;
+    Message.#floating.delete(host);
+    region._disposeFloating();
+    return true;
+  }
+
   /** @returns {void} */
   destroy() {
     if (this._cleaned) return;
     this._cleaned = true;
+    this._floatingHost = null;
     for (const entry of this._entries) {
       clearEntryTimers(entry);
       entry.node.remove();
@@ -288,13 +341,13 @@ export class Message extends Component {
 
   /**
    * @param {string|Node} msg
-   * @param {{kind: MessageKind, timeout: number, closable: boolean}} settings
+   * @param {{kind: MessageKind, timeout: number, closable: boolean, action?: MessageAction|null, leading?: Node|null}} settings
    * @param {{pct: number, text: string}|null} [progress=null]
    * @returns {any}
    */
   _createEntry(msg, settings, progress = null) {
     const iconHost = h('span', { class: 'zx-message__icon', ariaHidden: 'true' },
-      icon(settings.kind, { size: 18 })
+      settings.leading ?? icon(settings.kind, { size: 18 })
     );
     const content = h('div', { class: 'zx-message__content' });
     if (isNode(msg)) content.append(msg);
@@ -315,9 +368,13 @@ export class Message extends Component {
       timer: null,
       exitTimer: null,
       closed: false,
+      hovered: false,
+      focused: false,
+      returnFocus: null,
       progressBar: null,
       progressFill: null
     };
+    if (settings.leading) node.dataset.leading = '';
 
     if (progress) {
       node.dataset.progress = '';
@@ -336,6 +393,21 @@ export class Message extends Component {
       syncProgress(entry, progress);
     }
 
+    if (settings.action) {
+      const { label, kind, onclick } = settings.action;
+      const control = button({ label, kind, size: 'sm' });
+      control.classList.add('zx-message__action');
+      node.append(control);
+      this.listen(control, 'click', (event) => {
+        if (entry.closed) return;
+        try {
+          onclick?.(/** @type {MouseEvent} */ (event));
+        } finally {
+          this._close(entry);
+        }
+      });
+    }
+
     if (settings.closable) {
       const close = h('button', {
         class: 'zx-icon-btn zx-message__close',
@@ -346,8 +418,31 @@ export class Message extends Component {
       node.append(close);
       this.listen(close, 'click', () => this._close(entry));
     }
-    this.listen(node, 'mouseenter', () => this._pause(entry));
-    this.listen(node, 'mouseleave', () => this._resume(entry));
+    // Hover and focus each hold the timer (WCAG 2.2.1): a reader moving to the action or the close
+    // button must not have the message vanish under them, and it counts down again only once
+    // neither holds it.
+    this.listen(node, 'mouseenter', () => {
+      entry.hovered = true;
+      this._pause(entry);
+    });
+    this.listen(node, 'mouseleave', () => {
+      entry.hovered = false;
+      this._resume(entry);
+    });
+    this.listen(node, 'focusin', (event) => {
+      if (!entry.focused) {
+        const from = /** @type {FocusEvent} */ (event).relatedTarget;
+        entry.returnFocus = isNode(from) && !node.contains(/** @type {Node} */ (from)) ? from : null;
+      }
+      entry.focused = true;
+      this._pause(entry);
+    });
+    this.listen(node, 'focusout', (event) => {
+      const to = /** @type {FocusEvent} */ (event).relatedTarget;
+      if (isNode(to) && node.contains(/** @type {Node} */ (to))) return;
+      entry.focused = false;
+      this._resume(entry);
+    });
     return entry;
   }
 
@@ -361,7 +456,7 @@ export class Message extends Component {
 
   /** @param {any} entry @returns {void} */
   _schedule(entry) {
-    if (entry.closed || entry.remaining <= 0) return;
+    if (entry.closed || entry.remaining <= 0 || entry.hovered || entry.focused) return;
     entry.startedAt = Date.now();
     entry.timer = setTimeout(() => this._close(entry), entry.remaining);
   }
@@ -376,7 +471,7 @@ export class Message extends Component {
 
   /** @param {any} entry @returns {void} */
   _resume(entry) {
-    if (entry.closed || entry.timer !== null) return;
+    if (entry.closed || entry.timer !== null || entry.hovered || entry.focused) return;
     if (entry.remaining <= 0) {
       this._close(entry);
       return;
@@ -389,10 +484,12 @@ export class Message extends Component {
     if (entry.closed) return;
     entry.closed = true;
     clearEntryTimers(entry);
+    returnFocus(entry);
     if (!this._queue.isActive(entry)) {
       this._queue.remove(entry);
       entry.node.remove();
       this._entries.delete(entry);
+      this._releaseIfEmpty();
       return;
     }
 
@@ -415,6 +512,27 @@ export class Message extends Component {
     entry.node.remove();
     this._entries.delete(entry);
     this._queue.remove(entry);
+    this._releaseIfEmpty();
+  }
+
+  /**
+   * Takes a floating region out of the document once its last toast has gone, so an emptied host
+   * is not left holding a region nobody uses. Inline areas stay: their element is the caller's.
+   * @returns {void}
+   */
+  _releaseIfEmpty() {
+    if (!this._floatingHost || this._entries.size > 0) return;
+    Message.#release(this);
+  }
+
+  /**
+   * Destroys a floating region and removes its element.
+   * @returns {void}
+   */
+  _disposeFloating() {
+    const region = this.el;
+    this.destroy();
+    region.remove();
   }
 
   /**
@@ -428,11 +546,23 @@ export class Message extends Component {
     return message === key ? fallback : message;
   }
 
-  /** @param {Element|string|null|undefined} scope @returns {Message} */
+  /**
+   * Finds or creates the floating region for a scope. A cached region is reused only while it is
+   * still where it was put: a host emptied by `replaceChildren()` would otherwise keep receiving
+   * toasts in a node nobody can see.
+   * @param {Element|string|null|undefined} scope
+   * @returns {Message}
+   */
   static #floatingRegion(scope) {
-    const host = overlayHost(scope ?? null);
+    let host = overlayHost(scope ?? null);
+    // A scope that has itself left the document cannot show anything; the toast still must be seen.
+    if (!host.isConnected) host = overlayHost(null);
     const existing = this.#floating.get(host);
-    if (existing) return existing;
+    if (existing && existing.el.isConnected && existing.el.parentElement === host) return existing;
+    if (existing) {
+      this.#floating.delete(host);
+      existing._disposeFloating();
+    }
     const region = h('div', {
       class: 'zx-message-region',
       popover: 'manual',
@@ -441,10 +571,18 @@ export class Message extends Component {
     });
     host.append(region);
     const floating = new Message(region);
+    floating._floatingHost = host;
     this.#floating.set(host, floating);
     if (typeof region.showPopover === 'function') region.showPopover();
     return floating;
   }
+
+  /** @param {Message} region Floating region whose last toast closed. @returns {void} */
+  static #release(region) {
+    const host = region._floatingHost;
+    if (host && Message.#floating.get(host) === region) Message.#floating.delete(host);
+    region._disposeFloating();
+  }
 }
 
 /** @param {unknown} value @returns {MessageKind} */
@@ -460,6 +598,70 @@ function normalizeTimeout(value) {
   return Number.isFinite(timeout) ? Math.max(0, timeout) : 4000;
 }
 
+/**
+ * Settles how long a message stays. A message that carries an action stays at least
+ * `MESSAGE_ACTION_MIN_TIMEOUT`, so there is time to reach it; zero still means it stays until
+ * closed, and anything that is not a finite number falls back to the 4000ms default.
+ * @param {unknown} timeout Requested auto-dismiss delay in milliseconds.
+ * @param {boolean} [hasAction=false] Whether the message carries an action.
+ * @returns {number}
+ */
+export function messageTimeout(timeout, hasAction = false) {
+  const settled = normalizeTimeout(timeout);
+  return hasAction && settled > 0 ? Math.max(settled, MESSAGE_ACTION_MIN_TIMEOUT) : settled;
+}
+
+/**
+ * Copies a message action into the shape the message renders, or returns null when there is
+ * nothing to render: no object, or no label. An unknown `kind` reads as the default, secondary
+ * button, and a missing `onclick` leaves a button that only closes the message.
+ * @param {unknown} value Action descriptor.
+ * @returns {{label: string, kind: 'default'|'primary'|'danger'|'ghost', onclick: ((event: MouseEvent) => void)|null}|null}
+ */
+export function normalizeMessageAction(value) {
+  if (!value || typeof value !== 'object') return null;
+  const action = /** @type {Record<string, unknown>} */ (value);
+  const label = action.label == null ? '' : String(action.label).trim();
+  if (!label) return null;
+  const kind = ['primary', 'danger', 'ghost'].includes(String(action.kind))
+    ? /** @type {'primary'|'danger'|'ghost'} */ (action.kind) : 'default';
+  return {
+    label,
+    kind,
+    onclick: typeof action.onclick === 'function'
+      ? /** @type {(event: MouseEvent) => void} */ (action.onclick) : null
+  };
+}
+
+/**
+ * Accepts a node, or a component such as an Avatar, for the leading slot.
+ * @param {any} value Leading content.
+ * @returns {Node|null}
+ */
+function resolveLeading(value) {
+  if (isNode(value)) return /** @type {Node} */ (value);
+  if (value && typeof value === 'object' && typeof value.toElement === 'function') {
+    const element = value.toElement();
+    return isNode(element) ? element : null;
+  }
+  return null;
+}
+
+/**
+ * Hands focus back to where it came from when a message closes with focus inside it, so a keyboard
+ * reader is not dropped on the page body with the element they were on gone.
+ * @param {any} entry Message entry.
+ * @returns {void}
+ */
+function returnFocus(entry) {
+  const root = entry.node.getRootNode?.();
+  const active = root?.activeElement ?? globalThis.document?.activeElement;
+  if (!active || !entry.node.contains(active)) return;
+  const target = entry.returnFocus;
+  entry.returnFocus = null;
+  if (target?.isConnected && typeof target.focus === 'function') target.focus({ preventScroll: true });
+}
+
 /** @param {unknown} value @returns {number} */
 function normalizeLimit(value) {
   const limit = Number(value);

package/src/components/modal/modal.js

@@ -1,6 +1,6 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
-import { overlayHost } from '../../core/overlay-host.js';
+import { connectedOverlayHost, overlayHost } from '../../core/overlay-host.js';
 
 /**
  * Controls initial focus may be placed on: what a reader reaches with Tab, rather than everything
@@ -18,7 +18,7 @@ const FOCUSABLE_SELECTOR = [
  * @property {boolean} [closable=true] Whether Escape may close the modal.
  * @property {boolean} [lightDismiss=false] Whether a backdrop click closes the modal.
  * @property {boolean} [destroyOnClose=false] Whether to destroy the modal after it closes.
- * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -266,10 +266,25 @@ export class Modal extends Component {
       class: 'zx-modal'
     }, h('div', { class: 'zx-modal__content', ref: 'content' })));
     dialog.dataset.state = 'closed';
-    this.mountTarget().append(dialog);
+    this._mountInitial(dialog);
     return dialog;
   }
 
+  /**
+   * Gives a freshly rendered dialog its first home.
+   *
+   * A `scope` that is not in the document yet cannot say which theme it belongs to, and the
+   * `<body>` that `mountTarget()` would answer is outside it. The dialog then stays detached and
+   * `open()` places it, by which time the scope is in place. Called from `render()`, so it may
+   * read `this.options` but no instance state.
+   * @param {HTMLDialogElement} dialog The rendered dialog.
+   * @returns {void}
+   */
+  _mountInitial(dialog) {
+    if (this.options.scope != null && !connectedOverlayHost(this.options.scope)) return;
+    this.mountTarget().append(dialog);
+  }
+
   /**
    * Opens the modal in the browser top layer.
    * @returns {this}

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

@@ -29,7 +29,8 @@
   padding-inline: var(--zx-space-2);
   color: var(--zx-color-accent);
   font-size: var(--zx-text-xl);
-  font-weight: 750;
+  font-weight: 650;
+  letter-spacing: var(--zx-tracking-title);
 }
 
 .zx-navigation-bar__navigation {
@@ -51,10 +52,11 @@
   gap: var(--zx-space-2);
   border: 0;
   border-radius: var(--zx-control-radius);
-  background: var(--zx-color-bg-raised);
+  background: transparent;
   padding-inline: var(--zx-control-pad-x);
   color: var(--zx-color-text-muted);
   font: inherit;
+  font-weight: var(--zx-weight-medium);
   text-decoration: none;
   cursor: pointer;
 }
@@ -64,11 +66,12 @@
   color: var(--zx-color-text);
 }
 
+/* Where you are, not a pick: the neutral current fill, the full text colour, a heavier label. */
 .zx-navigation-bar__item[aria-current="page"],
 .zx-navigation-bar__item[aria-selected="true"] {
-  background: var(--zx-color-bg-selected);
-  color: var(--zx-color-accent);
-  font-weight: 650;
+  background: var(--zx-color-bg-current);
+  color: var(--zx-color-text);
+  font-weight: var(--zx-weight-semibold);
 }
 
 .zx-navigation-bar__item[aria-disabled="true"] {
@@ -81,18 +84,24 @@
   box-shadow: var(--zx-focus-ring);
 }
 
+/* A count beside a label, not a call to action: neutral, like the Tabbox count. */
 .zx-navigation-bar__badge {
   min-inline-size: var(--zx-space-4);
   border-radius: var(--zx-radius-full);
-  background: var(--zx-color-accent);
+  background: var(--zx-color-bg-current);
   padding-inline: var(--zx-space-1);
-  color: var(--zx-color-on-accent);
-  font-size: var(--zx-text-sm);
-  font-weight: 700;
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+  font-variant-numeric: tabular-nums;
+  font-weight: var(--zx-weight-medium);
   line-height: var(--zx-space-4);
   text-align: center;
 }
 
+.zx-navigation-bar__item:is([aria-current="page"], [aria-selected="true"]) .zx-navigation-bar__badge {
+  color: var(--zx-color-text);
+}
+
 .zx-navigation-bar__more {
   display: none;
 }

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

@@ -11,6 +11,7 @@ export function registerNumberFieldAdapter() {
       label: options.label ? String(options.label) : undefined,
       placeholder: options.placeholder,
       required: options.required,
+      name: field.name || null,
       ...(options.props ?? {})
     }));
     let setting = false;

package/src/components/number-field/number-field.css

@@ -75,3 +75,73 @@
   border-end-end-radius: var(--zx-control-radius);
   border-inline-start: 1px solid var(--zx-color-border-control);
 }
+
+/* In a Field the control fills its column, as a text input does, and gives way in a narrow one. */
+.zx-field__control > .zx-number-field {
+  display: flex;
+  inline-size: 100%;
+}
+
+.zx-field__control > .zx-number-field .zx-number-field__input {
+  min-inline-size: 0;
+}
+
+/*
+ * Quiet fields. Inside `[data-zx-fields="quiet"]` the number reads as text: no border, no fill,
+ * and the value at the start, where the text of the quiet fields around it starts. The steppers
+ * move after it, both at the trailing end, and stay hidden until hover or focus — kept in the
+ * layout, so nothing moves when they return. Focus brings back the border, the control fill and
+ * the focus ring. Disabled and read-only fields never light up.
+ */
+[data-zx-fields="quiet"] .zx-number-field {
+  border-color: transparent;
+  background: transparent;
+}
+
+[data-zx-fields="quiet"] .zx-number-field__input {
+  padding-inline-start: var(--zx-control-pad-x);
+  text-align: start;
+}
+
+[data-zx-fields="quiet"] .zx-number-field__step {
+  border-color: transparent;
+  opacity: 0;
+}
+
+[data-zx-fields="quiet"] .zx-number-field__step[data-step="down"] {
+  order: 1;
+  border-inline-end: 0;
+  border-inline-start: 1px solid transparent;
+  border-radius: 0;
+}
+
+[data-zx-fields="quiet"] .zx-number-field__step[data-step="up"] {
+  order: 2;
+}
+
+[data-zx-fields="quiet"] .zx-number-field:not([data-disabled], [data-readonly]):hover {
+  background: var(--zx-color-bg-hover);
+}
+
+[data-zx-fields="quiet"] .zx-number-field:not([data-disabled], [data-readonly]):is(:hover, :focus-within) .zx-number-field__step {
+  opacity: 1;
+}
+
+[data-zx-fields="quiet"] .zx-number-field:not([data-disabled], [data-readonly]):focus-within {
+  border-color: var(--zx-color-border-control);
+  background: var(--zx-color-bg-control);
+}
+
+[data-zx-fields="quiet"] .zx-number-field:not([data-disabled], [data-readonly]):focus-within .zx-number-field__step {
+  border-color: var(--zx-color-border-control);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  [data-zx-fields="quiet"] .zx-number-field {
+    transition: background-color var(--zx-dur-fast) var(--zx-ease), border-color var(--zx-dur-fast) var(--zx-ease);
+  }
+
+  [data-zx-fields="quiet"] .zx-number-field__step {
+    transition: opacity var(--zx-dur-fast) var(--zx-ease), border-color var(--zx-dur-fast) var(--zx-ease);
+  }
+}

package/src/components/number-field/number-field.js

@@ -336,6 +336,8 @@ export class NumberField extends Component {
   /** @param {KeyboardEvent} event @returns {void} */
   _onKeydown(event) {
     if (this._disabled || this._readonly) return;
+    // Chords belong to the page — Mod+Enter submits the form or dialog the field is in.
+    if (event.altKey || event.ctrlKey || event.metaKey) return;
     const large = Math.max(1, Math.trunc(Number(this.options.largeStep) || 1));
     const actions = {
       ArrowUp: () => this._stepBy(1),

package/src/components/pagination/pagination.css

@@ -3,7 +3,8 @@
  *
  * One row that wraps: the summary is pushed to the start, the page-size select and the pager sit
  * at the end. Page buttons are ordinary `.zx-btn` controls so they inherit the library's control
- * height, radius, and focus ring; only the current page repaints in the accent colour.
+ * height, radius, and focus ring; the current page takes the neutral current fill — it is where
+ * you are, not a call to action.
  */
 
 .zx-pagination {
@@ -70,15 +71,16 @@
   font-variant-numeric: tabular-nums;
 }
 
+/* The page you are on: the neutral current fill and a heavier figure, not a solid accent. */
 .zx-pagination__page[aria-current="page"] {
-  border-color: var(--zx-color-accent);
-  background: var(--zx-color-accent);
-  color: var(--zx-color-on-accent);
+  border-color: transparent;
+  background: var(--zx-color-bg-current);
+  color: var(--zx-color-text);
+  font-weight: var(--zx-weight-semibold);
 }
 
 .zx-pagination__page[aria-current="page"]:hover:not(:disabled) {
-  border-color: var(--zx-color-accent-hover);
-  background: var(--zx-color-accent-hover);
+  background: var(--zx-color-bg-current);
 }
 
 /* Decorative gap marker: never focusable, never announced. */

package/src/components/panel/panel.css

@@ -35,7 +35,7 @@
   padding: var(--zx-space-3) var(--zx-space-4);
   color: var(--zx-color-text);
   font: inherit;
-  font-weight: 650;
+  font-weight: var(--zx-weight-semibold);
   text-align: start;
 }
 

package/src/components/rating/rating.css

@@ -30,6 +30,13 @@
   clip-path: inset(0 calc(100% - var(--zx-rating-fill)) 0 0);
 }
 
+/* The icons are outlines; a chosen star is a solid one, so the two states differ in shape as well
+   as in colour. */
+.zx-rating__glyph[data-part="on"],
+.zx-rating__glyph[data-part="on"] .zx-icon {
+  fill: currentColor;
+}
+
 .zx-rating__symbol[data-preview] .zx-rating__glyph[data-part="on"] {
   color: var(--zx-color-warning);
   opacity: 0.75;

package/src/components/select/color.js

@@ -0,0 +1,22 @@
+import { isCssColor } from '../../core/util.js';
+
+/** A reference to one custom property, such as `var(--zx-color-tone-blue-fg)`. */
+const TOKEN_REFERENCE = /^var\(\s*--[\w-]+\s*\)$/;
+
+/**
+ * Accepts an item colour for an inline custom property: a CSS colour literal (`#0b7285`, `rgb(…)`,
+ * `oklch(…)`, a named colour) or a reference to a design token (`var(--zx-color-tone-blue-fg)`),
+ * so an item can follow the theme rather than fix one colour for light and dark alike. Anything
+ * else — other functions, declarations, a `var()` with a fallback — is refused.
+ *
+ * Shared by `Select.entity()` and `TagPicker`, the two components that take a colour per item.
+ *
+ * @param {unknown} value Candidate colour.
+ * @returns {string|null} The trimmed colour, or null when the value is not one.
+ */
+export function itemColor(value) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  if (TOKEN_REFERENCE.test(text)) return text;
+  return isCssColor(text) ? text : null;
+}

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

@@ -14,6 +14,8 @@ export function registerSelectFieldAdapter() {
       if (event.target.closest?.('.zx-field__label')) field.adapter.focus();
     });
     delete selectOptions.preset;
+    // The priority preset offers "No priority" (null) by default; a required field cannot hold it.
+    if (preset === 'priority' && props.clearable === undefined) selectOptions.clearable = !options.required;
     const select = field.own(preset === 'priority'
       ? Select.priority(null, selectOptions)
       : preset === 'status'