@lovett/ui 0.0.11 → 0.2.0

package/src/__tests__/stat-strip.test.tsx

@@ -0,0 +1,175 @@
+/**
+ * StatStrip — the divider trick and the reserved slots.
+ *
+ * jsdom has no layout, so nothing here can measure a wrap. What it CAN pin is
+ * the MECHANISM that makes the wrap correct, which is the part a future
+ * refactor is most likely to "simplify" back into the bug:
+ *
+ *   • Every cell carries BOTH a block-start and an inline-start border, and
+ *     the row cancels the outermost ones with a one-hairline negative offset
+ *     inside a clipping card. Replace that with `:not(:last-child)` borders
+ *     and a stray vertical rule appears at the start of every wrapped row —
+ *     which no gate reads the source can see, and which these assertions do.
+ *   • The footer slot is reserved for EVERY cell as soon as ANY cell owns one,
+ *     so a late-arriving delta cannot grow the strip (ADR-146 D9).
+ *   • A single cell needs no special case: its two borders are the outermost
+ *     ones, so they are clipped and it renders with no dividers at all.
+ */
+import { describe, expect, it } from 'vitest'
+import { render, screen } from '@testing-library/react'
+
+import { StatStrip, type StatStripCell } from '../stat-strip'
+
+// Named rather than indexed out of an array: `noUncheckedIndexedAccess`
+// would otherwise make every `CELLS[0]` an `| undefined` that needs an `as`,
+// and a cast in a test is a cast in the repo.
+const BUDGET: StatStripCell = {
+  key: 'budget',
+  label: 'Total budget',
+  value: '$1,204,000',
+}
+const FLIGHTED: StatStripCell = {
+  key: 'flighted',
+  label: 'Flighted',
+  value: '$1,180,500',
+}
+const VARIANCE: StatStripCell = {
+  key: 'variance',
+  label: 'Variance',
+  value: '-$23,500',
+}
+const CELLS: StatStripCell[] = [BUDGET, FLIGHTED, VARIANCE]
+
+function rowOf(container: HTMLElement): HTMLDListElement {
+  const row = container.querySelector('dl')
+  if (row === null) throw new Error('StatStrip rendered no <dl>')
+  return row
+}
+
+function cellsOf(container: HTMLElement): HTMLElement[] {
+  return Array.from(rowOf(container).children).filter(
+    (el): el is HTMLElement => el instanceof HTMLElement,
+  )
+}
+
+describe('StatStrip', () => {
+  it('renders one labelled cell per stat, as a description list', () => {
+    render(<StatStrip cells={CELLS} ariaLabel="Plan totals" />)
+    expect(screen.getByLabelText('Plan totals').tagName).toBe('DL')
+    // The label wraps in a span so a long localized string can wrap without
+    // pushing the info icon around; the semantic element is still the <dt>.
+    expect(screen.getByText('Total budget').closest('dt')).not.toBeNull()
+    expect(screen.getByText('$1,204,000').tagName).toBe('DD')
+  })
+
+  it('renders nothing at all for an empty strip', () => {
+    const { container } = render(<StatStrip cells={[]} />)
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('gives EVERY cell both dividers — never `:not(:last-child)`', () => {
+    const { container } = render(<StatStrip cells={CELLS} />)
+    const cells = cellsOf(container)
+    expect(cells).toHaveLength(3)
+    for (const cell of cells) {
+      expect(cell.style.borderBlockStart).toContain('rgb(var(--border))')
+      expect(cell.style.borderInlineStart).toContain('rgb(var(--border))')
+    }
+  })
+
+  it('cancels the outermost dividers with a clipped one-hairline offset', () => {
+    const { container } = render(<StatStrip cells={CELLS} />)
+    const row = rowOf(container)
+    expect(row.style.marginBlockStart).toBe('-1px')
+    expect(row.style.marginInlineStart).toBe('-1px')
+    // The clip is what turns those offsets into "no outer border". Without
+    // it the strip grows a doubled top and start edge.
+    expect(row.parentElement).toHaveClass('overflow-hidden')
+  })
+
+  it('needs no special case for a single cell', () => {
+    const { container } = render(<StatStrip cells={[BUDGET]} />)
+    const cells = cellsOf(container)
+    expect(cells).toHaveLength(1)
+    // Same borders as any other cell — both are the outermost ones, so both
+    // are clipped and the cell renders with no dividers.
+    expect(cells[0]?.style.borderInlineStart).toContain('rgb(var(--border))')
+  })
+
+  it('wraps by content, in the strip’s own width, not a device preset', () => {
+    const { container } = render(<StatStrip cells={CELLS} minCellWidth={240} />)
+    for (const cell of cellsOf(container)) {
+      // Identical basis + identical grow: cells in a row stay equal, and the
+      // row breaks where the content stops fitting.
+      expect(cell.style.flex).toBe('1 1 240px')
+      expect(cell).toHaveClass('min-w-0')
+    }
+  })
+
+  it('reserves the footer slot in every cell when any cell has a delta', () => {
+    const cells: StatStripCell[] = [
+      { ...BUDGET, delta: { value: 12.5 } },
+      FLIGHTED,
+    ]
+    const { container } = render(<StatStrip cells={cells} />)
+    for (const cell of cellsOf(container)) {
+      const slots = cell.querySelectorAll('dd')
+      expect(slots).toHaveLength(2)
+      expect(slots[1]?.style.minHeight).toBe('var(--space-6)')
+    }
+  })
+
+  it('renders no footer slot at all when no cell has one', () => {
+    const { container } = render(<StatStrip cells={CELLS} />)
+    for (const cell of cellsOf(container)) {
+      expect(cell.querySelectorAll('dd')).toHaveLength(1)
+    }
+  })
+
+  it('reserves a value slot so a ticking number cannot resize anything', () => {
+    render(<StatStrip cells={CELLS} valueChars={11} />)
+    expect(screen.getByText('$1,204,000')).toHaveStyle({ minWidth: '11ch' })
+  })
+
+  it('reads the info hint ONCE, and still shows it on hover', () => {
+    const { container } = render(
+      <StatStrip cells={[{ ...BUDGET, info: 'Sum of all line items' }]} />,
+    )
+    // Exactly one node carries the text. `role="img" aria-label` + `title`
+    // would name the icon AND describe it with the same sentence, so an
+    // accname-correct reader announces it twice.
+    expect(screen.getAllByText('Sum of all line items')).toHaveLength(1)
+    expect(
+      container.querySelector('[title="Sum of all line items"]'),
+    ).not.toBeNull()
+  })
+
+  it('forces the footer slot on before any delta has arrived', () => {
+    // The derivation cannot reserve for data that does not exist yet: with
+    // every `delta` still undefined it reserves nothing, and the slot pops in
+    // — growing the strip — the moment the fetch lands. `reserveFooter` is
+    // how a caller says "they are coming" (ADR-146 D9).
+    const { container } = render(<StatStrip cells={CELLS} reserveFooter />)
+    for (const cell of cellsOf(container)) {
+      const slots = cell.querySelectorAll('dd')
+      expect(slots).toHaveLength(2)
+      expect(slots[1]?.style.minHeight).toBe('var(--space-6)')
+    }
+  })
+
+  it('hides the reserved slot from AT in the cells that are only spacing', () => {
+    const cells: StatStripCell[] = [
+      { ...BUDGET, delta: { value: 12.5 } },
+      FLIGHTED,
+    ]
+    const { container } = render(<StatStrip cells={cells} />)
+    const [withDelta, withoutDelta] = cellsOf(container)
+    expect(
+      withDelta?.querySelectorAll('dd')[1]?.getAttribute('aria-hidden'),
+    ).toBeNull()
+    // An empty <dd> is announced as an empty description of the stat above it.
+    expect(
+      withoutDelta?.querySelectorAll('dd')[1]?.getAttribute('aria-hidden'),
+    ).toBe('true')
+  })
+})

package/src/__tests__/status.test.tsx

@@ -0,0 +1,293 @@
+/**
+ * The status vocabulary + the hidden-columns rail
+ * (`docs/design-briefs/tasks-board-header-primitives.md` §2 and §3).
+ *
+ * What is pinned here is the pair of things the source app got wrong and that
+ * no typecheck, lint or build can see:
+ *
+ *   1. **The ring measures.** Its arc is derived from the percent it was
+ *      given, by the documented formula, clamped rather than wrapped. The
+ *      constants below are computed by hand, not by re-running the component's
+ *      own maths — a test that recomputes the formula it is testing proves
+ *      nothing.
+ *   2. **The rail can only exist with both maps.** A lane with 0 visible and
+ *      5 total leaves the strip and reads `0 / 5`; the same lane with no
+ *      `totalItems` at all cannot be distinguished from an ordinary empty one,
+ *      so it must not claim to be hiding anything.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { Board } from '../board'
+import { ProgressLedger, ledgerProgress } from '../progress-ledger'
+import { BOARD_STATUS_KEYS, STATUS_GLYPHS, STATUS_LABELS, StatusGlyph, StatusRing } from '../status'
+
+/** The progress arc is the LAST circle — the first is the track. */
+function arc(container: HTMLElement): SVGCircleElement {
+  const circles = container.querySelectorAll('circle')
+  const last = circles[circles.length - 1]
+  if (!last) throw new Error('no arc rendered')
+  return last as unknown as SVGCircleElement
+}
+
+function track(container: HTMLElement): SVGCircleElement {
+  const first = container.querySelector('circle')
+  if (!first) throw new Error('no track rendered')
+  return first as unknown as SVGCircleElement
+}
+
+const num = (el: Element, attr: string) => Number(el.getAttribute(attr))
+
+describe('StatusRing — the arc actually measures', () => {
+  // size 40, stroke 4 -> r = 18, circumference = 2π·18 = 113.0973…
+  const CIRC = 113.09733552923255
+
+  it('draws the full circumference as the dash array', () => {
+    const { container } = render(<StatusRing percent={0} size={40} strokeWidth={4} />)
+    expect(num(arc(container), 'stroke-dasharray')).toBeCloseTo(CIRC, 4)
+  })
+
+  it('offsets by circumference · (1 − percent/100)', () => {
+    const { container } = render(<StatusRing percent={25} size={40} strokeWidth={4} />)
+    // 113.0973… × 0.75 = 84.8230…
+    expect(num(arc(container), 'stroke-dashoffset')).toBeCloseTo(84.82300164692441, 4)
+  })
+
+  it('closes the arc at 100 and draws nothing at 0', () => {
+    const full = render(<StatusRing percent={100} size={40} strokeWidth={4} />)
+    expect(num(arc(full.container), 'stroke-dashoffset')).toBeCloseTo(0, 6)
+
+    const none = render(<StatusRing percent={0} size={40} strokeWidth={4} />)
+    expect(num(arc(none.container), 'stroke-dashoffset')).toBeCloseTo(CIRC, 4)
+  })
+
+  it('clamps out-of-range input rather than wrapping it', () => {
+    // 140% must not read as 40%, and −20% must not read as 80%.
+    const over = render(<StatusRing percent={140} size={40} strokeWidth={4} />)
+    expect(num(arc(over.container), 'stroke-dashoffset')).toBeCloseTo(0, 6)
+
+    const under = render(<StatusRing percent={-20} size={40} strokeWidth={4} />)
+    expect(num(arc(under.container), 'stroke-dashoffset')).toBeCloseTo(CIRC, 4)
+  })
+
+  it('starts at twelve o’clock with a round cap', () => {
+    const { container } = render(<StatusRing percent={50} size={40} strokeWidth={4} />)
+    expect(arc(container).getAttribute('transform')).toBe('rotate(-90 20 20)')
+    expect(arc(container).getAttribute('stroke-linecap')).toBe('round')
+  })
+
+  it('runs the track on --border and the arc on the hue ladder', () => {
+    const { container } = render(<StatusRing percent={50} size={40} strokeWidth={4} />)
+    expect(track(container).getAttribute('stroke')).toBe('rgb(var(--border))')
+    expect(arc(container).getAttribute('stroke')).toBe('var(--h, rgb(var(--folder-slate)))')
+  })
+
+  it('names itself with the percent, and arms the ladder when given a hue', () => {
+    const { container } = render(<StatusRing percent={64} hue="blue" />)
+    expect(screen.getByRole('img', { name: '64% complete' })).toBeInTheDocument()
+    expect(container.querySelector('.hue.hue-blue')).not.toBeNull()
+  })
+
+  it('is silent when a text percentage sits beside it', () => {
+    // Announced twice is the defect, not the feature.
+    render(<StatusRing percent={64} decorative />)
+    expect(screen.queryByRole('img')).not.toBeInTheDocument()
+  })
+})
+
+describe('StatusGlyph — discrete state, never colour alone', () => {
+  it('covers every state with a lucide glyph and an operator label', () => {
+    expect(BOARD_STATUS_KEYS).toHaveLength(6)
+    for (const key of BOARD_STATUS_KEYS) {
+      expect(STATUS_GLYPHS[key]).toBeDefined()
+      expect(STATUS_LABELS[key].length).toBeGreaterThan(0)
+      // It really renders an <svg>, and nothing here is a hand-written one:
+      // every glyph is a lucide component (CLAUDE.md §6).
+      const { container, unmount } = render(<StatusGlyph status={key} />)
+      expect(container.querySelector('svg.lucide')).not.toBeNull()
+      expect(screen.getByRole('img', { name: STATUS_LABELS[key] })).toBeInTheDocument()
+      unmount()
+    }
+  })
+
+  it('carries its meaning in its accessible name', () => {
+    render(<StatusGlyph status="done" />)
+    expect(screen.getByRole('img', { name: 'Done' })).toBeInTheDocument()
+  })
+
+  it('goes silent when an adjacent visible label already says it', () => {
+    render(
+      <span>
+        <StatusGlyph status="blocked" decorative />
+        Blocked
+      </span>,
+    )
+    expect(screen.queryByRole('img')).not.toBeInTheDocument()
+  })
+})
+
+describe('ledgerProgress — one calculation, every consumer', () => {
+  const segments = [
+    { id: 'g1', label: 'Design', cells: [{ id: 'a', done: true }, { id: 'b', done: true }] },
+    {
+      id: 'g2',
+      label: 'Build',
+      cells: [{ id: 'c', done: true }, { id: 'd', done: false }, { id: 'e', done: false }],
+    },
+  ]
+
+  it('counts and rounds', () => {
+    expect(ledgerProgress(segments)).toEqual({ done: 3, total: 5, percent: 60 })
+  })
+
+  it('does not divide by zero', () => {
+    expect(ledgerProgress([])).toEqual({ done: 0, total: 0, percent: 0 })
+  })
+
+  it('draws the ring at the same number the ledger prints', () => {
+    const { container } = render(<ProgressLedger segments={segments} showRing />)
+    expect(screen.getByText('60%')).toBeInTheDocument()
+    // size 13, stroke 2 -> r = 5.5, circumference = 34.5575…, 60% -> 13.8230…
+    expect(num(arc(container), 'stroke-dashoffset')).toBeCloseTo(13.823007675795088, 4)
+    // The number is text two words away, so the ring must not repeat it.
+    expect(screen.queryByRole('img')).not.toBeInTheDocument()
+  })
+})
+
+describe('Board — hidden columns need BOTH maps', () => {
+  const columns = [
+    { id: 'planned', label: 'Planned', hue: 'slate' as const },
+    { id: 'building', label: 'Building', hue: 'blue' as const },
+  ]
+
+  const renderBoard = (props: Partial<Parameters<typeof Board>[0]> = {}) =>
+    render(
+      <Board
+        columns={columns}
+        items={{ planned: [], building: ['b1'] }}
+        draggable={false}
+        renderCard={({ itemId }) => <span>{itemId}</span>}
+        {...props}
+      />,
+    )
+
+  it('stacks a filtered-out lane into the rail as `0 / n`', () => {
+    renderBoard({
+      totalItems: { planned: ['p1', 'p2', 'p3', 'p4', 'p5'], building: ['b1'] },
+    })
+
+    const rail = screen.getByRole('complementary', { name: 'Hidden columns' })
+    const row = within(rail).getByText('Planned').closest('li')
+    expect(row).not.toBeNull()
+    expect(within(row!).getByText('0 / 5')).toBeInTheDocument()
+    // Read out in words, not as "zero slash five".
+    expect(within(row!).getByText('0 of 5 shown')).toBeInTheDocument()
+
+    // It has LEFT the strip — it is not a column with a zero in it.
+    expect(screen.queryByRole('region', { name: 'Planned' })).not.toBeInTheDocument()
+  })
+
+  it('cannot claim anything is hidden without totalItems', () => {
+    renderBoard()
+    expect(screen.queryByRole('complementary', { name: 'Hidden columns' })).not.toBeInTheDocument()
+    expect(screen.queryByText(/hidden by filters/)).not.toBeInTheDocument()
+  })
+
+  // Two renders, two tests, because both share one document — asserting an
+  // absence after an earlier render has already put the lane there passes or
+  // fails for the wrong reason.
+  it('keeps a genuinely empty lane by default', () => {
+    // The default is to SHOW. An empty lane is part of the board's shape and is
+    // a drop target, so a consumer that never passes the prop must not lose a
+    // lane the moment it empties — that is the silent-vanish footgun. Hiding is
+    // the FILTERED case, which the hidden-columns rail owns instead.
+    renderBoard()
+    expect(screen.getByRole('region', { name: 'Planned' })).toBeInTheDocument()
+  })
+
+  it('omits an empty lane when the host asks it to', () => {
+    renderBoard({ showEmptyColumns: false })
+    expect(screen.queryByRole('region', { name: 'Planned' })).not.toBeInTheDocument()
+  })
+
+  it('renders the footer ONLY when a filter is actually hiding something', () => {
+    // The footer takes its height out of the board's, so an always-mounted one
+    // would shorten every lane for nothing (action-bar brief §7: "when absent
+    // the board area reclaims its height"). `totalItems` equal to `items` is
+    // the case a `filtersActive` flag would get wrong — a filter IS on, and it
+    // is hiding nothing.
+    const { container, unmount } = renderBoard({
+      totalItems: { planned: [], building: ['b1'] },
+    })
+    expect(screen.queryByText(/hidden by filters/)).not.toBeInTheDocument()
+    expect(container.querySelector('.ds-board-hidden-summary')).toBeNull()
+    // The shell stays out of the box tree entirely, so the lanes are laid out
+    // exactly as they are on a board that has no filtering at all.
+    expect(container.querySelector('.ds-board-shell[data-footer]')).toBeNull()
+    unmount()
+
+    const withHidden = renderBoard({ totalItems: { planned: [], building: ['b1', 'b2'] } })
+    expect(screen.getByText('1 item hidden by filters')).toBeInTheDocument()
+    expect(
+      withHidden.container.querySelector('.ds-board-shell[data-footer="true"]'),
+    ).not.toBeNull()
+  })
+
+  it('says how much is hidden in total, in the board’s own noun', () => {
+    renderBoard({
+      totalItems: { planned: ['p1', 'p2'], building: ['b1', 'b2', 'b3'] },
+      itemNoun: { one: 'project', many: 'projects' },
+    })
+    // 2 hidden in Planned + 2 in Building.
+    expect(screen.getByRole('status')).toHaveTextContent('4 projects hidden by filters')
+  })
+
+  it('uses the singular for one', () => {
+    renderBoard({ totalItems: { planned: ['p1'], building: ['b1'] } })
+    expect(screen.getByRole('status')).toHaveTextContent('1 item hidden by filters')
+  })
+
+  it('offers a way out, as a real button', () => {
+    const onClear = vi.fn()
+    renderBoard({ totalItems: { planned: ['p1'], building: ['b1'] }, onClearFilters: onClear })
+    fireEvent.click(screen.getByRole('button', { name: 'Clear filters' }))
+    expect(onClear).toHaveBeenCalledOnce()
+  })
+
+  it('shows the count without a dead button when there is nowhere to clear to', () => {
+    renderBoard({ totalItems: { planned: ['p1'], building: ['b1'] } })
+    expect(screen.queryByRole('button', { name: 'Clear filters' })).not.toBeInTheDocument()
+  })
+
+  it('reads a reduced lane as `visible / total`, not as a bare count', () => {
+    renderBoard({ totalItems: { planned: ['p1'], building: ['b1', 'b2', 'b3'] } })
+    const building = screen.getByRole('region', { name: 'Building' })
+    expect(within(building).getByText('1 / 3')).toBeInTheDocument()
+    expect(within(building).getByText('1 of 3 shown')).toBeInTheDocument()
+  })
+
+  it('collapses the rail without losing it', () => {
+    renderBoard({ totalItems: { planned: ['p1', 'p2'], building: ['b1'] } })
+    const toggle = screen.getByRole('button', { name: /Hidden columns/ })
+    expect(toggle).toHaveAttribute('aria-expanded', 'true')
+    fireEvent.click(toggle)
+    expect(toggle).toHaveAttribute('aria-expanded', 'false')
+    expect(screen.getByRole('complementary', { name: 'Hidden columns' })).toBeInTheDocument()
+  })
+
+  it('marks a lane with a ring when it has a number, a glyph when it does not', () => {
+    render(
+      <Board
+        columns={[
+          { id: 'planned', label: 'Planned', hue: 'slate', progress: { done: 3, total: 4, percent: 75 } },
+          { id: 'building', label: 'Building', hue: 'blue', status: 'in-progress' },
+        ]}
+        items={{ planned: ['p1'], building: ['b1'] }}
+        draggable={false}
+        renderCard={({ itemId }) => <span>{itemId}</span>}
+      />,
+    )
+    expect(screen.getByRole('img', { name: 'Planned is 75% complete' })).toBeInTheDocument()
+    expect(screen.getByRole('img', { name: 'In progress' })).toBeInTheDocument()
+  })
+})