@apliteni/apliteni-ui 0.129.0 → 0.131.0

package/src/components/account-nav.js

@@ -5,6 +5,7 @@
 // the published name docs/components.md documents.
 // why: docs/components.md#the-page-shell
 import { esc } from './index.js';
+import { avatarInitials } from '../logic/avatar.js';
 
 // nav.js item objects. Labels are raw text — every nav primitive escapes, so a
 // pre-escaped `&` would come out as `&`. `key` means credentials;
@@ -38,10 +39,6 @@ export const accountMenuNav = () => ACCOUNT_NAV.map(toMenuTuple);
 // beside ACCOUNT_NAV for the same reason ACCOUNT_NAV lives here: both files
 // need it and shell.js already imports topbar.js.
 //
-// The display name is what a reader recognises, so it wins; the address is the
-// fallback. `?` is what nobody at all comes out as.
-export const initials = (name, email) => {
-  const from = String(name ?? '').trim() || String(email ?? '').split('@')[0] || '';
-  const parts = from.split(/[\s._-]+/).filter(Boolean).map((w) => w[0]);
-  return (parts.slice(0, 2).join('') || '?').toUpperCase();
-};
+// The displayed name alone supplies the letters. The part draws its user glyph
+// when no name is shown.
+export const initials = (name) => avatarInitials(name);

package/src/components/avatar.js

@@ -0,0 +1,53 @@
+import { esc, icon } from './index.js';
+import { safeUrl } from '../html.js';
+import { avatarHue, avatarInitials } from '../logic/avatar.js';
+export { avatarHue, avatarInitials, AVATAR_HUES } from '../logic/avatar.js';
+
+// Avatar — a person's round mark. The letters come from `name`, the hue from a hash of
+// `key`, and a photo covers the letter. A photo that fails to load removes itself, so the
+// letter shows and not the browser's broken-image glyph.
+// With no name the mark is the `user` glyph; `empty` is a dashed ring for "no one yet".
+// It is decoration beside the name it stands for, so it is hidden from assistive
+// technology, and it has no cursor, hover or focus of its own.
+// why: docs/components.md#avatar
+const cx = (...a) => a.filter(Boolean).join(' ');
+const wiredDocs = new WeakSet();
+
+function wireAvatarPhotos(doc) {
+  if (!doc || wiredDocs.has(doc)) return;
+  wiredDocs.add(doc);
+  doc.querySelectorAll('.ui-avatar > img[data-avatar-photo]').forEach((img) => {
+    if (!img.complete) return;
+    if (img.naturalWidth > 0) img.classList.add('is-loaded');
+    else img.remove();
+  });
+  doc.addEventListener('load', (event) => {
+    if (event.target?.matches?.('.ui-avatar > img[data-avatar-photo]')) event.target.classList.add('is-loaded');
+  }, true);
+  doc.addEventListener('error', (event) => {
+    if (event.target?.matches?.('.ui-avatar > img[data-avatar-photo]')) event.target.remove();
+  }, true);
+}
+
+if (typeof document !== 'undefined') wireAvatarPhotos(document);
+
+/**
+ * @param {object} [o]
+ * @param {string|number} [o.key]  the app's stable id for the person; picks the hue
+ * @param {string} [o.name]        the person's name; empty draws the `user` glyph
+ * @param {string} [o.initials]    the letters to draw, when the caller has already chosen them
+ * @param {string} [o.src]         a photo URL; the letters show if it fails to load
+ * @param {24|32} [o.size]         the mark's size in px
+ * @param {boolean} [o.empty]      a dashed ring in place of a person
+ * @returns {string} html
+ */
+export function avatar({ key, name, initials, src, size = 24, empty = false } = {}) {
+  if (typeof document !== 'undefined') wireAvatarPhotos(document);
+  const base = ['ui-avatar', size === 32 && 'ui-avatar--32'];
+  if (empty) return `<span class="${esc(cx(...base, 'ui-avatar--empty'))}" aria-hidden="true"></span>`;
+  const letters = initials || avatarInitials(name);
+  if (!letters) return `<span class="${esc(cx(...base, 'ui-avatar--anon'))}" aria-hidden="true">${icon('user')}</span>`;
+  const hue = avatarHue(key ?? name ?? letters);
+  const img = src ? `<img data-avatar-photo src="${esc(safeUrl(src))}" alt="" loading="lazy">` : '';
+  return `<span class="${esc(cx(...base, `ui-avatar--h${hue}`))}" data-initials="${letters.length}" aria-hidden="true">${esc(letters)}${img}</span>`;
+}

package/src/components/dropdown.js

@@ -16,6 +16,7 @@ export { dropdownMatch, dropdownFiltering, dropdownAvail } from '../logic/dropdo
 //   wireDropdown(container);   // or let wireTopbar() do it
 import { esc, icon } from './index.js';
 import { safeUrl } from '../html.js';
+import { avatar } from './avatar.js';
 // The fade's own length, read off the stylesheet rather than copied. why: src/motion.js
 import { transitionMs } from '../motion.js';
 const cx = (...a) => a.filter(Boolean).join(' ');
@@ -39,7 +40,7 @@ function ddItem(it, listbox, ext) {
   const role = listbox ? 'option' : 'menuitem';
   const asLink = !!it.href && !disabled && !listbox;
   const tag = asLink ? 'a' : 'div';
-  const lead = it.icon ? `<span class="ui-dropdown__ic">${icon(it.icon)}</span>` : '';
+  const lead = it.avatar ? avatar(it.avatar) : it.icon ? `<span class="ui-dropdown__ic">${icon(it.icon)}</span>` : '';
   const desc = it.description ? `<span class="ui-dropdown__desc">${esc(it.description)}</span>` : '';
   const main = `<span class="ui-dropdown__main"><span class="ui-dropdown__label">${esc(it.label)}</span>${desc}</span>`;
   const badge = ddBadge(it.badge);
@@ -87,14 +88,25 @@ const ddIsRow = (it) => it && it !== '---' && !it.separator;
 
 let _ddSeq = 0;
 
-function ddSearchContext(search, id) {
+// "Search 214 people": the size of the whole set, in the placeholder and in the field's
+// name. `count: true` counts the rows, less a "No one" row, which is not a person.
+// why: docs/components.md#a-dropdown-with-a-search-field
+function ddCount(count, rows) {
+  if (count == null || count === false) return null;
+  const n = count === true ? rows.filter((it) => ddIsRow(it) && !it.avatar?.empty).length : Number(count);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+function ddSearchContext(search, id, rows) {
   const o = search === true ? {} : search;
+  const n = ddCount(o.count, rows);
+  const counted = n == null ? null : `Search ${n} ${o.noun || 'people'}`;
   return {
     base: id || `ui-dd-${++_ddSeq}`,
     n: 0,
     q: o.query || '',
-    label: o.label,
-    placeholder: o.placeholder || 'Search',
+    label: o.label || counted,
+    placeholder: o.placeholder || counted || 'Search',
     empty: o.empty || 'No match for “{q}”',
     hint: o.hint || 'Check the spelling, or try fewer letters.',
   };
@@ -146,7 +158,7 @@ function ddSearchBody({ items, sections }, sx, name, scroll) {
  * @param {string} [o.value]       current value shown in the trigger
  * @param {string} [o.placeholder] shown when there is no value
  * @param {string} [o.variant]     'select' (listbox) | 'menu' (inferred from items)
- * @param {Array}  [o.items]       [{ label, value?, description?, icon?, badge?, selected?, disabled?, href?, danger? }]
+ * @param {Array}  [o.items]       [{ label, value?, description?, icon?, avatar?, badge?, selected?, disabled?, href?, danger? }]
  * @param {Array}  [o.sections]    [{ label, items }] — grouped alternative to items
  * @param {string} [o.foot]        content for a pinned block at the panel's bottom edge,
  *   drawn as `.ui-dropdown__foot` — raw HTML, so escape your own text
@@ -160,8 +172,10 @@ function ddSearchBody({ items, sections }, sx, name, scroll) {
  * @param {boolean} [o.disabled]   the trigger is off: no stop, no panel, the kit's
  *   unavailable paint. #580
  * @param {string} [o.ariaLabel]   accessible name for the panel and trigger
- * @param {boolean|object} [o.search] true, or { placeholder, label, empty, hint, query } —
- *   a field above the rows that filters them; `empty` may carry {q}
+ * @param {boolean|object} [o.search] true, or { placeholder, label, empty, hint, query, count, noun } —
+ *   a field above the rows that filters them; `empty` may carry {q}; `count` (a number, or
+ *   true to count the rows) puts the size of the set in the placeholder and the field's
+ *   name, "Search 214 people", and `noun` replaces "people"
  * @returns {string} html
  */
 export function dropdown({
@@ -174,13 +188,18 @@ export function dropdown({
   const isSelect = variant === 'select' || (variant == null && flat.some((it) => it && (it.selected || it.value != null)));
   const listRole = isSelect ? 'listbox' : 'menu';
   const cur = value != null ? value : (isSelect ? (flat.find((it) => it && it.selected)?.label) : null);
-  const sx = search ? ddSearchContext(search, id) : null;
+  const sx = search ? ddSearchContext(search, id, flat) : null;
   const name = ariaLabel || (label ? String(label).replace(/:\s*$/, '') : '') || 'Options';
 
+  // A picker of people: the trigger leads with the chosen row's mark, and with no value
+  // a dashed ring beside the placeholder. why: docs/components.md#avatar
+  const marked = isSelect && flat.some((it) => it && it.avatar);
+  const chosen = marked && cur != null ? flat.find((it) => it && it.label === cur) : null;
+  const lead = marked && (chosen?.avatar || cur == null) ? avatar(chosen?.avatar ?? { empty: true }) : '';
   const trig = triggerContent != null
     ? triggerContent
-    : `${label ? `<span class="ui-dropdown__pre">${esc(label)}</span>` : ''}` +
-      `<span class="ui-dropdown__value">${esc(cur != null ? cur : placeholder)}</span>`;
+    : `${lead}${label ? `<span class="ui-dropdown__pre">${esc(label)}</span>` : ''}` +
+      `<span class="${esc(cx('ui-dropdown__value', marked && cur == null && 'is-placeholder'))}">${esc(cur != null ? cur : placeholder)}</span>`;
   const triggerAttrs = [
     `class="${esc(cx('ui-dropdown__trigger', triggerClass))}"`,
     'type="button"',
@@ -962,6 +981,13 @@ function selectOption(dd, item) {
   const valueEl = dd.querySelector('[data-dropdown-trigger] .ui-dropdown__value');
   const label = item.querySelector('.ui-dropdown__label');
   if (valueEl && label) valueEl.textContent = label.textContent;
+  // A picker of people carries the row's mark up into the trigger.
+  const mark = item.querySelector(':scope > .ui-avatar');
+  const lead = dd.querySelector('[data-dropdown-trigger] > .ui-avatar');
+  if (mark && lead) lead.replaceWith(mark.cloneNode(true));
+  else if (mark) dd.querySelector('[data-dropdown-trigger]')?.prepend(mark.cloneNode(true));
+  else lead?.remove();
+  valueEl?.classList.remove('is-placeholder');
 }
 
 // Click-outside, Escape and the repositioning sweep, registered once per document

package/src/components/shell.js

@@ -4,6 +4,7 @@
 // why: docs/components.md#the-page-shell
 import { topbar as productTopbar } from './topbar.js';
 import { esc, icon, button } from './index.js';
+import { avatar } from './avatar.js';
 import { sidebarNav, breadcrumbs, wireNav } from './nav.js';
 import { dropdown, wireDropdown } from './dropdown.js';
 import { drawer, wireDrawer, closeDrawer } from './drawer.js';
@@ -67,7 +68,7 @@ const toReader = (a) => (isRecord(a) ? { name: str(a.name), email: str(a.email)
 const toMenuReader = (a) => {
   const { name, email } = toReader(a);
   const rest = isRecord(a) && !Array.isArray(a) ? a : {};
-  const out = { ...rest, name: esc(name), email: esc(email), initials: esc(initials(name, email)) };
+  const out = { ...rest, name: esc(name), email: esc(email), initials: initials(name, email), key: email || name };
   if (out.nav != null) out.nav = toItems(out.nav).map(toMenuTuple);
   return out;
 };
@@ -195,7 +196,7 @@ function settle(options) {
 // inside it. why: docs/components.md#the-page-shell
 const readerFace = (name, email, named, markOnly = false) =>
   `<span class="ui-app__av"${named ? ` role="img" aria-label="Signed in as ${esc(named)}"` : ' aria-hidden="true"'}>`
-  + `${esc(initials(name, email))}</span>`
+  + `${avatar({ key: email || name, initials: initials(name, email), size: 32 })}</span>`
   + (markOnly ? '' : `<span class="ui-app__who"${named ? ' aria-hidden="true"' : ''}>`
     + (name ? `<b>${esc(name)}</b>` : '')
     + (email ? `<span>${esc(email)}</span>` : '')

package/src/components/toasts.js

@@ -16,6 +16,9 @@ import { toast } from './index.js';
 const reduceMotion = () =>
   typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 
+const resolve = (container) =>
+  (typeof container === 'string' ? document.querySelector(container) : container) || null;
+
 // Slide-and-fade a toast out, then remove it. Idempotent.
 export function dismissToast(el) {
   if (!el || el.dataset.leaving) return;
@@ -36,20 +39,41 @@ function wireToast(el) {
   el.querySelector('.ui-toast__close')?.addEventListener('click', () => dismissToast(el));
 
   const bar = el.querySelector('[data-toast-timer]');
-  if (bar && !reduceMotion()) {
+  if (bar) {
     bar.classList.add('is-running');
     const dur = parseFloat(getComputedStyle(el).getPropertyValue('--toast-dur')) || 5;
-    let timer = setTimeout(() => dismissToast(el), dur * 1000);
-    el.addEventListener('mouseenter', () => { clearTimeout(timer); bar.style.animationPlayState = 'paused'; });
-    el.addEventListener('mouseleave', () => {
-      bar.style.animationPlayState = 'running';
-      const left = (parseFloat(getComputedStyle(bar).transform.split(',')[0].slice(7)) || 1);
-      timer = setTimeout(() => dismissToast(el), dur * 1000 * left);
-    });
-  } else if (bar && reduceMotion()) {
-    // No animated bar under reduced motion, but still auto-dismiss on time.
-    const dur = parseFloat(getComputedStyle(el).getPropertyValue('--toast-dur')) || 5;
-    setTimeout(() => dismissToast(el), dur * 1000);
+    let remaining = dur * 1000;
+    let started = Date.now();
+    let timer = setTimeout(() => dismissToast(el), remaining);
+    // The line's own pause lives in the sheet, on :hover and :focus-within, so
+    // it covers a keyboard reader too. What is left here is the countdown that
+    // has to stop with it. This runs even under reduced motion, where the line
+    // is hidden but the reader still gets the same hold.
+    let held = false;
+    const hold = () => {
+      if (held) return;
+      held = true;
+      clearTimeout(timer);
+      const visualLeft = !reduceMotion()
+        ? parseFloat(getComputedStyle(bar).transform.split(',')[0].slice(7))
+        : NaN;
+      remaining = Number.isFinite(visualLeft)
+        ? dur * 1000 * visualLeft
+        : Math.max(0, remaining - (Date.now() - started));
+    };
+    const release = () => {
+      if (!held || el.matches(':hover, :focus-within')) return;
+      held = false;
+      started = Date.now();
+      timer = setTimeout(() => dismissToast(el), remaining);
+    };
+    el.addEventListener('mouseenter', hold);
+    el.addEventListener('mouseleave', release);
+    el.addEventListener('focusin', hold);
+    // At focusout the old target has already blurred and the new one has not
+    // focused yet, so :focus-within reads false even for a move from the close
+    // button to the action. relatedTarget is the only thing that knows.
+    el.addEventListener('focusout', (e) => { if (!el.contains(e.relatedTarget)) release(); });
   }
 
   // Swipe-to-dismiss (ignore drags that start on a button).
@@ -77,7 +101,7 @@ function wireToast(el) {
 
 // Wire every toast currently inside a container (string selector or element).
 export function wireToastStack(container) {
-  const root = typeof container === 'string' ? document.querySelector(container) : container;
+  const root = resolve(container);
   if (!root) return null;
   root.querySelectorAll('.ui-toast').forEach(wireToast);
   return root;
@@ -85,7 +109,7 @@ export function wireToastStack(container) {
 
 // Build a toast from opts, prepend it to a live stack (newest on top), wire it.
 export function pushToast(container, opts = {}) {
-  const root = typeof container === 'string' ? document.querySelector(container) : container;
+  const root = resolve(container);
   if (!root) return null;
   root.insertAdjacentHTML('afterbegin', toast(opts));
   const el = root.firstElementChild;

package/src/components/topbar.js

@@ -4,6 +4,7 @@ import { brand } from '../assets/brand.js';
 import { icon, sun, moon } from '../assets/icons.js';
 import { esc } from './index.js';
 import { wireDropdown } from './dropdown.js';
+import { avatar } from './avatar.js';
 import { accountMenuNav, initials, toMenuTuple } from './account-nav.js';
 import { trustedAttr, trustedUrl } from '../html.js';
 const THEME_KEY = 'apliteni-strategy-theme';
@@ -55,7 +56,7 @@ export function versionSwitcher(versions = [], activeIdx = 0) {
 // shell.js computes the mark from the caller's own strings and passes it down
 // beside them. Left out, it is computed here from `name` and `email`.
 export function accountMenu({
-  name = 'Ada Lovelace', email = 'ada@apliteni.com', active = 'prefs', nav, initials: mark,
+  name = 'Ada Lovelace', email = 'ada@apliteni.com', active = 'prefs', nav, initials: mark, key,
 } = {}) {
   // initials() is shared with the rail's avatar — the two are the same reader
   // on the /account preset, and they used to disagree about who that was.
@@ -76,9 +77,9 @@ export function accountMenu({
   // `on` so the menu is visible in Storybook / standalone use (no /auth/me gate).
   // Consumes the shared dropdown wiring via the generic [data-dropdown] hooks.
   return `<div class="acct on" data-dropdown>` +
-    `<button class="avatar" data-dropdown-trigger aria-haspopup="menu" aria-expanded="false" aria-label="Account">${ini}</button>` +
+    `<button class="avatar" data-dropdown-trigger aria-haspopup="menu" aria-expanded="false" aria-label="Account">${avatar({ key: key ?? (email || name), initials: ini, size: 32 })}</button>` +
     `<div class="amenu" data-dropdown-panel role="menu">` +
-    `<div class="ahead"><span class="avatar">${ini}</span><span class="aw"><span class="anm">${name}</span><span class="aem" title="${trustedAttr(email)}">${email}</span></span></div>` +
+    `<div class="ahead">${avatar({ key: key ?? (email || name), initials: ini, size: 32 })}<span class="aw"><span class="anm">${name}</span><span class="aem" title="${trustedAttr(email)}">${email}</span></span></div>` +
     items.map(it).join('') +
     `<div class="asep"></div><a class="aout" href="#logout" data-dd-item tabindex="-1" role="menuitem">${icon('logout')}Sign out</a>` +
     `</div></div>`;

package/src/index.css

@@ -21,6 +21,7 @@
 @import "./styles/button.css";
 @import "./styles/card.css";
 @import "./styles/badge.css";
+@import "./styles/avatar.css";
 @import "./styles/segmented.css";
 @import "./styles/tabs.css";
 @import "./styles/input.css";

package/src/index.d.ts

@@ -31,6 +31,14 @@ export declare function icon(name: string, className?: string): string;
 export declare function snippet(opts?: Record<string, unknown>): string;
 export declare function button(opts?: Record<string, unknown>): string;
 export declare function badge(label: string, variant?: string): string;
+export declare const AVATAR_HUES: 8;
+/** Which of the eight person hues a key gets: FNV-1a 32 bit over its UTF-8 bytes, modulo 8. */
+export declare function avatarHue(key: unknown): number;
+/** The first letter of the first word and of the last word, upper-cased; '' for no name. */
+export declare function avatarInitials(name: unknown): string;
+export declare function avatar(opts?: {
+  key?: string | number; name?: string | null; initials?: string; src?: string; size?: 24 | 32; empty?: boolean;
+}): string;
 export declare const calloutIcons: Record<'neutral' | 'info' | 'success' | 'warn' | 'danger', string>;
 export declare function callout(opts?: Record<string, unknown>): string;
 export declare function card(opts?: Record<string, unknown>): string;

package/src/index.js

@@ -1,6 +1,7 @@
 // apliteni-ui — public entry.
 // Styles ship separately: `import 'apliteni-ui/css'`.
 export * from './components/index.js';
+export * from './components/avatar.js';
 export * from './components/dropdown.js';
 export * from './components/tooltip.js';
 export * from './components/tabs.js';

package/src/inline.js

@@ -35,6 +35,7 @@ export const styles = {
   button: read('styles/button.css'),
   card: read('styles/card.css'),
   badge: read('styles/badge.css'),
+  avatar: read('styles/avatar.css'),
   segmented: read('styles/segmented.css'),
   tabs: read('styles/tabs.css'),
   input: read('styles/input.css'),
@@ -72,6 +73,7 @@ export const cssText = [
   styles.button,
   styles.card,
   styles.badge,
+  styles.avatar,
   styles.segmented,
   styles.tabs,
   styles.input,

package/src/logic/avatar.js

@@ -0,0 +1,28 @@
+/** How many hues a person's mark can take. One per `--person-N` token. */
+export const AVATAR_HUES = 8;
+
+/**
+ * Which hue a person gets: FNV-1a, 32 bit, over the UTF-8 bytes of the app's stable
+ * key, modulo the number of hues. The kit ships it so two apps give one person one hue.
+ */
+export function avatarHue(key) {
+  let h = 0x811c9dc5;
+  for (const byte of new TextEncoder().encode(String(key ?? ''))) {
+    h ^= byte;
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h % AVATAR_HUES;
+}
+
+/**
+ * The letters of a mark: the first letter of the first word and of the last word, so a
+ * one-word name gives one letter. Empty when there is no name to read.
+ */
+export function avatarInitials(name) {
+  const words = String(name ?? '').normalize('NFC').trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return '';
+  const segmenter = typeof Intl.Segmenter === 'function' ? new Intl.Segmenter(undefined, { granularity: 'grapheme' }) : null;
+  const first = (w) => segmenter ? segmenter.segment(w)[Symbol.iterator]().next().value.segment : Array.from(w)[0];
+  const letters = words.length === 1 ? [first(words[0])] : [first(words[0]), first(words[words.length - 1])];
+  return letters.join('').toLocaleUpperCase();
+}

package/src/styles/avatar.css

@@ -0,0 +1,42 @@
+/* Avatar — a person's round mark. Solid fill in the person's hue, the letters in the
+   solid-signal ink. Only the part's own paint is here: a control that holds one keeps
+   its own cursor, hover and ring. why: docs/components.md#avatar */
+.ui-avatar {
+  --ui-avatar-size: 24px;
+  --ui-avatar-hue: var(--person-0);
+  inline-size: var(--ui-avatar-size);
+  block-size: var(--ui-avatar-size);
+  flex: none;
+  display: inline-grid;
+  place-items: center;
+  position: relative;
+  overflow: hidden;
+  border-radius: 50%;
+  font-size: var(--text-xs);
+  font-weight: var(--weight-bold);
+  line-height: 1;
+  vertical-align: middle;
+  background: var(--ui-avatar-hue); /* code-bg: inherit — an opaque fill with its own ink. */
+  color: var(--signal-solid-ink);
+}
+.ui-avatar--32 { --ui-avatar-size: 32px; font-size: var(--text-base); }
+/* Two letters in 24px leave the type at the kit's smallest step; in 32px one step down. */
+.ui-avatar--32[data-initials="2"] { font-size: var(--text-sm); }
+.ui-avatar--h0 { --ui-avatar-hue: var(--person-0); }
+.ui-avatar--h1 { --ui-avatar-hue: var(--person-1); }
+.ui-avatar--h2 { --ui-avatar-hue: var(--person-2); }
+.ui-avatar--h3 { --ui-avatar-hue: var(--person-3); }
+.ui-avatar--h4 { --ui-avatar-hue: var(--person-4); }
+.ui-avatar--h5 { --ui-avatar-hue: var(--person-5); }
+.ui-avatar--h6 { --ui-avatar-hue: var(--person-6); }
+.ui-avatar--h7 { --ui-avatar-hue: var(--person-7); }
+
+/* The photo covers the letters, so one that fails leaves them showing. */
+.ui-avatar img { position: absolute; inset: 0; inline-size: 100%; block-size: 100%; object-fit: cover; opacity: 0; }
+.ui-avatar img.is-loaded { opacity: 1; }
+.ui-avatar svg { inline-size: 62%; block-size: 62%; stroke: currentColor; fill: none; stroke-width: 2.5; }
+
+/* No name: the user glyph on the kit's quiet fill. */
+.ui-avatar--anon { background: var(--surface-3); /* code-bg: inherit — a glyph, no text on it. */ /* muted-ink: glyph — a person with no name */ color: var(--muted); }
+/* No one: a dashed ring of the same size. */
+.ui-avatar--empty { background: none; border: 1px dashed var(--muted); /* muted-ink: glyph — the ring is a mark, not text */ color: var(--muted); }

package/src/styles/callout.css

@@ -93,9 +93,16 @@
 .ui-toast__close:hover { color: var(--text); }
 .ui-toast__close:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); border-radius: var(--radius-xs); }
 
-/* auto-dismiss progress bar — .is-running is added by wireToastStack() */
+/* auto-dismiss progress line — .is-running is added by wireToastStack() */
 .ui-toast__timer { position: absolute; left: 0; bottom: 0; height: 3px; width: 100%; background: var(--toast-accent); opacity: 0.85; transform-origin: left; }
-.ui-toast__timer.is-running { animation: ui-toast-timer var(--toast-dur, 5s) linear forwards; /* motion: ambient — the bar spends the toast's dismiss timer, which the caller sets */ }
+.ui-toast__timer.is-running { animation: ui-toast-timer var(--toast-dur, 5s) linear forwards; /* motion: ambient — the line spends the toast's dismiss timer, which the caller sets */ }
+/* The line spends the notice's own timer, so it stops exactly when the timer
+   does: under the pointer, and while focus is anywhere inside. Holding both
+   pauses here rather than in each face's event wiring keeps the line and the
+   countdown from drifting apart, and gives a keyboard reader the same reprieve
+   a pointer reader gets. */
+.ui-toast:hover > .ui-toast__timer.is-running,
+.ui-toast:focus-within > .ui-toast__timer.is-running { animation-play-state: paused; }
 
 /* Legacy style classes share the neutral card. */
 .ui-toast--soft, .ui-toast--solid, .ui-toast--outline { background: var(--surface); color: var(--text); }
@@ -110,7 +117,10 @@
 
 @media (prefers-reduced-motion: reduce) {
   .ui-toast, .ui-toast.is-leaving { animation: none; }
-  .ui-toast__timer.is-running { animation: none; }
+  /* A line that cannot move sits full for the whole five seconds and reads as
+     "no time spent yet" — the opposite of what it is there to say. The notice
+     still expires on time; only the false readout goes. */
+  .ui-toast__timer { display: none; }
 }
 
 /* stack container for queued toasts */

package/src/styles/dropdown.css

@@ -425,3 +425,21 @@
   /* muted-ink: state — off, unset, disabled or archived badge */
   color: var(--muted);
 }
+
+/* A picker of people. A mark leads the trigger and each row; with no value the trigger
+   shows the dashed ring beside the placeholder in the placeholder ink. The mark's own
+   margins give back the room it takes, so the trigger keeps its height.
+   why: docs/components.md#avatar */
+.ui-dropdown__trigger > .ui-avatar {
+  --ui-avatar-pull: 4px;
+  --ui-avatar-pull-start: 10px;
+  margin-block: calc(var(--ui-avatar-pull) * -1);
+  margin-inline-start: calc(var(--ui-avatar-pull-start) * -1);
+}
+.ui-dropdown__value.is-placeholder { /* muted-ink: placeholder — no person chosen */ color: var(--muted); font-weight: var(--weight-medium); }
+
+/* A dropdown that is a form control takes its field's width, and its panel the
+   trigger's. why: docs/components.md#avatar */
+.ui-field > .ui-dropdown { display: grid; }
+.ui-field > .ui-dropdown > .ui-dropdown__trigger > .ui-dropdown__chevron { margin-left: auto; }
+.ui-field > .ui-dropdown > .ui-dropdown__panel { inline-size: 100%; min-width: 0; }

package/src/styles/layout.css

@@ -161,13 +161,10 @@
 .ui-app__av {
   width: var(--ui-app-av); height: var(--ui-app-av); flex: none;
   margin-inline-start: calc((var(--ui-nav-strip) - var(--ui-app-av)) / 2);
-  border-radius: var(--radius-pill);
-  background: var(--surface); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */
-  color: var(--strong);
-  display: grid; place-items: center;
-  font-size: calc(var(--text-xs) + 1px);
-  font-weight: var(--weight-semibold);
+  display: grid;
 }
+/* The mark is the Avatar part in the reader's hue, filling this box like the top bar's. */
+.ui-app__av > .ui-avatar { --ui-avatar-size: 100%; }
 .ui-app__who { font-size: calc(var(--text-sm) - 0.5px); line-height: 1.3; min-width: 0; }
 .ui-app__who b { display: block; color: var(--strong); font-weight: var(--weight-semibold); }
 /* nowrap is what makes the ellipsis fire — without it the address wraps, and

package/src/styles/topbar.css

@@ -209,7 +209,7 @@
    src/styles/dropdown.css:271 `.ui-dropdown__item:hover`.
    why: docs/foundations.md#elevation */
 .vopt:hover { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */ }
-/* The row is a keyboard stop: src/components/dropdown.js:1165
+/* The row is a keyboard stop: src/components/dropdown.js:1191
    `items[next < 0 ? 0 : next]?.focus()` moves focus onto a `[data-dd-item]` with
    the arrow keys, and this is one. It takes the ring on its own 10px radius, the
    same way `.amenu a` above does. #482 */
@@ -306,6 +306,10 @@
    what the kit's rows already chose. why: docs/foundations.md#the-focus-ring */
 .acct .avatar:hover:not(:focus-visible) { border-color: var(--accent); }
 .avatar:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); }
+/* The account button holding an Avatar: the part paints the circle in the reader's hue and
+   the button keeps its edge, cursor, hover and ring. why: docs/components.md#avatar */
+.avatar:has(> .ui-avatar) { background: none; padding: 0; overflow: hidden; }
+.avatar > .ui-avatar { --ui-avatar-size: 100%; }
 .amenu {
   position: absolute;
   right: 0; top: 44px;
@@ -372,7 +376,6 @@
   border-radius: 14px 14px 0 0;
   display: flex; align-items: center; gap: 11px;
 }
-.amenu .ahead .avatar { cursor: default; }
 .amenu .ahead .aw { min-width: 0; display: flex; flex-direction: column; gap: 1px; line-height: 1.35; }
 .amenu .ahead .anm { color: var(--strong); font-size: var(--text-sm); font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .amenu .ahead .aem { color: var(--text); font-size: calc(var(--text-xs) + 0.5px); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }

package/src/tokens/tokens.css

@@ -257,6 +257,19 @@
   --signal-solid-info: var(--cyan);
   --signal-solid-neutral: var(--muted);
 
+  /* Person hues: the eight fills an Avatar takes from a hash of the person's key. Fixed
+     values and not accent tints, so a person keeps one hue under every accent and in
+     every app. Each is an existing kit value for this theme, and --signal-solid-ink
+     holds 4.5:1 on all eight. why: docs/components.md#avatar */
+  --person-0: #bd8cff;
+  --person-1: #5ab0ff;
+  --person-2: #20dcf5;
+  --person-3: #3ad9a0;
+  --person-4: #98ff8f;
+  --person-5: #ffcf6a;
+  --person-6: #ff8a5c;
+  --person-7: #f5aec6;
+
   /* DEPRECATED since #295: no surface below the floating step casts, and the floating
      step reads --elev-drop rather than any of these. Published still, so a consumer
      reading one gets nothing rather than an unresolved var(), and a consumer who wants a
@@ -446,6 +459,16 @@
   --signal-solid-danger: var(--chip-danger-ink);
   --signal-solid-warn: var(--chip-warn-ink);
   --signal-solid-info: var(--chip-info-ink);
+
+  /* Person hues, light: the deepened forms, so white holds on every one. */
+  --person-0: #6a2dcc;
+  --person-1: #005ab4;
+  --person-2: #096a7c;
+  --person-3: #076c48;
+  --person-4: #145a26;
+  --person-5: #825900;
+  --person-6: #a8370c;
+  --person-7: #b7295f;
   --signal-solid-neutral: var(--muted);
 
   /* Deprecated and unread — see the dark block. */