@lovett/ui 0.0.10 → 0.1.0

package/src/__tests__/anchor.test.tsx

@@ -0,0 +1,422 @@
+/**
+ * lib/anchor — the one positioning routine every floating surface uses.
+ *
+ * `computeAnchoredPosition` is pinned as pure math (no DOM), then the hook
+ * is exercised through a harness with mocked geometry: an element ref, a
+ * virtual rect, a flip at the viewport edge, and re-measure on resize.
+ * `useOutsideClick` closes the file.
+ */
+import { useRef, useState } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import {
+  computeAnchoredPosition,
+  useAnchoredPosition,
+  useOutsideClick,
+  type AnchorAlign,
+  type AnchorRect,
+  type AnchorSide,
+} from '../lib/anchor'
+import { mockGeometry, setViewport } from './helpers/geometry'
+
+const VIEWPORT = { width: 1000, height: 800 }
+// right 480, bottom 332 — room on every side.
+const ANCHOR = { left: 400, top: 300, width: 80, height: 32 }
+const FLOATING = { width: 200, height: 120 }
+
+describe('computeAnchoredPosition', () => {
+  it('bottom-start: below the anchor, left edges aligned, offset applied', () => {
+    expect(
+      computeAnchoredPosition(ANCHOR, FLOATING, VIEWPORT, { side: 'bottom', align: 'start' }),
+    ).toEqual({ left: 400, top: 338, placement: { side: 'bottom', align: 'start' } })
+  })
+
+  it.each<[AnchorAlign, number]>([
+    ['start', 400],
+    ['center', 340],
+    ['end', 280],
+  ])('aligns %s along the cross axis for a vertical side', (align, left) => {
+    const r = computeAnchoredPosition(ANCHOR, FLOATING, VIEWPORT, { side: 'bottom', align })
+    expect(r.left).toBe(left)
+    expect(r.top).toBe(338)
+  })
+
+  it('side top places the element above the anchor', () => {
+    const r = computeAnchoredPosition(ANCHOR, FLOATING, VIEWPORT, { side: 'top' })
+    expect(r.top).toBe(300 - 120 - 6)
+    expect(r.placement.side).toBe('top')
+  })
+
+  it.each<[AnchorAlign, number]>([
+    ['start', 300],
+    ['center', 256],
+    ['end', 212],
+  ])('side right: to the right of the anchor, %s-aligned vertically', (align, top) => {
+    const r = computeAnchoredPosition(ANCHOR, FLOATING, VIEWPORT, { side: 'right', align })
+    expect(r.left).toBe(480 + 6)
+    expect(r.top).toBe(top)
+  })
+
+  it('side left places the element to the left of the anchor', () => {
+    const r = computeAnchoredPosition(ANCHOR, FLOATING, VIEWPORT, { side: 'left' })
+    expect(r.left).toBe(400 - 200 - 6)
+    expect(r.placement.side).toBe('left')
+  })
+
+  it('alignOffset shifts along the cross axis and is mirrored for end', () => {
+    expect(
+      computeAnchoredPosition(ANCHOR, FLOATING, VIEWPORT, { align: 'start', alignOffset: 10 }).left,
+    ).toBe(410)
+    expect(
+      computeAnchoredPosition(ANCHOR, FLOATING, VIEWPORT, { align: 'end', alignOffset: 10 }).left,
+    ).toBe(270)
+  })
+
+  it('honours a custom offset', () => {
+    expect(computeAnchoredPosition(ANCHOR, FLOATING, VIEWPORT, { offset: 0 }).top).toBe(332)
+  })
+
+  describe('flip', () => {
+    // bottom 732 → 60px of room below, 692 above.
+    const nearBottom = { left: 400, top: 700, width: 80, height: 32 }
+
+    it('flips to top when bottom cannot fit', () => {
+      const r = computeAnchoredPosition(nearBottom, FLOATING, VIEWPORT, { side: 'bottom' })
+      expect(r.placement.side).toBe('top')
+      expect(r.top).toBe(700 - 120 - 6)
+    })
+
+    it('does not flip when flip is false — clamps instead', () => {
+      const r = computeAnchoredPosition(nearBottom, FLOATING, VIEWPORT, {
+        side: 'bottom',
+        flip: false,
+      })
+      expect(r.placement.side).toBe('bottom')
+      expect(r.top).toBe(800 - 120 - 8)
+    })
+
+    it('flips to whichever side has more room when neither fits', () => {
+      const short = { width: 1000, height: 200 }
+      // top 90 / bottom 122: 82px above, 70px below; needs 126.
+      const r = computeAnchoredPosition(
+        { left: 400, top: 90, width: 80, height: 32 },
+        FLOATING,
+        short,
+        { side: 'bottom' },
+      )
+      expect(r.placement.side).toBe('top')
+      expect(r.top).toBe(8)
+    })
+
+    it('stays on the preferred side when the opposite has even less room', () => {
+      const short = { width: 1000, height: 200 }
+      // top 60 / bottom 92: 52px above, 100px below.
+      const r = computeAnchoredPosition(
+        { left: 400, top: 60, width: 80, height: 32 },
+        FLOATING,
+        short,
+        { side: 'bottom' },
+      )
+      expect(r.placement.side).toBe('bottom')
+      expect(r.top).toBe(200 - 120 - 8)
+    })
+
+    it('flips horizontally for side right at the right viewport edge', () => {
+      const r = computeAnchoredPosition(
+        { left: 900, top: 300, width: 80, height: 32 },
+        FLOATING,
+        VIEWPORT,
+        { side: 'right' },
+      )
+      expect(r.placement.side).toBe('left')
+      expect(r.left).toBe(900 - 200 - 6)
+    })
+
+    it('keeps the requested align in the placement it reports', () => {
+      const r = computeAnchoredPosition(nearBottom, FLOATING, VIEWPORT, { align: 'end' })
+      expect(r.placement).toEqual({ side: 'top', align: 'end' })
+    })
+  })
+
+  describe('clamp', () => {
+    const nearRight = { left: 950, top: 300, width: 40, height: 32 }
+
+    it('clamps into the viewport, gutter in from the edge', () => {
+      const r = computeAnchoredPosition(nearRight, FLOATING, VIEWPORT)
+      expect(r.left).toBe(1000 - 200 - 8)
+    })
+
+    it('leaves the overflow alone when clampToViewport is false', () => {
+      const r = computeAnchoredPosition(nearRight, FLOATING, VIEWPORT, { clampToViewport: false })
+      expect(r.left).toBe(950)
+    })
+
+    it('uses a custom gutter', () => {
+      const r = computeAnchoredPosition(nearRight, FLOATING, VIEWPORT, { gutter: 20 })
+      expect(r.left).toBe(1000 - 200 - 20)
+    })
+
+    it('pins to the gutter when the element is wider than the viewport', () => {
+      const r = computeAnchoredPosition(ANCHOR, { width: 1200, height: 40 }, VIEWPORT)
+      expect(r.left).toBe(8)
+    })
+  })
+
+  it('positions against a virtual point (zero-size rect)', () => {
+    const point: AnchorRect = { left: 300, top: 200, width: 0, height: 0 }
+    expect(computeAnchoredPosition(point, FLOATING, VIEWPORT, { offset: 0 })).toEqual({
+      left: 300,
+      top: 200,
+      placement: { side: 'bottom', align: 'start' },
+    })
+    expect(computeAnchoredPosition(point, FLOATING, VIEWPORT, { offset: 0, align: 'end' }).left).toBe(
+      100,
+    )
+  })
+
+  it('rounds to whole pixels', () => {
+    const r = computeAnchoredPosition(
+      { left: 100.4, top: 100.6, width: 80, height: 32 },
+      FLOATING,
+      VIEWPORT,
+      { align: 'center' },
+    )
+    expect(r.left).toBe(40)
+    expect(Number.isInteger(r.top)).toBe(true)
+  })
+})
+
+interface HarnessProps {
+  anchorRect?: AnchorRect | null
+  side?: AnchorSide
+  align?: AnchorAlign
+  flip?: boolean
+  rect?: string
+  size?: string
+}
+
+function Harness({
+  anchorRect = null,
+  side = 'bottom',
+  align = 'start',
+  flip = true,
+  rect = '400,300,80,32',
+  size = '200,120',
+}: HarnessProps) {
+  const anchorRef = useRef<HTMLButtonElement>(null)
+  const { ref, style, placement, positioned } = useAnchoredPosition<HTMLDivElement>({
+    anchorRef,
+    anchorRect,
+    side,
+    align,
+    flip,
+  })
+  return (
+    <>
+      <button type="button" ref={anchorRef} data-rect={rect}>
+        anchor
+      </button>
+      <div
+        ref={ref}
+        data-testid="floating"
+        data-size={size}
+        data-side={placement?.side}
+        data-align={placement?.align}
+        data-positioned={String(positioned)}
+        style={style}
+      >
+        floating
+      </div>
+    </>
+  )
+}
+
+describe('useAnchoredPosition', () => {
+  let restore: () => void
+  beforeEach(() => {
+    restore = mockGeometry()
+    setViewport(1000, 800)
+  })
+  afterEach(() => restore())
+
+  it('positions the floating element under the anchor ref with position: fixed', () => {
+    render(<Harness />)
+    const floating = screen.getByTestId('floating')
+    expect(floating.style.position).toBe('fixed')
+    expect(floating.style.left).toBe('400px')
+    expect(floating.style.top).toBe('338px')
+    expect(floating.dataset.positioned).toBe('true')
+    expect(floating.dataset.side).toBe('bottom')
+    expect(floating.dataset.align).toBe('start')
+    expect(floating.style.visibility).toBe('')
+  })
+
+  it('reports the flipped placement at a viewport edge', () => {
+    render(<Harness rect="400,700,80,32" />)
+    const floating = screen.getByTestId('floating')
+    expect(floating.dataset.side).toBe('top')
+    expect(floating.style.top).toBe(`${700 - 120 - 6}px`)
+  })
+
+  it('positions against a virtual rect, ignoring the anchor ref', () => {
+    render(<Harness anchorRect={{ left: 300, top: 200, width: 0, height: 0 }} />)
+    const floating = screen.getByTestId('floating')
+    expect(floating.style.left).toBe('300px')
+    expect(floating.style.top).toBe('206px')
+  })
+
+  it('re-measures when the virtual rect changes', () => {
+    const { rerender } = render(
+      <Harness anchorRect={{ left: 300, top: 200, width: 0, height: 0 }} />,
+    )
+    rerender(<Harness anchorRect={{ left: 500, top: 100, width: 0, height: 0 }} />)
+    const floating = screen.getByTestId('floating')
+    expect(floating.style.left).toBe('500px')
+    expect(floating.style.top).toBe('106px')
+  })
+
+  it('re-measures on window resize and scroll', () => {
+    const { rerender } = render(<Harness />)
+    // The anchor moved (re-declared rect) but nothing told React — a
+    // scroll or resize is what should re-read it.
+    rerender(<Harness rect="120,50,80,32" />)
+    act(() => {
+      window.dispatchEvent(new Event('resize'))
+    })
+    expect(screen.getByTestId('floating').style.left).toBe('120px')
+
+    rerender(<Harness rect="220,50,80,32" />)
+    act(() => {
+      window.dispatchEvent(new Event('scroll'))
+    })
+    expect(screen.getByTestId('floating').style.left).toBe('220px')
+  })
+
+  it('honours side and align props', () => {
+    render(<Harness side="right" align="end" />)
+    const floating = screen.getByTestId('floating')
+    expect(floating.dataset.side).toBe('right')
+    expect(floating.style.left).toBe('486px')
+    expect(floating.style.top).toBe('212px')
+  })
+
+  it('parks the element off-screen and hidden while it is not measured', () => {
+    // No geometry at all: the anchor rect is 0×0 at (0, 0) — that still
+    // measures. To see the parked frame, disable measuring.
+    function Disabled() {
+      const anchorRef = useRef<HTMLButtonElement>(null)
+      const { ref, style, positioned } = useAnchoredPosition<HTMLDivElement>({
+        anchorRef,
+        enabled: false,
+      })
+      return (
+        <>
+          <button type="button" ref={anchorRef} />
+          <div ref={ref} data-testid="floating" data-positioned={String(positioned)} style={style} />
+        </>
+      )
+    }
+    render(<Disabled />)
+    const floating = screen.getByTestId('floating')
+    expect(floating.dataset.positioned).toBe('false')
+    expect(floating.style.visibility).toBe('hidden')
+    expect(floating.style.pointerEvents).toBe('none')
+    expect(Number.parseInt(floating.style.left, 10)).toBeLessThan(-1000)
+  })
+
+  it('detaches its listeners on unmount', () => {
+    const add = vi.spyOn(window, 'addEventListener')
+    const remove = vi.spyOn(window, 'removeEventListener')
+    const { unmount } = render(<Harness />)
+    const added = add.mock.calls.filter(([type]) => type === 'resize' || type === 'scroll').length
+    unmount()
+    const removed = remove.mock.calls.filter(
+      ([type]) => type === 'resize' || type === 'scroll',
+    ).length
+    expect(added).toBeGreaterThan(0)
+    expect(removed).toBe(added)
+    add.mockRestore()
+    remove.mockRestore()
+  })
+})
+
+describe('useOutsideClick', () => {
+  function OutsideHarness({
+    onOutside,
+    enabled = true,
+  }: {
+    onOutside: () => void
+    enabled?: boolean
+  }) {
+    const a = useRef<HTMLDivElement>(null)
+    const b = useRef<HTMLDivElement>(null)
+    useOutsideClick([a, b], onOutside, { enabled })
+    return (
+      <>
+        <div ref={a}>
+          <button type="button">inside a</button>
+        </div>
+        <div ref={b}>
+          <button type="button">inside b</button>
+        </div>
+        <button type="button">outside</button>
+      </>
+    )
+  }
+
+  it('fires for a pointerdown outside every target', async () => {
+    const onOutside = vi.fn()
+    render(<OutsideHarness onOutside={onOutside} />)
+    await userEvent.click(screen.getByRole('button', { name: 'outside' }))
+    expect(onOutside).toHaveBeenCalledTimes(1)
+  })
+
+  it('ignores pointerdowns inside any target', async () => {
+    const onOutside = vi.fn()
+    render(<OutsideHarness onOutside={onOutside} />)
+    await userEvent.click(screen.getByRole('button', { name: 'inside a' }))
+    await userEvent.click(screen.getByRole('button', { name: 'inside b' }))
+    expect(onOutside).not.toHaveBeenCalled()
+  })
+
+  it('does nothing while disabled', async () => {
+    const onOutside = vi.fn()
+    render(<OutsideHarness onOutside={onOutside} enabled={false} />)
+    await userEvent.click(screen.getByRole('button', { name: 'outside' }))
+    expect(onOutside).not.toHaveBeenCalled()
+  })
+
+  it('detaches on unmount', async () => {
+    const onOutside = vi.fn()
+    const { unmount } = render(<OutsideHarness onOutside={onOutside} />)
+    unmount()
+    await userEvent.click(document.body)
+    expect(onOutside).not.toHaveBeenCalled()
+  })
+
+  it('reads the latest handler without re-subscribing', async () => {
+    const first = vi.fn()
+    const second = vi.fn()
+    function Latest() {
+      const [swap, setSwap] = useState(false)
+      const a = useRef<HTMLDivElement>(null)
+      useOutsideClick([a], swap ? second : first)
+      return (
+        <>
+          <div ref={a}>
+            <button type="button" onClick={() => setSwap(true)}>
+              swap
+            </button>
+          </div>
+          <button type="button">outside</button>
+        </>
+      )
+    }
+    render(<Latest />)
+    await userEvent.click(screen.getByRole('button', { name: 'swap' }))
+    await userEvent.click(screen.getByRole('button', { name: 'outside' }))
+    expect(first).not.toHaveBeenCalled()
+    expect(second).toHaveBeenCalledTimes(1)
+  })
+})

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')
+  })
+})