@lovett/ui 0.0.11 → 0.2.0

package/dist/tokens.css

@@ -33,6 +33,14 @@
  *                  --destructive(-bg, -foreground)
  *     • Folder:    --folder-red/amber/emerald/teal/blue/violet/pink/
  *                  slate/ink (categorical palette for folder accents)
+ *     • Series:    --series-1…8 (categorical CHART palette; ADR-146 D2.
+ *                  theme-INDEPENDENT, and the SLOT ORDER IS LOAD-BEARING
+ *                  — see the block near the end of this file before
+ *                  "tidying" it)
+ *     • Chart:     --chart-grid, --chart-axis, --chart-band (chart
+ *                  structure — gridlines, the darker baseline rule, and
+ *                  the hover band; ADR-146 D3. Theme-tuned, and all
+ *                  three ALREADY CARRY ALPHA — never add a second one)
  *     • Spacing:   --space-1…12 (4 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48)
  *     • Radius:    --radius-xs/sm/md/lg/xl/2xl/full, --radius (legacy)
  *     • Motion:    --ease-out, --ease-spring, --ease-in-out,
@@ -188,6 +196,34 @@
 
   --border: 255 255 255 / 0.08;
   --border-strong: 255 255 255 / 0.14;
+
+  /* ============================================================
+     CHART STRUCTURE — PUBLIC, theme-tuned (ADR-146 D3).
+     The greys a chart needs that are NOT a card border, plus the
+     hover-band fill. This is the "structure is required, not banned"
+     layer of the data-display recipe (CLAUDE.md §2): gridlines and a
+     baseline are what make a plot legible, and deleting them is the
+     flat/floating defect, not a cleanup.
+
+     --chart-axis IS DELIBERATELY DARKER THAN --chart-grid. The
+     baseline rule must outrank the gridlines. Every chart in the
+     Metoric kit draws it that way (#111111 baseline vs #dfe1e6 grid)
+     and it is the single detail that does most for chart legibility.
+     It lives as its own token precisely so it cannot drift back to
+     "same grey as the grid".
+
+     ALL THREE ALREADY CARRY AN ALPHA — they composite onto whichever
+     panel they sit on, so the panel stays opaque and the structure
+     stays translucent. Consume as `rgb(var(--chart-grid))` and NEVER
+     as `rgb(var(--chart-grid) / 0.5)`: a second alpha expands to
+     `rgb(255 255 255 / 0.07 / 0.5)`, which is invalid CSS and is
+     SILENTLY DISCARDED. `__tests__/token-shape.test.ts` fails on
+     exactly that shape.
+     ============================================================ */
+  --chart-grid: 255 255 255 / 0.07;
+  --chart-axis: 255 255 255 / 0.22;
+  --chart-band: 255 255 255 / 0.05;
+
   /* Semantic — PUBLIC */
   --success: 16 185 129;
   --success-bg: 16 185 129 / 0.12;
@@ -527,6 +563,14 @@
 
   --border: 0 0 0 / 0.12;
   --border-strong: 0 0 0 / 0.20;
+
+  /* Chart structure — see the :root block for the reasoning. The same
+     two invariants hold in light: --chart-axis stays darker than
+     --chart-grid, and all three already carry their alpha. */
+  --chart-grid: 0 0 0 / 0.08;
+  --chart-axis: 0 0 0 / 0.24;
+  --chart-band: 0 0 0 / 0.04;
+
   /* Bumped from 0.16 → 0.22 — inputs on a white --bg-input (above) sitting
    * inside a Card (--bg-card = 255 / same as input) need a stronger border
    * to delineate. The 0.16 value worked when --bg-input was slate-tinted; on
@@ -813,3 +857,71 @@
   --media-on-scrim: 255 255 255 / 0.88;
   --media-overlay-btn: 255 255 255 / 0.14;
 }
+
+/* ============================================================
+   CATEGORICAL SERIES PALETTE (theme-INDEPENDENT) — PUBLIC
+   ------------------------------------------------------------
+   The chart series palette (ADR-146 D2). Hues carried over from
+   `theme-v2.css`, which designed them at constant lightness ~0.62
+   and then never shipped a consumer.
+
+   THEME-INDEPENDENT ON PURPOSE, and verified rather than assumed:
+   lightness 0.62 sits inside BOTH the light band (0.43-0.77) and the
+   dark band (0.48-0.67), and all eight clear 3:1 against #ffffff,
+   against --surface-frame (#f7f7f9) and against dark --surface-card
+   (#1b1b1e). Same precedent as --hierarchy-* and --platform-* above:
+   one block, no light/dark override.
+
+   BARE TRIPLES. The call site owns the alpha — a line is
+   `rgb(var(--series-1))` and the area under it is
+   `rgb(var(--series-1) / 0.12)`. A baked-in alpha would expand to
+   `rgb(2 137 234 / 0.3 / 0.12)`, which is invalid and silently
+   dropped, and it would make the token un-shareable between the two
+   uses.
+
+   ------------------------------------------------------------
+   THE SLOT ORDER IS LOAD-BEARING. DO NOT "TIDY" IT.
+   ------------------------------------------------------------
+   The order was chosen by measurement (the dataviz skill's
+   validate_palette.js, adjacent-pair list, both modes), not by eye.
+   The order declared in theme-v2.css FAILS — teal against pink is
+   ΔE 1.2 for a deuteranope. This order passes all five checks in
+   both themes: worst adjacent pair ΔE 13.2 deutan / 21.0 normal,
+   identical light and dark. Re-ordering the slots breaks that, and
+   nothing in the build will tell you.
+
+   Three placements are deliberate:
+     • BLUE IS SLOT 1, not red. Slot 1 is the single-series default,
+       so a red slot 1 would paint every one-series chart in the
+       brand accent and destroy accent scarcity. Blue carries no
+       product meaning.
+     • RED IS SLOT 8. Red is reserved for --accent and
+       --destructive. It only enters a chart at eight series, where
+       the reader has bigger problems. It stays in the palette so
+       the eight-slot contract holds rather than being deleted.
+     • GREEN (slot 2) AND RED (slot 8) ARE FAR APART, so a
+       two-series chart never accidentally reads as pass/fail.
+
+   THE SCATTER / ALL-PAIRS CAP. Forms where any two marks can touch
+   — scatter, bubble, choropleth, small multiples — take the harder
+   all-pairs test, which no ordering of these eight can pass. Those
+   forms use ONLY slots 1, 6 and 7 (blue / amber / teal: verified
+   all-pairs in both modes, worst ΔE 14.8, all five checks PASS) and
+   CAP AT THREE SERIES. A fourth folds into "Other" or facets into
+   small multiples. Never generate a ninth hue.
+
+   Resolution is a frozen literal lookup in the primitive, never a
+   constructed name (ADR-146 D8): `--series-${i}` that misses yields
+   an undefined property, which makes rgb() invalid, which the
+   browser discards in silence with every gate still green.
+   ============================================================ */
+:root {
+  --series-1: 2 137 234;    /* blue   */
+  --series-2: 9 160 93;     /* green  */
+  --series-3: 153 100 229;  /* violet */
+  --series-4: 113 149 3;    /* olive  */
+  --series-5: 212 73 150;   /* pink   */
+  --series-6: 186 116 4;    /* amber  */
+  --series-7: 14 154 148;   /* teal   */
+  --series-8: 226 74 62;    /* red    */
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovett/ui",
-  "version": "0.0.11",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "Design system primitives, tokens, layouts, and patterns for the Lovett portfolio.",
@@ -55,6 +55,13 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
+    "@tiptap/core": "3.31.3",
+    "@tiptap/extension-mention": "3.31.3",
+    "@tiptap/extension-placeholder": "3.31.3",
+    "@tiptap/markdown": "3.31.3",
+    "@tiptap/pm": "3.31.3",
+    "@tiptap/react": "3.31.3",
+    "@tiptap/starter-kit": "3.31.3",
     "clsx": "^2.1.1",
     "mammoth": "^1.12.0",
     "react-markdown": "^10.1.0",

package/src/__tests__/avatar.test.tsx

@@ -0,0 +1,272 @@
+/**
+ * Avatar / AvatarGroup — ADR-147 D14.
+ *
+ * The contract worth pinning is not "it renders a circle". It is the four
+ * things the consolidated forks got wrong or could not do, plus the two D5
+ * degradations that a comment thread will hit in production:
+ *
+ *   • one `initials()`, capped at two words, first + last
+ *   • one tint derivation, stable per identity, `red` never in the set
+ *   • the monogram stays in the DOM UNDER the photo, so a broken `src`
+ *     degrades to a letter rather than a coloured hole
+ *   • `max` and `total` are separate, so 3 of 40 renders from 3 children
+ *   • a NULL name does not crash and is not fabricated
+ *
+ * `css: false` in the vitest config, so nothing here asserts a painted value —
+ * these are class and DOM contracts. Colour is verified by the measured note
+ * in `styles.css` and an eyeball pass in both themes.
+ */
+import { describe, expect, it } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+import {
+  AVATAR_TINTS,
+  Avatar,
+  AvatarGroup,
+  asAvatarTint,
+  avatarTintForKey,
+  initials,
+} from '../avatar'
+
+describe('initials()', () => {
+  it('takes the first and last word, capped at two', () => {
+    expect(initials('Marcus Webb')).toBe('MW')
+    // The divergence being resolved: community and admin returned 'MJ' here.
+    expect(initials('Mary Jane Watson')).toBe('MW')
+  })
+
+  it('takes one letter from a single-word name', () => {
+    expect(initials('Cher')).toBe('C')
+  })
+
+  it('uppercases and tolerates ragged whitespace', () => {
+    expect(initials('  ada   lovelace  ')).toBe('AL')
+  })
+
+  it('does not slice a surrogate pair in half', () => {
+    // A name whose first character is outside the BMP. `name[0]` returns half a
+    // code point and renders as a replacement glyph.
+    expect(initials('\u{1D400}lpha Beta')).toBe('\u{1D400}B')
+  })
+
+  it('returns ? for a null, undefined, empty or blank name and never invents one', () => {
+    // D5: users.name / given_name / family_name are ALL nullable by policy.
+    expect(initials(null)).toBe('?')
+    expect(initials(undefined)).toBe('?')
+    expect(initials('')).toBe('?')
+    expect(initials('   ')).toBe('?')
+  })
+})
+
+describe('avatarTintForKey()', () => {
+  it('is stable for the same seed', () => {
+    expect(avatarTintForKey('usr_9f2')).toBe(avatarTintForKey('usr_9f2'))
+  })
+
+  it('never returns red — that is the accent, and an avatar may not spend it', () => {
+    expect(AVATAR_TINTS).not.toContain('red')
+    const seeds = Array.from({ length: 400 }, (_, i) => `usr_${i}`)
+    for (const seed of seeds) {
+      expect(AVATAR_TINTS).toContain(avatarTintForKey(seed))
+    }
+  })
+
+  it('hashes the whole string, not the first character', () => {
+    // The community/admin fork keyed on `name.charCodeAt(0) % 4`, so every
+    // name starting with the same letter collided by construction.
+    expect(avatarTintForKey('Alice Adams')).not.toBe(avatarTintForKey('Aaron Ash'))
+  })
+
+  it('is not degenerate — it reaches most of the palette over a small sample', () => {
+    const seen = new Set(
+      Array.from({ length: 200 }, (_, i) => avatarTintForKey(`usr_${i}`)),
+    )
+    expect(seen.size).toBeGreaterThanOrEqual(AVATAR_TINTS.length - 1)
+  })
+})
+
+describe('asAvatarTint()', () => {
+  it('passes a known key through', () => {
+    expect(asAvatarTint('violet')).toBe('violet')
+  })
+
+  it('rejects anything that is not a key, so an untrusted string cannot reach the DOM', () => {
+    // `users.avatar_color` is a nullable TEXT column, so its contents are a
+    // string from the database, not a domain value.
+    expect(asAvatarTint(null)).toBeUndefined()
+    expect(asAvatarTint(undefined)).toBeUndefined()
+    expect(asAvatarTint('')).toBeUndefined()
+    expect(asAvatarTint('rebeccapurple')).toBeUndefined()
+    expect(asAvatarTint('var(--accent)')).toBeUndefined()
+  })
+
+  it('rejects red — it is not in the set, so it cannot be stored into one', () => {
+    expect(asAvatarTint('red')).toBeUndefined()
+  })
+})
+
+describe('Avatar', () => {
+  it('names itself for a screen reader and shows the monogram', () => {
+    render(<Avatar name="Marcus Webb" />)
+    const el = screen.getByRole('img', { name: 'Marcus Webb' })
+    expect(el).toHaveTextContent('MW')
+  })
+
+  it('takes a tint prop over the hash, and carries it as a class not a style', () => {
+    // Identity colour is DATA (D6). A key, so the token boundary holds — an
+    // arbitrary colour string out of the database would not.
+    const { container } = render(<Avatar name="Marcus Webb" tint="violet" />)
+    expect(container.firstChild).toHaveClass('ds-avatar', 'ds-avatar--violet')
+  })
+
+  it('falls back to the hash when no tint is given, seeded by id in preference to name', () => {
+    const { container: byName } = render(<Avatar name="Marcus Webb" />)
+    const { container: bySeed } = render(<Avatar name="Marcus Webb" seed="usr_9f2" />)
+    expect(byName.firstChild).toHaveClass(`ds-avatar--${avatarTintForKey('Marcus Webb')}`)
+    expect(bySeed.firstChild).toHaveClass(`ds-avatar--${avatarTintForKey('usr_9f2')}`)
+  })
+
+  it('gives the monogram its OWN element, not a bare text node', () => {
+    // Measured in @lovett/ds: as a bare text node it is an anonymous grid item,
+    // `text-box-trim` reaches nothing, and the glyph sat 1.3px high in a 24px
+    // avatar. Deleting the span is a silent 1.3px regression, so it is pinned.
+    const { container } = render(<Avatar name="Marcus Webb" />)
+    const mono = container.querySelector('.ds-avatar__mono')
+    expect(mono).not.toBeNull()
+    expect(mono).toHaveTextContent('MW')
+  })
+
+  it('renders the photo OVER the monogram, keeping the monogram in the DOM', () => {
+    const { container } = render(<Avatar name="Marcus Webb" src="https://x.test/m.png" />)
+    expect(container.querySelector('.ds-avatar__img')).not.toBeNull()
+    expect(container.querySelector('.ds-avatar__mono')).toHaveTextContent('MW')
+  })
+
+  it('degrades a broken src to the letter rather than a coloured hole', () => {
+    const { container } = render(<Avatar name="Marcus Webb" src="https://x.test/404.png" />)
+    const img = container.querySelector('.ds-avatar__img')
+    expect(img).not.toBeNull()
+    if (img) fireEvent.error(img)
+    expect(container.querySelector('.ds-avatar__img')).toBeNull()
+    expect(screen.getByRole('img', { name: 'Marcus Webb' })).toHaveTextContent('MW')
+  })
+
+  it('re-tries a NEW src after an earlier one failed', () => {
+    // A latching boolean would suppress every later photo for the life of the
+    // component once any URL 404s. Keyed by the failed src instead.
+    const { container, rerender } = render(<Avatar name="M W" src="https://x.test/404.png" />)
+    const img = container.querySelector('.ds-avatar__img')
+    if (img) fireEvent.error(img)
+    expect(container.querySelector('.ds-avatar__img')).toBeNull()
+    rerender(<Avatar name="M W" src="https://x.test/ok.png" />)
+    expect(container.querySelector('.ds-avatar__img')).not.toBeNull()
+  })
+
+  it('accepts an initial override', () => {
+    render(<Avatar name="Edwin Lovett" initial="You" />)
+    expect(screen.getByRole('img', { name: 'Edwin Lovett' })).toHaveTextContent('You')
+  })
+
+  describe('D5 — degraded identities', () => {
+    it('does not crash on a null name, and does not fabricate one', () => {
+      render(<Avatar name={null} />)
+      const el = screen.getByRole('img', { name: 'Unknown person' })
+      expect(el).toHaveTextContent('?')
+    })
+
+    it('treats a blank name the same as a null one', () => {
+      render(<Avatar name="   " />)
+      expect(screen.getByRole('img', { name: 'Unknown person' })).toHaveTextContent('?')
+    })
+
+    it('gives a null-named person a stable tint rather than throwing', () => {
+      const { container } = render(<Avatar name={null} />)
+      expect(container.firstChild).toHaveClass(
+        `ds-avatar--${avatarTintForKey('Unknown person')}`,
+      )
+    })
+  })
+
+  describe('sizing', () => {
+    it('is sm by default and carries no size modifier for it', () => {
+      const { container } = render(<Avatar name="Marcus Webb" />)
+      expect(container.firstChild).not.toHaveClass('ds-avatar--md', 'ds-avatar--lg')
+    })
+
+    it('carries a modifier class for a named size', () => {
+      const { container } = render(<Avatar name="Marcus Webb" size="lg" />)
+      expect(container.firstChild).toHaveClass('ds-avatar--lg')
+    })
+
+    it('carries a pixel size as custom properties, never as a hue or size class', () => {
+      const { container } = render(<Avatar name="Marcus Webb" size={26} />)
+      const el = container.firstChild
+      expect(el).toHaveStyle({ '--avatar-size': '26px' })
+      // 0.36 coefficient — the community fork's, so its call sites keep their
+      // rendered type size through the consolidation.
+      expect(el).toHaveStyle({ '--avatar-font': '9px' })
+      expect(el).not.toHaveClass('ds-avatar--md')
+    })
+  })
+
+  describe('accessibility', () => {
+    it('takes the ring class only when asked', () => {
+      const { container: plain } = render(<Avatar name="A B" />)
+      const { container: ringed } = render(<Avatar name="A B" ring />)
+      expect(plain.firstChild).not.toHaveClass('ds-avatar--ring')
+      expect(ringed.firstChild).toHaveClass('ds-avatar--ring')
+    })
+
+    it('hides itself from the a11y tree when decorative', () => {
+      // Every table row and byline renders the name beside the avatar;
+      // announcing the same person twice is worse than not announcing them.
+      const { container } = render(<Avatar name="Marcus Webb" decorative />)
+      expect(container.firstChild).toHaveAttribute('aria-hidden', 'true')
+      expect(screen.queryByRole('img')).toBeNull()
+    })
+  })
+})
+
+describe('AvatarGroup', () => {
+  const face = (n: string) => <Avatar key={n} name={n} />
+
+  it('shows every face when there are no more than max', () => {
+    render(<AvatarGroup max={3}>{['A One', 'B Two'].map(face)}</AvatarGroup>)
+    expect(screen.getAllByRole('img')).toHaveLength(2)
+    expect(screen.queryByText(/^\+/)).toBeNull()
+  })
+
+  it('collapses the tail into a +N', () => {
+    render(<AvatarGroup max={2}>{['A One', 'B Two', 'C Three'].map(face)}</AvatarGroup>)
+    expect(screen.getByRole('img', { name: '1 more' })).toHaveTextContent('+1')
+  })
+
+  it('counts from total, so 3 faces render out of 40 without 40 children', () => {
+    // The capability no fork had. `total` is separate from the children on
+    // purpose: a thread with 40 participants must not mount 40 avatars to
+    // throw 37 away.
+    render(
+      <AvatarGroup max={3} total={40}>
+        {['A One', 'B Two', 'C Three'].map(face)}
+      </AvatarGroup>,
+    )
+    expect(screen.getByRole('img', { name: '37 more' })).toHaveTextContent('+37')
+  })
+
+  it('overlaps by default and lays out spaced when asked', () => {
+    const { container: over } = render(<AvatarGroup>{[face('A One')]}</AvatarGroup>)
+    const { container: flat } = render(
+      <AvatarGroup overlap={false}>{[face('A One')]}</AvatarGroup>,
+    )
+    expect(over.firstChild).toHaveClass('ds-avatar-group--overlap')
+    expect(flat.firstChild).toHaveClass('ds-avatar-group--spaced')
+  })
+
+  it('sizes the +N chip with the faces', () => {
+    const { container } = render(
+      <AvatarGroup max={1} total={9} size="md">
+        {[face('A One')]}
+      </AvatarGroup>,
+    )
+    expect(container.querySelector('.ds-avatar-group__more')).toHaveClass('ds-avatar--md')
+  })
+})