@lovett/ui 0.0.11 → 0.2.0

package/src/avatar.tsx

@@ -0,0 +1,352 @@
+/**
+ * Avatar / AvatarGroup — a person.
+ *
+ * ADR-147 D14. Photo when there is one, initials on an identity tint when
+ * there is not.
+ *
+ * ## Why this exists
+ *
+ * Four forks of "a circle with someone's initials in it" shipped independently
+ * and disagreed on every axis (ADR-147 Context):
+ *
+ *   • `task-card.tsx` `AvatarStack`   — whole-string hash mod 7, first+last
+ *     initial, opaque tint-ladder fill.  *(lives on `feat/tasks-lens`)*
+ *   • `components/ui/community/primitives.tsx` — first-CHARACTER hash mod 4
+ *     over `--info/--success/--warning/--accent`, translucent `@0.14` fill.
+ *   • `components/ui/admin/primitives.tsx`     — byte-identical clone of it.
+ *   • `lenses/assets/folders/folder-row.tsx`   — no hash at all: every owner
+ *     rendered in `--accent`.
+ *
+ * So the same person was a different colour on three screens, one screen gave
+ * everybody the same colour, and two of the four spent the view's single
+ * accent moment on a face.
+ *
+ * ## The API is `@lovett/ds`'s, for four measured reasons (D14)
+ *
+ * 1. **`tint` is a prop** — which colour belongs to which person is DATA (it
+ *    travels with the user record: `users.avatar_color`, D6), not theme. The
+ *    hash is the documented FALLBACK for until that column is populated, and
+ *    it lives in exactly one function (`avatarTintForKey`) rather than four.
+ * 2. **The initial stays in the DOM behind the photo**, so a broken `src`
+ *    degrades to a legible letter rather than a coloured hole. No fork even
+ *    accepted a `src`.
+ * 3. **`--avatar-ring`** takes the HOST SURFACE's colour from a CSS variable,
+ *    so a stack on a card and a stack in an inset well both read correctly
+ *    with no variant prop. Set it with one of the `.ds-avatar-on-*` classes.
+ * 4. **`max` and `total` are separate**, so three faces render out of forty
+ *    without passing forty children.
+ *
+ * ## Two deliberate divergences from ds
+ *
+ * • **`tint` is a palette KEY, not a colour string.** ds passes a raw colour
+ *   and puts it straight in `style.background`. Here that would walk an
+ *   arbitrary literal out of the database into app code, which is the exact
+ *   thing CLAUDE.md §4's token boundary exists to stop — and a raw colour
+ *   arrives with no ink or edge partner, so nothing can promise it is
+ *   readable. A key resolves to a full contrast-tuned rung set in both
+ *   themes. Same shape as `FolderCard`'s `colorKey` (ADR-035 D6).
+ * • **The initials are not white.** ds hardcodes a white literal because its
+ *   tint is a saturated data colour. Ours is an 18% mix toward the card, so
+ *   the glyph takes the ink rung — see the measured note in `styles.css`.
+ *
+ * ## D5 — nothing here fabricates a name
+ *
+ * `users.name`, `given_name` and `family_name` are ALL nullable by standing
+ * policy (`0014_sso_names.sql:13-16`: store NULL rather than invent). So
+ * `name` is typed `string | null`: still required (the caller must say what it
+ * has), still allowed to be nothing. A missing name renders `?` on a stable
+ * tint and is announced as "Unknown person" — honest, not invented, and it
+ * does not crash.
+ */
+
+import { Children, useState } from 'react'
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import { FOLDER_COLOR_KEYS, type FolderColorKey } from './folder-card'
+import { cn } from './lib/utils'
+
+/* ── TINT ─────────────────────────────────────────────────────────────────── */
+
+/**
+ * The identity hues an avatar may take: every `--folder-*` key except `red`.
+ *
+ * `red` is excluded on purpose — `--folder-red` is byte-identical to
+ * `--accent` in light mode, so a red face would spend the view's single accent
+ * moment on a person (CLAUDE.md §Design principles → Color & emphasis).
+ *
+ * Deliberately the same set, in the same order, as the tasks board's
+ * `BOARD_HUE_KEYS` (`feat/tasks-lens`, `hue.ts`), so that when that branch
+ * merges its `AvatarStack` can adopt this primitive without any avatar
+ * changing colour.
+ */
+export type AvatarTint = Exclude<FolderColorKey, 'red'>
+
+/** All avatar tints, in palette order. */
+export const AVATAR_TINTS: readonly AvatarTint[] = FOLDER_COLOR_KEYS.filter(
+  (key): key is AvatarTint => key !== 'red',
+)
+
+/**
+ * Parse a stored colour into a tint, at the boundary.
+ *
+ * `users.avatar_color` (ADR-147 D6) is a nullable TEXT column: a string from
+ * the database, not a domain value. This is the one place it is validated —
+ * anything that is not a known key (an old value, a hand-edited row, a hex
+ * somebody wrote by hand) becomes `undefined`, and `Avatar` then falls back to
+ * the hash rather than rendering an unknown class or an untrusted literal.
+ *
+ * Returns `undefined` rather than a default so the caller can spread it
+ * conditionally under `exactOptionalPropertyTypes`, and so "no colour stored"
+ * and "slate was stored" stay distinguishable.
+ */
+export function asAvatarTint(value: string | null | undefined): AvatarTint | undefined {
+  if (value == null) return undefined
+  return AVATAR_TINTS.find((tint) => tint === value)
+}
+
+/**
+ * A stable tint for an arbitrary identity string.
+ *
+ * **This is the fallback, not the plan.** ADR-147 D6 adds `users.avatar_color`
+ * so identity colour becomes data that travels with the user record; until it
+ * is populated, this derives one. Deterministic, so the same person is the
+ * same colour on every render and every machine — an avatar that changes
+ * colour reads as a different person. A display hash, not a distribution or
+ * security primitive.
+ *
+ * Same algorithm and same key order as `hueForKey` on `feat/tasks-lens`; when
+ * that branch merges, the two collapse into one function.
+ */
+export function avatarTintForKey(seed: string): AvatarTint {
+  let hash = 0
+  for (let i = 0; i < seed.length; i += 1) {
+    hash = (hash * 31 + seed.charCodeAt(i)) | 0
+  }
+  const index = Math.abs(hash) % AVATAR_TINTS.length
+  return AVATAR_TINTS[index] ?? 'slate'
+}
+
+/* ── INITIALS ─────────────────────────────────────────────────────────────── */
+
+/** First whole glyph, so a surrogate pair or a combining mark is not sliced. */
+function firstGlyph(word: string): string {
+  return [...word][0] ?? ''
+}
+
+/**
+ * The monogram for a display name — **first and last word, capped at two**.
+ *
+ * The one helper, replacing three that disagreed: `task-card` took first+last,
+ * community and admin took the first two words ("Mary Jane Watson" → `MW` here
+ * and `MJ` there), and `folder-row` took a server-supplied string with no cap
+ * at all.
+ *
+ * First+last wins because the family name is the more identifying letter, and
+ * because it matches the tasks board, which is the only fork whose colour and
+ * geometry are already correct.
+ *
+ * Returns `?` for a null, empty or whitespace-only name (D5). It never
+ * fabricates.
+ */
+export function initials(name: string | null | undefined): string {
+  const words = (name ?? '').trim().split(/\s+/).filter(Boolean)
+  if (words.length === 0) return '?'
+  const first = firstGlyph(words[0] ?? '')
+  const last = words.length > 1 ? firstGlyph(words[words.length - 1] ?? '') : ''
+  return (first + last).toUpperCase()
+}
+
+/** Announced when a display name is null or blank. Honest, never invented. */
+const UNKNOWN_PERSON = 'Unknown person'
+
+/* ── AVATAR ───────────────────────────────────────────────────────────────── */
+
+export type AvatarSize = 'sm' | 'md' | 'lg'
+
+/**
+ * The two custom properties that carry a caller-supplied diameter into the
+ * CSS. Declared rather than cast: `as` on a style object is exactly the escape
+ * hatch CLAUDE.md asks us not to reach for.
+ */
+interface AvatarSizeVars extends CSSProperties {
+  '--avatar-size'?: string
+  '--avatar-font'?: string
+}
+
+/**
+ * Coefficient for a TWO-character monogram, taken from the community fork
+ * (`Math.round(size * 0.36)`), so its nine existing call sites keep the type
+ * size they render today. The three named sizes carry their own measured
+ * values in `styles.css` instead of deriving from this.
+ */
+function sizeVars(px: number): AvatarSizeVars {
+  return { '--avatar-size': `${px}px`, '--avatar-font': `${Math.round(px * 0.36)}px` }
+}
+
+export interface AvatarProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
+  /**
+   * Display name. Drives the monogram and the accessible name.
+   *
+   * Nullable on purpose (D5) — every name column in `users` is nullable by
+   * policy, and a component that cannot be handed a null forces every caller
+   * to invent a string.
+   */
+  name: string | null
+  /**
+   * Identity tint. Pass `users.avatar_color` once D6's column is populated;
+   * omit it and a stable tint is derived from `seed ?? name`.
+   */
+  tint?: AvatarTint
+  /** Photo. Falls back to the initials if it fails to load, or is absent. */
+  src?: string | null
+  /**
+   * `sm` (22) · `md` (32) · `lg` (52), or a raw pixel diameter.
+   *
+   * The number exists because the community and admin surfaces render avatars
+   * at 20, 24, 26 and 34 — none of which is on any scale. It keeps those call
+   * sites pixel-identical through the consolidation instead of making a
+   * colour refactor also a layout one. New code should use a named size.
+   */
+  size?: AvatarSize | number
+  /** Override the derived monogram — e.g. `"You"`, or a server-supplied one. */
+  initial?: string
+  /**
+   * Separating ring in the HOST SURFACE's colour, for overlapping faces.
+   * Reads `--avatar-ring`, which `.ds-avatar-on-card` / `-frame` / `-inset`
+   * set; defaults to the card surface.
+   */
+  ring?: boolean
+  /**
+   * Hash seed when `tint` is absent. Prefer a stable user id — a name can
+   * change, and the colour should not change with it.
+   */
+  seed?: string
+  /**
+   * Hide from the accessibility tree. Pass it when the name is already
+   * rendered beside the avatar (a table row, a byline), so a screen reader
+   * does not announce the same person twice.
+   */
+  decorative?: boolean
+}
+
+export function Avatar({
+  name,
+  tint,
+  src,
+  size = 'sm',
+  initial,
+  ring,
+  seed,
+  decorative,
+  className,
+  style,
+  ...rest
+}: AvatarProps) {
+  // Keyed by the src that failed rather than a bare boolean, so swapping in a
+  // new photo re-tries it. A boolean latches: once one URL 404s, every later
+  // one is suppressed for the life of the component.
+  const [failedSrc, setFailedSrc] = useState<string | null>(null)
+
+  const trimmed = name?.trim() ?? ''
+  const label = trimmed === '' ? UNKNOWN_PERSON : trimmed
+  const glyph = initial ?? initials(name)
+  const hue = tint ?? avatarTintForKey(seed ?? label)
+  const showImage = src != null && src !== '' && failedSrc !== src
+  const numeric = typeof size === 'number'
+
+  return (
+    <span
+      {...(decorative
+        ? { 'aria-hidden': true }
+        : { role: 'img', 'aria-label': label, title: label })}
+      className={cn(
+        'ds-avatar',
+        `ds-avatar--${hue}`,
+        !numeric && size !== 'sm' && `ds-avatar--${size}`,
+        ring && 'ds-avatar--ring',
+        className,
+      )}
+      style={numeric ? { ...sizeVars(size), ...style } : style}
+      {...rest}
+    >
+      {/*
+        The initial stays in the DOM BEHIND the photo, so a broken `src`
+        degrades to something legible instead of a coloured hole.
+
+        IT NEEDS ITS OWN ELEMENT. As a bare text node it is an anonymous grid
+        item; `text-box-trim` is not inherited and a grid container has no line
+        boxes of its own, so the optical-centring rule on `.ds-avatar` reaches
+        nothing at all. Measured in @lovett/ds: the glyph sat 1.3px high in a
+        24px avatar. A span is the element the trim can actually apply to.
+      */}
+      <span className="ds-avatar__mono">{glyph}</span>
+      {showImage ? (
+        <img className="ds-avatar__img" src={src} alt="" onError={() => setFailedSrc(src)} />
+      ) : null}
+    </span>
+  )
+}
+
+/* ── AVATAR GROUP ─────────────────────────────────────────────────────────── */
+
+export interface AvatarGroupProps extends HTMLAttributes<HTMLSpanElement> {
+  /** Show at most this many faces; the rest collapse into a `+N`. */
+  max?: number
+  /**
+   * Total participants, when more exist than were passed as children — so a
+   * thread with forty people renders three faces and `+37` without the caller
+   * mounting forty avatars to throw thirty-seven away.
+   */
+  total?: number
+  /** Size of the `+N` chip. Match the faces. */
+  size?: AvatarSize | number
+  /**
+   * Faces overlap and take a separating ring (default). `false` lays them
+   * side by side with a gap — what the tasks board card does, where the row
+   * is already tight and an overlap reads as a stack of one blob.
+   */
+  overlap?: boolean
+  children: ReactNode
+}
+
+export function AvatarGroup({
+  max = 3,
+  total,
+  size = 'sm',
+  overlap = true,
+  className,
+  children,
+  ...rest
+}: AvatarGroupProps) {
+  const faces = Children.toArray(children)
+  const shown = faces.slice(0, max)
+  const hidden = (total ?? faces.length) - shown.length
+  const numeric = typeof size === 'number'
+
+  return (
+    <span
+      className={cn(
+        'ds-avatar-group',
+        overlap ? 'ds-avatar-group--overlap' : 'ds-avatar-group--spaced',
+        className,
+      )}
+      {...rest}
+    >
+      {shown}
+      {hidden > 0 ? (
+        <span
+          role="img"
+          aria-label={`${hidden} more`}
+          className={cn(
+            'ds-avatar-group__more',
+            !numeric && size !== 'sm' && `ds-avatar--${size}`,
+          )}
+          style={numeric ? sizeVars(size) : undefined}
+        >
+          {/* tabular-nums lives in the CSS: +9 becoming +10 must not shift the
+              faces to its left. */}
+          +{hidden}
+        </span>
+      ) : null}
+    </span>
+  )
+}