@mediaradar/design-components 0.1.0 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import { ReactNode, RefObject } from 'react';
 
 /**
  * @pattern InfoTip
@@ -35,4 +36,1146 @@ interface InfoTipProps {
 }
 declare function InfoTip({ text, size, label, trigger }: InfoTipProps): react.JSX.Element;
 
-export { InfoTip, type InfoTipProps };
+/**
+ * @pattern AdvertiserQuickFilter
+ * @description Search-first quick filter. Mirrors the standard filter-chip
+ * shape (two-line caption + value + chevron) but never preloads the option
+ * list -- users must search first, since the advertiser pool is effectively
+ * endless. Selections are pinned in a "Selected (n)" section at the top so
+ * they're never lost when the user runs another search. Named for its
+ * original (and still primary) use, but the copy props make it reusable for
+ * any dimension that's also search-first in its own filter tray, so the
+ * dimension reads the same in the quick bar as it does there.
+ * @tokens rounded-control, rounded-card, border-border-default, border-border-strong,
+ * border-border-interactive, border-border-focus, bg-surface, bg-input,
+ * shadow-overlay, text-text-primary, text-text-secondary, text-text-tertiary,
+ * text-text-link, bg-brand-primaryAction, text-brand-onprimary,
+ * hover:bg-subtle, hover:text-text-primary, placeholder:text-text-tertiary
+ * @dependencies lucide-react
+ * @behavior The search input auto-focuses the moment the tray opens.
+ * Selections buffer in a local draft while open. Without `showFooter`,
+ * closing by any means (outside click, Escape, re-click) commits the draft
+ * to `onChange`. With `showFooter`, only the Apply button commits -- every
+ * 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.
+ * @usage
+ * ```tsx
+ * <AdvertiserQuickFilter options={advertisers} selected={selected} onChange={setSelected} />
+ * <AdvertiserQuickFilter options={advertisers} selected={selected} onChange={setSelected} showFooter clearValue={defaults} />
+ * ```
+ */
+interface AdvertiserQuickFilterProps {
+    /** Small uppercase label above the value. */
+    caption?: string;
+    options: {
+        id: string;
+        label: string;
+    }[];
+    selected: string[];
+    onChange: (next: string[]) => void;
+    align?: "left" | "right";
+    /** Optional leading icon rendered before the caption/value stack. */
+    icon?: React.ReactNode;
+    /**
+     * Deferred mode: checkbox edits stage in a draft; only the fixed
+     * Apply/Clear All footer commits or discards them (no live commit on
+     * close). Defaults to false -- live commit-on-close -- so an existing
+     * caller's behavior never changes just by picking up a new version of
+     * this component.
+     */
+    showFooter?: boolean;
+    /** What "Clear all" resets the draft to in footer mode (the page's
+     *  default selection). */
+    clearValue?: string[];
+    /** Selected ids the active workspace can't resolve. They stay in the
+     *  selection -- still committed back, still removable -- but they narrow
+     *  nothing, so the trigger label leaves them out of the count. */
+    parked?: string[];
+    /** Search box placeholder. Override alongside the other copy props when
+     *  the filter isn't advertisers, so the empty and no-results states name
+     *  the right dimension. */
+    searchPlaceholder?: string;
+    /** Completes "Start typing … to filter." in the pre-search prompt. */
+    promptLabel?: string;
+    /** The actionable next step under a no-results message. */
+    noResultsHint?: string;
+    /** The clear link in footerless mode (unused when `showFooter` is set). */
+    clearLabel?: string;
+    /**
+     * Optional prefix for `data-testid` attributes on the trigger, popover,
+     * search input, selected-section toggle, select-all-visible row, each
+     * option row (`${testIdPrefix}-option-<slugified-id>`), and the
+     * Apply/Clear All footer. Omit entirely for no test-id wiring at all --
+     * added specifically so an existing Playwright suite keyed off these ids
+     * (mr-clientapps' `AdvertisersPicker`) doesn't lose its locators when
+     * swapped over to this shared component.
+     */
+    testIdPrefix?: string;
+}
+declare function AdvertiserQuickFilter({ caption, options, selected, onChange, align, icon, showFooter, clearValue, parked, searchPlaceholder, promptLabel, noResultsHint, clearLabel, testIdPrefix, }: AdvertiserQuickFilterProps): react.JSX.Element;
+
+/**
+ * @pattern AdvertiserSearchPrompt
+ * @description Pre-search empty state for a search-first picker — shown the
+ * moment the tray opens, before anything has been typed. Used for option
+ * pools too large to preload (the advertiser list is effectively endless),
+ * where the caller must search before any options can be listed at all.
+ * Named for its original (and still primary) use, but the `label` prop makes
+ * it reusable for any other search-first dimension (a league picker, say).
+ * @tokens bg-subtle, text-text-tertiary
+ * @dependencies lucide-react
+ * @usage
+ * ```tsx
+ * <AdvertiserSearchPrompt />
+ * <AdvertiserSearchPrompt label="a league name" />
+ * ```
+ */
+interface AdvertiserSearchPromptProps {
+    /** Completes "Start typing … to filter." */
+    label?: string;
+}
+declare function AdvertiserSearchPrompt({ label }: AdvertiserSearchPromptProps): react.JSX.Element;
+
+/**
+ * @pattern CheckBox
+ * @description Tri-state checkbox rendered as a `<button>` (not a native
+ * `<input type="checkbox">`), so it can carry an indeterminate "some but not
+ * all" state without the native element's limited styling hooks. Designed to
+ * be dropped into a row that already has its own click-to-toggle handler
+ * (a common list/table pattern) without double-firing.
+ * @tokens bg-brand-primaryAction, border-border-interactive, bg-input,
+ * hover:border-brand-primaryAction, focus-visible:outline-border-focus
+ * @dependencies lucide-react
+ * @behavior `aria-checked` is `"mixed"` when indeterminate, otherwise the
+ * plain boolean. Indeterminate renders a dash (Minus) instead of a
+ * checkmark; checked renders a checkmark; neither renders nothing. The
+ * unchecked state previews the brand action color on hover, matching the
+ * color the box fills with once checked -- the hover state is a preview of
+ * the click's effect, not an unrelated highlight. `onClick` calls
+ * `stopPropagation` before firing `onChange`, so nesting this inside a row
+ * that toggles on its own click can't fire the toggle twice.
+ * @usage
+ * ```tsx
+ * <CheckBox checked={selected} ariaLabel="Select row" onChange={toggle} />
+ * <CheckBox checked={allSelected} indeterminate={someSelected} ariaLabel="Select all" onChange={toggleAll} />
+ * <CheckBox checked={false} disabled ariaLabel="Select row" title="Max 5 rows -- remove one first" onChange={toggle} />
+ * ```
+ */
+interface CheckBoxProps {
+    checked: boolean;
+    /**
+     * Some-but-not-all state for a "select all" checkbox -- shows a dash
+     * instead of a check, and reports `aria-checked="mixed"` instead of the
+     * plain boolean.
+     */
+    indeterminate?: boolean;
+    onChange: () => void;
+    /** Accessible label -- required since the control carries no visible text of its own. */
+    ariaLabel: string;
+    disabled?: boolean;
+    /** Forwarded as `data-testid`, for Playwright/test selectors. */
+    testId?: string;
+    /**
+     * Native tooltip -- e.g. explaining why a disabled box is disabled. Forwarded
+     * directly to the underlying `<button>`, same as a plain HTML `title` would
+     * be on any other disabled control.
+     */
+    title?: string;
+}
+declare function CheckBox({ checked, indeterminate, onChange, ariaLabel, disabled, testId, title }: CheckBoxProps): react.JSX.Element;
+
+/**
+ * @pattern DateRangeFilter
+ * @description Date-range control -- the two-line chip (caption + value) with
+ * a chevron that opens a two-pane picker: preset shortcuts on the left, a
+ * dual-month calendar with range highlighting on the right, Start/End fields,
+ * and Cancel/Apply. Shared by Creative Intel and the Account Review.
+ * @tokens rounded-control, rounded-card, border-border-default, border-border-strong,
+ * bg-surface, bg-input, bg-subtle, bg-ai-tint, bg-brand-primaryAction,
+ * shadow-overlay, text-text-primary, text-text-secondary, text-text-tertiary,
+ * hover:bg-subtle, hover:text-text-primary, focus-visible:outline-border-focus
+ * @dependencies lucide-react
+ * @behavior Escape and outside-click both close the popup. Opening always
+ * resets the draft (shortcut/start/end/visible month) to the last committed
+ * 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.
+ * @usage
+ * ```tsx
+ * <DateRangeFilter caption="Date Range" defaultValue="Rolling 6 months" onChange={setRange} />
+ * <DateRangeFilter presetSet="creativeIntel" defaultValue="Last 7 days" onChange={setRange} />
+ * <DateRangeFilter presetSet="creativeIntel" value={preset} range={[start, end]} onChange={setPreset} onRangeChange={(s, e) => setRange({ start: s, end: e })} />
+ * ```
+ */
+interface DateRangeFilterProps {
+    /** Static label shown above the value when `showDates` is false. */
+    caption?: string;
+    /** Initial preset (matched case-insensitively against the active preset set) or, if unmatched, treated as a custom label. Ignored once `value`/`range` are given -- see those. */
+    defaultValue?: string;
+    /**
+     * Controlled mode: the parent owns the committed preset/range instead of
+     * this component tracking it internally. Give both `value` and `range`
+     * together to enable it -- omit both (the default) for the original
+     * uncontrolled behavior, where `defaultValue` seeds the initial state and
+     * `onChange`/`onRangeChange` are fire-and-forget notifications. In
+     * controlled mode the chip's displayed value/dates always reflect these
+     * props directly, so the parent must call `onChange`/`onRangeChange` and
+     * feed the result back for the chip to update after Apply -- the same
+     * contract as a controlled `<input value onChange>`.
+     */
+    value?: string;
+    /** Controlled mode's resolved range -- see `value`. */
+    range?: [Date, Date];
+    /** Which edge of the trigger the popup aligns to. */
+    align?: "left" | "right";
+    /** Fired on Apply with the chip's new display value. */
+    onChange?: (value: string) => void;
+    /** Fired on Apply (and once on mount, uncontrolled only) with the resolved start/end dates -- e.g. to drive dependent table columns. */
+    onRangeChange?: (start: Date, end: Date) => void;
+    /** Show the resolved start-end dates in the chip instead of the preset name. */
+    showDates?: boolean;
+    /** Use an abbreviated date format (e.g. "Dec 1, 2025 - Jun 24, 2026") for the dates line. */
+    shortDates?: boolean;
+    /** Optional leading icon rendered before the caption/value stack. */
+    icon?: React.ReactNode;
+    /** 'creativeIntel' swaps in the day-level shortcut list (Today/Yesterday/Last N days/All available history) used by that dashboard. */
+    presetSet?: "default" | "creativeIntel";
+    /** Prefix for data-testid attributes on the trigger, popover, each preset option, and Cancel/Apply. Omit for no test-id wiring. */
+    testIdPrefix?: string;
+}
+declare function DateRangeFilter({ caption, defaultValue, value: controlledValue, range: controlledRange, align, onChange, onRangeChange, showDates, shortDates, icon, presetSet, testIdPrefix, }: DateRangeFilterProps): react.JSX.Element;
+
+/**
+ * @pattern SearchBar
+ * @description Filter-bar keyword search. 'default' is a plain keyword
+ * input; 'filterable' adds an attached match-type dropdown sharing one
+ * bordered control, mirroring the legacy Creative Intel search + match-type
+ * modal (Any Word/Exact Match/Contextual/Ad Code), including the Or/And
+ * sub-choice nested under Any Word.
+ * @tokens rounded-control, border-border-strong, bg-input, text-text-primary,
+ * text-text-tertiary, hover:bg-subtle, bg-brand-primaryAction, bg-subtle,
+ * bg-surface, border-brand-primaryAction, border-border-default,
+ * border-border-interactive, focus-visible:outline-border-focus,
+ * hover:text-text-primary, placeholder:text-text-tertiary, rounded-card,
+ * rounded-full, shadow-overlay, text-brand-primaryAction, text-text-secondary
+ * @dependencies lucide-react
+ * @behavior The match-type dropdown ('filterable' variant) closes on Escape
+ * and outside click. Each mode row is a real `radio` role, with a nested
+ * Or/And sub-choice under Any Word and its own click-to-toggle info tooltip.
+ * 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.
+ * @usage
+ * ```tsx
+ * <SearchBar value={query} onChange={setQuery} />
+ * <SearchBar variant="filterable" value={query} onChange={setQuery} matchValue={matchValue} onMatchChange={setMatchValue} />
+ * ```
+ */
+type SearchBarVariant = "default" | "filterable";
+type SearchMatchMode = "anyWord" | "exactMatch" | "contextual" | "adCode";
+interface SearchMatchValue {
+    mode: SearchMatchMode;
+    /** Only meaningful when mode === 'anyWord'. */
+    wordJoin: "Or" | "And";
+}
+declare const DEFAULT_SEARCH_MATCH: SearchMatchValue;
+interface SearchBarProps {
+    /** Input placeholder text. Also used as the input's `aria-label`. */
+    placeholder?: string;
+    value?: string;
+    onChange?: (v: string) => void;
+    /** 'default' is a plain keyword input; 'filterable' adds the match-type dropdown. */
+    variant?: SearchBarVariant;
+    /** The 'filterable' variant's dropdown state. */
+    matchValue?: SearchMatchValue;
+    onMatchChange?: (v: SearchMatchValue) => void;
+    className?: string;
+    /**
+     * Optional prefix for `data-testid` attributes on the input, the
+     * match-type trigger/popover, each mode row, and the Or/And radio pair
+     * (e.g. `${testIdPrefix}-search`, `${testIdPrefix}-mode-trigger`,
+     * `${testIdPrefix}-mode-anyWord`, `${testIdPrefix}-word-join-or`). Omit
+     * entirely for no test-id wiring at all -- added specifically so an
+     * existing Playwright suite keyed off these ids (mr-clientapps'
+     * `KeywordSearchBar`) doesn't lose its locators when swapped over to
+     * this shared component.
+     */
+    testIdPrefix?: string;
+}
+declare function SearchBar({ placeholder, value, onChange, variant, matchValue, onMatchChange, className, testIdPrefix, }: SearchBarProps): react.JSX.Element;
+
+/**
+ * @pattern SectionRail
+ * @description Generic titled section wrapper for a row of cards — a
+ * horizontal scroll rail on mobile/tablet (snap, bleeds to edges), a
+ * left-aligned 4-column grid on desktop. Card width is handled here, not on
+ * the card itself, so cards stay layout-agnostic; it works with any
+ * `children`. Real call sites vary: a fixed 4-item row that fills the
+ * desktop grid exactly, or a variable-length list with no "view all" link
+ * at all — both need to keep working without the row assuming a count.
+ * @tokens text-text-primary, text-text-secondary, text-text-link,
+ * rounded-control, rounded-sm, border-border, focus-visible:outline-solid,
+ * focus-visible:outline-border-focus, hover:bg-subtle, hover:text-text-primary,
+ * tracking-tight, font-serif
+ * @dependencies lucide-react
+ * @behavior Card width lives on the row, not the card: a fixed 268px per
+ * card in rail mode, capped at 320px per column in the lg+ grid, so cards
+ * stay layout-agnostic. The "view all" link only renders when both
+ * `viewAllLabel` and `viewAllHref` are given — either alone hides it, rather
+ * than falling back to a dead `href="#"`. Prev/next arrows are hidden below
+ * `sm` (swipe is the native affordance there) and at `lg`+ (the grid shows
+ * every card, nothing left to scroll to). `viewAllHref` renders as a plain
+ * 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.
+ * @usage
+ * ```tsx
+ * <SectionRail title="Sports" subtitle="Your tracked leagues" viewAllLabel="View all" viewAllHref="/sports">
+ *   {items.map((i) => <Card key={i.id}>{i.name}</Card>)}
+ * </SectionRail>
+ * ```
+ */
+interface SectionRailProps {
+    /** Section heading. */
+    title: string;
+    /** Use the serif display treatment instead of the default sans heading. */
+    titleSerif?: boolean;
+    /** Supporting line under the title. */
+    subtitle: string;
+    /** Label for the "view all" link. Has no effect unless `viewAllHref` is also given. */
+    viewAllLabel?: string;
+    /** Route the "view all" link points to. Has no effect unless `viewAllLabel` is also given. */
+    viewAllHref?: string;
+    /** The row's cards. Any content works — width is handled by the row, not the card. */
+    children: React.ReactNode;
+}
+declare function SectionRail({ title, titleSerif, subtitle, viewAllLabel, viewAllHref, children, }: SectionRailProps): react.JSX.Element;
+
+/**
+ * @pattern DataScopeFilter
+ * @description "Data" scope chip -- toggles the filter bar between All data
+ * and Final-only data (data that's finalized across the selected media
+ * formats, for stable report-ready numbers). One boolean, one control,
+ * shared across every dashboard that has this data-finality concept
+ * (Publisher Intel, Opportunities, Sports).
+ * @tokens rounded-control, border-border-strong, bg-input, hover:bg-subtle,
+ * hover:text-text-primary, focus-visible:outline-border-focus, rounded-card,
+ * border-border-default, bg-surface, shadow-overlay, text-text-primary,
+ * text-text-secondary, text-text-tertiary, text-brand-primaryAction
+ * @dependencies lucide-react
+ * @behavior Escape and outside-click both close the popover. The "Final
+ * only" option's info tooltip is a real InfoTip in hover mode, rendered as a
+ * sibling of the option button rather than nested inside it -- InfoTip
+ * renders its own `<button>`, and a button nested inside another button is
+ * 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).
+ * @usage
+ * ```tsx
+ * <DataScopeFilter value={finalOnly} onChange={setFinalOnly} />
+ * ```
+ */
+interface DataScopeFilterProps {
+    value: boolean;
+    onChange: (v: boolean) => void;
+    /** Which edge of the trigger the popover aligns to. Both known consumers
+     *  anchor this at the right edge of a filter bar, hence the default. */
+    align?: "left" | "right";
+}
+declare function DataScopeFilter({ value, onChange, align }: DataScopeFilterProps): react.JSX.Element;
+
+/**
+ * @pattern SelectFilter
+ * @description Single-select filter chip -- the caption-over-value trigger
+ * shape shared with AdvertiserQuickFilter/DateRangeFilter, opening a
+ * lightweight listbox of plain string options. Portal-rendered to
+ * `document.body` so the popover is never clipped by a scrollable ancestor
+ * (e.g. inside a modal) -- unlike this package's other chip popovers, none
+ * of which are known to sit inside a clipping container today.
+ * @tokens rounded-control, rounded-card, border-border-default,
+ * border-border-strong, bg-input, bg-surface, shadow-overlay,
+ * text-text-primary, text-text-secondary,
+ * text-text-tertiary, hover:bg-subtle, hover:text-text-primary,
+ * text-brand-primaryAction, focus-visible:outline-border-focus
+ * @dependencies lucide-react
+ * @behavior The popover is portal-rendered to document.body, so its own DOM
+ * node isn't inside the trigger. The outside-click check tests both the
+ * trigger and the popover explicitly for that reason -- treating the
+ * popover as "outside" would close it on every option click before
+ * `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.
+ * @usage
+ * ```tsx
+ * <SelectFilter caption="Rank" value={rankFilter} onChange={setRankFilter} options={['All', 'VP / Director', 'Manager', 'Coordinator']} />
+ * <SelectFilter caption="Group by" value={groupBy} onChange={setGroupBy} options={['Parent', 'Advertiser', 'Brand']} fullWidth testIdPrefix="dropdown-group-by" />
+ * ```
+ */
+interface SelectFilterProps {
+    caption: string;
+    value: string;
+    options: string[];
+    onChange: (v: string) => void;
+    /** Which edge of the trigger the popover aligns to. */
+    align?: "left" | "right";
+    /** Stretch the trigger (and the popover, when true) to fill its container. */
+    fullWidth?: boolean;
+    /** Extra classes merged onto the trigger button -- e.g. a background
+     *  override for a filter bar that isn't sitting on a filter-tray canvas. */
+    className?: string;
+    /**
+     * Optional prefix for `data-testid` attributes on the trigger
+     * (`${testIdPrefix}-trigger`), the popover (`${testIdPrefix}-popover`),
+     * and each option (`${testIdPrefix}-option-<slugified-label>`). Omit
+     * entirely for no test-id wiring at all -- added specifically so an
+     * existing Playwright suite keyed off hardcoded ids (mr-clientapps'
+     * `GroupBySelect`, e.g. `dropdown-group-by-option-parent`) can be re-keyed
+     * to this shared component's ids rather than losing its locators outright.
+     */
+    testIdPrefix?: string;
+}
+declare function SelectFilter({ caption, value, options, onChange, align, fullWidth, className, testIdPrefix, }: SelectFilterProps): react.JSX.Element;
+
+/**
+ * @pattern Card
+ * @description Layout primitive for grouping content in a bordered, elevated
+ * surface. Width is controlled by the parent container, not the Card itself,
+ * so it works unchanged as a fixed-width rail item or a grid cell. Applies an
+ * interactive hover treatment (deeper shadow) unless `staticCard` is set. An
+ * optional `title` (+ `subtitle`/`action`) renders a standard header row and
+ * switches the card into a padded content layout, replacing the header/body
+ * shell mr-clientapps-insights-studio's own `CardShell` used to hand-roll.
+ * @tokens rounded-card, border-border-default, bg-surface, shadow-raised,
+ * hover:shadow-overlay, p-card-padding, text-text-primary, text-text-tertiary
+ * @behavior Without `title`, children render directly as the card's only
+ * content -- no padding is applied, so callers that need a full-bleed image
+ * or gradient flush against the card edge (the common case in
+ * insights-studio-prototype's rail/grid cards) stay in control of their own
+ * inner layout, exactly as before this component grew a `title` prop. With
+ * `title`, the header and children are wrapped together in the card's
+ * standard padding, matching `CardShell`'s layout so it can be swapped in
+ * directly. `staticCard` drops the hover-shadow transition for non-clickable
+ * content (a KPI tile, a read-only summary) -- there's nothing to respond to.
+ * @variant interactive - Default. Clickable/hoverable content -- deeper
+ * shadow on hover signals it responds to the cursor.
+ * @variant static - Set `staticCard`. Non-clickable content -- no hover
+ * treatment.
+ * @usage
+ * ```tsx
+ * <Card>
+ *   <h3>Title</h3>
+ *   <p>Body content</p>
+ * </Card>
+ * <Card staticCard>Non-interactive content</Card>
+ * <Card title="Spend trend" subtitle="Last 90 days" action={<Link to="/spend">View all</Link>}>
+ *   <SpendChart />
+ * </Card>
+ * ```
+ */
+interface CardProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    /** Disable interactive hover treatment (when card isn't clickable). */
+    staticCard?: boolean;
+    /**
+     * Optional header title. Omit it (the default) to keep Card a bare,
+     * unpadded surface -- set it to get a title/subtitle/action header row
+     * plus the card's standard content padding, matching `CardShell`.
+     */
+    title?: string;
+    /** Shown under `title` in a muted tertiary color. Ignored without `title`. */
+    subtitle?: string;
+    /** Trailing header content, e.g. a "View all" link. Ignored without `title`. */
+    action?: ReactNode;
+}
+declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLElement>>;
+
+/**
+ * The one "no results" message, shared across every filtered table/list that
+ * can end up empty for the same two reasons -- see the component doc below
+ * for why they're deliberately not distinguished.
+ */
+declare const NO_RESULTS_TITLE = "No results match your filters";
+declare const NO_RESULTS_BODY = "Your filters may be too narrow, conflict with each other, or have no activity in this period.";
+/**
+ * The body for the active workspace: named while one is active, since its scope
+ * bounds the result as much as the filters do. Under "All data" (no name) the
+ * generic line stands alone.
+ */
+declare function noResultsBody(workspaceName?: string | null): string;
+/** One caller-supplied recovery action, rendered after the two named handlers. */
+interface NoResultsAction {
+    label: string;
+    onClick: () => void;
+    /** Rendered as the filled button; every other action renders as the quiet link/button. */
+    primary?: boolean;
+}
+declare const PRIMARY_ACTION_CLASS = "rounded-control bg-brand-primaryAction px-3.5 py-2 text-[13px] font-semibold text-white transition-colors hover:opacity-90";
+declare const QUIET_ACTION_CLASS = "rounded-control text-[13px] font-medium text-text-link transition-colors hover:underline focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-border-focus";
+/**
+ * @pattern NoResultsEmptyState
+ * @description Guided empty state for a query that returned nothing.
+ * Deliberately one state for two causes, because the user can't tell them
+ * apart and the fix is the same either way -- loosen the filters or widen the
+ * date range: (1) a filter combination that can't match anything, or (2) a
+ * valid combination with no activity in the selected period. So the copy
+ * names both possibilities instead of asserting one. Renders as a bare
+ * stack -- no border, background, or fixed height -- so it can sit directly
+ * in a colSpan table cell (or a card, or a chart body) that already owns
+ * that chrome, without imposing its own.
+ * @tokens bg-subtle, text-text-tertiary, text-base, text-text-primary,
+ * text-text-secondary, rounded-control, bg-brand-primaryAction, text-text-link,
+ * focus-visible:outline-border-focus
+ * @dependencies lucide-react
+ * @behavior The Clear button shows when `onClearFilters` is given AND
+ * `hasFilters` isn't explicitly `false` -- so a caller can either pass the
+ * handler conditionally (only when there's something to clear) or always
+ * pass it and gate visibility with `hasFilters` separately; both existing
+ * call patterns work unchanged. The Edit button shows whenever
+ * `onEditFilters` is given. `actions` appends further caller-defined
+ * 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.
+ * @usage
+ * ```tsx
+ * <NoResultsEmptyState hasFilters={hasFilters} onClearFilters={clearFilters} onEditFilters={openFilterTray} />
+ * <NoResultsEmptyState
+ *   title="Properties not set up in this workspace"
+ *   body="Switch to a workspace that has them defined or create a new one."
+ *   actions={[{ label: 'Switch workspace', onClick: openSwitcher, primary: true }, { label: 'Create workspace', onClick: createNew }]}
+ * />
+ * ```
+ */
+interface NoResultsEmptyStateProps {
+    /** @default NO_RESULTS_TITLE */
+    title?: string;
+    /** Replaces the default body wholesale, workspace name included. */
+    body?: string;
+    /** The active workspace's name, or nothing under "All data". Shapes the default body only -- ignored when `body` is given. */
+    workspaceName?: string | null;
+    /**
+     * Explicit override for whether the Clear button can show. Omit to derive
+     * it from whether `onClearFilters` was passed; pass `false` to force it
+     * hidden even though a handler was given (e.g. the handler exists but
+     * nothing is currently applied).
+     */
+    hasFilters?: boolean;
+    onClearFilters?: () => void;
+    onEditFilters?: () => void;
+    /** Extra recovery actions, rendered in order after Clear/Edit. */
+    actions?: NoResultsAction[];
+    /**
+     * Optional prefix for `data-testid` attributes on the container
+     * (`testIdPrefix` itself), the Clear button (`${testIdPrefix}-clear`), and
+     * the Edit button (`${testIdPrefix}-edit`). Omit for no test-id wiring.
+     * Pass `"no-results"` to reproduce mr-clientapps-insights-studio's current
+     * fixed ids (`no-results`, `no-results-clear`, `no-results-edit`) exactly.
+     */
+    testIdPrefix?: string;
+}
+declare function NoResultsEmptyState({ title, body, workspaceName, hasFilters, onClearFilters, onEditFilters, actions, testIdPrefix, }: NoResultsEmptyStateProps): react.JSX.Element;
+
+interface SummaryGroupItemValue {
+    id: string;
+    name: string;
+    /**
+     * Secondary line under the name. Takes a node rather than a plain string
+     * so a caller can render something richer than static text there -- e.g.
+     * mr-clientapps-insights-studio's Account Lists group swaps this for a
+     * "No accounts assigned -- click here to add accounts" link when a list is
+     * empty, which a plain `string` field couldn't hold.
+     */
+    meta?: React.ReactNode;
+}
+interface SummaryGroup {
+    id: string;
+    label: string;
+    items: SummaryGroupItemValue[];
+    onRemove: (id: string) => void;
+    onRemoveAll: () => void;
+    /** Nested sub-sections rendered, indented, beneath this group's own items. */
+    subGroups?: SummaryGroup[];
+}
+/**
+ * @pattern WorkspaceSelectedCard
+ * @description Sticky recap card listing what each section's picker has
+ * added, as collapsible groups with per-item remove and "Remove all" --
+ * generic over the `SummaryGroup` shape, no domain coupling. Reconciled from
+ * two implementations: insights-studio-prototype's generic `SummaryGroup[]`
+ * (kept, since it cleanly covers mr-clientapps-insights-studio's own usage
+ * too -- that app's fixed `sets`/`accountLists` prop pair is just this same
+ * shape with the group list hardcoded at the call site instead of passed
+ * in) and mr-clientapps-insights-studio's `SelectedSummary`, whose
+ * `wasEmpty`-ref auto-expand tracking turned out to be the correct one (see
+ * `@behavior`) and whose `shadow-1` -- not a real `@mediaradar/design-tokens`
+ * class, confirmed against the built theme -- pointed at a real, deliberately
+ * omitted elevation this card was missing; the local `shadow-1`/`shadow-2`
+ * naming maps to this package's `shadow-raised`/`shadow-overlay` respectively
+ * (raised: a static card like this one; overlay: a floating popover/menu),
+ * not a 1:1 name swap.
+ * @tokens rounded-card, border-border, bg-surface, shadow-raised,
+ * text-text-secondary, text-text-primary, rounded-full, bg-subtle,
+ * rounded-control, bg-canvas, hover:bg-subtle, hover:text-text-danger,
+ * text-text-link, divide-border
+ * @dependencies lucide-react
+ * @behavior A group auto-expands only on the empty-to-nonempty transition
+ * (including via a nested sub-group's items) and auto-collapses when
+ * emptied; manual open/close toggles in between are preserved. This is
+ * mr-clientapps-insights-studio's `wasEmpty`-ref logic, not
+ * insights-studio-prototype's original `prevCount`-comparison one --
+ * verified the two differ: the original re-opened a group on ANY item
+ * 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.
+ * @usage
+ * ```tsx
+ * <WorkspaceSelectedCard groups={[{ id: 'advertisers', label: 'Advertisers', items: selected, onRemove: removeOne, onRemoveAll: clearAll }]} />
+ * ```
+ */
+interface WorkspaceSelectedCardProps {
+    groups: SummaryGroup[];
+    /**
+     * Optional prefix for `data-testid` attributes on each group's toggle
+     * (`${testIdPrefix}-group-<group.id>`) and its "Remove all" button
+     * (`${testIdPrefix}-remove-all-<group.id>`), applied recursively to
+     * sub-groups too. Omit for no test-id wiring.
+     *
+     * NOTE: this does not reproduce mr-clientapps-insights-studio's current
+     * fixed ids byte-for-byte -- its container carries a separate, unrelated
+     * `workspace-selected-summary` id (this component has no single container
+     * element those groups sit inside, by design, so there's nothing to attach
+     * an equivalent id to) while its groups use a *different* prefix,
+     * `workspace-summary-group-<type>` / `workspace-summary-remove-all-<type>`.
+     * A consumer with existing Playwright locators keyed off those exact
+     * strings needs to update them, or the caller needs its own id mapping --
+     * not attempted here, same as `DateRangeFilter`'s documented preset-slug
+     * mismatch.
+     */
+    testIdPrefix?: string;
+}
+declare function WorkspaceSelectedCard({ groups, testIdPrefix }: WorkspaceSelectedCardProps): react.JSX.Element;
+
+/**
+ * @pattern BarChartPlaceholder
+ * @description Neutral, dataless stand-in for a ranked-bar chart --
+ * descending bar profile under a blank-labelled axis frame (dashed
+ * gridlines, blank y/x-tick boxes), so an unsatisfiable filter still reads
+ * as "a chart belongs here" rather than a failed load. No real value ever
+ * appears (no channel/league names, media types, dollar amounts,
+ * percentages, or series colors), and the shape holds the card's layout
+ * steady so nothing jumps when real data arrives.
+ * @tokens bg-subtle, border-border-default, rounded-xs
+ * @behavior Purely presentational -- `role="presentation"` and
+ * `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`.
+ * @usage
+ * ```tsx
+ * <BarChartPlaceholder />
+ * <BarChartPlaceholder height={180} />
+ * ```
+ */
+interface BarChartPlaceholderProps {
+    /** Chart height in pixels. */
+    height?: number;
+}
+declare function BarChartPlaceholder({ height }: BarChartPlaceholderProps): react.JSX.Element;
+
+/**
+ * @pattern LineChartPlaceholder
+ * @description Neutral, dataless stand-in for a multi-series trend chart --
+ * four grey paths over the shared axis frame, each with a solid-then-dashed
+ * handoff for the live chart's forecast tail, and a point at every sample.
+ * Points are positioned rather than drawn in the SVG: the plot stretches to
+ * the card, and a stretched `<circle>` would go oval. Same no-results use
+ * as `BarChartPlaceholder` -- no real value ever appears, and the shape
+ * holds the card's layout steady so nothing jumps when real data arrives.
+ * @tokens border-border-strong, bg-subtle, border-border-default, rounded-xs
+ * @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.
+ * @usage
+ * ```tsx
+ * <LineChartPlaceholder />
+ * <LineChartPlaceholder height={200} />
+ * ```
+ */
+interface LineChartPlaceholderProps {
+    /** Chart height in pixels. */
+    height?: number;
+}
+declare function LineChartPlaceholder({ height }: LineChartPlaceholderProps): react.JSX.Element;
+
+/**
+ * @pattern PieChartPlaceholder
+ * @description Neutral, dataless stand-in for a pie chart -- a grey disc
+ * seamed where slices would fall, beside a blank legend. No axis, matching
+ * the live pie it stands in for. Same no-results use as
+ * `BarChartPlaceholder`: an unsatisfiable filter reads as "a chart belongs
+ * here" rather than a failed load, with no real value (names, media types,
+ * dollar amounts, percentages, series colors) ever appearing.
+ * @tokens bg-subtle, border-border-default, rounded-xs
+ * @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.
+ * @usage
+ * ```tsx
+ * <PieChartPlaceholder />
+ * <PieChartPlaceholder legendRows={4} />
+ * ```
+ */
+interface PieChartPlaceholderProps {
+    /** Chart height in pixels. */
+    height?: number;
+    /** Number of blank legend rows to render beside the disc. */
+    legendRows?: number;
+}
+declare function PieChartPlaceholder({ height, legendRows }: PieChartPlaceholderProps): react.JSX.Element;
+
+/**
+ * @pattern StackedColumnPlaceholder
+ * @description Neutral, dataless stand-in for a 100% stacked column -- a
+ * single banded column beside a blank legend. `axis` follows the live card
+ * it stands in for: a share-of-total chart plotting on a 0-100% axis passes
+ * `axis`, a bare stack with no scale (e.g. a share-of-voice column) omits
+ * it. Same no-results use as `BarChartPlaceholder` -- no real value ever
+ * appears, and the shape holds the card's layout steady.
+ * @tokens bg-subtle, border-border-strong, border-border-default, rounded-control
+ * @behavior Purely presentational -- `role="presentation"` and
+ * `aria-hidden="true"` throughout. Band seams use `border-border-strong`
+ * rather than the softer `border-border-default` gridline color: on a
+ * `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.
+ * @usage
+ * ```tsx
+ * <StackedColumnPlaceholder />
+ * <StackedColumnPlaceholder axis />
+ * ```
+ */
+interface StackedColumnPlaceholderProps {
+    /** Chart height in pixels. */
+    height?: number;
+    /** Column width in pixels. */
+    width?: number;
+    /** Number of bands (and matching blank legend rows). */
+    legendRows?: number;
+    /** Wrap the column in a 0-100% axis frame, matching a live share-of-total chart. */
+    axis?: boolean;
+}
+declare function StackedColumnPlaceholder({ height, width, legendRows, axis, }: StackedColumnPlaceholderProps): react.JSX.Element;
+
+/**
+ * @pattern Tooltip
+ * @description Portalled hover/focus tooltip. Two ways to attach a trigger:
+ * wrap `children` (the default -- an inline trigger, e.g. a truncated table
+ * cell or a chart legend entry), or pass `anchorRef` for an element that
+ * already needs its own ref, or where wrapping in an extra inline box would
+ * disturb layout (an icon-only collapsed nav rail, for example) -- the two
+ * are mutually exclusive ways of specifying the trigger, and `children` is
+ * ignored when `anchorRef` is set. Positioned `fixed` from the trigger's
+ * bounding rect and rendered through a portal to `document.body`, so it
+ * escapes both `overflow` clipping inside scrollable panels and the broken
+ * `fixed` containing block a transformed ancestor creates.
+ * @tokens rounded-control, border-border-default, bg-surface, shadow-overlay,
+ * text-text-primary, bg-text-primary, text-surface
+ * @variant surface - Default. Themed surface/border bubble -- matches the
+ * Recharts chart tooltips this was originally built for.
+ * @variant inverted - Solid dark pill (no border) -- for a tooltip sitting
+ * over a nav rail or other icon-only surface, where the themed surface bubble
+ * doesn't read as clearly against a busy background.
+ * @behavior Shows on hover and on keyboard focus (so it stays reachable
+ * without a pointer) after `delay` ms (0 = immediate, the default). Hides
+ * immediately on mouseleave/blur, cancelling a pending delayed show if it
+ * hasn't fired yet -- except in `interactive` mode, which delays the hide
+ * briefly so the pointer can travel from the trigger into the tooltip's own
+ * content. Pass `whenTruncated` to only surface it once the trigger's content
+ * is actually clipped by ellipsis (`scrollWidth > clientWidth`). `placement`
+ * 'top'/'bottom' centre (or `align="start"` left-align) on the trigger;
+ * 'right' centres vertically beside the anchor and 'bottom-end' hangs below,
+ * 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.
+ * @usage
+ * ```tsx
+ * <Tooltip label="Full advertiser name" whenTruncated>
+ *   <span className="truncate">{name}</span>
+ * </Tooltip>
+ *
+ * const ref = useRef<HTMLButtonElement>(null);
+ * <button ref={ref}>Sports</button>
+ * <Tooltip label="Sports" anchorRef={ref} placement="right" delay={500} variant="inverted" />
+ * ```
+ */
+interface TooltipProps {
+    /** Tooltip content shown on hover/focus. */
+    label: ReactNode;
+    /** The trigger content, wrapped inline. Omit when using `anchorRef`. */
+    children?: ReactNode;
+    /**
+     * Attach to an existing element instead of wrapping `children` in a
+     * trigger span -- see the pattern description. When set, `children` /
+     * `className` / `whenTruncated` all still apply to that element (its
+     * `scrollWidth`/`clientWidth` drive `whenTruncated`), just without this
+     * component rendering a wrapping element of its own.
+     */
+    anchorRef?: RefObject<HTMLElement | null>;
+    /** Classes for the inline trigger wrapper (e.g. `truncate`, `min-w-0`). Ignored with `anchorRef`. */
+    className?: string;
+    /**
+     * Only reveal the tooltip when the trigger's content is actually clipped by
+     * ellipsis (`scrollWidth > clientWidth`). Off by default -- the tooltip always
+     * shows.
+     */
+    whenTruncated?: boolean;
+    /**
+     * When true, the tooltip accepts pointer events so it can contain links and
+     * other interactive content.
+     */
+    interactive?: boolean;
+    /**
+     * Which side of the trigger to render on. 'top' (default) / 'bottom'
+     * centre on the trigger (or left-align with `align="start"`). 'right' /
+     * 'bottom-end' are for an `anchorRef` anchor -- see the pattern description.
+     */
+    placement?: "top" | "bottom" | "right" | "bottom-end";
+    /**
+     * How the box lines up with the trigger horizontally, for 'top'/'bottom'
+     * placement only. "center" (the default) centres it; "start" puts its left
+     * edge on the trigger so it grows rightward, which reads better for a small
+     * icon sitting beside the text it describes -- a centred box there hangs
+     * out over the content to the left.
+     */
+    align?: "center" | "start";
+    /**
+     * Hover delay in ms before the tooltip appears. 0 (default) shows
+     * immediately. A collapsed nav rail passes 500 so a fast mouse pass over
+     * several icons doesn't flash a tooltip per icon.
+     */
+    delay?: number;
+    /** 'surface' (default) or 'inverted' -- see the pattern description. */
+    variant?: "surface" | "inverted";
+    /** Optional prefix for a `data-testid` on the floating tooltip bubble. */
+    testIdPrefix?: string;
+}
+declare function Tooltip({ label, children, anchorRef, className, whenTruncated, interactive, placement, align, delay, variant, testIdPrefix, }: TooltipProps): react.JSX.Element | null;
+
+/**
+ * @pattern AdvertiserNoResults
+ * @description Shown when a search-first picker's search returns nothing --
+ * gives an actionable next step rather than just a bare "no results"
+ * message. Named for its original (and still primary) use across
+ * `insights-studio-prototype`'s three advertiser-search filter trays
+ * (Creative Intel, Publisher, Sports), but the `hint` prop makes it reusable
+ * for any other search-first dimension. Distinct from the more general
+ * `NoResultsEmptyState` (a whole-board "no results match your filters"
+ * state) -- this one is scoped to a single search box returning nothing,
+ * inline within a picker's option list.
+ * @tokens text-text-primary, text-text-tertiary
+ * @usage
+ * ```tsx
+ * <AdvertiserNoResults query={query} />
+ * <AdvertiserNoResults query={query} hint="Try a different spelling, or switch the Agency Type." />
+ * ```
+ */
+interface AdvertiserNoResultsProps {
+    /** The search term that returned nothing. */
+    query: string;
+    /** The actionable next step under the message. */
+    hint?: string;
+}
+declare function AdvertiserNoResults({ query, hint, }: AdvertiserNoResultsProps): react.JSX.Element;
+
+/**
+ * @pattern SelectAllVisible
+ * @description "Select all visible" row for a search-first picker's result
+ * list -- only render it once the caller decides the visible result set is
+ * long enough to warrant it (`insights-studio-prototype`'s three advertiser-
+ * search filter trays all gate it behind a 5-result threshold; mr-clientapps'
+ * `ScopedSearchSection` uses the identical threshold and copy for its own
+ * scoped search sections). Communicates how many are visible and toggles
+ * between "Select all" and "Deselect" based on `allSelected`.
+ * @tokens rounded-control, text-text-link, hover:bg-subtle
+ * @dependencies lucide-react
+ * @usage
+ * ```tsx
+ * {results.length > 5 && (
+ *   <SelectAllVisible count={results.length} allSelected={allSelected} onToggle={toggleAll} />
+ * )}
+ * ```
+ */
+interface SelectAllVisibleProps {
+    /** Number of currently visible results. */
+    count: number;
+    /** Whether every visible result is already selected. */
+    allSelected: boolean;
+    onToggle: () => void;
+    /** Optional prefix for a `data-testid` on the row. */
+    testIdPrefix?: string;
+}
+declare function SelectAllVisible({ count, allSelected, onToggle, testIdPrefix }: SelectAllVisibleProps): react.JSX.Element;
+
+/**
+ * @pattern SelectedSection
+ * @description Collapsible "Selected (n)" container for a search-first
+ * picker. Selections can pile up and crowd out the live search results, so
+ * the user can fold them away to refocus on the search. Controlled so the
+ * parent can auto-collapse it (e.g. when the search is cleared, or jointly
+ * with a sibling "parked" section) -- `insights-studio-prototype`'s three
+ * advertiser-search filter trays all drive `open` this way. The caller
+ * renders each selected row itself as `children` rather than this component
+ * owning row markup: the three real call sites render genuinely different
+ * row content (plain rows, opacity-dimmed "parked" rows, per-tray custom
+ * columns), so a fixed row shape would have forced a compromise none of them
+ * 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
+ * @usage
+ * ```tsx
+ * <SelectedSection count={selected.length} open={open} onToggle={() => setOpen((o) => !o)}>
+ *   {selected.map((s) => <Row key={s.id} item={s} />)}
+ * </SelectedSection>
+ * ```
+ */
+interface SelectedSectionProps {
+    count: number;
+    open: boolean;
+    onToggle: () => void;
+    /** The caller renders each selected row itself. */
+    children: React.ReactNode;
+    /** Optional prefix for a `data-testid` on the toggle button. */
+    testIdPrefix?: string;
+}
+declare function SelectedSection({ count, open, onToggle, children, testIdPrefix }: SelectedSectionProps): react.JSX.Element | null;
+
+interface PickerRow {
+    id: string;
+    name: string;
+    children?: PickerRow[];
+}
+interface PickerColumn<T extends PickerRow> {
+    key: string;
+    header: string;
+    render: (row: T) => ReactNode;
+    className?: string;
+}
+interface PickerFilter<T extends PickerRow> {
+    label: string;
+    options: string[];
+    /** Returns the row's value for this filter (matched against options). */
+    value: (row: T) => string | undefined;
+}
+/** The subset of an account-list record this component actually renders in
+ *  its "Account lists" tab -- a caller's own richer type (with members,
+ *  createdBy, etc.) is passed in as-is; only these fields are read. */
+interface SelectionPickerAccountList {
+    id: string;
+    name: string;
+    /** Number of accounts currently in the list. */
+    count: number;
+    /** Entity types represented in the list, for a quick descriptive line. */
+    entityTypes: string[];
+    updatedAt: string;
+}
+interface SelectionPickerProps<T extends PickerRow> {
+    /** Full catalog to search/filter over client-side. Ignored when `results`
+     *  is given instead -- that's the async/paginated mode, see `results`. */
+    catalog?: T[];
+    selected: T[];
+    onChange: (next: T[]) => void;
+    columns: PickerColumn<T>[];
+    /** First filter is rendered as the primary entity-type group. */
+    filters: PickerFilter<T>[];
+    searchPlaceholder?: string;
+    /** Optional mock drill-down: returns child rows to reveal under a row. */
+    getChildren?: (row: T) => T[] | undefined;
+    helper?: string;
+    /** Trailing Info/drill-down column. Defaults to shown. */
+    showInfoColumn?: boolean;
+    /** Filter options pre-selected on mount, keyed by filter label. */
+    defaultFilters?: Record<string, string[]>;
+    /** When true, results appear only once the user types a query -- active
+     *  filters alone don't reveal the table (used where a filter is pre-selected). */
+    requireQuery?: boolean;
+    /** When true, the full catalog shows immediately without a search -- for
+     *  short, browsable lists (e.g. US states). */
+    showResultsWithoutSearch?: boolean;
+    /** When provided, a "Search / Account lists" source toggle appears and the
+     *  Account lists tab lets the user pull in whole uploaded lists. */
+    accountLists?: SelectionPickerAccountList[];
+    selectedListIds?: string[];
+    onToggleList?: (id: string) => void;
+    /** Rows that are already committed elsewhere and can't be toggled here --
+     *  they render dimmed with no checkbox at all (an "Add" picker shouldn't
+     *  offer to un-add something it isn't responsible for). Select-all skips
+     *  them, so it can't strip them out from under the caller. */
+    lockedIds?: ReadonlySet<string>;
+    /**
+     * Externally-computed, already-filtered rows -- for a caller whose search
+     * is server-side/async (loading, pagination) instead of a full in-memory
+     * `catalog` filtered client-side. When given, this replaces `catalog`'s
+     * own search/filter matching entirely: the component renders exactly
+     * these rows, still gated by the same "has the user searched or filtered
+     * yet" reveal rule as catalog mode. Pair with `onQueryChange` so the
+     * caller knows what to search for, and with
+     * `loading`/`error`/`hasMore`/`onLoadMore` for the rest of a typical async
+     * search's states. Omit (the default) to keep the original catalog +
+     * client-side search/filter behavior -- an existing caller's behavior
+     * never changes just by picking up a new version of this component.
+     */
+    results?: T[];
+    /** Fires on every keystroke in the search box with the new query text --
+     *  for a caller in `results` mode that needs to know what to search for.
+     *  Fire-and-forget; this component still owns the input's value either way. */
+    onQueryChange?: (query: string) => void;
+    /** Shows a centered spinner in place of rows. Only meaningful in `results` mode. */
+    loading?: boolean;
+    /** Shows a "couldn't load" message (see `errorMessage`) in place of rows. */
+    error?: boolean;
+    /** @default "Couldn't load options. Please try again." */
+    errorMessage?: string;
+    /** Shows a "Load more" button below the results when another page is available. */
+    hasMore?: boolean;
+    /** Disables the Load more button and shows a small spinner in it while a page is already in flight. */
+    loadingMore?: boolean;
+    onLoadMore?: () => void;
+    /** Extra toolbar content rendered after the built-in filter dropdowns --
+     *  e.g. a source/level multi-select the caller owns. A plain composition
+     *  slot; this component has no opinion on what it renders. */
+    toolbarExtra?: ReactNode;
+    /**
+     * Optional prefix for `data-testid` attributes on the search input
+     * (`${testIdPrefix}-search`), the source toggle buttons
+     * (`${testIdPrefix}-source-search` / `-lists`), each filter dropdown
+     * trigger (`${testIdPrefix}-filter-<slug>`) and its options, the
+     * select-all checkbox (`${testIdPrefix}-select-all`), each row
+     * (`${testIdPrefix}-row-<slug>`), the Load more button
+     * (`${testIdPrefix}-load-more`), and each Account lists row/count
+     * (`${testIdPrefix}-list-<id>` / `${testIdPrefix}-list-count`). Omit for
+     * no test-id wiring.
+     */
+    testIdPrefix?: string;
+}
+/**
+ * @pattern SelectionPicker
+ * @description Generic search-and-filter picker for building a selection out
+ * of a larger catalog -- a search box plus filter dropdowns above a checkbox
+ * table, with an optional "Search / Account lists" source toggle for pulling
+ * in whole pre-built lists at once. The table stays empty until the user
+ * actually searches or filters (no pre-loaded catalog dump), and checking a
+ * row commits immediately rather than staging into a separate "Add
+ * selected" step. Supports two data modes: a full in-memory `catalog`
+ * filtered client-side (the default), or externally-computed `results` for a
+ * caller whose search is server-side/async, with `loading`/`error`/
+ * `hasMore`/`onLoadMore` covering that mode's states.
+ * @tokens rounded-control, rounded-card, border-border-default, bg-input,
+ * bg-canvas, bg-surface, shadow-raised, shadow-overlay, text-text-primary,
+ * text-text-secondary, text-text-tertiary, text-text-link,
+ * text-brand-primaryAction, border-brand-primaryAction, bg-brand-primaryAction,
+ * bg-brand-primarySoft, bg-subtle, rounded-full, hover:bg-subtle,
+ * hover:bg-canvas, hover:text-text-primary, placeholder:text-text-tertiary,
+ * cursor-default
+ * @dependencies lucide-react, this package's own CheckBox
+ * @behavior "Select all" is scoped to the current search/filter results (or
+ * the currently-loaded page(s) of `results`), not the whole catalog, and
+ * skips lockedIds throughout so it can't toggle rows it isn't responsible
+ * for. Filter dropdowns are portal-rendered and close on outside-click,
+ * Escape, or scroll. Long option lists (>8) get an in-dropdown search box.
+ * Row and select-all checkboxes use this package's own `CheckBox`, wired
+ * 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.
+ * @usage
+ * ```tsx
+ * <SelectionPicker
+ *   catalog={advertisers}
+ *   selected={selected}
+ *   onChange={setSelected}
+ *   columns={[{ key: 'name', header: 'Advertiser', render: (r) => r.name }]}
+ *   filters={[{ label: 'Category', options: categories, value: (r) => r.category }]}
+ * />
+ * <SelectionPicker
+ *   catalog={[]}
+ *   results={searchResults}
+ *   onQueryChange={setQuery}
+ *   loading={status === 'loading'}
+ *   error={status === 'error'}
+ *   hasMore={hasMore}
+ *   loadingMore={loadingMore}
+ *   onLoadMore={loadMore}
+ *   selected={selected}
+ *   onChange={setSelected}
+ *   columns={columns}
+ *   filters={[]}
+ *   toolbarExtra={<LevelMultiSelect checked={levels} onToggle={toggleLevel} options={levelOptions} />}
+ * />
+ * ```
+ */
+declare function SelectionPicker<T extends PickerRow>({ catalog, selected, onChange, columns, filters, searchPlaceholder, getChildren, helper, showInfoColumn, defaultFilters, requireQuery, showResultsWithoutSearch, accountLists, selectedListIds, onToggleList, lockedIds, results, onQueryChange, loading, error, errorMessage, hasMore, loadingMore, onLoadMore, toolbarExtra, testIdPrefix, }: SelectionPickerProps<T>): react.JSX.Element;
+
+interface PubBreak {
+    brand: string;
+    owner: string;
+    tags: string[];
+    spendN: number;
+    pct: number;
+    yoy: number | "NEW";
+}
+interface PublisherBreakdownListProps {
+    rows: PubBreak[];
+    /** @default 10 */
+    defaultVisibleCount?: number;
+    /** Set false when the container already supplies its own padding. @default true */
+    padded?: boolean;
+    /** When provided, the truncated-list footer becomes a plain link instead of
+     *  the inline "see all" expand/collapse behavior. */
+    viewAllHref?: string;
+    /**
+     * Custom per-row logo/avatar rendering -- e.g. a real logo-fetching hook or
+     * a brand-name-to-domain favicon lookup. Defaults to a plain initials
+     * monogram so the component works with zero configuration; this package
+     * intentionally doesn't ship a brand -> logo/domain lookup table, since
+     * that's fixture/business data, not a design-system concern.
+     */
+    renderLogo?: (row: PubBreak) => ReactNode;
+}
+/**
+ * @pattern PublisherBreakdownList
+ * @description Flat Current/Previous/YoY spend list, prop-driven end to end
+ * -- no data fetching of its own. Row padding is configurable so it can sit
+ * flush inside a bordered card or inline within an already-padded container.
+ * mr-clientapps-insights-studio's analogous "Top publishers" UI
+ * (`PublisherBreakdown.tsx`) was evaluated for reconciliation and
+ * deliberately NOT merged into this component -- see the escape-hatch note
+ * below. `renderLogo` lets a caller plug in real per-row logos; without it,
+ * rows show a plain initials monogram.
+ * @tokens text-text-primary, text-text-tertiary, text-text-secondary,
+ * text-text-link, text-text-warning, text-text-success, text-text-danger,
+ * border-border-default, bg-surface, bg-subtle, rounded-control, rounded-full,
+ * shadow-overlay
+ * @behavior Truncates to `defaultVisibleCount` rows with a "See all (N more)"
+ * / "Show less" toggle, unless `viewAllHref` is given, in which case the
+ * footer becomes a plain link out instead (e.g. to a full breakdown page).
+ *
+ * Escape hatch: mr-clientapps-insights-studio's own publisher breakdown
+ * (`domains/reviews/src/components/media-spend/PublisherBreakdown.tsx`) is a
+ * genuinely different component, not just a differently-styled copy of this
+ * one -- a three-level Owner/Publisher/Property accordion, each level
+ * independently paginated against a live API (`usePublisherBreakdown`/
+ * `usePublisherBreakdownChildren`), with per-row logo fetching via a batched
+ * hook. None of that -- the recursive expand/collapse tree, the live
+ * fetching, the level toggle -- has an equivalent in this flat,
+ * fully-synchronous, prop-driven list, and bolting it on would mean either
+ * building the accordion machinery into every consumer of this component
+ * (including ones that only ever wanted a flat list, like the Opportunities
+ * battle card) or branching internally on which "mode" is active -- exactly
+ * 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.
+ * @usage
+ * ```tsx
+ * <PublisherBreakdownList rows={publishers} defaultVisibleCount={10} />
+ * ```
+ */
+declare function PublisherBreakdownList({ rows, defaultVisibleCount, padded, viewAllHref, renderLogo }: PublisherBreakdownListProps): react.JSX.Element;
+
+export { AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, BarChartPlaceholder, type BarChartPlaceholderProps, Card, type CardProps, CheckBox, type CheckBoxProps, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, DateRangeFilter, type DateRangeFilterProps, InfoTip, type InfoTipProps, LineChartPlaceholder, type LineChartPlaceholderProps, NO_RESULTS_BODY, NO_RESULTS_TITLE, type NoResultsAction, NoResultsEmptyState, type NoResultsEmptyStateProps, PRIMARY_ACTION_CLASS, type PickerColumn, type PickerFilter, type PickerRow, PieChartPlaceholder, type PieChartPlaceholderProps, type PubBreak, PublisherBreakdownList, type PublisherBreakdownListProps, QUIET_ACTION_CLASS, SearchBar, type SearchBarProps, type SearchBarVariant, type SearchMatchMode, type SearchMatchValue, SectionRail, type SectionRailProps, SelectAllVisible, type SelectAllVisibleProps, SelectFilter, type SelectFilterProps, SelectedSection, type SelectedSectionProps, SelectionPicker, type SelectionPickerAccountList, type SelectionPickerProps, StackedColumnPlaceholder, type StackedColumnPlaceholderProps, type SummaryGroup, type SummaryGroupItemValue, Tooltip, type TooltipProps, WorkspaceSelectedCard, type WorkspaceSelectedCardProps, noResultsBody };