@mediaradar/design-components 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -17,6 +17,9 @@ import { VariantProps } from 'class-variance-authority';
  * not just a decorative hover effect. Both modes close on Escape and on any
  * outside click. The bubble is portaled to document.body and repositions
  * itself to stay clear of the right viewport edge.
+ * @a11y The trigger is a <button> reporting aria-expanded; the bubble is
+ * role="tooltip" and Escape dismisses it. It describes its anchor rather
+ * than naming it, so the anchor still needs its own accessible name.
  * @usage
  * ```tsx
  * <InfoTip text="Trims time periods to data that has finalized across the selected media formats." />
@@ -61,6 +64,10 @@ declare function InfoTip({ text, size, label, trigger }: InfoTipProps): react.JS
  * other close path discards the draft, so the trigger label never previews
  * an unapplied change. The pinned "selected" section persists across
  * searches and collapses when the search is cleared.
+ * @a11y Trigger is a <button> with aria-expanded and aria-haspopup; the menu is
+ * role="dialog", closed on Escape. Option rows are role="checkbox" with
+ * aria-checked, so each row is itself the control -- don't wrap them in
+ * another clickable element.
  * @usage
  * ```tsx
  * <AdvertiserQuickFilter options={advertisers} selected={selected} onChange={setSelected} />
@@ -159,6 +166,13 @@ declare function AdvertiserSearchPrompt({ label }: AdvertiserSearchPromptProps):
  * `stopPropagation` before firing `onChange` by default, so nesting this
  * inside a row that toggles on its own click can't fire the toggle twice;
  * pass `stopPropagation={false}` where the row should also see the click.
+ * @a11y The <button> itself carries role="checkbox" and aria-checked ("mixed"
+ * when indeterminate), so it IS the control -- never nest it inside
+ * another button or a row that is itself clickable. `ariaLabel` is
+ * required because the box renders no text. Where the whole row should be
+ * the control, use CheckBoxBox inside your own <button role="checkbox">
+ * instead: a <button> inside a <button> is invalid markup, and a <div
+ * onClick> wrapper is not keyboard-reachable at all.
  * @usage
  * ```tsx
  * <CheckBox checked={selected} ariaLabel="Select row" onChange={toggle} />
@@ -221,6 +235,10 @@ declare function CheckBox({ checked, indeterminate, onChange, ariaLabel, disable
  * the control has no correct option: nesting the interactive `CheckBox`
  * produces a button inside a button, and dropping to a `<div>` with a click
  * handler loses keyboard access entirely.
+ * @a11y Presentational only: aria-hidden, no focus stop, no click handling. The
+ * ancestor owns role="checkbox", aria-checked, the accessible name and the
+ * click. Use it exactly when that ancestor is itself the control; use
+ * CheckBox when the box is the control.
  * @usage
  * ```tsx
  * <button type="button" role="checkbox" aria-checked={on} onClick={toggle}>
@@ -257,6 +275,9 @@ declare function CheckBoxBox({ checked, indeterminate, disabled, className }: Ch
  * values, so a previous unsaved edit never lingers into the next open. Only
  * the Apply button commits -- Cancel, Escape, and outside-click all discard
  * the draft silently.
+ * @a11y Trigger is a <button> with aria-expanded and an aria-label from the
+ * caption; the panel is role="dialog" and Escape closes it. Focus is not
+ * moved into the panel, so it is reached by tabbing.
  * @usage
  * ```tsx
  * <DateRangeFilter caption="Date Range" defaultValue="Rolling 6 months" onChange={setRange} />
@@ -327,6 +348,11 @@ declare function DateRangeFilter({ caption, defaultValue, value: controlledValue
  * The text input carries an `aria-label` derived from `placeholder` — the
  * wrapping `<label>` has no visible text content (just an icon and the
  * input), so it grants the input no accessible name on its own.
+ * @a11y The <input> takes its accessible name from `ariaLabel`. The match-mode
+ * popover is a radio group (role="radio" + aria-checked) and its trigger
+ * reports aria-expanded. Escape closes the popover only, leaving focus in
+ * the field -- a consumer nesting this inside another dismissible layer
+ * must sequence the two dismissals itself.
  * @usage
  * ```tsx
  * <SearchBar value={query} onChange={setQuery} />
@@ -390,6 +416,9 @@ declare function SearchBar({ placeholder, value, onChange, variant, matchValue,
  * anchor rather than a framework router Link — this package has no router
  * peer dependency, and the two consuming apps disagree on one (react-router-dom
  * vs next/link); a plain anchor is the one thing that works unmodified in both.
+ * @a11y Rail items are buttons and take their accessible name from `ariaLabel`,
+ * since several render icon-only. Without it they announce as unnamed
+ * buttons.
  * @usage
  * ```tsx
  * <SectionRail title="Sports" subtitle="Your tracked leagues" viewAllLabel="View all" viewAllHref="/sports">
@@ -432,6 +461,10 @@ declare function SectionRail({ title, titleSerif, subtitle, viewAllLabel, viewAl
  * invalid HTML that breaks click targeting (confirmed against how
  * mr-clientapps-insights-studio's own equivalent, `ChipOption`, already
  * avoids exactly this by rendering its InfoTip as a sibling, not a child).
+ * @a11y Trigger is a <button> with aria-expanded and aria-haspopup; the menu is
+ * role="listbox" with role="option" rows carrying aria-selected. Escape
+ * closes it. Use the listbox semantics as given -- adding a second role to
+ * the wrapper breaks the option/listbox relationship.
  * @usage
  * ```tsx
  * <DataScopeFilter value={finalOnly} onChange={setFinalOnly} />
@@ -467,6 +500,11 @@ declare function DataScopeFilter({ value, onChange, align }: DataScopeFilterProp
  * `onChange` ever fires, so nothing would ever get selected. Selecting an
  * option commits immediately and closes -- there's no separate draft/Apply
  * step; Escape and outside-click just close without side effects.
+ * @a11y Trigger is a <button>; the popover is role="listbox" with role="option"
+ * rows carrying aria-selected. The trigger owns the accessible name via
+ * the caption. The popover is not a focus trap and does not move focus on
+ * open, so keyboard users tab into it; a consumer rendering it inside
+ * another dismissible layer has to sequence the two dismissals itself.
  * @usage
  * ```tsx
  * <SelectFilter caption="Rank" value={rankFilter} onChange={setRankFilter} options={['All', 'VP / Director', 'Manager', 'Coordinator']} />
@@ -598,6 +636,10 @@ declare const QUIET_ACTION_CLASS = "rounded-control text-[13px] font-medium text
  * recovery buttons (e.g. "Switch workspace") after the two named ones, for
  * empty states whose fix isn't about filters at all -- primary gets the
  * filled treatment, everything else the quiet one.
+ * @a11y The optional action is a real <button> with visible text as its
+ * accessible name; the illustration is aria-hidden. Nothing here announces
+ * automatically, so a consumer replacing results should manage its own
+ * live region if the change needs announcing.
  * @usage
  * ```tsx
  * <NoResultsEmptyState hasFilters={hasFilters} onClearFilters={clearFilters} onEditFilters={openFilterTray} />
@@ -689,6 +731,8 @@ interface SummaryGroup {
  * increase, including one added to an already-open or already
  * manually-collapsed nonempty group, silently undoing the user's own
  * collapse. Sub-groups render indented beneath their parent's own items.
+ * @a11y The card's toggle is a button reporting aria-expanded, with an aria-
+ * label since it renders icon-only. Decorative marks are aria-hidden.
  * @usage
  * ```tsx
  * <WorkspaceSelectedCard groups={[{ id: 'advertisers', label: 'Advertisers', items: selected, onRemove: removeOne, onRemoveAll: clearAll }]} />
@@ -731,6 +775,9 @@ declare function WorkspaceSelectedCard({ groups, testIdPrefix }: WorkspaceSelect
  * `aria-hidden="true"` throughout, since none of the boxes carry real
  * content for assistive tech to announce. The bar count and profile are a
  * fixed shape, not driven by `height`.
+ * @a11y role="presentation" with aria-hidden marks: a visual stand-in with no
+ * data, deliberately invisible to assistive tech. Don't add a caption
+ * expecting it to be announced.
  * @usage
  * ```tsx
  * <BarChartPlaceholder />
@@ -756,6 +803,9 @@ declare function BarChartPlaceholder({ height }: BarChartPlaceholderProps): reac
  * @behavior Purely presentational -- `role="presentation"` and
  * `aria-hidden="true"` throughout (inherited from `AxisFrame`). The series
  * count and shapes are fixed; `height` is the only variable.
+ * @a11y role="presentation" with aria-hidden marks: a visual stand-in with no
+ * data, deliberately invisible to assistive tech. Don't add a caption
+ * expecting it to be announced.
  * @usage
  * ```tsx
  * <LineChartPlaceholder />
@@ -780,6 +830,9 @@ declare function LineChartPlaceholder({ height }: LineChartPlaceholderProps): re
  * @behavior Purely presentational -- `role="presentation"` and
  * `aria-hidden="true"` throughout. `legendRows` controls the blank legend
  * only; the disc's seam count is a fixed shape.
+ * @a11y role="presentation" with aria-hidden marks: it is a visual stand-in with
+ * no data, deliberately invisible to assistive tech. Don't add a caption
+ * expecting it to be announced.
  * @usage
  * ```tsx
  * <PieChartPlaceholder />
@@ -809,6 +862,8 @@ declare function PieChartPlaceholder({ height, legendRows }: PieChartPlaceholder
  * `bg-subtle` fill the default-strength seam disappears and the stack reads
  * as one undivided block. Legend rows are reversed (bottom-up) when `axis`
  * is off, matching a bare stack's usual bottom-anchored reading order.
+ * @a11y role="presentation" with aria-hidden marks: a visual stand-in with no
+ * data, deliberately invisible to assistive tech.
  * @usage
  * ```tsx
  * <StackedColumnPlaceholder />
@@ -858,6 +913,10 @@ declare function StackedColumnPlaceholder({ height, width, legendRows, axis, }:
  * right-aligned to the anchor's right edge -- both meant for `anchorRef`
  * anchors near the viewport's right edge, where a centred box would run
  * off-screen or read awkwardly beside a narrow icon.
+ * @a11y Renders role="tooltip" and is wired to its anchor by aria-describedby,
+ * so the anchor must exist and keep a stable id. It describes rather than
+ * labels: it is announced in addition to the anchor's own name, not
+ * instead of it, so never put the only label for a control in here.
  * @usage
  * ```tsx
  * <Tooltip label="Full advertiser name" whenTruncated>
@@ -959,6 +1018,10 @@ declare function AdvertiserNoResults({ query, hint, }: AdvertiserNoResultsProps)
  * between "Select all" and "Deselect" based on `allSelected`.
  * @tokens rounded-control, text-text-link, hover:bg-subtle
  * @dependencies lucide-react
+ * @a11y A plain <button>, not a checkbox -- it performs a bulk action rather
+ * than holding a checked state, so it deliberately carries no
+ * role="checkbox" or aria-checked. Its icon is aria-hidden and the visible
+ * text is the accessible name.
  * @usage
  * ```tsx
  * {results.length > 5 && (
@@ -992,6 +1055,9 @@ declare function SelectAllVisible({ count, allSelected, onToggle, testIdPrefix }
  * need. Self-hides at `count === 0` so a caller can render it unconditionally.
  * @tokens rounded-control, text-text-tertiary, hover:text-text-primary
  * @dependencies lucide-react
+ * @a11y The disclosure header is a button reporting aria-expanded, and the
+ * chevron is aria-hidden. It is a disclosure, not a selection control --
+ * the rows inside own their own semantics.
  * @usage
  * ```tsx
  * <SelectedSection count={selected.length} open={open} onToggle={() => setOpen((o) => !o)}>
@@ -1147,6 +1213,10 @@ interface SelectionPickerProps<T extends PickerRow> {
  * with both an `onChange` and the row's own `onClick` -- `CheckBox` stops
  * click propagation before firing `onChange`, which is exactly what lets it
  * sit inside a row that toggles on its own click without double-firing.
+ * @a11y Search is an <input>; result rows and the account-list menu
+ * (role="menu") are buttons. Escape closes the menu. Loading, empty and
+ * error states announce through role="status", so a consumer should NOT
+ * wrap this in its own live region -- that would double-announce.
  * @usage
  * ```tsx
  * <SelectionPicker
@@ -1234,6 +1304,9 @@ interface PublisherBreakdownListProps {
  * the kind of forked-with-extra-indirection outcome this package's README
  * calls out as not actually shared. Per that guidance, this component stays
  * the flat-list case only; mr-clientapps' accordion stays where it is, un-migrated.
+ * @a11y Rows are buttons. One row manages tabIndex directly and a row tooltip
+ * uses role="tooltip", dismissed on Escape. The tooltip describes rather
+ * than names, so never put a row's only label in it.
  * @usage
  * ```tsx
  * <PublisherBreakdownList rows={publishers} defaultVisibleCount={10} />
@@ -1275,6 +1348,9 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
  * and relies on its per-variant hover/brightness treatment instead. `loading`
  * implies `disabled` (and sets `aria-busy`), since a control mid-submit
  * shouldn't accept another click.
+ * @a11y Renders a native <button>, so it keeps native keyboard behaviour.
+ * `loading` sets aria-busy, and the spinner is aria-hidden. Icon-only
+ * usage needs an aria-label from the caller -- nothing here supplies one.
  * @usage
  * ```tsx
  * <Button variant="primary" size="md">Save changes</Button>
@@ -1300,6 +1376,9 @@ interface FilterDropdownFooterProps {
  * visible. Shared by the Media/Advertiser/Date/Group By/Time Increment quick
  * filters on Sports Dashboard, Publisher Intel, and Opportunities.
  * @tokens border-border-default
+ * @a11y Clear and Apply are real Buttons with visible text as their accessible
+ * names, in that DOM order. It adds no roles or live regions of its own --
+ * the menu that contains it owns dismissal and focus.
  * @usage
  * ```tsx
  * <FilterDropdownFooter onApply={handleApply} onClear={handleClear} />
@@ -1343,12 +1422,16 @@ interface NameListModalProps {
  * checkboxes under it. Shared by the Account Lists table and the list detail
  * page so create/rename look identical; `fieldLabel`/`placeholder` relabel it
  * for dialogs that name something other than a list.
- * @tokens rounded-card, border-border-default, bg-surface, shadow-overlay, text-text-primary, text-text-secondary, rounded-control, bg-input, focus:border-brand-primaryAction
+ * @tokens bg-scrim, rounded-card, border-border-default, bg-surface, shadow-overlay, text-text-primary, text-text-secondary, rounded-control, bg-input, focus:border-brand-primaryAction
  * @behavior Escape closes the dialog via `onCancel`, same as clicking the
  * scrim backdrop. Submit is disabled until the name is non-empty (trimmed).
  * When `options` are given they render as CheckBox rows below the field, and
  * their state comes back as `onSubmit`'s second argument -- a handler that
  * only takes the name stays valid.
+ * @a11y role="dialog" with aria-modal, labelled by its title. The name field
+ * takes focus on open and Escape closes via onCancel. Focus is NOT trapped
+ * and NOT restored to the opener on close -- confirmed in the source -- so
+ * a consumer that needs either must supply it around this component.
  * @usage
  * ```tsx
  * <NameListModal title="Rename list" initialName={list.name} submitLabel="Save" onCancel={close} onSubmit={rename} />
@@ -1379,10 +1462,6 @@ interface ChipContentProps {
  * @description Shared foundation for filter-bar chip triggers — pairs
  * `chipTriggerClass` with `ChipContent` for the caption/value/icon layout, so
  * every dropdown chip across the app matches.
- * @props
- * caption: string -- small uppercase label above the value
- * value: ReactNode -- the current selection, shown below the caption
- * icon?: ReactNode -- optional leading icon rendered before the caption/value stack
  * @tokens rounded-control, bg-input, border-border-default, border-border-strong, text-text-secondary, text-text-tertiary, text-text-primary, hover:bg-subtle, focus-visible:outline-border-focus, hover:text-text-primary
  * @behavior `chipTriggerClass` takes a `ChipVariant`: `box` (default, the
  * boxed two-line chip on the default border) or `inline` (same fill, darker
@@ -1392,6 +1471,9 @@ interface ChipContentProps {
  * treatment every dropdown trigger depends on — open/close, Escape, and
  * outside-click dismissal all live in each consumer, not here. A new dropdown
  * built on `chipTriggerClass` has to implement its own dismissal handling.
+ * @a11y `chipTriggerClass` supplies only the shared focus-visible outline.
+ * Roles, aria-expanded and dismissal all belong to the consumer's own
+ * trigger -- this styles a control, it does not make one.
  * @usage
  * ```tsx
  * <button className={chipTriggerClass("box")}>
@@ -1429,6 +1511,9 @@ interface FilterChipBarProps<T extends ChipLike> {
  * @behavior A parked chip (key in `parkedKeys`) renders with no fill and a
  * dashed edge instead of the solid applied style, and its hover tooltip
  * reads "Not in this workspace" instead of the filter's group label.
+ * @a11y Each chip's remove control is a button with its own aria-label naming
+ * what it clears; the chip's icon is aria-hidden. An overflow tooltip uses
+ * role="tooltip", which describes rather than labels.
  * @usage
  * ```tsx
  * <FilterChipBar chips={activeChips} onRemove={removeChip} onClearAll={clearAll} />
@@ -1482,6 +1567,9 @@ interface SortButtonProps<K extends string> {
  * standard three-state cycle — sort, reverse, then unsorted. `disabled` keeps
  * the column's inherited header color rather than dimming it — the column
  * isn't unavailable, there's just no data under it.
+ * @a11y Renders a <button> and sets aria-sort on it. Intended for a table header
+ * cell -- put it inside the <th> rather than replacing it, so the sort
+ * state stays associated with the column for screen readers.
  * @usage
  * ```tsx
  * const [sort, setSort] = useState<SortState<'spend'>>(null)
@@ -1503,6 +1591,9 @@ interface PagerProps {
  * ellipsis gaps. Shared by My Exports and Account Matcher.
  * @tokens rounded-control, text-text-secondary, bg-brand-primaryAction, text-brand-onprimary, hover:bg-subtle, hover:text-text-primary, text-text-tertiary
  * @dependencies lucide-react
+ * @a11y Page controls are buttons with their own aria-labels, and the current
+ * page is marked with aria-current. Don't relabel them with visible text
+ * alone -- the labels are what a screen reader announces.
  * @usage
  * ```tsx
  * <Pager page={page} totalPages={totalPages} onPage={setPage} />
@@ -1571,6 +1662,10 @@ declare function Tag({ children, className }: TagProps): react.JSX.Element;
  * Changing the per-page count reports it and leaves the host to reset to page
  * 1. With one page of results the pager still renders, so the bar's height
  * and the range readout don't come and go as filters narrow.
+ * @a11y A <nav aria-label="Pagination"> wrapping <button> controls, each with
+ * its own aria-label (Previous/Next/Last). The chevron icons are aria-
+ * hidden, so the labels are the only accessible names -- don't override
+ * them with visible text alone.
  * @usage
  * ```tsx
  * <TablePagination
@@ -1655,6 +1750,10 @@ interface MultiSelectGroup {
  * selection floor by silently ignoring any toggle that would drop below it —
  * there's no error state, the click just does nothing. Group parents are
  * tri-state and toggle all of their children in one action.
+ * @a11y Trigger is a <button> with aria-expanded; the menu is role="dialog" and
+ * Escape closes it. Option rows carry their own checkbox semantics. Focus
+ * is not moved into the menu on open, so keyboard users tab into it in DOM
+ * order.
  * @usage
  * ```tsx
  * <MultiSelectFilter caption="Media" options={mediaOptions} selected={selected} onChange={setSelected} />
@@ -1755,6 +1854,10 @@ interface ToggleProps {
  * need (usually label left, switch pushed right).
  * @variant md - Settings panels and modals, where the switch is the row's subject.
  * @variant sm - Dense rows next to 13px body text, where the md track overpowers its own label.
+ * @a11y The <button> carries role="switch" and aria-checked, so it is the
+ * control -- don't nest it in another interactive element. `label`
+ * supplies the accessible name; without it the switch is announced
+ * unlabelled.
  * @usage
  * ```tsx
  * <Toggle checked={enabled} onChange={setEnabled} label="Email news alerts" />
@@ -1790,6 +1893,9 @@ interface FreshnessProps {
  * timestamps stops reading as a wall of identical text. Color carries the
  * urgency signal at a glance.
  * @tokens bg-status-success, bg-status-warning, bg-text-tertiary
+ * @a11y role="img" with an aria-label per level, so the dot has a text
+ * alternative rather than announcing as decoration. The label is the only
+ * thing a screen reader gets -- the colour carries no meaning on its own.
  * @usage
  * ```tsx
  * <Freshness level="fresh" />

package/dist/index.js

@@ -2683,13 +2683,13 @@ function NameListModal({
     return () => window.removeEventListener("keydown", onKey);
   }, [onCancel]);
   return createPortal5(
-    // The scrim is a literal: @mediaradar/design-tokens has no scrim token yet.
-    // Same light/dark values as insights-studio-prototype's local --color-scrim;
-    // the dark one keys off data-theme, the attribute design-tokens' dark.css uses.
+    // bg-scrim, not a literal: design-tokens gained a scrim token in 2.5.0.
+    // No in-data-[theme=dark] override needed any more -- the token redefines
+    // itself under that attribute in dark.css, so one class covers both themes.
     /* @__PURE__ */ jsx26(
       "div",
       {
-        className: "fixed inset-0 z-70 flex items-center justify-center bg-[rgba(20,17,13,0.55)] in-data-[theme=dark]:bg-[rgba(0,0,0,0.65)] px-4",
+        className: "fixed inset-0 z-70 flex items-center justify-center bg-scrim px-4",
         onMouseDown: (e) => e.target === e.currentTarget && onCancel(),
         children: /* @__PURE__ */ jsxs24(
           "div",