@12-apps/ui 6.14.0 → 6.15.1

package/src/components/form/HeaderActions/HeaderActions.tsx

@@ -0,0 +1,134 @@
+'use client';
+
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import MoreHorizIcon from '@mui/icons-material/MoreHoriz';
+import Box from '@mui/material/Box/index.js';
+import ListItemIcon from '@mui/material/ListItemIcon/index.js';
+import ListItemText from '@mui/material/ListItemText/index.js';
+import Menu from '@mui/material/Menu/index.js';
+import MenuItem from '@mui/material/MenuItem/index.js';
+import React, { useState } from 'react';
+
+import { HeaderButton } from '../HeaderButton';
+import type { HeaderActionItem, HeaderActionsProps } from './HeaderActions.types';
+
+/** Drop the gated-away entries, so everything below can count what is left. */
+function present(
+  actions: HeaderActionsProps['actions'],
+): HeaderActionItem[] {
+  return actions.filter(
+    (action): action is HeaderActionItem => Boolean(action) && (action as HeaderActionItem).visible !== false,
+  );
+}
+
+/**
+ * The page header's actions, as ONE control that scales with how many there
+ * are: nothing, a button, or a button plus an overflow menu.
+ *
+ * | actions | renders |
+ * |---|---|
+ * | 0 | nothing at all — not an empty box, and not a menu with no items |
+ * | 1 | that action, as an ordinary `HeaderButton` |
+ * | n | the FIRST as a button; the other n−1 inside one dropdown |
+ *
+ * ## Why the first one stays a button
+ *
+ * A header whose every action lives behind a menu costs two clicks for the
+ * thing the page is FOR — "Novo produto" on a catalog, "Nova categoria" on the
+ * categories list. Folding it in with the exports and the reorder screens
+ * would treat a merchant's daily action as equal to the one they use monthly.
+ * So the array is in PRIORITY order and index 0 keeps its button; everything
+ * after it is secondary by the caller's own declaration.
+ *
+ * ## Why this takes a list and not children
+ *
+ * The 0/1/n decision is only decidable over data. A component handed JSX can
+ * count `React.Children`, but it cannot tell a gated-away action from an
+ * absent one, cannot read a label to put in a menu row, and cannot re-render
+ * a `<Button>` as a `<MenuItem>` without reaching into its props. Every
+ * caller in the estate had therefore hand-written the row, which is how four
+ * equally-weighted buttons ended up wrapping the line on a catalog page.
+ *
+ * ## One element, so the spacing is the component's and not the mount's
+ *
+ * It renders an `inline-flex` box rather than a fragment. A fragment inherits
+ * whatever gap its parent happens to set, and the two mounts here set
+ * different ones — a `Dashboard.Header` spaces its children, a
+ * `Dashboard.Action` slot does not, which is why the pair of buttons in that
+ * slot sat flush against each other. The gap belongs to the control.
+ *
+ * ## The ids survive the move
+ *
+ * An action that overflows keeps its `dataTestId` on its `MenuItem`. It is a
+ * different element in a different place, and it must still answer to the same
+ * selector: otherwise adding a fifth action to a header silently breaks the
+ * suite of the action that got pushed out, which is the last place anyone
+ * would look.
+ */
+export function HeaderActions({
+  actions,
+  moreLabel,
+  collapseBelow = 'md',
+  testIdPrefix = 'header-actions',
+}: HeaderActionsProps): React.JSX.Element | null {
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
+  const items = present(actions);
+  const open = Boolean(anchorEl);
+
+  // Before the early return would be a conditional hook; after it is the only
+  // legal place. Nothing below runs for an empty list anyway.
+  const [primary, ...overflow] = items;
+  if (!primary) return null;
+
+  return (
+    <Box sx={{ display: 'inline-flex', alignItems: 'center', gap: 1 }}>
+      <HeaderButton
+        text={primary.text}
+        icon={primary.icon}
+        onClick={primary.onClick}
+        disabled={primary.disabled}
+        variant={primary.variant}
+        color={primary.color}
+        collapseBelow={collapseBelow}
+        dataTestId={primary.dataTestId ?? primary.id}
+      />
+      {overflow.length > 0 && (
+        <>
+          <HeaderButton
+            text={moreLabel}
+            icon={<MoreHorizIcon fontSize="small" />}
+            endIcon={<ExpandMoreIcon fontSize="small" />}
+            onClick={(event) => setAnchorEl(event.currentTarget)}
+            collapseBelow={collapseBelow}
+            aria-haspopup="menu"
+            aria-expanded={open}
+            dataTestId={`${testIdPrefix}-more-trigger`}
+          />
+          <Menu
+            anchorEl={anchorEl}
+            open={open}
+            onClose={() => setAnchorEl(null)}
+            anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+            transformOrigin={{ vertical: 'top', horizontal: 'right' }}
+            data-testid={`${testIdPrefix}-more-menu`}
+          >
+            {overflow.map((action) => (
+              <MenuItem
+                key={action.id}
+                disabled={action.disabled}
+                onClick={() => {
+                  setAnchorEl(null);
+                  action.onClick?.();
+                }}
+                data-testid={action.dataTestId ?? action.id}
+              >
+                <ListItemIcon sx={{ minWidth: 32 }}>{action.icon}</ListItemIcon>
+                <ListItemText>{action.text}</ListItemText>
+              </MenuItem>
+            ))}
+          </Menu>
+        </>
+      )}
+    </Box>
+  );
+}

package/src/components/form/HeaderActions/HeaderActions.types.ts

@@ -0,0 +1,64 @@
+import type { ReactNode } from 'react';
+
+import type { HeaderButtonProps } from '../HeaderButton';
+
+/**
+ * One page-header action, declared as DATA rather than composed as an element.
+ *
+ * That is the whole point of the type. A header that composes its buttons as
+ * JSX can only ever render all of them, because nothing can count a fragment's
+ * children without walking React internals — so "three actions" and "seven
+ * actions" produce the same row, and the seventh button is what wraps the line
+ * on a laptop. A list can be measured, so the component can decide.
+ */
+export interface HeaderActionItem {
+  /**
+   * Stable identity. Used as the React key, and as the `data-testid` fallback
+   * so an action that MOVES into the overflow menu keeps the selector it had
+   * as a button — a suite driving it by id must not care where it ended up.
+   */
+  id: string;
+  /** The label. Shown beside the icon as a button; alone in the menu row. */
+  text: ReactNode;
+  /** Leading icon. Always visible as a button, and in the menu row. */
+  icon: ReactNode;
+  onClick?: () => void;
+  disabled?: boolean;
+  /**
+   * Drop this action entirely when false. Present so a caller can declare a
+   * permission- or plan-gated action inline, instead of building the array
+   * conditionally and losing the reason it is missing.
+   *
+   * @default true
+   */
+  visible?: boolean;
+  /** Overrides the `data-testid`, which otherwise falls back to {@link id}. */
+  dataTestId?: string;
+  /** MUI variant for the PRIMARY rendering. Ignored inside the menu. */
+  variant?: HeaderButtonProps['variant'];
+  /** MUI color for the PRIMARY rendering. Ignored inside the menu. */
+  color?: HeaderButtonProps['color'];
+}
+
+/** Props for {@link HeaderActions}. */
+export interface HeaderActionsProps {
+  /**
+   * The actions, in priority order — the first is the one that stays a button.
+   *
+   * `false`/`null`/`undefined` entries are dropped, so a caller can write
+   * `[edit, canDelete && del]` without pre-filtering.
+   */
+  actions: Array<HeaderActionItem | false | null | undefined>;
+  /**
+   * The overflow trigger's label, which is also its accessible name. REQUIRED:
+   * this package ships no copy of its own, in any language.
+   */
+  moreLabel: string;
+  /** Width below which every button collapses to icon-only. @default 'md' */
+  collapseBelow?: HeaderButtonProps['collapseBelow'];
+  /**
+   * Prefix for the overflow trigger's and menu's own test ids. The ACTIONS
+   * keep their own ids either way. @default 'header-actions'
+   */
+  testIdPrefix?: string;
+}

package/src/components/form/HeaderActions/index.ts

@@ -0,0 +1,2 @@
+export { HeaderActions } from './HeaderActions';
+export type { HeaderActionItem, HeaderActionsProps } from './HeaderActions.types';

package/src/components/form/Input/Input.styles.ts

@@ -3,6 +3,8 @@ import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 
 import type { InputProps } from './Input.types';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 type InputVariant = NonNullable<InputProps['variant']>;
 
 // Define pulse animation
@@ -90,7 +92,7 @@ export const inputBaseStyles = (theme: Theme, variant?: InputVariant): CSSObject
       return {
         backgroundColor: alpha(theme.palette.background.paper, 0.1),
         backdropFilter: 'blur(20px)',
-        border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+        border: `1px solid ${fieldEdge(theme)}`,
         '&:hover': {
           backgroundColor: alpha(theme.palette.background.paper, 0.15),
           borderColor: alpha(theme.palette.primary.main, 0.3),
@@ -104,7 +106,7 @@ export const inputBaseStyles = (theme: Theme, variant?: InputVariant): CSSObject
     case 'underline':
       return {
         '&:before': {
-          borderBottomColor: alpha(theme.palette.divider, 0.42),
+          borderBottomColor: fieldEdge(theme),
         },
         '&:hover:not(.Mui-disabled):before': {
           borderBottomColor: theme.palette.primary.main,
@@ -155,7 +157,7 @@ const gradientStyles = (theme: Theme): CSSObject => ({
 
 export const outlinedStyles = (theme: Theme): CSSObject => ({
   '& fieldset': {
-    borderColor: alpha(theme.palette.divider, 0.23),
+    borderColor: fieldEdge(theme),
   },
   '&:hover fieldset': {
     borderColor: theme.palette.primary.main,

package/src/components/form/InputOTP/InputOTP.styles.ts

@@ -1,6 +1,8 @@
 import { alpha } from '@mui/material/styles/index.js';
 import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 interface ColorPalette {
   main: string;
   dark?: string;
@@ -82,7 +84,7 @@ export const otpSlotSx = (theme: Theme, flags: OtpSlotFlags): CSSObject => {
       ...(glass && {
         backgroundColor: alpha(theme.palette.background.paper, 0.1),
         backdropFilter: 'blur(20px)',
-        '& fieldset': { border: `1px solid ${alpha(theme.palette.divider, 0.2)}` },
+        '& fieldset': { border: `1px solid ${fieldEdge(theme)}` },
       }),
       ...(gradient && {
         '&.Mui-focused fieldset': {

package/src/components/form/PhoneInput/PhoneInput.tsx

@@ -17,6 +17,8 @@ import { usePhoneInput } from './PhoneInput.hooks';
 import type { CountryData,PhoneInputProps } from './PhoneInput.types';
 import type { PhoneInputCopy } from '../../../copy';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 // Country data with expanded support
 
 // Styled components
@@ -25,7 +27,7 @@ const GlassTextField = styled(TextField)(({ theme }) => ({
     background: `linear-gradient(135deg, ${alpha(theme.palette.background.paper, 0.8)} 0%, ${alpha(theme.palette.background.paper, 0.6)} 100%)`,
     backdropFilter: 'blur(10px)',
     WebkitBackdropFilter: 'blur(10px)',
-    border: `1px solid ${alpha(theme.palette.divider, 0.18)}`,
+    border: `1px solid ${fieldEdge(theme)}`,
     transition: theme.transitions.create(['border-color', 'box-shadow', 'background']),
     '&:hover': {
       background: `linear-gradient(135deg, ${alpha(theme.palette.background.paper, 0.9)} 0%, ${alpha(theme.palette.background.paper, 0.7)} 100%)`,

package/src/components/form/RadioGroup/RadioGroup.styles.ts

@@ -3,6 +3,8 @@ import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 
 import { glowAnimation, rippleAnimation, scaleAnimation, slideAnimation } from './RadioGroup.animations';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 interface ColorPalette {
   main: string;
   dark?: string;
@@ -119,7 +121,7 @@ const cardBase = (theme: Theme, flags: SurfaceFlags, palette: ColorPalette): CSS
   return {
     cursor: 'pointer',
     transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
-    border: `2px solid ${selected ? palette.main : alpha(theme.palette.divider, 0.3)}`,
+    border: `2px solid ${selected ? palette.main : fieldEdge(theme)}`,
     backgroundColor: selected ? alpha(palette.main, 0.05) : theme.palette.background.paper,
     position: 'relative' as const,
     overflow: 'hidden' as const,
@@ -183,7 +185,7 @@ const buttonBase = (theme: Theme, flags: SurfaceFlags, palette: ColorPalette): C
     borderRadius: theme.spacing(1),
     transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
     fontWeight: 500,
-    border: `2px solid ${selected ? palette.main : alpha(theme.palette.divider, 0.5)}`,
+    border: `2px solid ${selected ? palette.main : fieldEdge(theme)}`,
     backgroundColor: selected ? palette.main : 'transparent',
     color: selected ? palette.contrastText || '#fff' : theme.palette.text.primary,
     position: 'relative' as const,

package/src/components/form/RichTextEditor/RichTextEditor.tsx

@@ -8,6 +8,8 @@ import { useRichTextEditor } from './RichTextEditor.hooks';
 import type { RichTextEditorProps, ToolbarConfig } from './RichTextEditor.types';
 import { RichTextEditorToolbar } from './RichTextEditorToolbar';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 const DEFAULT_TOOLBAR: Required<Omit<ToolbarConfig, 'customItems'>> & Pick<ToolbarConfig, 'customItems'> = {
   bold: true,
   italic: true,
@@ -68,7 +70,7 @@ const editorContentSx = (theme: Theme, disabled: boolean, placeholder?: string,
   '& a': { color: theme.palette.primary.main, textDecoration: 'underline' } });
 
 const shellSx = (theme: Theme, isFocused: boolean, disabled: boolean) => ({
-  border: `1px solid ${alpha(theme.palette.divider, 0.12)}`,
+  border: `1px solid ${fieldEdge(theme)}`,
   borderRadius: 1,
   overflow: 'hidden',
   transition: 'border-color 0.2s ease-in-out',

package/src/components/form/Select/Select.tsx

@@ -8,6 +8,8 @@ import React from 'react';
 
 import type { SelectProps } from './Select.types';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 // Define pulse animation
 const pulseAnimation = keyframes`
   0% {
@@ -57,7 +59,7 @@ const pulseStyles = (theme: Theme): CSSObject => ({
 const glassVariant = (theme: Theme): CSSObject => ({
   backgroundColor: alpha(theme.palette.background.paper, 0.1),
   backdropFilter: 'blur(20px)',
-  border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+  border: `1px solid ${fieldEdge(theme)}`,
   '& fieldset': { border: 'none' },
   '&:hover': {
     backgroundColor: alpha(theme.palette.background.paper, 0.15),
@@ -105,7 +107,7 @@ const gradientVariant = (theme: Theme): CSSObject => ({
 
 /** `default` variant: standard outlined borders with hover/focus/error states. */
 const defaultVariant = (theme: Theme): CSSObject => ({
-  '& fieldset': { borderColor: alpha(theme.palette.divider, 0.23) },
+  '& fieldset': { borderColor: fieldEdge(theme) },
   '&:hover fieldset': { borderColor: theme.palette.primary.main },
   '&.Mui-focused fieldset': { borderColor: theme.palette.primary.main, borderWidth: 2 },
   '&.Mui-error fieldset': { borderColor: theme.palette.error.main },

package/src/components/form/Textarea/Textarea.styles.ts

@@ -1,6 +1,8 @@
 import { alpha, keyframes } from '@mui/material/styles/index.js';
 import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 const glowAnimation = keyframes`
   0% {
     box-shadow: 0 0 5px currentColor;
@@ -107,7 +109,7 @@ const glassStyles = glass
   ? {
       backgroundColor: alpha(theme.palette.background.paper, 0.1),
       backdropFilter: 'blur(20px)',
-      border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+      border: `1px solid ${fieldEdge(theme)}`,
       '&:hover': {
         backgroundColor: alpha(theme.palette.background.paper, 0.15),
         backdropFilter: 'blur(25px)',

package/src/components/form/Textarea/Textarea.tsx

@@ -30,6 +30,8 @@ const TextareaRichEditor = lazy(async () => ({
   default: (await import('./TextareaRichEditor')).TextareaRichEditor }));
 import type { TextareaProps } from './Textarea.types';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 // Interface for styled component props
 interface StyledTextareaProps {
   customVariant?: string;
@@ -71,7 +73,7 @@ const StyledTextarea = styled(TextareaAutosize, {
     width: '100%',
     fontFamily: theme.typography.fontFamily,
     borderRadius: theme.spacing(1),
-    border: `2px solid ${error ? errorColor.main : theme.palette.divider}`,
+    border: `2px solid ${error ? errorColor.main : fieldEdge(theme)}`,
     backgroundColor: theme.palette.background.paper,
     color: theme.palette.text.primary,
     transition: 'all 0.3s ease',
@@ -108,7 +110,7 @@ const StyledLabel = styled(InputLabel, {
     backdropFilter: 'blur(10px)',
     padding: '4px 8px',
     borderRadius: '4px',
-    border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+    border: `1px solid ${fieldEdge(theme)}`,
     display: 'inline-block' }) }));
 
 // IconWrapper - replaced with inline Box component for better TypeScript compatibility

package/src/components/form/Textarea/TextareaRichEditor.tsx

@@ -19,6 +19,8 @@ import React, { useEffect, useRef, useState } from 'react';
 import { floatAnimation, getColorFromTheme } from './Textarea.styles';
 import type { RichEditorToolbarCopy } from '../../../copy';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 const RichToolbar = styled(Box)<{ glass?: boolean }>(({ theme, glass }) => ({
   display: 'flex',
   alignItems: 'center',
@@ -104,7 +106,7 @@ const ContentEditableDiv = styled('div')<{
     minHeight: '120px',
     padding: theme.spacing(1.5),
     borderRadius: `0 0 ${theme.spacing(1)} ${theme.spacing(1)}`,
-    border: `2px solid ${error ? errorColor.main : focused ? colorPalette.main : theme.palette.divider}`,
+    border: `2px solid ${error ? errorColor.main : focused ? colorPalette.main : fieldEdge(theme)}`,
     borderTop: 'none',
     backgroundColor: glass
       ? alpha(theme.palette.background.paper, 0.1)

package/src/components/form/Toggle/Toggle.styles.ts

@@ -1,6 +1,8 @@
 import { alpha, keyframes } from '@mui/material/styles/index.js';
 import type { CSSObject, PaletteColor, Theme } from '@mui/material/styles/index.js';
 
+import { fieldEdge } from '../../../tokens/field-edge';
+
 const glowAnimation = keyframes`
   0% { box-shadow: 0 0 5px currentColor; }
   50% { box-shadow: 0 0 15px currentColor, 0 0 25px currentColor; }
@@ -74,7 +76,7 @@ export const baseStyles = (
   fontWeight: 500,
   borderRadius: theme.spacing(1),
   transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
-  border: `2px solid ${alpha(theme.palette.divider, 0.3)}`,
+  border: `2px solid ${fieldEdge(theme)}`,
   color: theme.palette.text.primary,
   backgroundColor: 'transparent',
   position: 'relative',

package/src/components/layout/Dashboard/Dashboard.md

@@ -27,7 +27,13 @@ import { Dashboard } from '@12-apps/ui/layout/Dashboard';
     <Dashboard.Settings title="Product settings">In development</Dashboard.Settings>
     <Dashboard.Spacer />
     <Dashboard.Export onExport={(id) => exportAs(id)} />
-    <Dashboard.Action><Button variant="contained">New product</Button></Dashboard.Action>
+    <Dashboard.Actions
+      moreLabel={copy.moreActions}
+      actions={[
+        { id: 'new-product', text: 'New product', icon: <AddIcon fontSize="small" />, onClick: onCreate },
+        { id: 'import', text: 'Import sheet', icon: <UploadIcon fontSize="small" />, onClick: onImport },
+      ]}
+    />
   </Dashboard.Header>
   <Dashboard.Filters>
     <SearchInput />
@@ -51,7 +57,8 @@ import { Dashboard } from '@12-apps/ui/layout/Dashboard';
 | `Dashboard.Settings` | (in header) | Gear icon. Default: opens a dialog with `children`. With `href` (+ optional `linkComponent`): renders as a link to a settings route (e.g. the page's Configuração section) — no dialog. |
 | `Dashboard.Export` | (in header) | Export dropdown (CSV/Excel/JSON by default); calls `onExport(id)`. |
 | `Dashboard.Spacer` | (in header) | Pushes following controls to the right edge. |
-| `Dashboard.Action` | (in header) | Slot for a primary/secondary button. |
+| `Dashboard.Action` | (in header) | Slot for ONE header control that is not an action — a link, a toggle, a status pill. |
+| `Dashboard.Actions` | (in header) | The header's actions declared as a list. 0 renders nothing, 1 renders a button, n renders the first as a button and the other n−1 in a dropdown. See [HeaderActions](../../form/HeaderActions/HeaderActions.md). |
 | `Dashboard.Filters` | filters | Collapsible search/filter region; visibility driven by `FilterToggle`. |
 | `Dashboard.MoreFilters` | (in filters) | Expandable advanced panel for ranges/dates. |
 | `Dashboard.Body` | body | Main content area (the table/grid). |

package/src/components/layout/Dashboard/Dashboard.tsx

@@ -16,6 +16,7 @@ import React, { useMemo, useState } from 'react';
 import { DashboardContext, useDashboardContext } from './DashboardContext';
 import {
   DashboardAction,
+  DashboardActions,
   DashboardExport,
   DashboardFilterToggle,
   DashboardInfo,
@@ -309,6 +310,7 @@ Dashboard.FilterToggle = DashboardFilterToggle;
 Dashboard.Settings = DashboardSettings;
 Dashboard.Export = DashboardExport;
 Dashboard.Action = DashboardAction;
+Dashboard.Actions = DashboardActions;
 Dashboard.Filters = DashboardFilters;
 Dashboard.MoreFilters = DashboardMoreFilters;
 Dashboard.Body = DashboardBody;

package/src/components/layout/Dashboard/Dashboard.types.ts

@@ -1,5 +1,7 @@
 import type { ElementType, ReactNode } from 'react';
 
+import type { HeaderActionsProps } from '../../form/HeaderActions';
+
 /** A single breadcrumb entry for `<Dashboard.Breadcrumb>`. */
 export interface DashboardBreadcrumbItem {
   /** Visible label. */
@@ -139,6 +141,16 @@ export interface DashboardActionProps {
   children: ReactNode;
 }
 
+/**
+ * Props for `<Dashboard.Actions>` — the header's actions DECLARED, rather than
+ * composed one `<Dashboard.Action>` at a time.
+ *
+ * `testIdPrefix` is not among them: the Dashboard already has one, from its
+ * root, and letting the part carry a second would give one page two answers to
+ * "what is this header called".
+ */
+export type DashboardActionsProps = Omit<HeaderActionsProps, 'testIdPrefix'>;
+
 /** Props for `<Dashboard.Filters>` — the collapsible search/filter region. */
 export interface DashboardFiltersProps {
   /** Filter controls (search input, pills, `<Dashboard.MoreFilters>`, …). */

package/src/components/layout/Dashboard/DashboardParts.tsx

@@ -19,10 +19,12 @@ import Tooltip from '@mui/material/Tooltip/index.js';
 import Typography from '@mui/material/Typography/index.js';
 import React, { useState } from 'react';
 
+import { HeaderActions } from '../../form/HeaderActions';
 import { HeaderButton } from '../../form/HeaderButton';
 import { useDashboardContext } from './DashboardContext';
 import type {
   DashboardActionProps,
+  DashboardActionsProps,
   DashboardExportFormat,
   DashboardExportProps,
   DashboardFilterToggleProps,
@@ -206,3 +208,37 @@ export const DashboardAction = ({ children }: DashboardActionProps): React.JSX.E
   <Box sx={{ display: 'inline-flex' }}>{children}</Box>
 );
 DashboardAction.displayName = 'Dashboard.Action';
+
+/**
+ * The header's actions, declared as a LIST — `<Dashboard.Action>`'s plural.
+ *
+ * `<Dashboard.Action>` is a slot: it renders whatever you hand it, once per
+ * action, and a page with five of them draws five equally-loud buttons. That is
+ * the right primitive for one button and the wrong one for five, and the pages
+ * here that grew a fifth action all grew it the same way — by adding a fifth
+ * slot, because the slot was the only thing on offer.
+ *
+ * This part answers the question the slot cannot: given N actions, how many
+ * belong on the bar? See {@link HeaderActions} for the rule (0 ⇒ nothing,
+ * 1 ⇒ a button, n ⇒ a button and a menu of the rest).
+ *
+ * Both stay. A header still composes `<Dashboard.Action>` for the one control
+ * that is not an action at all — a link, a toggle, a status pill — and reaches
+ * for this when it has actions to rank.
+ */
+export const DashboardActions = ({
+  actions,
+  moreLabel,
+  collapseBelow,
+}: DashboardActionsProps): React.JSX.Element => {
+  const { testIdPrefix } = useDashboardContext();
+  return (
+    <HeaderActions
+      actions={actions}
+      moreLabel={moreLabel}
+      collapseBelow={collapseBelow}
+      testIdPrefix={`${testIdPrefix}-actions`}
+    />
+  );
+};
+DashboardActions.displayName = 'Dashboard.Actions';

package/src/components/layout/Dashboard/index.ts

@@ -4,6 +4,7 @@ export { DashboardContext, useDashboardContext } from './DashboardContext';
 export type { DashboardContextValue } from './DashboardContext';
 export type {
   DashboardActionProps,
+  DashboardActionsProps,
   DashboardBodyProps,
   DashboardBreadcrumbItem,
   DashboardBreadcrumbProps,