@startsimpli/ui 0.4.93 → 0.4.95

package/src/components/states/__tests__/caveat-and-absence.test.tsx

@@ -0,0 +1,662 @@
+import * as React from 'react'
+import { render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+import { Caveat } from '../Caveat'
+import { Footnote, FootnoteScope } from '../Footnote'
+import { Absence, ABSENCE_DASH } from '../Absence'
+import { EmptyState } from '../EmptyState'
+import { StatTile } from '../../dashboard/StatTile'
+import { DashboardSection } from '../../dashboard/DashboardSection'
+import { Card, CardHeader, CardTitle } from '../../ui/card'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Physical-direction utilities break the moment the document flips to RTL.
+ * Every class the new primitives emit has to be logical.
+ */
+const PHYSICAL_CLASS =
+  /(^|\s)-?(pl|pr|ml|mr|left|right|border-l|border-r|rounded-l|rounded-r|text-left|text-right)(-|$|\s)/
+
+function physicalClassesIn(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll<HTMLElement>('*'))
+    .flatMap((el) => Array.from(el.classList))
+    .filter((cls) => PHYSICAL_CLASS.test(cls))
+}
+
+describe('physicalClassesIn (the RTL guard itself)', () => {
+  it('catches the physical utilities it exists to ban', () => {
+    const { container } = render(
+      <div className="pl-2">
+        <span className="ml-1 text-left" />
+        <span className="border-r" />
+      </div>,
+    )
+    expect(physicalClassesIn(container).sort()).toEqual([
+      'border-r',
+      'ml-1',
+      'pl-2',
+      'text-left',
+    ])
+  })
+
+  it('passes the logical utilities the primitives use', () => {
+    const { container } = render(
+      <div className="ps-2">
+        <span className="ms-1 me-1 text-start start-0" />
+      </div>,
+    )
+    expect(physicalClassesIn(container)).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Caveat — the disclosure affordance
+// ---------------------------------------------------------------------------
+
+describe('Caveat', () => {
+  it('collapses to a marker: the note is present but not visible', () => {
+    render(<Caveat subject="Streams reported">Estimates only.</Caveat>)
+
+    const trigger = screen.getByRole('button')
+    expect(trigger).toHaveAttribute('aria-expanded', 'false')
+    expect(screen.getByRole('note', { hidden: true })).not.toBeVisible()
+  })
+
+  it('gives the trigger an accessible name that names what it qualifies', () => {
+    render(<Caveat subject="Streams reported">Estimates only.</Caveat>)
+
+    expect(
+      screen.getByRole('button', { name: 'Why? Streams reported' }),
+    ).toBeInTheDocument()
+  })
+
+  it('renders a real button, not a hover-only affordance', () => {
+    render(<Caveat>Estimates only.</Caveat>)
+
+    const trigger = screen.getByRole('button')
+    expect(trigger.tagName).toBe('BUTTON')
+    expect(trigger).toHaveAttribute('type', 'button')
+  })
+
+  it('expands on click and exposes the note through aria-describedby', async () => {
+    const user = userEvent.setup()
+    render(<Caveat subject="Streams">Settlement lags about a month.</Caveat>)
+
+    const trigger = screen.getByRole('button')
+    await user.click(trigger)
+
+    expect(trigger).toHaveAttribute('aria-expanded', 'true')
+    const note = screen.getByRole('note')
+    expect(note).toBeVisible()
+    expect(note).toHaveTextContent('Settlement lags about a month.')
+    expect(trigger).toHaveAttribute('aria-describedby', note.id)
+  })
+
+  it('does not point a screen reader at the note while it is collapsed', () => {
+    render(<Caveat>Estimates only.</Caveat>)
+
+    expect(screen.getByRole('button')).not.toHaveAttribute('aria-describedby')
+  })
+
+  it('always resolves aria-controls, open or closed', async () => {
+    const user = userEvent.setup()
+    const { container } = render(<Caveat>Estimates only.</Caveat>)
+
+    const trigger = screen.getByRole('button')
+    const controlled = trigger.getAttribute('aria-controls')!
+    expect(container.querySelector(`#${controlled}`)).not.toBeNull()
+
+    await user.click(trigger)
+    expect(container.querySelector(`#${controlled}`)).not.toBeNull()
+  })
+
+  it('opens from the keyboard alone', async () => {
+    const user = userEvent.setup()
+    render(<Caveat>Estimates only.</Caveat>)
+
+    await user.tab()
+    expect(screen.getByRole('button')).toHaveFocus()
+
+    await user.keyboard('{Enter}')
+    expect(screen.getByRole('button')).toHaveAttribute('aria-expanded', 'true')
+
+    await user.keyboard(' ')
+    expect(screen.getByRole('button')).toHaveAttribute('aria-expanded', 'false')
+  })
+
+  it('closes on Escape', async () => {
+    const user = userEvent.setup()
+    render(<Caveat defaultOpen>Estimates only.</Caveat>)
+
+    const trigger = screen.getByRole('button')
+    expect(trigger).toHaveAttribute('aria-expanded', 'true')
+
+    await user.type(trigger, '{Escape}')
+    expect(trigger).toHaveAttribute('aria-expanded', 'false')
+  })
+
+  it('honours defaultOpen', () => {
+    render(<Caveat defaultOpen>Estimates only.</Caveat>)
+    expect(screen.getByRole('note')).toBeVisible()
+  })
+
+  it('can be driven as a controlled disclosure', async () => {
+    const user = userEvent.setup()
+    const onOpenChange = jest.fn()
+    render(
+      <Caveat open={false} onOpenChange={onOpenChange}>
+        Estimates only.
+      </Caveat>,
+    )
+
+    await user.click(screen.getByRole('button'))
+
+    expect(onOpenChange).toHaveBeenCalledWith(true)
+    // Controlled: the parent said closed, so it stayed closed.
+    expect(screen.getByRole('button')).toHaveAttribute('aria-expanded', 'false')
+  })
+
+  it('renders the label itself when the trigger is text', () => {
+    render(
+      <Caveat trigger="text" label="Why?" subject="Streams">
+        Estimates only.
+      </Caveat>,
+    )
+
+    expect(screen.getByRole('button')).toHaveTextContent('Why?')
+  })
+
+  it('closes an overlay when the pointer lands outside it', async () => {
+    const user = userEvent.setup()
+    render(
+      <div>
+        <Caveat defaultOpen>Estimates only.</Caveat>
+        <button type="button">Elsewhere</button>
+      </div>,
+    )
+
+    await user.click(screen.getByRole('button', { name: 'Elsewhere' }))
+    expect(
+      screen.getByRole('button', { name: 'Why?' }),
+    ).toHaveAttribute('aria-expanded', 'false')
+  })
+
+  it('leaves an inline caveat open when the pointer lands outside it', async () => {
+    const user = userEvent.setup()
+    render(
+      <div>
+        <Caveat placement="inline" defaultOpen>
+          Estimates only.
+        </Caveat>
+        <button type="button">Elsewhere</button>
+      </div>,
+    )
+
+    await user.click(screen.getByRole('button', { name: 'Elsewhere' }))
+    expect(
+      screen.getByRole('button', { name: 'Why?' }),
+    ).toHaveAttribute('aria-expanded', 'true')
+  })
+
+  it('anchors the overlay to the logical start by default', () => {
+    render(<Caveat defaultOpen>Estimates only.</Caveat>)
+    expect(screen.getByRole('note').className).toContain('start-0')
+  })
+
+  it('anchors to the opposite logical edge when it would open off-screen', () => {
+    const spy = jest
+      .spyOn(Element.prototype, 'getBoundingClientRect')
+      .mockReturnValue({
+        width: 256,
+        height: 60,
+        top: 0,
+        bottom: 60,
+        left: window.innerWidth - 20,
+        right: window.innerWidth + 236,
+        x: window.innerWidth - 20,
+        y: 0,
+        toJSON: () => ({}),
+      } as DOMRect)
+
+    try {
+      render(<Caveat defaultOpen>Estimates only.</Caveat>)
+      const note = screen.getByRole('note')
+      expect(note.className).toContain('end-0')
+      expect(note.className).not.toContain('start-0')
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('emits no physical-direction classes', () => {
+    const { container } = render(
+      <Caveat defaultOpen subject="Streams">
+        Estimates only.
+      </Caveat>,
+    )
+    expect(physicalClassesIn(container)).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// FootnoteScope — a caveat authored per item, said once per section
+// ---------------------------------------------------------------------------
+
+describe('FootnoteScope', () => {
+  const SETTLEMENT = 'Streaming settles about a month after play.'
+
+  it('prints a repeated note once, however many items claim it', () => {
+    render(
+      <FootnoteScope>
+        <p>
+          Spotify
+          <Footnote note={SETTLEMENT} />
+        </p>
+        <p>
+          Apple
+          <Footnote note={SETTLEMENT} />
+        </p>
+        <p>
+          Anghami
+          <Footnote note={SETTLEMENT} />
+        </p>
+      </FootnoteScope>,
+    )
+
+    expect(screen.getAllByText(SETTLEMENT, { exact: false })).toHaveLength(1)
+  })
+
+  it('leaves a marker on every item that claimed it', () => {
+    const { container } = render(
+      <FootnoteScope>
+        <p>
+          Spotify
+          <Footnote note={SETTLEMENT} />
+        </p>
+        <p>
+          Apple
+          <Footnote note={SETTLEMENT} />
+        </p>
+      </FootnoteScope>,
+    )
+
+    expect(container.querySelectorAll('[data-footnote="1"]')).toHaveLength(2)
+  })
+
+  it('numbers distinct notes in the order they were claimed', () => {
+    render(
+      <FootnoteScope>
+        <p>
+          Streams
+          <Footnote note="First note." />
+        </p>
+        <p>
+          Listeners
+          <Footnote note="Second note." />
+        </p>
+      </FootnoteScope>,
+    )
+
+    const list = screen.getByRole('list', { name: 'Notes' })
+    const items = within(list).getAllByRole('listitem')
+    expect(items).toHaveLength(2)
+    expect(items[0]).toHaveTextContent('First note.')
+    expect(items[1]).toHaveTextContent('Second note.')
+  })
+
+  it('points each marker at the one printed copy of its note', () => {
+    const { container } = render(
+      <FootnoteScope>
+        <p>
+          Streams
+          <Footnote note={SETTLEMENT} />
+        </p>
+      </FootnoteScope>,
+    )
+
+    const marker = container.querySelector('[data-footnote="1"]') as HTMLAnchorElement
+    const describedBy = marker.getAttribute('aria-describedby')!
+    const target = container.querySelector(`#${describedBy}`)
+
+    expect(marker.getAttribute('href')).toBe(`#${describedBy}`)
+    expect(target).toHaveTextContent(SETTLEMENT)
+  })
+
+  it('names the marker for a screen reader', () => {
+    render(
+      <FootnoteScope>
+        <p>
+          Streams
+          <Footnote note={SETTLEMENT} />
+        </p>
+      </FootnoteScope>,
+    )
+
+    expect(screen.getByRole('link', { name: 'Note 1' })).toBeInTheDocument()
+  })
+
+  it('drops the note when the last item claiming it goes away', () => {
+    const { rerender } = render(
+      <FootnoteScope>
+        <p>
+          Spotify
+          <Footnote note={SETTLEMENT} />
+        </p>
+      </FootnoteScope>,
+    )
+    expect(screen.getAllByText(SETTLEMENT, { exact: false })).toHaveLength(1)
+
+    rerender(
+      <FootnoteScope>
+        <p>Spotify</p>
+      </FootnoteScope>,
+    )
+    expect(screen.queryByText(SETTLEMENT, { exact: false })).not.toBeInTheDocument()
+  })
+
+  it('renders no list at all when nothing claimed a note', () => {
+    render(
+      <FootnoteScope>
+        <p>Spotify</p>
+      </FootnoteScope>,
+    )
+    expect(screen.queryByRole('list')).not.toBeInTheDocument()
+  })
+
+  it('keeps the information when a Footnote has no scope above it', async () => {
+    const user = userEvent.setup()
+    render(<Footnote note={SETTLEMENT} subject="Streams" />)
+
+    const trigger = screen.getByRole('button', { name: 'Note Streams' })
+    await user.click(trigger)
+    expect(screen.getByRole('note')).toHaveTextContent(SETTLEMENT)
+  })
+
+  it('emits no physical-direction classes', () => {
+    const { container } = render(
+      <FootnoteScope>
+        <p>
+          Spotify
+          <Footnote note={SETTLEMENT} />
+        </p>
+      </FootnoteScope>,
+    )
+    expect(physicalClassesIn(container)).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Absence — tiers of "we do not have this"
+// ---------------------------------------------------------------------------
+
+describe('Absence', () => {
+  it('renders a missing value as a dash, never a zero and never a blank', () => {
+    const { container } = render(
+      <Absence tier="value" title="Anghami has not reported plays" />,
+    )
+
+    expect(container.textContent).toContain(ABSENCE_DASH)
+    expect(container.textContent).not.toMatch(/\b0\b/)
+    expect(container.textContent?.trim()).not.toBe('')
+  })
+
+  it('names what is missing for a screen reader on the value tier', () => {
+    render(
+      <Absence
+        tier="value"
+        title="Anghami has not reported plays"
+        description="Nothing has been sent for this platform."
+      />,
+    )
+
+    expect(
+      screen.getByText(
+        'Anghami has not reported plays. Nothing has been sent for this platform.',
+      ),
+    ).toBeInTheDocument()
+  })
+
+  it('carries the reason behind a disclosure rather than in the body', async () => {
+    const user = userEvent.setup()
+    render(
+      <Absence
+        tier="value"
+        title="Monthly listeners"
+        why="Anghami has not reported this."
+      />,
+    )
+
+    expect(screen.queryByText('Anghami has not reported this.')).not.toBeVisible()
+    await user.click(screen.getByRole('button'))
+    expect(screen.getByText('Anghami has not reported this.')).toBeVisible()
+  })
+
+  it('renders the note tier as one line, not a card', () => {
+    render(
+      <Absence
+        tier="note"
+        title="One reading so far"
+        description="The next refresh gives us something to compare it against."
+      />,
+    )
+
+    const note = screen.getByRole('note')
+    expect(note).toHaveAttribute('data-absence', 'note')
+    expect(note).toHaveTextContent('One reading so far')
+    expect(note.className).not.toContain('shadow')
+  })
+
+  it('draws the note tier as a dashed inset when it stands in for content', () => {
+    render(
+      <Absence tier="note" inset title="No history yet" description="Nothing recorded." />,
+    )
+    expect(screen.getByRole('note').className).toContain('border-dashed')
+  })
+
+  it('renders the card tier with its own chrome and a why behind a disclosure', async () => {
+    const user = userEvent.setup()
+    const { container } = render(
+      <Absence
+        tier="card"
+        title="Your earnings are not connected yet"
+        description="There is no monthly figure to show you."
+        why="Streams and money are not the same number."
+      />,
+    )
+
+    expect(container.querySelector('[data-absence="card"]')).not.toBeNull()
+    expect(
+      screen.getByText('Your earnings are not connected yet'),
+    ).toBeInTheDocument()
+    expect(screen.queryByText('Streams and money are not the same number.')).not.toBeVisible()
+
+    await user.click(screen.getByRole('button'))
+    expect(screen.getByText('Streams and money are not the same number.')).toBeVisible()
+  })
+
+  it('renders the page tier as the full surface, with an action', async () => {
+    const user = userEvent.setup()
+    const onClick = jest.fn()
+    render(
+      <Absence
+        tier="page"
+        title="Nothing to show yet"
+        description="Your account is not linked to an artist profile."
+        action={{ label: 'Talk to MCR', onClick }}
+        icon={<span data-testid="icon" />}
+      />,
+    )
+
+    const surface = screen.getByRole('status')
+    expect(surface).toHaveAttribute('data-absence', 'page')
+    expect(screen.getByTestId('icon')).toBeInTheDocument()
+
+    await user.click(screen.getByRole('button', { name: 'Talk to MCR' }))
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('costs a different amount of the page at each tier', () => {
+    const value = render(<Absence tier="value" title="Missing" />)
+    const page = render(
+      <Absence tier="page" title="Missing" description="Nothing here yet." />,
+    )
+
+    // A missing tile is a span; a missing screen is a live region.
+    expect(value.container.querySelector('[data-absence="value"]')?.tagName).toBe('SPAN')
+    expect(page.container.querySelector('[data-absence="page"]')).toHaveAttribute(
+      'aria-live',
+      'polite',
+    )
+  })
+
+  it('says a screen-level sentence once across several absent cards', () => {
+    const NOT_CONNECTED = 'Not connected yet — none of the above is a report of zero.'
+
+    render(
+      <FootnoteScope>
+        <Absence tier="card" title="Renewals" description="Nothing filed." note={NOT_CONNECTED} />
+        <Absence tier="card" title="Register a work" description="Not wired up." note={NOT_CONNECTED} />
+        <Absence tier="card" title="Billing" description="Nothing connected." note={NOT_CONNECTED} />
+      </FootnoteScope>,
+    )
+
+    expect(screen.getAllByText(NOT_CONNECTED, { exact: false })).toHaveLength(1)
+  })
+
+  it('never renders a spinner in place of an answer', () => {
+    const { container } = render(
+      <Absence tier="card" title="Renewals" description="Nothing filed." />,
+    )
+    expect(container.querySelector('.animate-spin')).toBeNull()
+    expect(container.querySelector('.animate-pulse')).toBeNull()
+  })
+
+  it('emits no physical-direction classes at any tier', () => {
+    const tiers = ['value', 'note', 'card', 'page'] as const
+    tiers.forEach((tier) => {
+      const { container, unmount } = render(
+        <Absence tier={tier} title="Missing" description="Nothing here." why="Nobody reported it." />,
+      )
+      expect(physicalClassesIn(container)).toEqual([])
+      unmount()
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// EmptyState — extended, not replaced
+// ---------------------------------------------------------------------------
+
+describe('EmptyState', () => {
+  it('draws an optional icon above the heading', () => {
+    render(<EmptyState title="Nothing yet" icon={<span data-testid="icon" />} />)
+    expect(screen.getByTestId('icon')).toBeInTheDocument()
+  })
+
+  it('renders extra content under the action', () => {
+    render(
+      <EmptyState title="Nothing yet">
+        <span data-testid="extra" />
+      </EmptyState>,
+    )
+    expect(screen.getByTestId('extra')).toBeInTheDocument()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// The canonical slots: StatTile, CardHeader, DashboardSection
+// ---------------------------------------------------------------------------
+
+describe('caveat slots', () => {
+  it('StatTile holds a caveat beside the kicker, not in the body', async () => {
+    const user = userEvent.setup()
+    render(
+      <StatTile
+        label="Streams reported"
+        value="1.2M"
+        caveat="Some platforms report a lifetime count."
+      />,
+    )
+
+    const trigger = screen.getByRole('button', { name: 'Why? Streams reported' })
+    expect(
+      screen.queryByText('Some platforms report a lifetime count.'),
+    ).not.toBeVisible()
+
+    await user.click(trigger)
+    expect(screen.getByText('Some platforms report a lifetime count.')).toBeVisible()
+  })
+
+  it('StatTile renders exactly as before when no caveat is passed', () => {
+    render(<StatTile label="Streams" value="1.2M" />)
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+    expect(screen.getByText('1.2M')).toBeInTheDocument()
+  })
+
+  it('CardHeader holds a caveat without disturbing a card that has none', async () => {
+    const user = userEvent.setup()
+    const plain = render(
+      <Card>
+        <CardHeader>
+          <CardTitle>Earnings</CardTitle>
+        </CardHeader>
+      </Card>,
+    )
+    expect(plain.container.querySelectorAll('button')).toHaveLength(0)
+    plain.unmount()
+
+    render(
+      <Card>
+        <CardHeader caveat="Settlement lags about a month.">
+          <CardTitle>Earnings</CardTitle>
+        </CardHeader>
+      </Card>,
+    )
+    await user.click(screen.getByRole('button'))
+    expect(screen.getByText('Settlement lags about a month.')).toBeVisible()
+  })
+
+  it('DashboardSection prints a tile-authored note once per section', () => {
+    const SETTLEMENT = 'Streaming settles about a month after play.'
+
+    render(
+      <DashboardSection title="Earnings">
+        <StatTile label="Spotify" value="1.2M" note={SETTLEMENT} />
+        <StatTile label="Apple" value="0.8M" note={SETTLEMENT} />
+        <StatTile label="Anghami" value="0.1M" note={SETTLEMENT} />
+        <StatTile label="Deezer" value="0.4M" note={SETTLEMENT} />
+      </DashboardSection>,
+    )
+
+    expect(screen.getAllByText(SETTLEMENT, { exact: false })).toHaveLength(1)
+  })
+
+  it('DashboardSection can opt out of collecting footnotes', () => {
+    render(
+      <DashboardSection title="Earnings" footnotes={false}>
+        <StatTile label="Spotify" value="1.2M" note="Settles late." />
+      </DashboardSection>,
+    )
+
+    // With no scope the note falls back to a per-tile disclosure rather than
+    // disappearing.
+    expect(screen.queryByRole('list')).not.toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Note Spotify' })).toBeInTheDocument()
+  })
+
+  it('DashboardSection carries a caveat on its heading', () => {
+    render(
+      <DashboardSection title="Earnings" caveat="Estimates only.">
+        <div />
+      </DashboardSection>,
+    )
+
+    expect(
+      screen.getByRole('button', { name: 'Why? Earnings' }),
+    ).toBeInTheDocument()
+  })
+})

package/src/components/states/index.ts

@@ -1,4 +1,10 @@
 export { ErrorState } from './ErrorState'
 export type { ErrorStateProps } from './ErrorState'
-export { EmptyState } from './EmptyState'
+export { EmptyState, StateAction } from './EmptyState'
 export type { EmptyStateProps, EmptyStateAction } from './EmptyState'
+export { Caveat } from './Caveat'
+export type { CaveatProps, CaveatPlacement } from './Caveat'
+export { FootnoteScope, Footnote } from './Footnote'
+export type { FootnoteScopeProps, FootnoteProps } from './Footnote'
+export { Absence, ABSENCE_DASH } from './Absence'
+export type { AbsenceProps, AbsenceTier } from './Absence'