@12-apps/ui 6.13.2 → 6.15.0

package/src/components/data-display/DataViews/data-views-selection-extra.ts

@@ -0,0 +1,67 @@
+/**
+ * The selection-WIDENING slot: what a paginated grid needs so an operator can
+ * act on "everything matching the filter" rather than on the page in front of
+ * them.
+ *
+ * It is a slot of its own rather than a share of the bulk-actions menu because
+ * the two answer different questions — `actions` is what HAPPENS to the
+ * selection, this is what the selection IS. Folding a widening into the actions
+ * menu files "change what I picked" under "do this to what I picked", where
+ * every entry is expected to write something.
+ */
+import type { DataViewsController } from "./use-data-views-state";
+
+/**
+ * What a widening control gets to decide with.
+ *
+ * `allOnPageSelected` is the one thing a host cannot compute for itself, and
+ * the whole reason this is a context rather than a bare node: the grid owns
+ * which rows the page is currently rendering — server mode pages at the
+ * backend, so the host's `rows` prop and the page can differ mid-fetch — and
+ * "every row here is ticked" is the trigger a select-all-matching control
+ * hangs on. Deriving it host-side would be a second, slightly different answer
+ * to the question the grid already answers to draw its own header checkbox.
+ */
+export interface SelectionExtraContext<T extends Record<string, unknown>> {
+  /** The selected rows, off-page ones included. */
+  selectedRows: T[];
+  /** Drop the whole selection. */
+  clearSelection: () => void;
+  /** Every row the page is rendering is selected — and the page is not empty. */
+  allOnPageSelected: boolean;
+  /** How many rows the page is rendering. */
+  pageRowCount: number;
+}
+
+/** The host's widening control, called only while something is selected. */
+export type SelectionExtraRender<T extends Record<string, unknown>> = (
+  context: SelectionExtraContext<T>,
+) => React.ReactNode;
+
+/**
+ * Resolve the host's control against the page on screen.
+ *
+ * Measured against `c.matched` — which in server mode IS the page — rather than
+ * the `rows` prop, so the answer cannot lag a page change.
+ *
+ * Returns `undefined` with nothing selected, so the toolbar renders no empty
+ * slot: a widening with nothing to widen is not a control.
+ */
+export function resolveSelectionExtra<T extends Record<string, unknown>>({
+  c,
+  getRowId,
+  selectionExtra,
+}: {
+  c: DataViewsController<T>;
+  getRowId: (row: T) => string | number;
+  selectionExtra?: SelectionExtraRender<T>;
+}): React.ReactNode {
+  if (selectionExtra === undefined || c.selectedRows.length === 0) return undefined;
+  const page = c.matched;
+  return selectionExtra({
+    selectedRows: c.selectedRows,
+    clearSelection: c.clearSelection,
+    allOnPageSelected: page.length > 0 && page.every((row) => c.selectedIds.has(getRowId(row))),
+    pageRowCount: page.length,
+  });
+}

package/src/components/data-display/DataViews/data-views-shell-toolbar.tsx

@@ -22,6 +22,7 @@ export function ShellToolbar<T extends Record<string, unknown>>({
   testIdPrefix,
   rowActions,
   bulkActions,
+  selectionExtra,
   toolbarRightSlot,
   showInline,
   compactControls,
@@ -40,6 +41,8 @@ export function ShellToolbar<T extends Record<string, unknown>>({
   exportConfig?: DataViewExport;
   rowActions?: RowAction<T>[];
   bulkActions?: (selectedRows: T[], clearSelection: () => void) => React.ReactNode;
+  /** Already resolved by the shell, which is the party that knows the page. */
+  selectionExtra?: React.ReactNode;
   toolbarRightSlot?: React.ReactNode;
   /** Search + filters, rendered on the toolbar line (see `GridToolbar`). */
   filterControls?: React.ReactNode;
@@ -71,6 +74,7 @@ export function ShellToolbar<T extends Record<string, unknown>>({
       clearSelection={c.clearSelection}
       rowActions={rowActions}
       bulkActions={bulkActions}
+      selectionExtra={selectionExtra}
       sortFields={c.resolvedSortFields}
       activeSortField={c.activeSortField}
       activeSortOrder={c.activeSortOrder}

package/src/components/data-display/DataViews/data-views-toolbar.tsx

@@ -25,6 +25,8 @@ export interface GridToolbarProps<T extends Record<string, unknown>> {
   clearSelection: () => void;
   rowActions?: RowAction<T>[];
   bulkActions?: (selectedRows: T[], clearSelection: () => void) => React.ReactNode;
+  /** A control between the count and the actions menu — see `selectionExtra`. */
+  selectionExtra?: React.ReactNode;
   sortFields: SortFieldDefinition[];
   activeSortField: string;
   activeSortOrder: "asc" | "desc";
@@ -161,6 +163,7 @@ export function GridToolbar<T extends Record<string, unknown>>(props: GridToolba
         clearSelection={props.clearSelection}
         selectAllTestId={`${testIdPrefix}-select-all`}
         clearAllTestId={`${testIdPrefix}-clear-all`}
+        selectionExtra={props.selectionExtra}
         actions={renderBulkActions({
           rowActions: props.rowActions,
           bulkActions: props.bulkActions,

package/src/components/data-display/DataViews/index.ts

@@ -45,6 +45,7 @@ export type {
   DataViewExportFormat,
   DataViewExportRequest,
 } from "./data-views-export";
+export type { SelectionExtraContext, SelectionExtraRender } from "./data-views-selection-extra";
 export {
   DataViewsScopeTabs,
   resolveScope,

package/src/components/form/HeaderActions/HeaderActions.md

@@ -0,0 +1,72 @@
+# HeaderActions
+
+The page header's actions as ONE control, sized to how many there are.
+
+```tsx
+import { HeaderActions } from '@12-apps/ui/form/HeaderActions';
+
+<HeaderActions
+  moreLabel={copy.moreActions}
+  actions={[
+    { id: 'new-product', text: 'Novo produto', icon: <AddIcon fontSize="small" />, onClick: onCreate },
+    { id: 'order-highlights', text: 'Ordenar destaques', icon: <ListIcon fontSize="small" />, onClick: onOrder },
+    { id: 'export-sheet', text: 'Exportar planilha', icon: <DownloadIcon fontSize="small" />, onClick: onExport },
+    canImport && { id: 'import-sheet', text: 'Importar planilha', icon: <UploadIcon fontSize="small" />, onClick: onImport },
+  ]}
+/>
+```
+
+| 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 |
+
+## The array is in priority order
+
+Index 0 is the action that keeps its button, so the order you declare is the
+ranking you get. Put the thing the page is FOR first — "Novo produto" on a
+catalog — and everything the merchant reaches for monthly after it.
+
+## Falsy entries are dropped
+
+`[edit, canDelete && del]` is a legal array, and so is
+`{ …, visible: false }`. Both mean the same thing and both keep the gate at the
+call site, where a reader can see WHY an action is missing, instead of in an
+array built somewhere above.
+
+## Test ids survive the overflow
+
+An action that moves into the menu keeps its `dataTestId` (falling back to its
+`id`) on the `MenuItem`. Adding a fifth action to a header must not silently
+break the suite of the action it pushed out.
+
+The overflow trigger and its menu take their ids from `testIdPrefix`
+(`header-actions` by default): `…-more-trigger` and `…-more-menu`.
+
+## It brings its own spacing
+
+The component renders one `inline-flex` box, not a fragment. A fragment inherits
+whatever gap its parent sets, and the two mounts set different ones — a
+`Dashboard.Header` spaces its children, a `Dashboard.Action` slot does not.
+
+## Copy
+
+`moreLabel` is REQUIRED and has no default. This package ships no words of its
+own, in any language — the label is also the trigger's accessible name, so a
+default would be read out to a screen-reader user in the wrong language.
+
+## Inside a Dashboard
+
+`<Dashboard.Actions>` is the same component wired to the Dashboard's own
+`testIdPrefix`; prefer it when the header is a `<Dashboard.Header>`.
+
+```tsx
+<Dashboard.Header title="Produtos">
+  <Dashboard.Spacer />
+  <Dashboard.Actions moreLabel={copy.moreActions} actions={actions} />
+</Dashboard.Header>
+```
+
+`<Dashboard.Action>` (singular) stays for the one header control that is not an
+action at all — a link, a toggle, a status pill.

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/layout/ContentToolbar/ContentToolbar.md

@@ -8,12 +8,19 @@ pages and projects.
 ## Anatomy
 
 ```
-[Select All] [Clear All] | N items selected  <actions>      (o)══  ▦▾   Sort By: … ▾   Content Type: … ▾   ⨏
-└──────────────── left cluster (selection chrome) ─────┘     └──────────── rightControls slot ────────────┘
+[Select All] [Clear All] | N selected  <selectionExtra> <actions>   (o)══  ▦▾   Sort By: … ▾   ⨏
+└─────────────────── left cluster (selection chrome) ──────────────┘   └───── rightControls slot ─────┘
 ```
 
 - **Left cluster** — always shows **Select All**. Once `hasSelection` is true it
-  adds **Clear All**, an "N items selected" count, and an optional `actions` slot.
+  adds **Clear All**, an "N items selected" count, and two optional slots:
+  `selectionExtra` then `actions`.
+- **`selectionExtra` vs `actions`** — `actions` is what HAPPENS to the selection
+  (delete, export, send). `selectionExtra` is what the selection IS: the
+  "select all N matching the filter" widening a paginated list needs once its
+  whole page is ticked. They are separate slots because an operator reasonably
+  expects every entry in an actions menu to write something, and a widening
+  writes nothing.
 - **Right cluster** — a free `rightControls` node. Compose it from the shipped
   controls below (or anything else).
 

package/src/components/layout/ContentToolbar/ContentToolbar.tsx

@@ -28,6 +28,7 @@ type SelectionClusterProps = Pick<
   | 'selectAll'
   | 'clearSelection'
   | 'actions'
+  | 'selectionExtra'
   | 'selectAllTestId'
   | 'clearAllTestId'
   | 'edgeAlign'
@@ -43,6 +44,7 @@ function SelectionCluster({
   selectAll,
   clearSelection,
   actions,
+  selectionExtra,
   selectAllTestId,
   clearAllTestId,
   edgeAlign = false,
@@ -106,6 +108,7 @@ function SelectionCluster({
           >
             {selectedCount} {selectedCount === 1 ? 'item' : 'items'} selected
           </Typography>
+          {selectionExtra}
           {actionsSlot}
         </>
       ) : (
@@ -219,6 +222,7 @@ export function ContentToolbar({
   rightControls,
   leadingControls,
   actions,
+  selectionExtra,
   selectAllTestId,
   clearAllTestId,
   edgeAlign = false,
@@ -258,6 +262,7 @@ export function ContentToolbar({
           selectAll={selectAll}
           clearSelection={clearSelection}
           actions={actions}
+          selectionExtra={selectionExtra}
           selectAllTestId={selectAllTestId}
           clearAllTestId={clearAllTestId}
           selectAllLabel={selectAllLabel}

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

@@ -45,6 +45,21 @@ export interface ContentToolbarProps {
    * what the action does.
    */
   actions?: ReactNode;
+  /**
+   * A control rendered between the count and {@link actions}, and ONLY while
+   * something is selected.
+   *
+   * It is a second slot rather than more room in `actions` because the two
+   * answer different questions. `actions` is what HAPPENS to the selection;
+   * this is what the selection IS — the "select all 143 matching" widening
+   * that a paginated grid needs once its whole page is ticked. Folding a
+   * widening control into the actions menu would file "change what I picked"
+   * under "do this to what I picked", where an operator reasonably expects
+   * every entry to write something.
+   *
+   * Ignored when nothing is selected: a widening has nothing to widen.
+   */
+  selectionExtra?: ReactNode;
   /** Test id for the Select All button. */
   selectAllTestId?: string;
   /** Test id for the Clear All button. */

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,

package/dist/chunk-2WWKBD4D.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/layout/ContentToolbar/ContentToolbar.tsx"],"sourcesContent":["'use client';\n\nimport Box from '@mui/material/Box/index.js';\nimport Button from '@mui/material/Button/index.js';\nimport Checkbox from '@mui/material/Checkbox/index.js';\nimport Divider from '@mui/material/Divider/index.js';\nimport Typography from '@mui/material/Typography/index.js';\nimport React from 'react';\n\nimport type { ContentToolbarProps } from './ContentToolbar.types';\n\nconst selectionButtonSx = {\n  minWidth: 0,\n  height: 'auto',\n  borderRadius: 0.5,\n  fontWeight: 600,\n  py: 0.5,\n  px: 1.5,\n  fontSize: '0.75rem',\n  textTransform: 'none',\n  color: 'text.primary',\n} as const;\n\ntype SelectionClusterProps = Pick<\n  ContentToolbarProps,\n  | 'hasSelection'\n  | 'selectedCount'\n  | 'selectAll'\n  | 'clearSelection'\n  | 'actions'\n  | 'selectAllTestId'\n  | 'clearAllTestId'\n  | 'edgeAlign'\n  | 'selectAllLabel'\n  | 'selectAllText'\n  | 'clearAllText'\n>;\n\n/** The left cluster: Select All + (when selecting) Clear All / count / actions. */\nfunction SelectionCluster({\n  hasSelection,\n  selectedCount,\n  selectAll,\n  clearSelection,\n  actions,\n  selectAllTestId,\n  clearAllTestId,\n  edgeAlign = false,\n  selectAllLabel,\n  selectAllText,\n  clearAllText,\n}: SelectionClusterProps): React.JSX.Element {\n  const actionsSlot = actions !== undefined && (\n    <Box sx={{ ml: 0.5, display: 'flex', flexShrink: 0, alignItems: 'center' }}>{actions}</Box>\n  );\n  return (\n    <Box\n      sx={{\n        display: 'flex',\n        minWidth: 0,\n        // Mobile: don't grow, so the controls sit on the SAME line as the checkbox\n        // (no orphaned selection row). Desktop: grow to push controls right.\n        flex: { xs: '0 0 auto', md: 1 },\n        alignItems: 'center',\n        gap: 1.5,\n        ml: edgeAlign ? -1.5 : 0,\n      }}\n    >\n      {/* Desktop: a \"Select All\" text button (md+). Mobile: a compact checkbox\n          that toggles select-all/clear — the text would eat the tight row. */}\n      <Button\n        variant=\"text\"\n        size=\"small\"\n        color=\"inherit\"\n        onClick={selectAll}\n        data-testid={selectAllTestId}\n        sx={{ ...selectionButtonSx, display: { xs: 'none', md: 'inline-flex' } }}\n      >\n        {selectAllText}\n      </Button>\n      <Checkbox\n        size=\"small\"\n        checked={hasSelection}\n        onChange={(event) => (event.target.checked ? selectAll() : clearSelection())}\n        data-testid={`${selectAllTestId}-checkbox`}\n        inputProps={{ 'aria-label': selectAllLabel }}\n        sx={{ p: 0.5, display: { xs: 'inline-flex', md: 'none' } }}\n      />\n      {hasSelection ? (\n        <>\n          <Button\n            variant=\"text\"\n            size=\"small\"\n            color=\"inherit\"\n            onClick={clearSelection}\n            data-testid={clearAllTestId}\n            sx={selectionButtonSx}\n          >\n            {clearAllText}\n          </Button>\n          <Divider orientation=\"vertical\" flexItem sx={{ height: 16, alignSelf: 'center' }} />\n          <Typography\n            component=\"span\"\n            data-testid=\"selected-count-indicator\"\n            sx={{ fontSize: '0.875rem', color: 'text.secondary', whiteSpace: 'nowrap', flexShrink: 0 }}\n          >\n            {selectedCount} {selectedCount === 1 ? 'item' : 'items'} selected\n          </Typography>\n          {actionsSlot}\n        </>\n      ) : (\n        actionsSlot\n      )}\n    </Box>\n  );\n}\n\n/**\n * The BROWSING half of the toolbar: search + filters on the left, the page's\n * own controls on the right. Split out of {@link ContentToolbar} so that\n * function stays inside the complexity gate — it is layout only, and the\n * decision of whether to show it at all is made by the caller.\n */\nfunction BrowsingClusters({\n  leadingControls,\n  rightControls,\n  hasSelection,\n  edgeAlign,\n}: {\n  leadingControls?: React.ReactNode;\n  rightControls: React.ReactNode;\n  hasSelection: boolean;\n  edgeAlign: boolean;\n}): React.JSX.Element {\n  return (\n    <>\n      {/* minWidth:0 lets this cluster be the one that gives up width as the row\n       * tightens, which is what the filter overflow measures against. */}\n      {leadingControls !== undefined && (\n        <Box\n          sx={{\n            display: 'flex',\n            alignItems: 'center',\n            flexGrow: 1,\n            minWidth: 0,\n            // The collapse ladder has a FLOOR — below roughly 400px even the\n            // fully-collapsed row does not fit, and its controls cannot shrink\n            // (they are flexShrink:0 so an over-packed row sheds instead of\n            // squeezing). Past that point this scrolls rather than letting them\n            // paint outside the toolbar, which is what a narrow phone did.\n            overflowX: 'auto',\n            // No scrollbar gutter stealing height on the common case.\n            scrollbarWidth: 'thin',\n          }}\n        >\n          {leadingControls}\n        </Box>\n      )}\n      {/* ml:auto keeps the controls right-aligned even when the cluster wraps to\n       * its own row (where justify-content:space-between would otherwise snap a\n       * lone item to the left); it's a no-op on a shared row. */}\n      <Box\n        sx={{\n          display: 'flex',\n          alignItems: 'center',\n          // Same single-line rule as the row itself: this cluster wrapping\n          // INTERNALLY buys a second line just as surely as the row wrapping\n          // does. It bit at exactly 900px, the `md` breakpoint where the \"N de\n          // N\" counter appears and pushes Exibir/Exportar over the edge.\n          flexWrap: leadingControls === undefined ? 'wrap' : 'nowrap',\n          // Tight (5px) when browsing so the controls fit one line beside the\n          // checkbox; roomier (14px) in selection mode where they get their own row.\n          gap: hasSelection ? '14px' : '5px',\n          ml: 'auto',\n          mr: edgeAlign ? -1.5 : 0,\n          '& > *': { flexShrink: 0 },\n        }}\n      >\n        {rightControls}\n      </Box>\n    </>\n  );\n}\n\n/**\n * Shared toolbar for content pages (Favorites, Personal Space, Recents, …). The\n * left cluster owns selection chrome — **Select All**, and once items are\n * selected, **Clear All** + an \"N items selected\" count + an optional `actions`\n * slot. The right cluster is a free `rightControls` slot for page-specific\n * controls (ViewSelector, SortByDropdown, MultiSelectDropdown, FilterTrigger).\n *\n * Faithful, generic MUI port of the reference `ContentPageToolbar` — the\n * domain-specific default actions are intentionally left to the consumer via\n * the `actions` slot so this stays agnostic and reusable across projects.\n *\n * @example\n * ```tsx\n * <ContentToolbar\n *   hasSelection={selected.size > 0}\n *   selectedCount={selected.size}\n *   selectAll={selectAll}\n *   clearSelection={clear}\n *   rightControls={\n *     <>\n *       <ViewSelector viewMode={view} onViewModeChange={setView} zoom={zoom} onZoomChange={setZoom} />\n *       <SortByDropdown fields={FIELDS} activeField={field} onFieldChange={setField} />\n *       <MultiSelectDropdown label=\"Content Type\" options={types} selected={typeSet} onToggle={toggle} onClear={clear} />\n *       <FilterTrigger open={panelOpen} onOpenChange={setPanelOpen} hasActiveFilters={hasFilters} />\n *     </>\n *   }\n * />\n * ```\n */\nexport function ContentToolbar({\n  hasSelection,\n  selectedCount,\n  selectAll,\n  clearSelection,\n  rightControls,\n  leadingControls,\n  actions,\n  selectAllTestId,\n  clearAllTestId,\n  edgeAlign = false,\n  exclusiveSelection = false,\n  selectAllLabel,\n  selectAllText,\n  clearAllText,\n}: ContentToolbarProps): React.JSX.Element {\n  // Under `exclusiveSelection` the two states are alternatives, not neighbours:\n  // browsing shows the controls and no checkbox, selecting shows the checkbox\n  // and no controls. Anything else double-books the row.\n  const showSelection = !exclusiveSelection || hasSelection;\n  const showControls = !exclusiveSelection || !hasSelection;\n  return (\n    // Two clusters on one line. They may wrap onto separate rows ONLY for a\n    // toolbar without `leadingControls` — one carrying search + filters is\n    // driven by a measured collapse ladder (see `useFilterOverflow`), and a\n    // wrap there is the ladder having failed: it would silently buy a second\n    // row instead of shedding a control into \"Mais\", which is the one outcome\n    // the ladder exists to prevent.\n    <Box\n      sx={{\n        display: 'flex',\n        alignItems: 'center',\n        justifyContent: 'space-between',\n        gap: 2,\n        flexWrap: leadingControls === undefined ? 'wrap' : 'nowrap',\n        rowGap: 1,\n      }}\n    >\n      {showSelection && (\n        <SelectionCluster\n          selectAllText={selectAllText}\n          clearAllText={clearAllText}\n          hasSelection={hasSelection}\n          selectedCount={selectedCount}\n          selectAll={selectAll}\n          clearSelection={clearSelection}\n          actions={actions}\n          selectAllTestId={selectAllTestId}\n          clearAllTestId={clearAllTestId}\n          selectAllLabel={selectAllLabel}\n          edgeAlign={edgeAlign}\n        />\n      )}\n\n      {showControls && (\n        <BrowsingClusters\n          leadingControls={leadingControls}\n          rightControls={rightControls}\n          hasSelection={hasSelection}\n          edgeAlign={edgeAlign}\n        />\n      )}\n    </Box>\n  );\n}\n"],"mappings":"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","names":[]}