@zeyos/zx 4.4.0 → 5.0.0

package/src/components/select/glyphs.js

@@ -0,0 +1,165 @@
+import { h } from '../../core/dom.js';
+import { icon } from '../../core/icons.js';
+
+/**
+ * The shapes a workflow-status glyph can take. Each status reads by shape first and colour
+ * second, so the set stays legible to readers who do not see the colour.
+ * @typedef {'dotted'|'ring'|'progress'|'review'|'ready'|'waiting'|'done'|'canceled'|'duplicate'} StatusIndicator
+ */
+/** @typedef {'muted'|'neutral'|'warning'|'info'|'accent'|'success'|'danger'} StatusTone */
+/**
+ * The built-in workflow statuses. `review` and `cancelled` are accepted as spellings of
+ * `in-review` and `canceled`.
+ * @typedef {'backlog'|'todo'|'in-progress'|'in-review'|'review'|'ready'|'waiting'|'done'|'canceled'|'cancelled'|'duplicate'} StatusId
+ */
+/**
+ * @typedef {Object} StatusIconOptions
+ * @property {StatusIndicator} [indicator] Shape, overriding the status's own.
+ * @property {StatusTone} [tone] Colour, overriding the status's own.
+ * @property {string|null} [label=null] Accessible name. Without one the glyph is decorative
+ *   (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+ *   status.
+ */
+/**
+ * @typedef {Object} PriorityIconOptions
+ * @property {string|null} [label=null] Accessible name. Without one the glyph is decorative
+ *   (`aria-hidden`) and must sit beside text, or inside a control with a tooltip, that says the
+ *   priority.
+ */
+
+/** Every shape `statusIcon()` draws. */
+export const STATUS_INDICATORS = Object.freeze([
+  'dotted', 'ring', 'progress', 'review', 'ready', 'waiting', 'done', 'canceled', 'duplicate'
+]);
+
+/** Every colour a status glyph takes, from the semantic set. */
+export const STATUS_TONES = Object.freeze([
+  'muted', 'neutral', 'warning', 'info', 'accent', 'success', 'danger'
+]);
+
+/**
+ * The built-in statuses in workflow order, as `[id, message key, English name, indicator, tone]`.
+ * `Select.status()` lists them; `statusIcon()` draws them.
+ */
+export 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']
+]);
+
+/** Other spellings of the built-in status ids. */
+const STATUS_ALIASES = Object.freeze({ review: 'in-review', cancelled: 'canceled' });
+
+/** The top priority level, the one coloured level: a danger square with an exclamation mark. */
+export const PRIORITY_URGENT = 4;
+
+/**
+ * Resolves the shape and colour of a status glyph.
+ *
+ * A status is a built-in id (or one of its other spellings), or a status item of the kind
+ * `Select.status({items})` takes, whose own `indicator` and `tone` win over the built-in status
+ * its `ID` names. Options win over both. An unknown shape falls back to the empty ring and an
+ * unknown colour to muted, as `Select.status()` does with a custom item.
+ * @param {StatusId|string|{ID?: unknown, id?: unknown, indicator?: unknown, tone?: unknown}|null|undefined} status
+ * @param {StatusIconOptions} [options={}] Overrides.
+ * @returns {{indicator: StatusIndicator, tone: StatusTone}}
+ */
+export function resolveStatusGlyph(status, options = {}) {
+  const item = status && typeof status === 'object' ? status : null;
+  const id = normalizeStatusId(item ? (item.ID ?? item.id) : status);
+  const preset = DEFAULT_STATUSES.find(([key]) => key === id);
+  const indicator = String(options.indicator ?? item?.indicator ?? preset?.[3] ?? 'ring');
+  const tone = String(options.tone ?? item?.tone ?? preset?.[4] ?? 'muted');
+  return {
+    indicator: /** @type {StatusIndicator} */ (STATUS_INDICATORS.includes(indicator) ? indicator : 'ring'),
+    tone: /** @type {StatusTone} */ (STATUS_TONES.includes(tone) ? tone : 'muted')
+  };
+}
+
+/**
+ * Maps a status id to its built-in spelling: trimmed, lower-cased, and `review` / `cancelled`
+ * read as `in-review` / `canceled`.
+ * @param {unknown} id Status id.
+ * @returns {string}
+ */
+export function normalizeStatusId(id) {
+  const key = String(id ?? '').trim().toLowerCase();
+  return STATUS_ALIASES[key] ?? key;
+}
+
+/**
+ * Settles a priority level: an integer from 0 (lowest) to 4 (highest), or `null` for no priority.
+ * Out-of-range numbers clamp; anything that is not a number reads as 0.
+ * @param {unknown} level Priority level.
+ * @returns {number|null}
+ */
+export function normalizePriorityLevel(level) {
+  if (level === null || level === undefined || level === '') return null;
+  return Math.max(0, Math.min(PRIORITY_URGENT, Math.trunc(Number(level) || 0)));
+}
+
+/**
+ * Draws the workflow-status glyph `Select.status()` shows, for a list row, a board column, a
+ * filter chip, or a heading — so every place a status appears reads as the picker that changes it.
+ *
+ * Built-in statuses: `backlog` (dotted ring), `todo` (empty ring), `in-progress` (ring with a
+ * centre dot), `in-review` (half filled; also `review`), `ready` (a third filled), `waiting` (two
+ * thirds filled), `done` (filled, with a check), `canceled` (filled, with a cross; also
+ * `cancelled`), and `duplicate` (ring with a slash). Colour only repeats what the shape says.
+ * @param {StatusId|string|{ID?: unknown, indicator?: unknown, tone?: unknown}} status Built-in id,
+ *   or a status item with its own `indicator` and `tone`.
+ * @param {StatusIconOptions} [options={}] Shape, colour, and accessible-name overrides.
+ * @returns {HTMLSpanElement} A `.zx-status-icon` element, decorative unless `label` is given.
+ */
+export function statusIcon(status, options = {}) {
+  const { indicator, tone } = resolveStatusGlyph(status, options ?? {});
+  const marker = /** @type {HTMLSpanElement} */ (h('span', {
+    class: 'zx-status-icon',
+    dataset: { indicator, tone }
+  }));
+  if (indicator === 'done') marker.append(icon('check', { size: 8 }));
+  if (indicator === 'canceled') marker.append(icon('x', { size: 7 }));
+  return name(marker, options?.label);
+}
+
+/**
+ * Draws the priority glyph `Select.priority()` shows. Levels 0–3 are four signal bars in muted
+ * ink, filled up to the level; level 4, the highest, is a filled danger square whose "!" the
+ * stylesheet draws, so it never joins the text beside it; no priority (`null`) is a row of dashes.
+ * @param {number|null} level Priority level, 0 (lowest) to 4 (highest), or `null` for none.
+ * @param {PriorityIconOptions} [options={}] Accessible-name option.
+ * @returns {HTMLSpanElement} A `.zx-priority-icon` element, decorative unless `label` is given.
+ */
+export function priorityIcon(level, options = {}) {
+  const normalized = normalizePriorityLevel(level);
+  const glyph = /** @type {HTMLSpanElement} */ (h('span', {
+    class: 'zx-priority-icon',
+    dataset: { level: normalized === null ? 'none' : normalized }
+  }, normalized === PRIORITY_URGENT ? null : Array.from({ length: PRIORITY_URGENT }, (_, index) => h('span', {
+    dataset: { filled: String(normalized !== null && index <= normalized) }
+  }))));
+  return name(glyph, options?.label);
+}
+
+/**
+ * Makes a glyph an image with an accessible name, or hides it from assistive technology.
+ * @param {HTMLSpanElement} glyph Glyph element.
+ * @param {unknown} label Accessible name, if any.
+ * @returns {HTMLSpanElement}
+ */
+function name(glyph, label) {
+  const text = label == null ? '' : String(label).trim();
+  if (text) {
+    glyph.setAttribute('role', 'img');
+    glyph.setAttribute('aria-label', text);
+  } else {
+    glyph.setAttribute('aria-hidden', 'true');
+  }
+  return glyph;
+}

package/src/components/select/select.css

@@ -30,7 +30,10 @@
   padding-inline-start: var(--zx-space-2) !important;
 }
 
-.zx-select__control:has(.zx-select__input:focus-visible) {
+/* The ring follows keyboard focus. A text input matches :focus-visible on a click as well, so the
+   component marks a pointer focus on a read-only input (`data-focus-origin="pointer"`) and the ring
+   waits for the first key. An editable input keeps it on click, as any text field does. */
+.zx-select:not([data-focus-origin="pointer"]) .zx-select__control:has(.zx-select__input:focus-visible) {
   box-shadow: var(--zx-focus-ring);
 }
 
@@ -85,9 +88,17 @@
   border-radius: var(--zx-radius-full);
 }
 
+/* Disabled reads the way a disabled Field does: text and frame fade together, nothing else
+   changes. Inside a disabled Field the field has already faded, so the Select does not again. */
+.zx-select[aria-disabled="true"] {
+  opacity: 0.65;
+}
+
+.zx-field[data-disabled="true"] .zx-select[aria-disabled="true"] {
+  opacity: 1;
+}
+
 .zx-select[aria-disabled="true"] .zx-select__control {
-  background: var(--zx-color-bg-page);
-  color: var(--zx-color-text-muted);
   cursor: default;
 }
 
@@ -97,7 +108,7 @@
   max-inline-size: calc(100vw - var(--zx-space-4));
   overflow: hidden;
   border: 1px solid var(--zx-color-overlay-border);
-  border-radius: var(--zx-radius-md);
+  border-radius: var(--zx-radius-lg);
   background-color: var(--zx-color-overlay-surface);
   background-image: var(--zx-overlay-surface-image);
   background-clip: padding-box;
@@ -118,10 +129,12 @@
   display: flex;
   align-items: center;
   gap: var(--zx-space-2);
-  min-block-size: var(--zx-control-height);
+  /* The same row as a menu item: a little under a control, the smallest radius. */
+  min-block-size: calc(var(--zx-control-height) - 2px);
   border-radius: var(--zx-radius-sm);
   cursor: default;
-  padding: var(--zx-space-1) var(--zx-control-pad-x);
+  padding: var(--zx-space-1) var(--zx-space-2);
+  line-height: 1.35;
 }
 
 .zx-select__option-content {
@@ -137,6 +150,8 @@
   background: var(--zx-color-overlay-hover);
 }
 
+/* The highlighted option (keyboard or pointer) is a neutral step; a chosen option is a pick and
+   keeps the accent tint and its check mark. */
 .zx-select__option[aria-selected="true"] {
   background: var(--zx-color-overlay-selected);
 }
@@ -146,6 +161,7 @@
   color: var(--zx-color-accent);
 }
 
+/* A caption for the options under it, in sentence case: quieter than the options, never louder. */
 .zx-select__group {
   position: sticky;
   z-index: 1;
@@ -153,10 +169,8 @@
   background: var(--zx-color-overlay-scrim);
   color: var(--zx-color-text-muted);
   font-size: var(--zx-text-xs);
-  font-weight: 700;
-  letter-spacing: 0.04em;
-  padding: var(--zx-space-2) var(--zx-control-pad-x) var(--zx-space-1);
-  text-transform: uppercase;
+  font-weight: var(--zx-weight-semibold);
+  padding: var(--zx-space-1) var(--zx-space-2);
 }
 
 @media (prefers-reduced-transparency: reduce) {
@@ -175,13 +189,13 @@
 
 .zx-select__separator {
   block-size: 1px;
-  margin: var(--zx-space-1) var(--zx-control-pad-x);
+  margin: var(--zx-space-1) var(--zx-space-2);
   background: var(--zx-color-overlay-divider);
 }
 
 .zx-select__empty {
   color: var(--zx-color-text-muted);
-  padding: var(--zx-space-3) var(--zx-control-pad-x);
+  padding: var(--zx-space-3) var(--zx-space-2);
   text-align: center;
 }
 
@@ -191,30 +205,59 @@
   gap: var(--zx-space-2);
 }
 
-.zx-select__priority-icon {
+/* The priority glyph — `priorityIcon()`, and the one Select.priority() draws, which also carries
+   `.zx-select__priority-icon`. Priority is read by height, not by hue: four signal bars, the filled
+   ones in muted ink and the rest a step quieter. Only the top level, the one that needs attention,
+   is coloured — a danger square with an exclamation mark. "No priority" is a row of dashes. Every
+   glyph takes the same box, so the labels after them line up. */
+.zx-priority-icon {
   display: inline-flex;
-  gap: 2px;
   flex: none;
-  color: var(--zx-color-warning);
+  vertical-align: middle;
+  align-items: flex-end;
+  gap: 1px;
+  box-sizing: border-box;
+  inline-size: 15px;
+  block-size: 14px;
+  padding-block: 1px;
+  color: var(--zx-color-text-muted);
 }
 
-.zx-select__priority-icon > span {
-  inline-size: 7px;
-  block-size: 7px;
-  border: 1px solid currentColor;
-  border-radius: 2px;
+.zx-priority-icon > span {
+  inline-size: 3px;
+  border-radius: 1px;
+  background: var(--zx-color-border-strong);
 }
 
-.zx-select__priority-icon > span[data-filled="true"] { background: currentColor; }
-.zx-select__priority-icon[data-level="0"] { color: var(--zx-color-success); }
-.zx-select__priority-icon[data-level="1"] {
-  color: color-mix(in srgb, var(--zx-color-success) 35%, var(--zx-color-warning));
+.zx-priority-icon > span:nth-child(1) { block-size: 25%; }
+.zx-priority-icon > span:nth-child(2) { block-size: 50%; }
+.zx-priority-icon > span:nth-child(3) { block-size: 75%; }
+.zx-priority-icon > span:nth-child(4) { block-size: 100%; }
+.zx-priority-icon > span[data-filled="true"] { background: currentColor; }
+
+.zx-priority-icon[data-level="none"] { align-items: center; }
+.zx-priority-icon[data-level="none"] > span {
+  block-size: 2px;
+  background: currentColor;
 }
-.zx-select__priority-icon[data-level="2"] { color: var(--zx-color-warning); }
-.zx-select__priority-icon[data-level="3"] {
-  color: color-mix(in srgb, var(--zx-color-warning) 35%, var(--zx-color-danger));
+
+.zx-priority-icon[data-level="4"] {
+  align-items: center;
+  justify-content: center;
+  inline-size: 14px;
+  margin-inline-end: 1px;
+  padding: 0;
+  border-radius: var(--zx-radius-sm);
+  background: var(--zx-color-danger);
+  color: var(--zx-color-on-accent);
+  font-size: 11px;
+  font-weight: var(--zx-weight-semibold);
+  line-height: 1;
+}
+
+.zx-priority-icon[data-level="4"]::before {
+  content: "!";
 }
-.zx-select__priority-icon[data-level="4"] { color: var(--zx-color-danger); }
 
 .zx-select__status {
   display: grid;
@@ -223,13 +266,20 @@
   gap: var(--zx-space-2);
 }
 
+/* An entity without a colour of its own is a neutral tile with muted ink; one with a colour is
+   filled with it and drawn in the inverse text colour. */
 .zx-select__entity-glyph {
   display: inline-grid;
   place-items: center;
   inline-size: 20px;
   block-size: 20px;
   border-radius: var(--zx-radius-sm);
-  background: var(--zx-select-entity-color, var(--zx-color-accent-subtle));
+  background: var(--zx-color-bg-muted);
+  color: var(--zx-color-text-muted);
+}
+
+.zx-select__entity-glyph[style*="--zx-select-entity-color"] {
+  background: var(--zx-select-entity-color);
   color: var(--zx-color-text-invert);
 }
 
@@ -256,10 +306,14 @@
   font-size: var(--zx-text-xs);
 }
 
-.zx-select__status-indicator {
+/* The workflow-status glyph — `statusIcon()`, and the one Select.status() draws, which also carries
+   `.zx-select__status-indicator`. Each status is a shape first and a colour second. */
+.zx-status-icon {
   position: relative;
   display: inline-grid;
   place-items: center;
+  box-sizing: border-box;
+  vertical-align: middle;
   inline-size: 14px;
   block-size: 14px;
   flex: none;
@@ -268,37 +322,37 @@
   color: var(--zx-color-text-muted);
 }
 
-.zx-select__status-indicator[data-tone="neutral"] { color: var(--zx-color-border-strong); }
-.zx-select__status-indicator[data-tone="warning"] { color: var(--zx-color-warning); }
-.zx-select__status-indicator[data-tone="info"] { color: var(--zx-color-info); }
-.zx-select__status-indicator[data-tone="accent"] { color: var(--zx-color-accent); }
-.zx-select__status-indicator[data-tone="success"] { color: var(--zx-color-success); }
-.zx-select__status-indicator[data-tone="danger"] { color: var(--zx-color-danger); }
+.zx-status-icon[data-tone="neutral"] { color: var(--zx-color-border-strong); }
+.zx-status-icon[data-tone="warning"] { color: var(--zx-color-warning); }
+.zx-status-icon[data-tone="info"] { color: var(--zx-color-info); }
+.zx-status-icon[data-tone="accent"] { color: var(--zx-color-accent); }
+.zx-status-icon[data-tone="success"] { color: var(--zx-color-success); }
+.zx-status-icon[data-tone="danger"] { color: var(--zx-color-danger); }
 
-.zx-select__status-indicator[data-indicator="dotted"] { border-style: dotted; }
-.zx-select__status-indicator[data-indicator="progress"]::after {
+.zx-status-icon[data-indicator="dotted"] { border-style: dotted; }
+.zx-status-icon[data-indicator="progress"]::after {
   content: "";
   inline-size: 4px;
   block-size: 4px;
   border-radius: inherit;
   background: currentColor;
 }
-.zx-select__status-indicator[data-indicator="review"] {
+.zx-status-icon[data-indicator="review"] {
   background: linear-gradient(90deg, currentColor 50%, transparent 50%);
 }
-.zx-select__status-indicator[data-indicator="ready"] {
+.zx-status-icon[data-indicator="ready"] {
   background: conic-gradient(currentColor 0 35%, transparent 35% 100%);
 }
-.zx-select__status-indicator[data-indicator="waiting"] {
+.zx-status-icon[data-indicator="waiting"] {
   background: conic-gradient(currentColor 0 70%, transparent 70% 100%);
 }
-.zx-select__status-indicator:is([data-indicator="done"], [data-indicator="canceled"]) {
+.zx-status-icon:is([data-indicator="done"], [data-indicator="canceled"]) {
   background: currentColor;
 }
-.zx-select__status-indicator:is([data-indicator="done"], [data-indicator="canceled"]) > .zx-icon {
+.zx-status-icon:is([data-indicator="done"], [data-indicator="canceled"]) > .zx-icon {
   color: var(--zx-color-bg-raised);
 }
-.zx-select__status-indicator[data-indicator="duplicate"]::after {
+.zx-status-icon[data-indicator="duplicate"]::after {
   content: "";
   inline-size: 8px;
   block-size: 2px;
@@ -343,7 +397,7 @@
 
 @media (prefers-reduced-motion: no-preference) {
   .zx-select__loading {
-    animation: zx-select-spin var(--zx-dur-slow) linear infinite;
+    animation: zx-select-spin 720ms linear infinite;
   }
 }
 
@@ -352,3 +406,42 @@
     transform: rotate(1turn);
   }
 }
+
+/*
+ * Quiet fields. Inside `[data-zx-fields="quiet"]` — a property panel, an inspector — the control
+ * reads as its value: no border, no fill, no chevron or clear button. Hover brings the hover fill
+ * and the chevron back; focus or an open list brings back the border, the control fill and the
+ * focus ring. A disabled control never lights up.
+ */
+[data-zx-fields="quiet"] .zx-select__control,
+[data-zx-fields="quiet"] .zx-select[aria-disabled="true"] .zx-select__control {
+  border-color: transparent;
+  background: transparent;
+}
+
+[data-zx-fields="quiet"] .zx-select :is(.zx-select__toggle, .zx-select__clear) {
+  opacity: 0;
+}
+
+[data-zx-fields="quiet"] .zx-select:not([aria-disabled="true"]):hover .zx-select__control {
+  background: var(--zx-color-bg-hover);
+}
+
+[data-zx-fields="quiet"] .zx-select:not([aria-disabled="true"]):is(:hover, :focus-within, [data-state="open"]) :is(.zx-select__toggle, .zx-select__clear) {
+  opacity: 1;
+}
+
+[data-zx-fields="quiet"] .zx-select:not([aria-disabled="true"]):is(:focus-within, [data-state="open"]) .zx-select__control {
+  border-color: var(--zx-color-border-control);
+  background: var(--zx-color-bg-control);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  [data-zx-fields="quiet"] .zx-select__control {
+    transition: background-color var(--zx-dur-fast) var(--zx-ease), border-color var(--zx-dur-fast) var(--zx-ease);
+  }
+
+  [data-zx-fields="quiet"] .zx-select :is(.zx-select__toggle, .zx-select__clear) {
+    transition: opacity var(--zx-dur-fast) var(--zx-ease);
+  }
+}