@zeyos/zx 4.4.0 → 5.0.0

package/src/components/avatar/avatar.js

@@ -1,20 +1,44 @@
 import { Component } from '../../core/component.js';
 import { h } from '../../core/dom.js';
 
+/**
+ * A categorical tone from the design system's tone palette (`--zx-color-tone-*`).
+ * @typedef {'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'} AvatarTone
+ */
+
 /**
  * @typedef {Object} AvatarOptions
  * @property {string|null} [src=null] Image URL.
- * @property {string} [name=''] Name used to derive fallback initials.
+ * @property {string} [name=''] Name used to derive the fallback initials and tone.
  * @property {string|null} [initials=null] Explicit fallback initials.
  * @property {string|null} [label=null] Accessible label; null makes the avatar decorative.
- * @property {string|number} [size='md'] Preset (`sm`, `md`, `lg`) or pixel size.
+ * @property {string|number} [size='md'] Preset — `sm` 24px, `md` 32px, `lg` 40px at the default
+ * spacing unit — or a pixel size. Below 24px the fallback shows a single initial.
  * @property {'circle'|'rounded'|'square'} [shape='circle'] Avatar shape.
+ * @property {AvatarTone|null} [tone=null] Fallback colour from the tone palette. `null` derives a
+ * stable tone from the name (or the initials when there is no name), so the same person gets the
+ * same colour on every screen; see {@link avatarTone}.
  * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Optional presence state.
  * @property {string|null} [statusLabel=null] Text alternative for the presence state.
  */
 
 /**
- * Stable-size user image with deterministic initials fallback and optional presence state.
+ * The tone palette, in hash order. Every entry is a valid `tone`; the hash picks among the
+ * chromatic ones and keeps `slate`, the neutral, for a fallback with no name behind it. Order is
+ * part of the contract: changing it moves every derived avatar to a different colour.
+ * @type {ReadonlyArray<AvatarTone>}
+ */
+export const AVATAR_TONES = Object.freeze(['blue', 'teal', 'green', 'amber', 'orange', 'red', 'pink', 'violet', 'slate']);
+
+/** The tones a name can hash to: the palette without its neutral. */
+const HASHED_TONES = Object.freeze(AVATAR_TONES.filter((tone) => tone !== 'slate'));
+
+/** Below this rendered size the fallback has room for one initial, not two. */
+const SINGLE_INITIAL_BELOW = 24;
+
+/**
+ * Stable-size user image with a deterministic fallback — initials on a tone picked from the name —
+ * and an optional presence state.
  * @extends {Component<AvatarOptions>}
  */
 export class Avatar extends Component {
@@ -28,6 +52,7 @@ export class Avatar extends Component {
     label: null,
     size: 'md',
     shape: 'circle',
+    tone: null,
     status: null,
     statusLabel: null
   };
@@ -48,6 +73,7 @@ export class Avatar extends Component {
       label: this.options.label,
       size: this.options.size,
       shape: this.options.shape,
+      tone: this.options.tone,
       status: this.options.status,
       statusLabel: this.options.statusLabel
     };
@@ -87,7 +113,7 @@ export class Avatar extends Component {
    */
   set(values = {}) {
     if (!values || typeof values !== 'object') return this;
-    for (const key of ['src', 'name', 'initials', 'label', 'size', 'shape', 'status', 'statusLabel']) {
+    for (const key of ['src', 'name', 'initials', 'label', 'size', 'shape', 'tone', 'status', 'statusLabel']) {
       if (Object.hasOwn(values, key)) this._state[key] = values[key];
     }
     this._sync();
@@ -130,7 +156,15 @@ export class Avatar extends Component {
       this.el.style.removeProperty('--zx-avatar-size');
     }
     this._syncLabel();
-    this.refs.fallback.textContent = String(this._state.initials || avatarInitials(this._state.name));
+    const name = String(this._state.name ?? '');
+    const limit = typeof size === 'number' && size < SINGLE_INITIAL_BELOW ? 1 : 2;
+    this.refs.fallback.textContent = this._state.initials
+      ? clipGraphemes(String(this._state.initials), limit)
+      : avatarInitials(name, limit);
+    const tone = AVATAR_TONES.includes(this._state.tone)
+      ? this._state.tone
+      : avatarTone(name.trim() ? name : this._state.initials);
+    this.el.dataset.tone = tone;
     const src = this._state.src == null ? '' : String(this._state.src).trim();
     if (src) {
       this.refs.image.setAttribute('src', src);
@@ -195,18 +229,48 @@ export class Avatar extends Component {
 }
 
 /**
- * Derives at most two uppercase initials from the first and last words of a name.
+ * Derives uppercase initials from the first and last words of a name.
  * @param {unknown} name Name-like value.
+ * @param {1|2} [limit=2] How many initials to return: two by default, one for an avatar too small
+ * to hold two legibly.
  * @returns {string}
  */
-export function avatarInitials(name) {
+export function avatarInitials(name, limit = 2) {
   const words = String(name ?? '').trim().split(/\s+/u).filter(Boolean);
   if (words.length === 0) return '?';
   const first = uppercaseInitial(words[0]);
-  const last = words.length > 1 ? uppercaseInitial(words[words.length - 1]) : '';
+  const last = limit > 1 && words.length > 1 ? uppercaseInitial(words[words.length - 1]) : '';
   return `${first}${last}`;
 }
 
+/**
+ * Picks a stable fallback tone for a name.
+ *
+ * The name is trimmed, NFC-normalised and lower-cased, then hashed with 32-bit FNV-1a over its
+ * UTF-16 code units, and the hash picks one of the eight chromatic tones of {@link AVATAR_TONES}.
+ * The result depends on nothing but the name — not the locale, the page, or the order avatars
+ * render in — so a person keeps their colour everywhere. An empty name is `slate`, the neutral
+ * tone, which no name hashes to.
+ * @param {unknown} name Name-like value.
+ * @returns {AvatarTone}
+ */
+export function avatarTone(name) {
+  const key = String(name ?? '').trim().normalize('NFC').toLowerCase();
+  if (!key) return 'slate';
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < key.length; index += 1) {
+    hash ^= key.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return HASHED_TONES[(hash >>> 0) % HASHED_TONES.length];
+}
+
+/** Keeps the first `limit` graphemes of explicit initials. @param {string} value @param {number} limit @returns {string} */
+function clipGraphemes(value, limit) {
+  if (limit > 1) return value;
+  return firstGrapheme(value.trim()) || value;
+}
+
 /** Returns one uppercased grapheme even when Unicode case expansion produces multiple letters. @param {string} word @returns {string} */
 function uppercaseInitial(word) {
   return firstGrapheme(firstGrapheme(word).toUpperCase());

package/src/components/badge/badge.css

@@ -1,3 +1,8 @@
+/*
+ * The neutral soft fill is a wash of the text colour rather than an opaque step of the surface
+ * scale: it darkens whatever it sits on by the same amount. In the dark theme the muted step is
+ * the raised one, so an opaque muted badge vanished on a raised card, a menu, or a dialog.
+ */
 .zx-badge {
   display: inline-flex;
   align-items: center;
@@ -5,12 +10,12 @@
   max-inline-size: 100%;
   border: 1px solid transparent;
   border-radius: var(--zx-radius-full);
-  background: var(--zx-color-bg-muted);
+  background: color-mix(in srgb, var(--zx-color-text) 7%, transparent);
   color: var(--zx-color-text-muted);
   padding-block: 2px;
   padding-inline: var(--zx-space-2);
   font-size: var(--zx-text-xs);
-  font-weight: 600;
+  font-weight: var(--zx-weight-medium);
   font-variant-numeric: tabular-nums;
   line-height: 1.35;
   white-space: nowrap;
@@ -127,6 +132,39 @@
   color: var(--zx-color-info);
 }
 
+/*
+ * Tone — categorical colour from the tone palette, for what a badge *is* (a project, a label, a
+ * module) rather than how it is doing. Declared after every `kind` rule so a tone wins at equal
+ * specificity: a badge has one colour, and a tone is the more specific request. Soft by default,
+ * borderless; solid fills with the tone's foreground; outline draws it.
+ */
+.zx-badge[data-tone] {
+  border-color: transparent;
+  background: var(--zx-badge-tone-bg);
+  color: var(--zx-badge-tone-fg);
+}
+
+.zx-badge[data-tone="blue"] { --zx-badge-tone-bg: var(--zx-color-tone-blue-bg); --zx-badge-tone-fg: var(--zx-color-tone-blue-fg); }
+.zx-badge[data-tone="teal"] { --zx-badge-tone-bg: var(--zx-color-tone-teal-bg); --zx-badge-tone-fg: var(--zx-color-tone-teal-fg); }
+.zx-badge[data-tone="green"] { --zx-badge-tone-bg: var(--zx-color-tone-green-bg); --zx-badge-tone-fg: var(--zx-color-tone-green-fg); }
+.zx-badge[data-tone="amber"] { --zx-badge-tone-bg: var(--zx-color-tone-amber-bg); --zx-badge-tone-fg: var(--zx-color-tone-amber-fg); }
+.zx-badge[data-tone="orange"] { --zx-badge-tone-bg: var(--zx-color-tone-orange-bg); --zx-badge-tone-fg: var(--zx-color-tone-orange-fg); }
+.zx-badge[data-tone="red"] { --zx-badge-tone-bg: var(--zx-color-tone-red-bg); --zx-badge-tone-fg: var(--zx-color-tone-red-fg); }
+.zx-badge[data-tone="pink"] { --zx-badge-tone-bg: var(--zx-color-tone-pink-bg); --zx-badge-tone-fg: var(--zx-color-tone-pink-fg); }
+.zx-badge[data-tone="violet"] { --zx-badge-tone-bg: var(--zx-color-tone-violet-bg); --zx-badge-tone-fg: var(--zx-color-tone-violet-fg); }
+.zx-badge[data-tone="slate"] { --zx-badge-tone-bg: var(--zx-color-tone-slate-bg); --zx-badge-tone-fg: var(--zx-color-tone-slate-fg); }
+
+.zx-badge[data-variant="solid"][data-tone] {
+  background: var(--zx-badge-tone-fg);
+  color: var(--zx-color-bg-surface);
+}
+
+.zx-badge[data-variant="outline"][data-tone] {
+  border-color: currentColor;
+  background: transparent;
+  color: var(--zx-badge-tone-fg);
+}
+
 .zx-badge[data-size="sm"] {
   gap: calc(var(--zx-space-1) / 2);
   padding-block: 1px;
@@ -139,6 +177,20 @@
   block-size: 5px;
 }
 
+/* A small badge with a dot keeps the medium badge's text size and a full step between dot and
+   label: at 11px with a 2px gap the dot ran into the first letter. The label's end gets a little
+   more room than the dot's start, which the pill's round end would otherwise crowd. */
+.zx-badge[data-size="sm"]:has(> .zx-badge__dot) {
+  gap: var(--zx-space-1);
+  padding-inline: var(--zx-space-1) calc(var(--zx-space-1) * 1.5);
+  font-size: var(--zx-text-xs);
+}
+
+.zx-badge[data-size="sm"]:has(> .zx-badge__dot) .zx-badge__dot {
+  inline-size: 6px;
+  block-size: 6px;
+}
+
 .zx-badge-group {
   display: inline-flex;
   flex-wrap: wrap;

package/src/components/badge/badge.js

@@ -1,11 +1,20 @@
 import { h } from '../../core/dom.js';
 import { icon as createIcon } from '../../core/icons.js';
 
+/**
+ * A categorical tone from the design system's tone palette (`--zx-color-tone-*`).
+ * @typedef {'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'} BadgeTone
+ */
+
 /**
  * @typedef {Object} BadgeOptions
  * @property {string} [label=''] Visible badge text.
  * @property {string|null} [icon=null] Icon name from `icons.js`, rendered before the label.
  * @property {'neutral'|'accent'|'success'|'warning'|'danger'|'info'} [kind='neutral'] Semantic intent.
+ * @property {BadgeTone|null} [tone=null] Categorical colour — a project, a label, a module — from
+ * the tone palette rather than the status set, so a tag never reads as a warning. When set it
+ * decides the colour and `kind` is ignored for it; `variant` still applies. Unknown names are
+ * ignored.
  * @property {'soft'|'solid'|'outline'} [variant='soft'] Fill treatment.
  * @property {'md'|'sm'} [size='md'] Badge size.
  * @property {boolean} [dot=false] Renders a small leading status dot instead of an icon.
@@ -18,18 +27,26 @@ const KINDS = Object.freeze(['neutral', 'accent', 'success', 'warning', 'danger'
 /** Fill treatments. */
 const VARIANTS = Object.freeze(['soft', 'solid', 'outline']);
 
+/**
+ * Categorical tones, in the order they are documented.
+ * @type {ReadonlyArray<BadgeTone>}
+ */
+export const BADGE_TONES = Object.freeze(['blue', 'teal', 'green', 'amber', 'orange', 'red', 'pink', 'violet', 'slate']);
+
 /** @type {Readonly<BadgeOptions>} */
 const defaults = Object.freeze({
   label: '',
   icon: null,
   kind: 'neutral',
+  tone: null,
   variant: 'soft',
   size: 'md',
   dot: false
 });
 
 /**
- * Creates a status pill: a small, non-interactive label carrying a semantic colour.
+ * Creates a status pill: a small, non-interactive label carrying a semantic colour — or, with
+ * `tone`, a categorical one.
  *
  * The badge is plain text content, so it needs no ARIA of its own. A badge without a label but
  * with a `title` is named for assistive technology through `role="img"`.
@@ -45,7 +62,8 @@ export function badge(opts = {}) {
     dataset: {
       kind: normalizeKind(options.kind),
       variant: normalizeVariant(options.variant),
-      size: normalizeSize(options.size)
+      size: normalizeSize(options.size),
+      tone: normalizeBadgeTone(options.tone) ?? undefined
     }
   }));
 
@@ -86,6 +104,15 @@ function normalizeVariant(value) {
     /** @type {'soft'|'solid'|'outline'} */ (value) : 'soft';
 }
 
+/**
+ * Resolves a categorical tone name, or null for anything outside the palette.
+ * @param {unknown} value Requested tone.
+ * @returns {BadgeTone|null}
+ */
+export function normalizeBadgeTone(value) {
+  return BADGE_TONES.includes(/** @type {BadgeTone} */ (value)) ? /** @type {BadgeTone} */ (value) : null;
+}
+
 /** @param {unknown} value @returns {'md'|'sm'} */
 function normalizeSize(value) {
   return value === 'sm' ? 'sm' : 'md';

package/src/components/button/button.css

@@ -40,20 +40,22 @@
   cursor: not-allowed;
 }
 
+/* The screen's one solid accent. It reads the solid-accent roles, which keep the deep stop with
+   white ink in both themes — the dark theme's bright text accent would make it a glowing slab. */
 .zx-btn[data-kind="primary"] {
-  border-color: var(--zx-color-accent);
-  background: var(--zx-color-accent);
-  color: var(--zx-color-on-accent);
+  border-color: var(--zx-color-accent-solid);
+  background: var(--zx-color-accent-solid);
+  color: var(--zx-color-on-accent-solid);
 }
 
 .zx-btn[data-kind="primary"]:hover:not(:disabled) {
-  border-color: var(--zx-color-accent-hover);
-  background: var(--zx-color-accent-hover);
+  border-color: var(--zx-color-accent-solid-hover);
+  background: var(--zx-color-accent-solid-hover);
 }
 
 .zx-btn[data-kind="primary"]:active:not(:disabled) {
-  border-color: var(--zx-color-accent-active);
-  background: var(--zx-color-accent-active);
+  border-color: var(--zx-color-accent-solid-active);
+  background: var(--zx-color-accent-solid-active);
 }
 
 .zx-btn[data-kind="danger"] {
@@ -66,6 +68,8 @@
   background: color-mix(in srgb, var(--zx-color-danger) 88%, var(--zx-color-text));
 }
 
+/* Ghost: no chrome until hovered, and its glyph in the subtle text colour so a row of them reads
+   as quiet affordances rather than a second toolbar of buttons. */
 .zx-btn[data-kind="ghost"] {
   border-color: transparent;
   background: none;
@@ -74,11 +78,43 @@
   box-shadow: none;
 }
 
+.zx-btn[data-kind="ghost"]:focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-btn[data-kind="ghost"] > .zx-icon {
+  color: var(--zx-color-text-subtle);
+}
+
 .zx-btn[data-kind="ghost"]:hover:not(:disabled) {
   border-color: transparent;
   background: var(--zx-color-bg-hover);
 }
 
+.zx-btn[data-kind="ghost"]:hover:not(:disabled) > .zx-icon {
+  color: var(--zx-color-text);
+}
+
+/* A pressed toggle (`aria-pressed="true"`, e.g. a Toolbar item with `active`) is a mode you are
+   in, not a pick: the neutral current fill and the full text colour, never the accent. */
+.zx-btn[aria-pressed="true"] {
+  border-color: var(--zx-color-border-control);
+  background: var(--zx-color-bg-current);
+  color: var(--zx-color-text);
+}
+
+.zx-btn[data-kind="ghost"][aria-pressed="true"] {
+  border-color: transparent;
+}
+
+.zx-btn[aria-pressed="true"] > .zx-icon {
+  color: var(--zx-color-text);
+}
+
+.zx-btn[aria-pressed="true"]:hover:not(:disabled) {
+  background: var(--zx-color-bg-current);
+}
+
 .zx-btn[data-size="sm"] {
   min-block-size: calc(var(--zx-control-height) - var(--zx-space-1));
   padding-inline: var(--zx-space-2);
@@ -93,14 +129,35 @@
   display: inline-flex;
 }
 
+/* Busy (setButtonBusy): the action is running. It keeps its look and its focus; a spinner leads
+   the label, and an icon it had steps aside for the spinner so the width holds. */
+.zx-btn[aria-busy="true"] {
+  cursor: progress;
+}
+
+.zx-btn[aria-busy="true"] > .zx-icon {
+  display: none;
+}
+
+.zx-btn__spinner {
+  flex: none;
+}
+
+/* The key hint is quieter than the label by colour and weight, not by opacity: faded white on a
+   solid fill falls below 4.5:1. On a solid button it keeps the button's ink at a lighter weight. */
 .zx-btn__shortcut {
   font: inherit;
   font-size: var(--zx-text-xs);
-  opacity: .7;
+  font-weight: 400;
+  color: var(--zx-color-text-muted);
   margin-inline-start: var(--zx-space-1);
   white-space: nowrap;
 }
 
+.zx-btn:is([data-kind="primary"], [data-kind="danger"]) .zx-btn__shortcut {
+  color: inherit;
+}
+
 .zx-btn-group > .zx-btn:not(:first-child) {
   margin-inline-start: -1px;
   border-start-start-radius: 0;
@@ -135,7 +192,8 @@
     backdrop-filter: none;
   }
 
-  .zx-btn[data-kind="primary"] {
+  .zx-btn[data-kind="primary"],
+  .zx-btn[aria-pressed="true"] {
     border-color: Highlight;
     background: Highlight;
     color: HighlightText;

package/src/components/button/button.js

@@ -1,5 +1,6 @@
 import { h } from '../../core/dom.js';
 import { icon as createIcon } from '../../core/icons.js';
+import { spinner } from '../loading/spinner.js';
 
 /** @typedef {{label:string,keys:string}} ButtonShortcut Visible hint and ARIA key combination; the host binds the action. */
 
@@ -10,6 +11,8 @@ import { icon as createIcon } from '../../core/icons.js';
  * @property {'default'|'primary'|'danger'|'ghost'} [kind='default'] Visual intent.
  * @property {'md'|'sm'} [size='md'] Control size.
  * @property {boolean} [disabled=false] Whether the button is disabled.
+ * @property {boolean} [busy=false] Whether the button is working on its action — see
+ *   `setButtonBusy()`.
  * @property {string} [title] Native title text.
  * @property {ButtonShortcut} [shortcut] Keyboard hint; does not register a keyboard handler.
  * @property {(event: MouseEvent) => void} [onclick] Click callback.
@@ -52,6 +55,7 @@ export function button(opts = {}) {
   if (options.shortcut) element.append(h('kbd', { class: 'zx-btn__shortcut', ariaHidden: 'true' }, options.shortcut.label));
   if (!options.label && options.title) element.setAttribute('aria-label', options.title);
   if (typeof options.onclick === 'function') element.onclick = options.onclick;
+  if (options.busy) setButtonBusy(element, true);
   return element;
 }
 
@@ -69,6 +73,40 @@ export function buttonGroup(buttons) {
   return group;
 }
 
+/**
+ * Marks a button as working on its action, or done. A busy button shows a spinner before its
+ * label, announces `aria-busy`, and ignores activation — but stays focusable, unlike a disabled
+ * one, so focus does not fall to the page while the work runs and the reader hears it finish.
+ * Works on any `.zx-btn`, including one the application built itself.
+ * @param {HTMLButtonElement} element
+ * @param {boolean} busy
+ * @returns {HTMLButtonElement} The same button.
+ */
+export function setButtonBusy(element, busy) {
+  // One guard per button, installed on first use: a busy button swallows clicks — keyboard
+  // activation included — before any of the application's own listeners see them.
+  if (!element.hasAttribute('data-busy-guard')) {
+    element.setAttribute('data-busy-guard', '');
+    element.addEventListener('click', (event) => {
+      if (element.getAttribute('aria-busy') !== 'true') return;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+    }, { capture: true });
+  }
+  element.querySelector(':scope > .zx-btn__spinner')?.remove();
+  if (busy) {
+    element.setAttribute('aria-busy', 'true');
+    element.setAttribute('aria-disabled', 'true');
+    const ring = spinner({ size: 'sm', kind: 'current' });
+    ring.classList.add('zx-btn__spinner');
+    element.prepend(ring);
+  } else {
+    element.removeAttribute('aria-busy');
+    element.removeAttribute('aria-disabled');
+  }
+  return element;
+}
+
 /** @param {unknown} value @returns {'default'|'primary'|'danger'|'ghost'} */
 function normalizeKind(value) {
   return ['primary', 'danger', 'ghost'].includes(String(value)) ?