@mediaradar/design-components 0.7.0 → 0.8.1

package/dist/index.d.cts

@@ -165,6 +165,7 @@ declare function AdvertiserSearchPrompt({ label }: AdvertiserSearchPromptProps):
  * ```
  */
 interface CheckBoxProps {
+    /** Whether the box is checked. Controlled: the parent owns this value. */
     checked: boolean;
     /**
      * Some-but-not-all state for a "select all" checkbox -- shows a dash
@@ -172,9 +173,14 @@ interface CheckBoxProps {
      * plain boolean.
      */
     indeterminate?: boolean;
+    /**
+     * Called on click with no argument -- flip `checked` yourself. The click
+     * doesn't bubble, so a row that toggles on its own click won't fire twice.
+     */
     onChange: () => void;
     /** Accessible label -- required since the control carries no visible text of its own. */
     ariaLabel: string;
+    /** Blocks clicks, dims the box to 50% opacity, and cancels its hover preview. */
     disabled?: boolean;
     /** Forwarded as `data-testid`, for Playwright/test selectors. */
     testId?: string;
@@ -493,6 +499,8 @@ interface CardProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
     subtitle?: string;
     /** Trailing header content, e.g. a "View all" link. Ignored without `title`. */
     action?: ReactNode;
+    /** Card body. Rendered edge to edge without `title`; inside the standard padding with it. */
+    children?: ReactNode;
 }
 declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLElement>>;
 
@@ -1194,6 +1202,8 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
     asChild?: boolean;
     /** Shows a spinner in place of the leading edge and disables the button. */
     loading?: boolean;
+    /** Button label and/or icon. With `asChild`, the single element that receives the button styling. */
+    children?: ReactNode;
 }
 /**
  * @pattern Button
@@ -1409,7 +1419,7 @@ interface PagerProps {
  */
 declare function Pager({ page, totalPages, onPage }: PagerProps): react.JSX.Element;
 
-declare const SIZES: {
+declare const SIZES$1: {
     /** Matches a 15px lucide icon exactly, so a workspace name in a menu row
      *  left-aligns with labels in icon-led rows above and below it. */
     readonly xs: "h-[15px] w-[15px] rounded-[4px] text-[8px] tracking-tight";
@@ -1420,7 +1430,7 @@ declare const SIZES: {
 interface WorkspaceAvatarProps {
     /** Omit for the unscoped "All data workspace". */
     name?: string;
-    size?: keyof typeof SIZES;
+    size?: keyof typeof SIZES$1;
 }
 /**
  * @pattern WorkspaceAvatar
@@ -1437,4 +1447,239 @@ interface WorkspaceAvatarProps {
  */
 declare function WorkspaceAvatar({ name, size }: WorkspaceAvatarProps): react.JSX.Element;
 
-export { AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, type CheckBoxProps, ChipContent, type ChipContentProps, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, DateRangeFilter, type DateRangeFilterProps, FilterChipBar, type FilterChipBarProps, FilterDropdownFooter, type FilterDropdownFooterProps, InfoTip, type InfoTipProps, LineChartPlaceholder, type LineChartPlaceholderProps, NO_RESULTS_BODY, NO_RESULTS_TITLE, NameListModal, type NameListModalProps, type NoResultsAction, NoResultsEmptyState, type NoResultsEmptyStateProps, PRIMARY_ACTION_CLASS, Pager, type PagerProps, 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, SortButton, type SortButtonProps, type SortDir, type SortState, StackedColumnPlaceholder, type StackedColumnPlaceholderProps, type SummaryGroup, type SummaryGroupItemValue, Tooltip, type TooltipProps, WorkspaceAvatar, type WorkspaceAvatarProps, WorkspaceSelectedCard, type WorkspaceSelectedCardProps, buttonVariants, chipTriggerClass, cycleSort, noResultsBody, sortProp };
+interface TagProps {
+    /** The tag's text, e.g. "Digital". Keep it short: the chip doesn't wrap or truncate. */
+    children: ReactNode;
+    /** Extra classes merged onto the chip. */
+    className?: string;
+}
+/**
+ * @pattern Tag
+ * @description Canonical descriptive tag — a neutral beige chip (e.g.
+ * "Digital", a focus area, a category). Use this for every non-semantic
+ * label so tags read the same everywhere. Colored/semantic badges (NEW, ±%
+ * deltas, status, counts) are intentionally NOT this component.
+ * @tokens bg-subtle, text-text-secondary, rounded-full
+ * @usage
+ * ```tsx
+ * <Tag>Digital</Tag>
+ * ```
+ */
+declare function Tag({ children, className }: TagProps): react.JSX.Element;
+
+/**
+ * @pattern TablePagination
+ * @description Full table-footer pagination bar: a rows-per-page select, a
+ * first/prev/pages/next/last pager, and the resolved "1 – 25 of N results"
+ * range. Owns no state — the host page holds `page` and `perPage` so the
+ * paged slice and the bar can't disagree.
+ * @tokens rounded-control, border-border-default, bg-input, text-text-primary, text-text-secondary, text-text-tertiary, bg-brand-primaryAction, text-brand-onprimary, hover:bg-subtle, hover:text-text-primary, focus:outline-border-focus
+ * @behavior The current page is filled with the brand action color (matching
+ * the Contacts pager). First/prev disable on page 1, next/last on the last
+ * page — disabled controls stay in the layout so the row never reflows.
+ * 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.
+ * @usage
+ * ```tsx
+ * <TablePagination
+ *   page={page}
+ *   perPage={perPage}
+ *   totalItems={matching.length}
+ *   onPageChange={setPage}
+ *   onPerPageChange={(n) => { setPerPage(n); setPage(1) }}
+ *   itemLabel="results"
+ * />
+ * ```
+ */
+declare function TablePagination({ page, perPage, totalItems, onPageChange, onPerPageChange, perPageOptions, itemLabel, className, }: {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    onPageChange: (page: number) => void;
+    onPerPageChange: (perPage: number) => void;
+    perPageOptions?: number[];
+    itemLabel?: string;
+    className?: string;
+}): react.JSX.Element;
+type TablePaginationProps = Parameters<typeof TablePagination>[0];
+
+/** Resolve a label to its actual [start, end] span, ending at `today`. */
+declare function resolveRange(label: string, today?: Date): [Date, Date];
+declare function DateRangePicker({ defaultValue, align, presets, onChange, onRangeChange, showFooter, today, years, }: {
+    defaultValue?: string;
+    align?: 'left' | 'right';
+    /** Rolling presets shown above Custom Range. Defaults to 3/6/12 months. */
+    presets?: string[];
+    onChange?: (label: string) => void;
+    /** Reports the resolved start/end dates — used to drive dependent views (e.g. table columns). */
+    onRangeChange?: (start: Date, end: Date) => void;
+    /** Deferred mode: preset/custom-range picks stage in a draft; only the fixed
+     *  Apply footer commits it (no live commit on click). */
+    showFooter?: boolean;
+    /** End of the available data window: rolling presets resolve back from here.
+     *  Defaults to the current date. */
+    today?: Date;
+    /** Years offered in the Custom Range selects. Defaults to the last four,
+     *  ending with `today`'s year. */
+    years?: number[];
+}): react.JSX.Element;
+type DateRangePickerProps = Parameters<typeof DateRangePicker>[0];
+
+interface MultiSelectGroup {
+    id: string;
+    label: string;
+    children: {
+        id: string;
+        label: string;
+    }[];
+}
+/**
+ * @pattern MultiSelectFilter
+ * @description Quick-access multi-select chip — mirrors the DateRangeFilter
+ * button shape (two-line caption + value with a chevron) and opens a
+ * searchable checkbox popover. Used for the page-level Media Type /
+ * Advertiser filters that share state with the filter tray.
+ * @tokens rounded-control, rounded-card, border-border-default, bg-surface, shadow-overlay, text-text-primary, text-text-secondary, text-text-tertiary, text-text-link, border-border-interactive, bg-brand-primaryAction, bg-input, hover:bg-subtle, hover:text-text-primary, placeholder:text-text-tertiary
+ * @dependencies lucide-react
+ * @behavior Same draft/commit-on-close pattern as AdvertiserQuickFilter — the
+ * draft resyncs from `selected` every time the tray opens, and (without
+ * showFooter) any close path commits it, while showFooter mode requires the
+ * Apply button and discards the draft on every other close. `min` enforces a
+ * 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.
+ * @usage
+ * ```tsx
+ * <MultiSelectFilter caption="Media" options={mediaOptions} selected={selected} onChange={setSelected} />
+ * ```
+ */
+declare function MultiSelectFilter({ caption, options, groups, selected, onChange, allLabel, searchable, searchPlaceholder, align, fullIsAll, min, icon, showFooter, clearValue, menuWidthClass, plainParent, fullWidth, }: {
+    caption: string;
+    options?: {
+        id: string;
+        label: string;
+    }[];
+    /** When provided, renders a nested parent → children tree (selection tracks
+     *  leaf ids; parents are tri-state and toggle all their children). */
+    groups?: MultiSelectGroup[];
+    selected: string[];
+    onChange: (next: string[]) => void;
+    allLabel?: string;
+    searchable?: boolean;
+    /** Overrides the search box's placeholder. The default derives from the
+     *  caption, which reads wrong once a caption is singular ("Search topic"). */
+    searchPlaceholder?: string;
+    align?: 'left' | 'right';
+    /** Treat "all options selected" as the unfiltered "All" state in the label. */
+    fullIsAll?: boolean;
+    /** Minimum selections that must remain (a toggle that would drop below is ignored). */
+    min?: number;
+    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). */
+    showFooter?: boolean;
+    /** What "Clear all" resets the draft to — the page's default selection. */
+    clearValue?: string[];
+    /** Tailwind width class for the dropdown panel (default `w-60`). Widen it when
+     *  option labels are long and would otherwise wrap. */
+    menuWidthClass?: string;
+    /** Render group parents at normal weight instead of semibold. */
+    plainParent?: boolean;
+    /** Stretch the trigger (and, with `menuWidthClass="w-full"`, the panel) to fill
+     *  its container — for stacked/full-width form layouts instead of the chip bar. */
+    fullWidth?: boolean;
+}): react.JSX.Element;
+type MultiSelectFilterProps = Parameters<typeof MultiSelectFilter>[0];
+
+/**
+ * Track, knob and travel per size. The knob leaves a 2px gutter at each end, so
+ * its "on" offset is always track − knob − 2 — keep that relationship if a new
+ * size is added, or the knob will sit off-centre at one end.
+ */
+declare const SIZES: {
+    readonly sm: {
+        readonly track: "h-5 w-9";
+        readonly knob: "h-4 w-4";
+        readonly on: "translate-x-[18px]";
+    };
+    readonly md: {
+        readonly track: "h-6 w-11";
+        readonly knob: "h-5 w-5";
+        readonly on: "translate-x-[22px]";
+    };
+};
+interface ToggleProps {
+    /** Whether the switch is on. Controlled: the parent owns this value. */
+    checked: boolean;
+    /** Receives the value being switched TO, not the current one. */
+    onChange: (next: boolean) => void;
+    /** Accessible name; the visible label lives in the row around it. */
+    label: string;
+    /** `md` for settings rows where the switch is the subject; `sm` for dense rows next to 13px text. */
+    size?: keyof typeof SIZES;
+    /** Blocks clicks and dims the switch to 50% opacity. */
+    disabled?: boolean;
+    /** Extra classes merged onto the track (the outer `<button>`). */
+    className?: string;
+}
+/**
+ * @pattern Toggle
+ * @description The app's on/off switch. Use it for a setting that takes effect
+ * as a state the user keeps — "only include enriched creatives", "email me a
+ * digest" — where a checkbox would read as an item being ticked off a list.
+ * Rendered as a `<button role="switch">` so the on/off state is announced as a
+ * switch rather than a checkbox, and so the track and knob can carry the brand
+ * fill without fighting a native input's styling hooks.
+ * @tokens bg-brand-primaryAction, bg-border-interactive, bg-surface, shadow-raised, outline-border-focus
+ * @behavior The knob is positioned by `translate-x`, not by flex alignment, so
+ * the slide animates. Off uses `bg-border-interactive` rather than a grey
+ * literal, which keeps the track visible against `bg-surface` in dark mode.
+ * Pair it with a label and any InfoTip in the surrounding row: this component
+ * draws only the switch, so rows stay free to lay the label out however they
+ * 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.
+ * @usage
+ * ```tsx
+ * <Toggle checked={enabled} onChange={setEnabled} label="Email news alerts" />
+ * <Toggle size="sm" checked={enabled} onChange={setEnabled} label="Only include enriched creatives" />
+ * ```
+ */
+declare function Toggle({ checked, onChange, label, size, disabled, className }: ToggleProps): react.JSX.Element;
+
+interface AISparkProps {
+    size?: number;
+    className?: string;
+}
+/**
+ * @pattern AISpark
+ * @description Assistant glyph — the lucide Sparkles icon stroked with the
+ * MR orange→violet assistant gradient. Each instance scopes its own gradient
+ * id, and the stops follow light/dark mode.
+ * @dependencies lucide-react
+ * @usage
+ * ```tsx
+ * <AISpark size={14} />
+ * ```
+ */
+declare function AISpark({ size, className }: AISparkProps): react.JSX.Element;
+
+type FreshnessLevel = "fresh" | "recent" | "stale";
+interface FreshnessProps {
+    level: FreshnessLevel;
+}
+/**
+ * @pattern Freshness
+ * @description Freshness dot — prefixed to card meta rows so a row of 4
+ * 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
+ * @usage
+ * ```tsx
+ * <Freshness level="fresh" />
+ * ```
+ */
+declare function Freshness({ level }: FreshnessProps): react.JSX.Element;
+
+export { AISpark, type AISparkProps, AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, type CheckBoxProps, ChipContent, type ChipContentProps, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, DateRangeFilter, type DateRangeFilterProps, DateRangePicker, type DateRangePickerProps, FilterChipBar, type FilterChipBarProps, FilterDropdownFooter, type FilterDropdownFooterProps, Freshness, type FreshnessLevel, type FreshnessProps, InfoTip, type InfoTipProps, LineChartPlaceholder, type LineChartPlaceholderProps, MultiSelectFilter, type MultiSelectFilterProps, type MultiSelectGroup, NO_RESULTS_BODY, NO_RESULTS_TITLE, NameListModal, type NameListModalProps, type NoResultsAction, NoResultsEmptyState, type NoResultsEmptyStateProps, PRIMARY_ACTION_CLASS, Pager, type PagerProps, 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, SortButton, type SortButtonProps, type SortDir, type SortState, StackedColumnPlaceholder, type StackedColumnPlaceholderProps, type SummaryGroup, type SummaryGroupItemValue, TablePagination, type TablePaginationProps, Tag, type TagProps, Toggle, type ToggleProps, Tooltip, type TooltipProps, WorkspaceAvatar, type WorkspaceAvatarProps, WorkspaceSelectedCard, type WorkspaceSelectedCardProps, buttonVariants, chipTriggerClass, cycleSort, noResultsBody, resolveRange, sortProp };

package/dist/index.d.ts

@@ -165,6 +165,7 @@ declare function AdvertiserSearchPrompt({ label }: AdvertiserSearchPromptProps):
  * ```
  */
 interface CheckBoxProps {
+    /** Whether the box is checked. Controlled: the parent owns this value. */
     checked: boolean;
     /**
      * Some-but-not-all state for a "select all" checkbox -- shows a dash
@@ -172,9 +173,14 @@ interface CheckBoxProps {
      * plain boolean.
      */
     indeterminate?: boolean;
+    /**
+     * Called on click with no argument -- flip `checked` yourself. The click
+     * doesn't bubble, so a row that toggles on its own click won't fire twice.
+     */
     onChange: () => void;
     /** Accessible label -- required since the control carries no visible text of its own. */
     ariaLabel: string;
+    /** Blocks clicks, dims the box to 50% opacity, and cancels its hover preview. */
     disabled?: boolean;
     /** Forwarded as `data-testid`, for Playwright/test selectors. */
     testId?: string;
@@ -493,6 +499,8 @@ interface CardProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
     subtitle?: string;
     /** Trailing header content, e.g. a "View all" link. Ignored without `title`. */
     action?: ReactNode;
+    /** Card body. Rendered edge to edge without `title`; inside the standard padding with it. */
+    children?: ReactNode;
 }
 declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLElement>>;
 
@@ -1194,6 +1202,8 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
     asChild?: boolean;
     /** Shows a spinner in place of the leading edge and disables the button. */
     loading?: boolean;
+    /** Button label and/or icon. With `asChild`, the single element that receives the button styling. */
+    children?: ReactNode;
 }
 /**
  * @pattern Button
@@ -1409,7 +1419,7 @@ interface PagerProps {
  */
 declare function Pager({ page, totalPages, onPage }: PagerProps): react.JSX.Element;
 
-declare const SIZES: {
+declare const SIZES$1: {
     /** Matches a 15px lucide icon exactly, so a workspace name in a menu row
      *  left-aligns with labels in icon-led rows above and below it. */
     readonly xs: "h-[15px] w-[15px] rounded-[4px] text-[8px] tracking-tight";
@@ -1420,7 +1430,7 @@ declare const SIZES: {
 interface WorkspaceAvatarProps {
     /** Omit for the unscoped "All data workspace". */
     name?: string;
-    size?: keyof typeof SIZES;
+    size?: keyof typeof SIZES$1;
 }
 /**
  * @pattern WorkspaceAvatar
@@ -1437,4 +1447,239 @@ interface WorkspaceAvatarProps {
  */
 declare function WorkspaceAvatar({ name, size }: WorkspaceAvatarProps): react.JSX.Element;
 
-export { AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, type CheckBoxProps, ChipContent, type ChipContentProps, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, DateRangeFilter, type DateRangeFilterProps, FilterChipBar, type FilterChipBarProps, FilterDropdownFooter, type FilterDropdownFooterProps, InfoTip, type InfoTipProps, LineChartPlaceholder, type LineChartPlaceholderProps, NO_RESULTS_BODY, NO_RESULTS_TITLE, NameListModal, type NameListModalProps, type NoResultsAction, NoResultsEmptyState, type NoResultsEmptyStateProps, PRIMARY_ACTION_CLASS, Pager, type PagerProps, 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, SortButton, type SortButtonProps, type SortDir, type SortState, StackedColumnPlaceholder, type StackedColumnPlaceholderProps, type SummaryGroup, type SummaryGroupItemValue, Tooltip, type TooltipProps, WorkspaceAvatar, type WorkspaceAvatarProps, WorkspaceSelectedCard, type WorkspaceSelectedCardProps, buttonVariants, chipTriggerClass, cycleSort, noResultsBody, sortProp };
+interface TagProps {
+    /** The tag's text, e.g. "Digital". Keep it short: the chip doesn't wrap or truncate. */
+    children: ReactNode;
+    /** Extra classes merged onto the chip. */
+    className?: string;
+}
+/**
+ * @pattern Tag
+ * @description Canonical descriptive tag — a neutral beige chip (e.g.
+ * "Digital", a focus area, a category). Use this for every non-semantic
+ * label so tags read the same everywhere. Colored/semantic badges (NEW, ±%
+ * deltas, status, counts) are intentionally NOT this component.
+ * @tokens bg-subtle, text-text-secondary, rounded-full
+ * @usage
+ * ```tsx
+ * <Tag>Digital</Tag>
+ * ```
+ */
+declare function Tag({ children, className }: TagProps): react.JSX.Element;
+
+/**
+ * @pattern TablePagination
+ * @description Full table-footer pagination bar: a rows-per-page select, a
+ * first/prev/pages/next/last pager, and the resolved "1 – 25 of N results"
+ * range. Owns no state — the host page holds `page` and `perPage` so the
+ * paged slice and the bar can't disagree.
+ * @tokens rounded-control, border-border-default, bg-input, text-text-primary, text-text-secondary, text-text-tertiary, bg-brand-primaryAction, text-brand-onprimary, hover:bg-subtle, hover:text-text-primary, focus:outline-border-focus
+ * @behavior The current page is filled with the brand action color (matching
+ * the Contacts pager). First/prev disable on page 1, next/last on the last
+ * page — disabled controls stay in the layout so the row never reflows.
+ * 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.
+ * @usage
+ * ```tsx
+ * <TablePagination
+ *   page={page}
+ *   perPage={perPage}
+ *   totalItems={matching.length}
+ *   onPageChange={setPage}
+ *   onPerPageChange={(n) => { setPerPage(n); setPage(1) }}
+ *   itemLabel="results"
+ * />
+ * ```
+ */
+declare function TablePagination({ page, perPage, totalItems, onPageChange, onPerPageChange, perPageOptions, itemLabel, className, }: {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    onPageChange: (page: number) => void;
+    onPerPageChange: (perPage: number) => void;
+    perPageOptions?: number[];
+    itemLabel?: string;
+    className?: string;
+}): react.JSX.Element;
+type TablePaginationProps = Parameters<typeof TablePagination>[0];
+
+/** Resolve a label to its actual [start, end] span, ending at `today`. */
+declare function resolveRange(label: string, today?: Date): [Date, Date];
+declare function DateRangePicker({ defaultValue, align, presets, onChange, onRangeChange, showFooter, today, years, }: {
+    defaultValue?: string;
+    align?: 'left' | 'right';
+    /** Rolling presets shown above Custom Range. Defaults to 3/6/12 months. */
+    presets?: string[];
+    onChange?: (label: string) => void;
+    /** Reports the resolved start/end dates — used to drive dependent views (e.g. table columns). */
+    onRangeChange?: (start: Date, end: Date) => void;
+    /** Deferred mode: preset/custom-range picks stage in a draft; only the fixed
+     *  Apply footer commits it (no live commit on click). */
+    showFooter?: boolean;
+    /** End of the available data window: rolling presets resolve back from here.
+     *  Defaults to the current date. */
+    today?: Date;
+    /** Years offered in the Custom Range selects. Defaults to the last four,
+     *  ending with `today`'s year. */
+    years?: number[];
+}): react.JSX.Element;
+type DateRangePickerProps = Parameters<typeof DateRangePicker>[0];
+
+interface MultiSelectGroup {
+    id: string;
+    label: string;
+    children: {
+        id: string;
+        label: string;
+    }[];
+}
+/**
+ * @pattern MultiSelectFilter
+ * @description Quick-access multi-select chip — mirrors the DateRangeFilter
+ * button shape (two-line caption + value with a chevron) and opens a
+ * searchable checkbox popover. Used for the page-level Media Type /
+ * Advertiser filters that share state with the filter tray.
+ * @tokens rounded-control, rounded-card, border-border-default, bg-surface, shadow-overlay, text-text-primary, text-text-secondary, text-text-tertiary, text-text-link, border-border-interactive, bg-brand-primaryAction, bg-input, hover:bg-subtle, hover:text-text-primary, placeholder:text-text-tertiary
+ * @dependencies lucide-react
+ * @behavior Same draft/commit-on-close pattern as AdvertiserQuickFilter — the
+ * draft resyncs from `selected` every time the tray opens, and (without
+ * showFooter) any close path commits it, while showFooter mode requires the
+ * Apply button and discards the draft on every other close. `min` enforces a
+ * 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.
+ * @usage
+ * ```tsx
+ * <MultiSelectFilter caption="Media" options={mediaOptions} selected={selected} onChange={setSelected} />
+ * ```
+ */
+declare function MultiSelectFilter({ caption, options, groups, selected, onChange, allLabel, searchable, searchPlaceholder, align, fullIsAll, min, icon, showFooter, clearValue, menuWidthClass, plainParent, fullWidth, }: {
+    caption: string;
+    options?: {
+        id: string;
+        label: string;
+    }[];
+    /** When provided, renders a nested parent → children tree (selection tracks
+     *  leaf ids; parents are tri-state and toggle all their children). */
+    groups?: MultiSelectGroup[];
+    selected: string[];
+    onChange: (next: string[]) => void;
+    allLabel?: string;
+    searchable?: boolean;
+    /** Overrides the search box's placeholder. The default derives from the
+     *  caption, which reads wrong once a caption is singular ("Search topic"). */
+    searchPlaceholder?: string;
+    align?: 'left' | 'right';
+    /** Treat "all options selected" as the unfiltered "All" state in the label. */
+    fullIsAll?: boolean;
+    /** Minimum selections that must remain (a toggle that would drop below is ignored). */
+    min?: number;
+    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). */
+    showFooter?: boolean;
+    /** What "Clear all" resets the draft to — the page's default selection. */
+    clearValue?: string[];
+    /** Tailwind width class for the dropdown panel (default `w-60`). Widen it when
+     *  option labels are long and would otherwise wrap. */
+    menuWidthClass?: string;
+    /** Render group parents at normal weight instead of semibold. */
+    plainParent?: boolean;
+    /** Stretch the trigger (and, with `menuWidthClass="w-full"`, the panel) to fill
+     *  its container — for stacked/full-width form layouts instead of the chip bar. */
+    fullWidth?: boolean;
+}): react.JSX.Element;
+type MultiSelectFilterProps = Parameters<typeof MultiSelectFilter>[0];
+
+/**
+ * Track, knob and travel per size. The knob leaves a 2px gutter at each end, so
+ * its "on" offset is always track − knob − 2 — keep that relationship if a new
+ * size is added, or the knob will sit off-centre at one end.
+ */
+declare const SIZES: {
+    readonly sm: {
+        readonly track: "h-5 w-9";
+        readonly knob: "h-4 w-4";
+        readonly on: "translate-x-[18px]";
+    };
+    readonly md: {
+        readonly track: "h-6 w-11";
+        readonly knob: "h-5 w-5";
+        readonly on: "translate-x-[22px]";
+    };
+};
+interface ToggleProps {
+    /** Whether the switch is on. Controlled: the parent owns this value. */
+    checked: boolean;
+    /** Receives the value being switched TO, not the current one. */
+    onChange: (next: boolean) => void;
+    /** Accessible name; the visible label lives in the row around it. */
+    label: string;
+    /** `md` for settings rows where the switch is the subject; `sm` for dense rows next to 13px text. */
+    size?: keyof typeof SIZES;
+    /** Blocks clicks and dims the switch to 50% opacity. */
+    disabled?: boolean;
+    /** Extra classes merged onto the track (the outer `<button>`). */
+    className?: string;
+}
+/**
+ * @pattern Toggle
+ * @description The app's on/off switch. Use it for a setting that takes effect
+ * as a state the user keeps — "only include enriched creatives", "email me a
+ * digest" — where a checkbox would read as an item being ticked off a list.
+ * Rendered as a `<button role="switch">` so the on/off state is announced as a
+ * switch rather than a checkbox, and so the track and knob can carry the brand
+ * fill without fighting a native input's styling hooks.
+ * @tokens bg-brand-primaryAction, bg-border-interactive, bg-surface, shadow-raised, outline-border-focus
+ * @behavior The knob is positioned by `translate-x`, not by flex alignment, so
+ * the slide animates. Off uses `bg-border-interactive` rather than a grey
+ * literal, which keeps the track visible against `bg-surface` in dark mode.
+ * Pair it with a label and any InfoTip in the surrounding row: this component
+ * draws only the switch, so rows stay free to lay the label out however they
+ * 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.
+ * @usage
+ * ```tsx
+ * <Toggle checked={enabled} onChange={setEnabled} label="Email news alerts" />
+ * <Toggle size="sm" checked={enabled} onChange={setEnabled} label="Only include enriched creatives" />
+ * ```
+ */
+declare function Toggle({ checked, onChange, label, size, disabled, className }: ToggleProps): react.JSX.Element;
+
+interface AISparkProps {
+    size?: number;
+    className?: string;
+}
+/**
+ * @pattern AISpark
+ * @description Assistant glyph — the lucide Sparkles icon stroked with the
+ * MR orange→violet assistant gradient. Each instance scopes its own gradient
+ * id, and the stops follow light/dark mode.
+ * @dependencies lucide-react
+ * @usage
+ * ```tsx
+ * <AISpark size={14} />
+ * ```
+ */
+declare function AISpark({ size, className }: AISparkProps): react.JSX.Element;
+
+type FreshnessLevel = "fresh" | "recent" | "stale";
+interface FreshnessProps {
+    level: FreshnessLevel;
+}
+/**
+ * @pattern Freshness
+ * @description Freshness dot — prefixed to card meta rows so a row of 4
+ * 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
+ * @usage
+ * ```tsx
+ * <Freshness level="fresh" />
+ * ```
+ */
+declare function Freshness({ level }: FreshnessProps): react.JSX.Element;
+
+export { AISpark, type AISparkProps, AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, type CheckBoxProps, ChipContent, type ChipContentProps, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, DateRangeFilter, type DateRangeFilterProps, DateRangePicker, type DateRangePickerProps, FilterChipBar, type FilterChipBarProps, FilterDropdownFooter, type FilterDropdownFooterProps, Freshness, type FreshnessLevel, type FreshnessProps, InfoTip, type InfoTipProps, LineChartPlaceholder, type LineChartPlaceholderProps, MultiSelectFilter, type MultiSelectFilterProps, type MultiSelectGroup, NO_RESULTS_BODY, NO_RESULTS_TITLE, NameListModal, type NameListModalProps, type NoResultsAction, NoResultsEmptyState, type NoResultsEmptyStateProps, PRIMARY_ACTION_CLASS, Pager, type PagerProps, 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, SortButton, type SortButtonProps, type SortDir, type SortState, StackedColumnPlaceholder, type StackedColumnPlaceholderProps, type SummaryGroup, type SummaryGroupItemValue, TablePagination, type TablePaginationProps, Tag, type TagProps, Toggle, type ToggleProps, Tooltip, type TooltipProps, WorkspaceAvatar, type WorkspaceAvatarProps, WorkspaceSelectedCard, type WorkspaceSelectedCardProps, buttonVariants, chipTriggerClass, cycleSort, noResultsBody, resolveRange, sortProp };