@mediaradar/design-components 0.19.0 → 0.20.0

package/dist/index.d.cts

@@ -1888,6 +1888,96 @@ interface WorkspaceAvatarProps {
  */
 declare function WorkspaceAvatar({ name, size }: WorkspaceAvatarProps): react.JSX.Element;
 
+type ToastTone = "neutral" | "success" | "warning";
+interface ToastProps {
+    /** What happened, in a short sentence. Past tense: "12 accounts removed". */
+    message: ReactNode;
+    /**
+     * One follow-up, usually Undo. Giving a toast an action extends how long it
+     * stays, since the reader now has to notice it, read it, decide and reach.
+     */
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+    /** Called when the toast has dismissed itself, or the action closed it. */
+    onClose: () => void;
+    /**
+     * Carried by a leading icon, never by the surface. The surface stays the
+     * same on every toast on purpose -- see @behavior.
+     */
+    tone?: ToastTone;
+    /**
+     * Override the duration. The defaults are 5s, or 10s when there is an
+     * action; both pause while hovered or focused. Set deliberately or not at
+     * all -- a one-off number here is how the product ended up with six.
+     */
+    duration?: number;
+    className?: string;
+}
+/**
+ * @pattern Toast
+ * @description Transient feedback about the page or the task: "12 accounts
+ * removed", "Export started". Floats at the bottom of the window so it never
+ * pushes the page around, dismisses itself, and may carry one action.
+ *
+ * It is one of three shapes of feedback, and the shape is the first decision:
+ * feedback about the control you just used stays ON it (a copy button's icon
+ * becoming a tick); feedback about the page or task floats, which is this;
+ * and feedback you have to act on before continuing stays inline where the
+ * action is, and does not dismiss.
+ * @props
+ * message: ReactNode
+ * action?: { label: string; onClick: () => void }
+ * onClose: () => void
+ * tone?: 'neutral' | 'success' | 'warning' (default 'neutral')
+ * duration?: number -- ms; defaults to 5000, or 10000 with an action
+ * @tokens bg-inverseSurface, text-text-inverse, text-text-inverseSuccess,
+ * text-text-inverseWarning, rounded-control, shadow-overlay,
+ * z-toast, duration-(--mr-motion-duration-interactive), ease-interactive,
+ * focus-visible:outline-border-focus
+ * @dependencies lucide-react
+ * @behavior The surface is the same on every toast. Tone is a leading icon in
+ * green or amber, not a colour wash: a toast already has the reader's attention because it
+ * appeared, so colouring the whole surface adds nothing and makes a failure
+ * read as an alarm. It also keeps one object rather than one per mood -- the
+ * product had a dark pill, a light pill and a green pill doing the same job.
+ *
+ * Timing is tied to whether there is an action, not set per call site. 5s
+ * reads comfortably; 10s is what an Undo needs, because the reader has to
+ * notice the toast, read it, decide and then reach for it. Both pause on
+ * hover and on keyboard focus, which is the real fix for the two toasts that
+ * previously never dismissed at all -- they were held open so an Undo could
+ * be caught, at the cost of a message that never left.
+ * @a11y role="status" with aria-live="polite", so it is announced without
+ * interrupting. The action is a real button inside the live region, reachable
+ * by keyboard; focusing it pauses the timer, so a keyboard user is never
+ * racing the dismissal. The icon is decorative -- the message carries the
+ * meaning, since tone shown only as an icon cannot be the sole signal.
+ * @variant neutral - Something happened. The default, and most toasts.
+ * @variant success - A thing completed that the reader was waiting on.
+ * @variant warning - It completed with something worth knowing. Not for failure -- a failure the reader must act on belongs inline, not in a message that leaves.
+ * @use when reporting something that already happened, that the reader does
+ * not have to act on.
+ * @use with an action when the thing is reversible and reversing it is cheap
+ * -- an Undo on a bulk delete.
+ * @avoid when the reader must act before continuing. A toast leaves; anything
+ * load-bearing belongs inline, next to what it is about.
+ * @avoid when the feedback is about the control just used. A copy button's
+ * tick belongs on the button, where the reader is already looking.
+ * @avoid for errors that lose work. An error that leaves after ten seconds is
+ * an error nobody can act on.
+ * @avoid stacking several at once. Toasts queue; two at the same time means
+ * the second is read and the first is not.
+ * @usage
+ * ```tsx
+ * <Toast message="Export started" onClose={clear} />
+ * <Toast message="12 accounts removed" action={{ label: 'Undo', onClick: undo }} onClose={clear} />
+ * <Toast tone="success" message="Account created" onClose={clear} />
+ * ```
+ */
+declare function Toast({ message, action, onClose, tone, duration, className }: ToastProps): react.ReactPortal;
+
 interface TagProps {
     /** The tag's text, e.g. "Digital". Keep it short: the chip doesn't wrap or truncate. */
     children: ReactNode;
@@ -2279,4 +2369,4 @@ interface PageHeaderProps {
  */
 declare function PageHeader({ title, description, actions, className }: PageHeaderProps): 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, 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, PageHeader, type PageHeaderProps, 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, SectionHeading, type SectionHeadingProps, 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, ariaSortFor, 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, PageHeader, type PageHeaderProps, 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, SectionHeading, type SectionHeadingProps, 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, Toast, type ToastProps, type ToastTone, Toggle, type ToggleProps, Tooltip, type TooltipProps, WorkspaceAvatar, type WorkspaceAvatarProps, WorkspaceSelectedCard, type WorkspaceSelectedCardProps, ariaSortFor, buttonVariants, chipTriggerClass, cycleSort, noResultsBody, resolveRange, sortProp };

package/dist/index.d.ts

@@ -1888,6 +1888,96 @@ interface WorkspaceAvatarProps {
  */
 declare function WorkspaceAvatar({ name, size }: WorkspaceAvatarProps): react.JSX.Element;
 
+type ToastTone = "neutral" | "success" | "warning";
+interface ToastProps {
+    /** What happened, in a short sentence. Past tense: "12 accounts removed". */
+    message: ReactNode;
+    /**
+     * One follow-up, usually Undo. Giving a toast an action extends how long it
+     * stays, since the reader now has to notice it, read it, decide and reach.
+     */
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+    /** Called when the toast has dismissed itself, or the action closed it. */
+    onClose: () => void;
+    /**
+     * Carried by a leading icon, never by the surface. The surface stays the
+     * same on every toast on purpose -- see @behavior.
+     */
+    tone?: ToastTone;
+    /**
+     * Override the duration. The defaults are 5s, or 10s when there is an
+     * action; both pause while hovered or focused. Set deliberately or not at
+     * all -- a one-off number here is how the product ended up with six.
+     */
+    duration?: number;
+    className?: string;
+}
+/**
+ * @pattern Toast
+ * @description Transient feedback about the page or the task: "12 accounts
+ * removed", "Export started". Floats at the bottom of the window so it never
+ * pushes the page around, dismisses itself, and may carry one action.
+ *
+ * It is one of three shapes of feedback, and the shape is the first decision:
+ * feedback about the control you just used stays ON it (a copy button's icon
+ * becoming a tick); feedback about the page or task floats, which is this;
+ * and feedback you have to act on before continuing stays inline where the
+ * action is, and does not dismiss.
+ * @props
+ * message: ReactNode
+ * action?: { label: string; onClick: () => void }
+ * onClose: () => void
+ * tone?: 'neutral' | 'success' | 'warning' (default 'neutral')
+ * duration?: number -- ms; defaults to 5000, or 10000 with an action
+ * @tokens bg-inverseSurface, text-text-inverse, text-text-inverseSuccess,
+ * text-text-inverseWarning, rounded-control, shadow-overlay,
+ * z-toast, duration-(--mr-motion-duration-interactive), ease-interactive,
+ * focus-visible:outline-border-focus
+ * @dependencies lucide-react
+ * @behavior The surface is the same on every toast. Tone is a leading icon in
+ * green or amber, not a colour wash: a toast already has the reader's attention because it
+ * appeared, so colouring the whole surface adds nothing and makes a failure
+ * read as an alarm. It also keeps one object rather than one per mood -- the
+ * product had a dark pill, a light pill and a green pill doing the same job.
+ *
+ * Timing is tied to whether there is an action, not set per call site. 5s
+ * reads comfortably; 10s is what an Undo needs, because the reader has to
+ * notice the toast, read it, decide and then reach for it. Both pause on
+ * hover and on keyboard focus, which is the real fix for the two toasts that
+ * previously never dismissed at all -- they were held open so an Undo could
+ * be caught, at the cost of a message that never left.
+ * @a11y role="status" with aria-live="polite", so it is announced without
+ * interrupting. The action is a real button inside the live region, reachable
+ * by keyboard; focusing it pauses the timer, so a keyboard user is never
+ * racing the dismissal. The icon is decorative -- the message carries the
+ * meaning, since tone shown only as an icon cannot be the sole signal.
+ * @variant neutral - Something happened. The default, and most toasts.
+ * @variant success - A thing completed that the reader was waiting on.
+ * @variant warning - It completed with something worth knowing. Not for failure -- a failure the reader must act on belongs inline, not in a message that leaves.
+ * @use when reporting something that already happened, that the reader does
+ * not have to act on.
+ * @use with an action when the thing is reversible and reversing it is cheap
+ * -- an Undo on a bulk delete.
+ * @avoid when the reader must act before continuing. A toast leaves; anything
+ * load-bearing belongs inline, next to what it is about.
+ * @avoid when the feedback is about the control just used. A copy button's
+ * tick belongs on the button, where the reader is already looking.
+ * @avoid for errors that lose work. An error that leaves after ten seconds is
+ * an error nobody can act on.
+ * @avoid stacking several at once. Toasts queue; two at the same time means
+ * the second is read and the first is not.
+ * @usage
+ * ```tsx
+ * <Toast message="Export started" onClose={clear} />
+ * <Toast message="12 accounts removed" action={{ label: 'Undo', onClick: undo }} onClose={clear} />
+ * <Toast tone="success" message="Account created" onClose={clear} />
+ * ```
+ */
+declare function Toast({ message, action, onClose, tone, duration, className }: ToastProps): react.ReactPortal;
+
 interface TagProps {
     /** The tag's text, e.g. "Digital". Keep it short: the chip doesn't wrap or truncate. */
     children: ReactNode;
@@ -2279,4 +2369,4 @@ interface PageHeaderProps {
  */
 declare function PageHeader({ title, description, actions, className }: PageHeaderProps): 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, 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, PageHeader, type PageHeaderProps, 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, SectionHeading, type SectionHeadingProps, 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, ariaSortFor, 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, PageHeader, type PageHeaderProps, 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, SectionHeading, type SectionHeadingProps, 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, Toast, type ToastProps, type ToastTone, Toggle, type ToggleProps, Tooltip, type TooltipProps, WorkspaceAvatar, type WorkspaceAvatarProps, WorkspaceSelectedCard, type WorkspaceSelectedCardProps, ariaSortFor, buttonVariants, chipTriggerClass, cycleSort, noResultsBody, resolveRange, sortProp };