@mediaradar/design-components 0.14.0 → 0.16.0

package/dist/index.d.cts

@@ -229,6 +229,60 @@ interface BadgeProps {
  */
 declare function Badge({ tone, kind, dot, children, className }: BadgeProps): react.JSX.Element;
 
+interface DeltaProps {
+    /** The change itself. Its sign picks the direction; render the absolute value. */
+    value: number;
+    /** What the number is in -- "%" for a percentage, "pts" for share points. */
+    suffix?: string;
+    /**
+     * Adds a direction arrow before the number. For a column of deltas scanned
+     * rather than read, where the arrow is what the eye follows. A single delta
+     * beside a figure does not need one -- the sign already says which way.
+     */
+    arrow?: boolean;
+    /** Appended after the suffix, e.g. "YoY". Keep it to one or two words. */
+    period?: string;
+    className?: string;
+}
+/**
+ * @pattern Delta
+ * @description A change over time -- the +6.2% / -2.1% beside a figure. Green
+ * up, red down, always with an explicit sign.
+ * @props
+ * value: number -- sign picks the direction
+ * suffix?: string -- "%" or "pts"
+ * arrow?: boolean (default false) -- direction arrow, for a column scanned rather than read
+ * period?: string -- e.g. "YoY"
+ * @tokens text-text-success, text-text-danger
+ * @dependencies lucide-react
+ * @behavior Takes the type size of whatever contains it rather than setting
+ * its own, because it is inline text inside a table cell or a card rather
+ * than a box of its own -- a fixed size would fight the density its table
+ * already chose.
+ * @a11y The sign is the point: colour alone cannot carry direction, for
+ * anyone who cannot distinguish the two and for anyone reading it printed or
+ * in greyscale. `+` and `-` are always rendered, so the colour is
+ * reinforcement rather than the only signal. The arrow is decorative and
+ * hidden, since the sign beside it already says the same thing.
+ * @use when showing a change against a previous period beside the figure it
+ * relates to.
+ * @use with `arrow` when deltas run down a column and the reader is scanning
+ * for the ones that moved.
+ * @avoid when the number is not a change -- a share, a total or a rate is
+ * just a number, and colouring it green or red tells the reader something
+ * untrue about it.
+ * @avoid when up is not good. Green-for-up reads as green-for-better, so a
+ * rising cost or a rising error rate needs its own treatment rather than this
+ * one inverted, which nobody will notice.
+ * @usage
+ * ```tsx
+ * <Delta value={6.2} suffix="%" />
+ * <Delta value={-2.1} suffix="%" period="YoY" />
+ * <Delta value={1.4} suffix="pts" arrow />
+ * ```
+ */
+declare function Delta({ value, suffix, arrow, period, className }: DeltaProps): react.JSX.Element;
+
 /**
  * @pattern CheckBox
  * @description Tri-state checkbox rendered as a `<button>` (not a native
@@ -978,18 +1032,29 @@ declare function StackedColumnPlaceholder({ height, width, legendRows, axis, }:
  * 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
+ * text-text-primary, bg-text-primary, text-surface,
+ * duration-(--mr-motion-duration-interactive)
  * @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
+ * without a pointer) after `delay` ms (0 = immediate, the default). Fades in
+ * and out (opacity, `ease-in-out`, over the sys
+ * `--mr-motion-duration-interactive` token -- 200ms today); the bubble stays
+ * mounted through the fade-out and is removed from the DOM once it ends.
+ * Under `prefers-reduced-motion: reduce` there is no fade: it appears and is
+ * removed instantly. The hide starts 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. Re-hovering (or re-focusing) the trigger while the
+ * bubble is still fading out reverses the fade from where it is, without
+ * waiting out `delay` again, since it is already on screen; so does moving
+ * the pointer back into an `interactive` bubble. A non-interactive bubble is
+ * `pointer-events-none` throughout, fade-out included, so it never
+ * intercepts clicks meant for what sits under it. 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,
@@ -1398,31 +1463,46 @@ interface PublisherBreakdownListProps {
 declare function PublisherBreakdownList({ rows, defaultVisibleCount, padded, viewAllHref, renderLogo }: PublisherBreakdownListProps): react.JSX.Element;
 
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "danger" | "primary" | "secondary" | "ghost" | null | undefined;
-    size?: "icon" | "sm" | "md" | "lg" | null | undefined;
+    variant?: "link" | "danger" | "primary" | "secondary" | "ghost" | "dangerGhost" | null | undefined;
+    size?: "xs" | "sm" | "md" | null | undefined;
+    iconOnly?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
-    /** Render the button styling onto the single child element instead of a `<button>` (e.g. a router `<Link>`). */
+    /**
+     * Render the button styling onto the single child element instead of a
+     * `<button>` (e.g. a router `<Link>` or an `<a>`). The child must be exactly
+     * one React element; it keeps its own tag, content and semantics.
+     */
     asChild?: boolean;
-    /** Shows a spinner in place of the leading edge and disables the button. */
+    /**
+     * Shows a spinner in place of the leading edge and disables the button.
+     * With `asChild` there is no spinner (the child owns its content, and a
+     * spinner belongs inside a real `<button>`): `loading` only sets
+     * `aria-busy` and forwards `disabled` to the child, which only has an
+     * effect on elements that support it -- an `<a>` stays clickable, so block
+     * navigation yourself while loading.
+     */
     loading?: boolean;
     /** Button label and/or icon. With `asChild`, the single element that receives the button styling. */
     children?: ReactNode;
 }
 /**
  * @pattern Button
- * @description Primary interactive control for actions. Five visual variants
- * (primary, secondary, ghost, danger, link) and four sizes (sm, md, lg, icon).
+ * @description The one control for every clickable action, from the main call
+ * to action on a screen down to a quiet toolbar utility. Six variants
+ * (primary, secondary, ghost, danger, dangerGhost, link) across three sizes
+ * (xs, sm, md), labelled or icon-only.
  * Supports polymorphic rendering via `asChild` (Radix Slot) to apply button
  * styling to a different element, e.g. a router `<Link>`. Also exports the
  * raw `buttonVariants` cva function for consumers composing button styling
  * onto something other than this component.
- * @tokens bg-brand-primaryAction, text-brand-onprimary, bg-surface, text-text-primary, border-border-interactive, hover:bg-subtle, bg-status-danger, text-status-onstatus, text-text-link, rounded-control, duration-(--mr-motion-duration-interactive), ease-interactive
+ * @tokens bg-brand-primaryAction, text-brand-onprimary, bg-surface, text-text-primary, border-border-strong, hover:border-border-interactive, hover:bg-subtle, bg-status-danger, text-status-onstatus, text-text-secondary, hover:text-text-danger, text-text-link, rounded-control, duration-(--mr-motion-duration-interactive), ease-interactive
  * @dependencies class-variance-authority, @radix-ui/react-slot, lucide-react
  * @variant primary - The one primary action on a screen. Solid brand fill.
  * @variant secondary - Any other real action competing for attention (Cancel, Export). Bordered, neutral fill.
  * @variant ghost - Low-emphasis action inside a dense toolbar or row where a border would add visual noise.
- * @variant danger - Destructive/irreversible actions (Delete, Remove). Never pair with `primary` in the same control group.
+ * @variant danger - Filled red. Only for a confirmed destructive action, typically the confirm button in a dialog. Never pair with `primary` in the same control group.
+ * @variant dangerGhost - Neutral at rest, red on hover. For a destructive affordance inline in a row or toolbar -- what the product reaches for far more often than filled danger.
  * @variant link - Reads as inline text, not a control. Use inside body copy or where a full button would overpower the surrounding content.
  * @behavior `disabled` removes pointer events entirely (not just a style
  * change) and dims to 40% opacity. Focus handling is a deliberate exception:
@@ -1430,16 +1510,42 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
  * but Button suppresses it (`focus-visible:outline-hidden focus-visible:ring-0`)
  * and relies on its per-variant hover/brightness treatment instead. `loading`
  * implies `disabled` (and sets `aria-busy`), since a control mid-submit
- * shouldn't accept another click.
- * @a11y Renders a native <button>, so it keeps native keyboard behaviour.
+ * shouldn't accept another click. `asChild` renders only the child element,
+ * through Radix `Slot`, with the button classes, ref and remaining props
+ * merged onto it -- no wrapping `<button>`. With `asChild`, `loading` draws
+ * no spinner; it sets `aria-busy` and forwards `disabled`, which an `<a>`
+ * ignores, so a loading link stays clickable unless the caller blocks it.
+ * @a11y Renders a native <button>, so it keeps native keyboard behaviour
+ * (with `asChild`, the child element's own semantics apply instead).
  * `loading` sets aria-busy, and the spinner is aria-hidden. Icon-only
  * usage needs an aria-label from the caller -- nothing here supplies one.
+ * @use when the user is triggering an action in place -- saving, applying,
+ * confirming, opening a dialog, running an export.
+ * @use when you need a destructive affordance: dangerGhost inline in a row or
+ * toolbar, danger only as the confirm button in a dialog already opened.
+ * @use when an action sits inside a sentence -- variant="link", which drops
+ * the box and the semibold weight so it does not read as emphasis.
+ * @use when the action is icon-only in a dense toolbar -- iconOnly squares the
+ * box at whichever size you picked, so it lines up with labelled buttons
+ * beside it. Supply an aria-label; nothing here does.
+ * @avoid when the control navigates to a different route -- render a real link
+ * via asChild, so middle-click, right-click and open-in-new-tab keep working.
+ * variant="link" styles a button as text; it does not make a button a link.
+ * @avoid when there is already a primary on the screen -- a second primary
+ * means neither reads as the main action. Use secondary or ghost.
+ * @avoid when the control toggles a persistent on/off state -- use CheckBox or
+ * a switch. A button fires; it does not hold a state.
+ * @avoid when you are about to hand-roll a button with raw classes. There is
+ * no case this does not cover, and every copy is a divergence in hover, focus,
+ * disabled and loading behaviour at once.
  * @usage
  * ```tsx
  * <Button variant="primary" size="md">Save changes</Button>
+ * <Button variant="dangerGhost" size="sm" iconOnly aria-label="Remove row"><X size={15} /></Button>
  * <Button variant="secondary" size="sm">Cancel</Button>
  * <Button variant="danger">Delete</Button>
  * <Button variant="primary" loading>Saving…</Button>
+ * <Button asChild variant="secondary"><a href="/reports">View reports</a></Button>
  * ```
  */
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
@@ -1720,11 +1826,24 @@ interface TagProps {
 }
 /**
  * @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
+ * @description Canonical descriptive tag -- a neutral chip naming what a
+ * thing IS: a category, a media type, a focus area. Always neutral, never
+ * semantic, never removable.
+ *
+ * The product separates three jobs that most systems collapse into one, by
+ * who authored the label. Badge is the system's view of a thing (status,
+ * count, AI-generated) and its colour means something. Tag is the thing
+ * describing itself, and stays neutral. FilterChipBar is the user describing
+ * what they want to see, and is the only one you can remove.
+ * @use when labelling what something is -- a category, a media type, a focus
+ * area, a property of the row rather than a judgement about it.
+ * @avoid when the colour would mean something. A status, a count, an
+ * AI marker or anything the system decided is a Badge.
+ * @avoid when the user should be able to dismiss it. An applied filter is a
+ * FilterChipBar chip, which belongs to the filter bar rather than to the row.
+ * @avoid when there are more than a handful in a row. Tags are scanned, and a
+ * dozen neutral chips read as texture rather than as information.
+ * @tokens text-micro, bg-subtle, text-text-tertiary, rounded-full
  * @usage
  * ```tsx
  * <Tag>Digital</Tag>
@@ -1986,4 +2105,4 @@ interface FreshnessProps {
  */
 declare function Freshness({ level }: FreshnessProps): react.JSX.Element;
 
-export { AISpark, type AISparkProps, AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, Badge, type BadgeKind, type BadgeProps, type BadgeTone, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, CheckBoxBox, type CheckBoxBoxProps, type CheckBoxProps, ChipContent, type ChipContentProps, type ChipVariant, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, type DateGranularity, 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 };
+export { AISpark, type AISparkProps, AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, Badge, type BadgeKind, type BadgeProps, type BadgeTone, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, CheckBoxBox, type CheckBoxBoxProps, type CheckBoxProps, ChipContent, type ChipContentProps, type ChipVariant, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, type DateGranularity, DateRangeFilter, type DateRangeFilterProps, DateRangePicker, type DateRangePickerProps, Delta, type DeltaProps, 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

@@ -229,6 +229,60 @@ interface BadgeProps {
  */
 declare function Badge({ tone, kind, dot, children, className }: BadgeProps): react.JSX.Element;
 
+interface DeltaProps {
+    /** The change itself. Its sign picks the direction; render the absolute value. */
+    value: number;
+    /** What the number is in -- "%" for a percentage, "pts" for share points. */
+    suffix?: string;
+    /**
+     * Adds a direction arrow before the number. For a column of deltas scanned
+     * rather than read, where the arrow is what the eye follows. A single delta
+     * beside a figure does not need one -- the sign already says which way.
+     */
+    arrow?: boolean;
+    /** Appended after the suffix, e.g. "YoY". Keep it to one or two words. */
+    period?: string;
+    className?: string;
+}
+/**
+ * @pattern Delta
+ * @description A change over time -- the +6.2% / -2.1% beside a figure. Green
+ * up, red down, always with an explicit sign.
+ * @props
+ * value: number -- sign picks the direction
+ * suffix?: string -- "%" or "pts"
+ * arrow?: boolean (default false) -- direction arrow, for a column scanned rather than read
+ * period?: string -- e.g. "YoY"
+ * @tokens text-text-success, text-text-danger
+ * @dependencies lucide-react
+ * @behavior Takes the type size of whatever contains it rather than setting
+ * its own, because it is inline text inside a table cell or a card rather
+ * than a box of its own -- a fixed size would fight the density its table
+ * already chose.
+ * @a11y The sign is the point: colour alone cannot carry direction, for
+ * anyone who cannot distinguish the two and for anyone reading it printed or
+ * in greyscale. `+` and `-` are always rendered, so the colour is
+ * reinforcement rather than the only signal. The arrow is decorative and
+ * hidden, since the sign beside it already says the same thing.
+ * @use when showing a change against a previous period beside the figure it
+ * relates to.
+ * @use with `arrow` when deltas run down a column and the reader is scanning
+ * for the ones that moved.
+ * @avoid when the number is not a change -- a share, a total or a rate is
+ * just a number, and colouring it green or red tells the reader something
+ * untrue about it.
+ * @avoid when up is not good. Green-for-up reads as green-for-better, so a
+ * rising cost or a rising error rate needs its own treatment rather than this
+ * one inverted, which nobody will notice.
+ * @usage
+ * ```tsx
+ * <Delta value={6.2} suffix="%" />
+ * <Delta value={-2.1} suffix="%" period="YoY" />
+ * <Delta value={1.4} suffix="pts" arrow />
+ * ```
+ */
+declare function Delta({ value, suffix, arrow, period, className }: DeltaProps): react.JSX.Element;
+
 /**
  * @pattern CheckBox
  * @description Tri-state checkbox rendered as a `<button>` (not a native
@@ -978,18 +1032,29 @@ declare function StackedColumnPlaceholder({ height, width, legendRows, axis, }:
  * 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
+ * text-text-primary, bg-text-primary, text-surface,
+ * duration-(--mr-motion-duration-interactive)
  * @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
+ * without a pointer) after `delay` ms (0 = immediate, the default). Fades in
+ * and out (opacity, `ease-in-out`, over the sys
+ * `--mr-motion-duration-interactive` token -- 200ms today); the bubble stays
+ * mounted through the fade-out and is removed from the DOM once it ends.
+ * Under `prefers-reduced-motion: reduce` there is no fade: it appears and is
+ * removed instantly. The hide starts 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. Re-hovering (or re-focusing) the trigger while the
+ * bubble is still fading out reverses the fade from where it is, without
+ * waiting out `delay` again, since it is already on screen; so does moving
+ * the pointer back into an `interactive` bubble. A non-interactive bubble is
+ * `pointer-events-none` throughout, fade-out included, so it never
+ * intercepts clicks meant for what sits under it. 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,
@@ -1398,31 +1463,46 @@ interface PublisherBreakdownListProps {
 declare function PublisherBreakdownList({ rows, defaultVisibleCount, padded, viewAllHref, renderLogo }: PublisherBreakdownListProps): react.JSX.Element;
 
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "danger" | "primary" | "secondary" | "ghost" | null | undefined;
-    size?: "icon" | "sm" | "md" | "lg" | null | undefined;
+    variant?: "link" | "danger" | "primary" | "secondary" | "ghost" | "dangerGhost" | null | undefined;
+    size?: "xs" | "sm" | "md" | null | undefined;
+    iconOnly?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
-    /** Render the button styling onto the single child element instead of a `<button>` (e.g. a router `<Link>`). */
+    /**
+     * Render the button styling onto the single child element instead of a
+     * `<button>` (e.g. a router `<Link>` or an `<a>`). The child must be exactly
+     * one React element; it keeps its own tag, content and semantics.
+     */
     asChild?: boolean;
-    /** Shows a spinner in place of the leading edge and disables the button. */
+    /**
+     * Shows a spinner in place of the leading edge and disables the button.
+     * With `asChild` there is no spinner (the child owns its content, and a
+     * spinner belongs inside a real `<button>`): `loading` only sets
+     * `aria-busy` and forwards `disabled` to the child, which only has an
+     * effect on elements that support it -- an `<a>` stays clickable, so block
+     * navigation yourself while loading.
+     */
     loading?: boolean;
     /** Button label and/or icon. With `asChild`, the single element that receives the button styling. */
     children?: ReactNode;
 }
 /**
  * @pattern Button
- * @description Primary interactive control for actions. Five visual variants
- * (primary, secondary, ghost, danger, link) and four sizes (sm, md, lg, icon).
+ * @description The one control for every clickable action, from the main call
+ * to action on a screen down to a quiet toolbar utility. Six variants
+ * (primary, secondary, ghost, danger, dangerGhost, link) across three sizes
+ * (xs, sm, md), labelled or icon-only.
  * Supports polymorphic rendering via `asChild` (Radix Slot) to apply button
  * styling to a different element, e.g. a router `<Link>`. Also exports the
  * raw `buttonVariants` cva function for consumers composing button styling
  * onto something other than this component.
- * @tokens bg-brand-primaryAction, text-brand-onprimary, bg-surface, text-text-primary, border-border-interactive, hover:bg-subtle, bg-status-danger, text-status-onstatus, text-text-link, rounded-control, duration-(--mr-motion-duration-interactive), ease-interactive
+ * @tokens bg-brand-primaryAction, text-brand-onprimary, bg-surface, text-text-primary, border-border-strong, hover:border-border-interactive, hover:bg-subtle, bg-status-danger, text-status-onstatus, text-text-secondary, hover:text-text-danger, text-text-link, rounded-control, duration-(--mr-motion-duration-interactive), ease-interactive
  * @dependencies class-variance-authority, @radix-ui/react-slot, lucide-react
  * @variant primary - The one primary action on a screen. Solid brand fill.
  * @variant secondary - Any other real action competing for attention (Cancel, Export). Bordered, neutral fill.
  * @variant ghost - Low-emphasis action inside a dense toolbar or row where a border would add visual noise.
- * @variant danger - Destructive/irreversible actions (Delete, Remove). Never pair with `primary` in the same control group.
+ * @variant danger - Filled red. Only for a confirmed destructive action, typically the confirm button in a dialog. Never pair with `primary` in the same control group.
+ * @variant dangerGhost - Neutral at rest, red on hover. For a destructive affordance inline in a row or toolbar -- what the product reaches for far more often than filled danger.
  * @variant link - Reads as inline text, not a control. Use inside body copy or where a full button would overpower the surrounding content.
  * @behavior `disabled` removes pointer events entirely (not just a style
  * change) and dims to 40% opacity. Focus handling is a deliberate exception:
@@ -1430,16 +1510,42 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
  * but Button suppresses it (`focus-visible:outline-hidden focus-visible:ring-0`)
  * and relies on its per-variant hover/brightness treatment instead. `loading`
  * implies `disabled` (and sets `aria-busy`), since a control mid-submit
- * shouldn't accept another click.
- * @a11y Renders a native <button>, so it keeps native keyboard behaviour.
+ * shouldn't accept another click. `asChild` renders only the child element,
+ * through Radix `Slot`, with the button classes, ref and remaining props
+ * merged onto it -- no wrapping `<button>`. With `asChild`, `loading` draws
+ * no spinner; it sets `aria-busy` and forwards `disabled`, which an `<a>`
+ * ignores, so a loading link stays clickable unless the caller blocks it.
+ * @a11y Renders a native <button>, so it keeps native keyboard behaviour
+ * (with `asChild`, the child element's own semantics apply instead).
  * `loading` sets aria-busy, and the spinner is aria-hidden. Icon-only
  * usage needs an aria-label from the caller -- nothing here supplies one.
+ * @use when the user is triggering an action in place -- saving, applying,
+ * confirming, opening a dialog, running an export.
+ * @use when you need a destructive affordance: dangerGhost inline in a row or
+ * toolbar, danger only as the confirm button in a dialog already opened.
+ * @use when an action sits inside a sentence -- variant="link", which drops
+ * the box and the semibold weight so it does not read as emphasis.
+ * @use when the action is icon-only in a dense toolbar -- iconOnly squares the
+ * box at whichever size you picked, so it lines up with labelled buttons
+ * beside it. Supply an aria-label; nothing here does.
+ * @avoid when the control navigates to a different route -- render a real link
+ * via asChild, so middle-click, right-click and open-in-new-tab keep working.
+ * variant="link" styles a button as text; it does not make a button a link.
+ * @avoid when there is already a primary on the screen -- a second primary
+ * means neither reads as the main action. Use secondary or ghost.
+ * @avoid when the control toggles a persistent on/off state -- use CheckBox or
+ * a switch. A button fires; it does not hold a state.
+ * @avoid when you are about to hand-roll a button with raw classes. There is
+ * no case this does not cover, and every copy is a divergence in hover, focus,
+ * disabled and loading behaviour at once.
  * @usage
  * ```tsx
  * <Button variant="primary" size="md">Save changes</Button>
+ * <Button variant="dangerGhost" size="sm" iconOnly aria-label="Remove row"><X size={15} /></Button>
  * <Button variant="secondary" size="sm">Cancel</Button>
  * <Button variant="danger">Delete</Button>
  * <Button variant="primary" loading>Saving…</Button>
+ * <Button asChild variant="secondary"><a href="/reports">View reports</a></Button>
  * ```
  */
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
@@ -1720,11 +1826,24 @@ interface TagProps {
 }
 /**
  * @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
+ * @description Canonical descriptive tag -- a neutral chip naming what a
+ * thing IS: a category, a media type, a focus area. Always neutral, never
+ * semantic, never removable.
+ *
+ * The product separates three jobs that most systems collapse into one, by
+ * who authored the label. Badge is the system's view of a thing (status,
+ * count, AI-generated) and its colour means something. Tag is the thing
+ * describing itself, and stays neutral. FilterChipBar is the user describing
+ * what they want to see, and is the only one you can remove.
+ * @use when labelling what something is -- a category, a media type, a focus
+ * area, a property of the row rather than a judgement about it.
+ * @avoid when the colour would mean something. A status, a count, an
+ * AI marker or anything the system decided is a Badge.
+ * @avoid when the user should be able to dismiss it. An applied filter is a
+ * FilterChipBar chip, which belongs to the filter bar rather than to the row.
+ * @avoid when there are more than a handful in a row. Tags are scanned, and a
+ * dozen neutral chips read as texture rather than as information.
+ * @tokens text-micro, bg-subtle, text-text-tertiary, rounded-full
  * @usage
  * ```tsx
  * <Tag>Digital</Tag>
@@ -1986,4 +2105,4 @@ interface FreshnessProps {
  */
 declare function Freshness({ level }: FreshnessProps): react.JSX.Element;
 
-export { AISpark, type AISparkProps, AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, Badge, type BadgeKind, type BadgeProps, type BadgeTone, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, CheckBoxBox, type CheckBoxBoxProps, type CheckBoxProps, ChipContent, type ChipContentProps, type ChipVariant, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, type DateGranularity, 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 };
+export { AISpark, type AISparkProps, AdvertiserNoResults, type AdvertiserNoResultsProps, AdvertiserQuickFilter, type AdvertiserQuickFilterProps, AdvertiserSearchPrompt, type AdvertiserSearchPromptProps, Badge, type BadgeKind, type BadgeProps, type BadgeTone, BarChartPlaceholder, type BarChartPlaceholderProps, Button, type ButtonProps, Card, type CardProps, CheckBox, CheckBoxBox, type CheckBoxBoxProps, type CheckBoxProps, ChipContent, type ChipContentProps, type ChipVariant, DEFAULT_SEARCH_MATCH, DataScopeFilter, type DataScopeFilterProps, type DateGranularity, DateRangeFilter, type DateRangeFilterProps, DateRangePicker, type DateRangePickerProps, Delta, type DeltaProps, 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 };