@12-apps/ui 1.0.0 → 1.3.0

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { KeyboardArrowDown as ChevronDownIcon, Search as SearchIcon } from '@mui/icons-material';
+import SearchIcon from '@mui/icons-material/Search';
 import {
   Box,
   Button,
@@ -11,7 +11,6 @@ import {
   Menu,
   MenuItem,
   TextField,
-  Typography,
 } from '@mui/material';
 import React, { useMemo, useState } from 'react';
 
@@ -20,25 +19,7 @@ import type {
   MultiSelectExtraOption,
   MultiSelectOption,
 } from './ContentToolbar.types';
-
-/**
- * Trigger label from the current selection: `allLabel` when none/all are
- * selected, the single label when one, else "first (+N)". Uses Set iteration
- * order so the label reflects the first-clicked option.
- */
-function buildTriggerLabel<TValue extends string>(
-  selected: ReadonlySet<TValue>,
-  options: MultiSelectOption<TValue>[],
-  allLabel: string,
-): string {
-  const size = selected.size;
-  if (size === 0 || size === options.length) return allLabel;
-  const labelMap = new Map(options.map((option) => [option.value, option.label]));
-  const firstValue = selected.values().next().value as TValue;
-  const firstLabel = labelMap.get(firstValue) ?? allLabel;
-  if (size === 1) return firstLabel;
-  return `${firstLabel} (+${size - 1})`;
-}
+import { buildTriggerLabel, InlineTrigger, PillTrigger, StackedTrigger } from './MultiSelectTriggers';
 
 /** One checkbox menu row with an optional trailing count. */
 function CheckboxRow({
@@ -84,11 +65,13 @@ export function MultiSelectDropdown<TValue extends string = string>({
   searchable,
   searchPlaceholder = 'Search…',
   noResultsLabel = 'No results',
+  layout = 'inline',
   'data-testid': testId,
 }: MultiSelectDropdownProps<TValue>): React.JSX.Element {
   const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
   const [query, setQuery] = useState('');
   const open = Boolean(anchorEl);
+  const stacked = layout === 'stacked';
   // Reset the query each time the menu closes so it reopens showing everything.
   const close = (): void => {
     setAnchorEl(null);
@@ -100,24 +83,18 @@ export function MultiSelectDropdown<TValue extends string = string>({
   const anyExtraChecked = extraOptions?.some((option) => option.checked) ?? false;
   const clearDisabled = selected.size === 0 && !anyExtraChecked;
 
+  const openMenu = (event: React.MouseEvent<HTMLElement>): void => setAnchorEl(event.currentTarget);
+  const triggerProps = { triggerLabel, open, onOpen: openMenu, testId };
+
+  const renderTrigger = (): React.JSX.Element => {
+    if (stacked) return <StackedTrigger label={label} {...triggerProps} />;
+    if (layout === 'pill') return <PillTrigger label={label} selectedCount={selected.size} {...triggerProps} />;
+    return <InlineTrigger label={label} {...triggerProps} />;
+  };
+
   return (
-    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1, fontSize: '0.875rem' }}>
-      <Typography component="span" sx={{ color: 'text.secondary', fontSize: '0.875rem' }}>
-        {label}:
-      </Typography>
-      <Button
-        variant="text"
-        size="small"
-        color="inherit"
-        data-testid={testId}
-        aria-haspopup="menu"
-        aria-expanded={open}
-        onClick={(event) => setAnchorEl(event.currentTarget)}
-        sx={{ minWidth: 0, height: 32, px: 1, gap: 0.5, color: 'text.primary', textTransform: 'none', fontWeight: 600 }}
-      >
-        {triggerLabel}
-        <ChevronDownIcon sx={{ fontSize: 14 }} />
-      </Button>
+    <>
+      {renderTrigger()}
       <MultiSelectMenu
         anchorEl={anchorEl}
         open={open}
@@ -133,9 +110,10 @@ export function MultiSelectDropdown<TValue extends string = string>({
         onQueryChange={setQuery}
         searchPlaceholder={searchPlaceholder}
         noResultsLabel={noResultsLabel}
+        matchAnchorWidth={stacked}
         testId={testId}
       />
-    </Box>
+    </>
   );
 }
 
@@ -191,9 +169,24 @@ interface MultiSelectMenuProps<TValue extends string> {
   onQueryChange: (value: string) => void;
   searchPlaceholder: string;
   noResultsLabel: string;
+  /** Match the menu width to the trigger and left-align it (stacked select). */
+  matchAnchorWidth?: boolean;
   testId?: string;
 }
 
+/**
+ * Menu placement. Default: anchored to the trigger's right (toolbar). When
+ * `matchAnchorWidth` (stacked select), match the trigger width and left-align so
+ * the menu sits flush under the full-width control.
+ */
+function resolveMenuPlacement(
+  matchAnchorWidth: boolean | undefined,
+  anchorEl: HTMLElement | null,
+): { anchorWidth: number | undefined; align: 'left' | 'right' } {
+  if (!matchAnchorWidth) return { anchorWidth: undefined, align: 'right' };
+  return { anchorWidth: anchorEl?.offsetWidth, align: 'left' };
+}
+
 /** The (optional) search box + checkbox list + optional "Options" section + a "Clear" footer. */
 function MultiSelectMenu<TValue extends string>({
   anchorEl,
@@ -210,6 +203,7 @@ function MultiSelectMenu<TValue extends string>({
   onQueryChange,
   searchPlaceholder,
   noResultsLabel,
+  matchAnchorWidth,
   testId,
 }: MultiSelectMenuProps<TValue>): React.JSX.Element {
   const trimmed = query.trim().toLowerCase();
@@ -217,18 +211,24 @@ function MultiSelectMenu<TValue extends string>({
     () => (trimmed ? options.filter((option) => option.label.toLowerCase().includes(trimmed)) : options),
     [options, trimmed],
   );
+  const { anchorWidth, align } = resolveMenuPlacement(matchAnchorWidth, anchorEl);
   return (
     <Menu
       anchorEl={anchorEl}
       open={open}
       onClose={close}
-      anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
-      transformOrigin={{ vertical: 'top', horizontal: 'right' }}
+      anchorOrigin={{ vertical: 'bottom', horizontal: align }}
+      transformOrigin={{ vertical: 'top', horizontal: align }}
       // Keep focus on the search box (don't let the Menu grab the first item),
       // and stop MUI's typeahead from swallowing keystrokes meant for the input.
       autoFocus={!showSearch}
       disableAutoFocusItem
-      slotProps={{ paper: { sx: { minWidth: 180 } }, list: { sx: { pt: showSearch ? 0 : undefined } } }}
+      slotProps={{
+        // Cap the height so a long list (e.g. many categories) scrolls instead
+        // of running off-screen; the sticky search box stays pinned on top.
+        paper: { sx: { minWidth: anchorWidth ?? 180, width: anchorWidth, maxHeight: 360 } },
+        list: { sx: { pt: showSearch ? 0 : undefined, pb: 0 } },
+      }}
     >
       {showSearch && (
         <MenuSearchField query={query} onQueryChange={onQueryChange} placeholder={searchPlaceholder} testId={testId} />
@@ -277,7 +277,22 @@ function MenuClearFooter({
   testId?: string;
 }): React.JSX.Element {
   return (
-    <Box sx={{ display: 'flex', justifyContent: 'flex-end', borderTop: 1, borderColor: 'divider', px: 1, py: 0.75 }}>
+    <Box
+      sx={{
+        // Pin to the bottom of the scroll viewport so it stays visible while the
+        // options list scrolls (mirrors the sticky search box on top).
+        position: 'sticky',
+        bottom: 0,
+        zIndex: 1,
+        display: 'flex',
+        justifyContent: 'flex-end',
+        borderTop: 1,
+        borderColor: 'divider',
+        bgcolor: 'background.paper',
+        px: 1,
+        py: 0.75,
+      }}
+    >
       <Button
         variant="text"
         size="small"

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

@@ -0,0 +1,139 @@
+'use client';
+
+import ChevronDownIcon from '@mui/icons-material/KeyboardArrowDown';
+import { Box, Button, Typography } from '@mui/material';
+import React, { useId } from 'react';
+
+import type { MultiSelectOption } from './ContentToolbar.types';
+
+/**
+ * Trigger label from the current selection: `allLabel` when none/all are
+ * selected, the single label when one, else "first (+N)". Uses Set iteration
+ * order so the label reflects the first-clicked option.
+ */
+export function buildTriggerLabel<TValue extends string>(
+  selected: ReadonlySet<TValue>,
+  options: MultiSelectOption<TValue>[],
+  allLabel: string,
+): string {
+  const size = selected.size;
+  if (size === 0 || size === options.length) return allLabel;
+  const labelMap = new Map(options.map((option) => [option.value, option.label]));
+  const firstValue = selected.values().next().value as TValue;
+  const firstLabel = labelMap.get(firstValue) ?? allLabel;
+  if (size === 1) return firstLabel;
+  return `${firstLabel} (+${size - 1})`;
+}
+
+export interface TriggerProps {
+  label: string;
+  triggerLabel: string;
+  open: boolean;
+  onOpen: (event: React.MouseEvent<HTMLElement>) => void;
+  testId?: string;
+}
+
+/** Compact `Label:` text button for a horizontal toolbar (the default layout). */
+export function InlineTrigger({ label, triggerLabel, open, onOpen, testId }: TriggerProps): React.JSX.Element {
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1, fontSize: '0.875rem' }}>
+      <Typography component="span" sx={{ color: 'text.secondary', fontSize: '0.875rem' }}>
+        {label}:
+      </Typography>
+      <Button
+        variant="text"
+        size="small"
+        color="inherit"
+        data-testid={testId}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={onOpen}
+        sx={{ minWidth: 0, height: 32, px: 1, gap: 0.5, color: 'text.primary', textTransform: 'none', fontWeight: 600 }}
+      >
+        {triggerLabel}
+        <ChevronDownIcon sx={{ fontSize: 14 }} />
+      </Button>
+    </Box>
+  );
+}
+
+/** Full-width, outlined select-style control with the label above (stacked layout). */
+export function StackedTrigger({ label, triggerLabel, open, onOpen, testId }: TriggerProps): React.JSX.Element {
+  // Name the button by label + value (aria-labelledby): a <button> isn't labelable.
+  const baseId = useId();
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1 }}>
+      <Typography id={`${baseId}-label`} component="label" sx={{ fontSize: '0.75rem', fontWeight: 500, color: 'text.secondary' }}>
+        {label}
+      </Typography>
+      <Button
+        variant="outlined"
+        color="inherit"
+        fullWidth
+        data-testid={testId}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-labelledby={`${baseId}-label ${baseId}-value`}
+        onClick={onOpen}
+        endIcon={<ChevronDownIcon sx={{ fontSize: 18, color: 'text.secondary' }} />}
+        sx={{
+          justifyContent: 'space-between',
+          height: 40,
+          px: 1.5,
+          color: 'text.primary',
+          textTransform: 'none',
+          fontWeight: 400,
+          fontSize: '0.875rem',
+          borderColor: 'divider',
+          bgcolor: 'background.paper',
+          '&:hover': { borderColor: 'text.primary', bgcolor: 'background.paper' },
+        }}
+      >
+        <Box
+          component="span" id={`${baseId}-value`}
+          sx={{ flex: 1, minWidth: 0, textAlign: 'left', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}
+        >
+          {triggerLabel}
+        </Box>
+      </Button>
+    </Box>
+  );
+}
+
+/** Rounded outlined chip (`Label ▾`, `Label (N) ▾` when selected) for a filter row. */
+export function PillTrigger({
+  label,
+  open,
+  onOpen,
+  testId,
+  selectedCount,
+}: TriggerProps & { selectedCount: number }): React.JSX.Element {
+  const active = selectedCount > 0;
+  return (
+    <Button
+      variant="outlined"
+      color="inherit"
+      size="small"
+      data-testid={testId}
+      aria-haspopup="menu"
+      aria-expanded={open}
+      onClick={onOpen}
+      endIcon={<ChevronDownIcon sx={{ fontSize: 16 }} />}
+      sx={{
+        borderRadius: 999,
+        height: 34,
+        px: 1.5,
+        color: 'text.primary',
+        fontWeight: 600,
+        fontSize: '0.8125rem',
+        textTransform: 'none',
+        borderColor: active ? 'primary.main' : 'divider',
+        bgcolor: active ? 'action.selected' : 'background.paper',
+        '&:hover': { borderColor: active ? 'primary.main' : 'text.primary', bgcolor: active ? 'action.selected' : 'action.hover' },
+      }}
+    >
+      {label}
+      {active ? ` (${selectedCount})` : ''}
+    </Button>
+  );
+}

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

@@ -1,6 +1,9 @@
 'use client';
 
-import { Check as CheckIcon, KeyboardArrowDown as ChevronDownIcon, MoreVert as KebabIcon } from '@mui/icons-material';
+import CheckIcon from '@mui/icons-material/Check';
+import ChevronDownIcon from '@mui/icons-material/KeyboardArrowDown';
+import KebabIcon from '@mui/icons-material/MoreVert';
+import ViewIcon from '@mui/icons-material/Visibility';
 import { Box, Button, IconButton, Menu, MenuItem, Popover, Stack, Typography } from '@mui/material';
 import React, { useState } from 'react';
 
@@ -278,7 +281,6 @@ export function SavedViewsMenu<V extends SavedViewLike = SavedViewLike>({
     close();
   };
   const labels = { ...DEFAULT_LABELS, ...labelOverrides };
-
   const pinned = views.filter((view) => view.pinned);
   const recent = views.filter((view) => !view.pinned).slice(0, RECENT_LIMIT);
 
@@ -304,9 +306,14 @@ export function SavedViewsMenu<V extends SavedViewLike = SavedViewLike>({
         data-testid={`${testIdPrefix}-button`}
         aria-haspopup="menu"
         aria-expanded={Boolean(anchorEl)}
+        aria-label={activeViewName ?? labels.mainView}
         sx={{ minWidth: 0, height: 32, px: 1, gap: 0.5, color: 'text.primary', textTransform: 'none', fontWeight: 600 }}
       >
-        {activeViewName ?? labels.mainView}
+        {/* Mobile: an eye icon stands in for the view name to keep the toolbar one line. */}
+        <ViewIcon sx={{ fontSize: 18, display: { xs: 'inline-flex', md: 'none' } }} />
+        <Box component="span" sx={{ display: { xs: 'none', md: 'inline' } }}>
+          {activeViewName ?? labels.mainView}
+        </Box>
         <ChevronDownIcon sx={{ fontSize: 14 }} />
       </Button>
       <Popover

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

@@ -1,6 +1,7 @@
 'use client';
 
-import { Check as CheckIcon, KeyboardArrowDown as ChevronDownIcon } from '@mui/icons-material';
+import CheckIcon from '@mui/icons-material/Check';
+import ChevronDownIcon from '@mui/icons-material/KeyboardArrowDown';
 import { Box, Button, Divider, ListSubheader, Menu, MenuItem, Typography } from '@mui/material';
 import React, { useState } from 'react';
 
@@ -45,6 +46,20 @@ function buildTriggerLabel(
   return `${fieldDef.label} (${orderOption.label.toLowerCase()})`;
 }
 
+/** The trigger's full label (md+), short label (mobile), and direction arrow. */
+function resolveTriggerParts(
+  fieldDef: SortFieldDefinition | undefined,
+  orderOption: SortOrderOption | undefined,
+  orderOptions: SortOrderOption[],
+): { full: string; short: string; arrowSuffix: string } {
+  const useRangeLabel = fieldDef?.triggerLabelStyle === 'range' && orderOptions.length === 2;
+  const orderIndex = orderOptions.findIndex((option) => option.value === orderOption?.value);
+  const arrow = resolveArrowDirection(orderOption, orderIndex);
+  const arrowSuffix = orderOptions.length > 0 && !useRangeLabel ? ` ${arrow === 'down' ? '↓' : '↑'}` : '';
+  const full = buildTriggerLabel(fieldDef, orderOption);
+  return { full, short: fieldDef?.label ?? full, arrowSuffix };
+}
+
 const sectionLabelSx = { px: 1, py: 0.75, fontSize: '0.75rem', fontWeight: 600, color: 'text.primary', lineHeight: 1.5 } as const;
 
 /** A fixed-width check slot (empty when unchecked) so labels align. */
@@ -162,22 +177,24 @@ export function SortByDropdown<TField extends string = string>({
   const activeFieldDef = findActiveField(fields, activeField);
   const orderOptions = activeFieldDef?.orderOptions ?? [];
   const activeOrderOption = findActiveOrder(activeFieldDef, activeOrder);
-  const useRangeLabel = activeFieldDef?.triggerLabelStyle === 'range' && orderOptions.length === 2;
-
-  const orderIndex = orderOptions.findIndex((option) => option.value === activeOrderOption?.value);
-  const arrow = resolveArrowDirection(activeOrderOption, orderIndex);
-  const arrowSuffix = orderOptions.length > 0 && !useRangeLabel ? ` ${arrow === 'down' ? '↓' : '↑'}` : '';
+  const trigger = resolveTriggerParts(activeFieldDef, activeOrderOption, orderOptions);
 
   function handleFieldChange(field: TField): void {
+    // Switch field in ONE callback. Previously this also fired `onOrderChange`
+    // to reset the order, but a consumer whose `onOrderChange` derives the field
+    // from its own (now-stale) prop would re-apply the OLD field — silently
+    // reverting the field change (e.g. picking "E-mail" snapped back to "Nome").
+    // The field-change consumer owns the resulting order.
     onFieldChange(field);
-    const nextOrder = safeFields.find((candidate) => candidate.value === field)?.orderOptions?.[0]?.value;
-    if (nextOrder && onOrderChange) onOrderChange(nextOrder);
     close();
   }
 
   return (
     <Box sx={{ display: 'flex', alignItems: 'center', gap: 1, fontSize: '0.875rem' }}>
-      <Typography component="span" sx={{ color: 'text.secondary', fontSize: '0.875rem' }}>
+      <Typography
+        component="span"
+        sx={{ display: { xs: 'none', md: 'inline' }, color: 'text.secondary', fontSize: '0.875rem' }}
+      >
         Sort By:
       </Typography>
       <Button
@@ -190,8 +207,15 @@ export function SortByDropdown<TField extends string = string>({
         onClick={(event) => setAnchorEl(event.currentTarget)}
         sx={{ minWidth: 0, height: 32, px: 1, gap: 0.5, color: 'text.primary', textTransform: 'none', fontWeight: 600 }}
       >
-        {buildTriggerLabel(activeFieldDef, activeOrderOption)}
-        {arrowSuffix}
+        {/* Full "Nome (crescente)" on md+; just the field name on mobile — the
+            arrow already conveys the direction, so the parenthetical is dropped. */}
+        <Box component="span" sx={{ display: { xs: 'none', md: 'inline' } }}>
+          {trigger.full}
+        </Box>
+        <Box component="span" sx={{ display: { xs: 'inline', md: 'none' } }}>
+          {trigger.short}
+        </Box>
+        {trigger.arrowSuffix}
         <ChevronDownIcon sx={{ fontSize: 14 }} />
       </Button>
       <SortMenu

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

@@ -1,12 +1,11 @@
 'use client';
 
-import {
-  Check as CheckIcon,
-  KeyboardArrowDown as ChevronDownIcon,
-  GridViewOutlined as GridIcon,
-  FormatListBulletedRounded as ListIcon,
-} from '@mui/icons-material';
+import CheckIcon from '@mui/icons-material/Check';
+import ChevronDownIcon from '@mui/icons-material/KeyboardArrowDown';
+import GridIcon from '@mui/icons-material/GridViewOutlined';
+import ListIcon from '@mui/icons-material/FormatListBulletedRounded';
 import { Box, Button, ListItemIcon, ListItemText, Menu, MenuItem, Slider } from '@mui/material';
+// Type-only, so it is erased at build time and costs no barrel transform.
 import type { SvgIconComponent } from '@mui/icons-material';
 import React, { useState } from 'react';
 

package/src/components/layout/ContentToolbar/__tests__/MultiSelectDropdown.test.tsx

@@ -108,3 +108,24 @@ describe('MultiSelectDropdown search (FUT-169)', () => {
     expect(screen.getByTestId('cat-search')).toBeInTheDocument();
   });
 });
+
+describe('MultiSelectDropdown stacked trigger accessibility', () => {
+  it("names the trigger by the field label AND value so it isn't announced as just its value", () => {
+    render(
+      <MultiSelectDropdown
+        label="Papéis"
+        layout="stacked"
+        options={MANY_OPTIONS}
+        selected={new Set<string>()}
+        onToggle={vi.fn()}
+        onClear={vi.fn()}
+        allLabel="Todas"
+        data-testid="roles"
+      />,
+    );
+
+    // The accessible name resolves aria-labelledby to "<label> <value>", so the
+    // field name (not just "Todas") distinguishes this trigger from a sibling.
+    expect(screen.getByRole('button', { name: 'Papéis Todas' })).toBe(screen.getByTestId('roles'));
+  });
+});

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

@@ -2,7 +2,7 @@ import { Box, Button, TextField, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 
-import { Dashboard } from './Dashboard';
+import { Dashboard, markDashboardSlot } from './Dashboard';
 
 const meta: Meta<typeof Dashboard> = {
   title: 'Layout/Dashboard/Tests',
@@ -162,3 +162,29 @@ export const OrderIndependentRendering: Story = {
     });
   },
 };
+
+/** A page-owned wrapper around `<Dashboard.Header>`, tagged with its slot. */
+const WrappedHeader = markDashboardSlot(
+  ({ title }: { title: string }) => <Dashboard.Header title={title} />,
+  'header',
+);
+
+export const MarkedWrapperKeepsHeaderAboveBody: Story = {
+  name: '🧪 A slot-marked header wrapper still renders above the body',
+  render: () => (
+    <Dashboard>
+      <Dashboard.Breadcrumb items={[{ label: 'Admin', href: '#' }, { label: 'Wrapped' }]} />
+      <WrappedHeader title="Wrapped" />
+      <Dashboard.Body>{body}</Dashboard.Body>
+    </Dashboard>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Wrapped header sits above the body, not below it', async () => {
+      const header = canvas.getByTestId('dashboard-header');
+      const content = canvas.getByTestId('dashboard-body');
+      const headerBeforeBody = header.compareDocumentPosition(content) & Node.DOCUMENT_POSITION_FOLLOWING;
+      await expect(Boolean(headerBeforeBody)).toBe(true);
+    });
+  },
+};

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

@@ -1,11 +1,9 @@
 'use client';
 
-import {
-  ExpandLess as ExpandLessIcon,
-  ExpandMore as ExpandMoreIcon,
-  FilterListRounded as FilterIcon,
-  NavigateNext as NavigateNextIcon,
-} from '@mui/icons-material';
+import ExpandLessIcon from '@mui/icons-material/ExpandLess';
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import FilterIcon from '@mui/icons-material/FilterListRounded';
+import NavigateNextIcon from '@mui/icons-material/NavigateNext';
 import {
   Box,
   Breadcrumbs as MuiBreadcrumbs,
@@ -41,10 +39,31 @@ import type {
  * a `<Dashboard.Header>` still renders below it.
  */
 const SLOT_ORDER = ['breadcrumb', 'header', 'filters', 'body'] as const;
-type SlotKey = (typeof SLOT_ORDER)[number];
+/** A slot a component can occupy in the canonical Dashboard order. */
+export type DashboardSlot = (typeof SLOT_ORDER)[number];
 
 /** Marker attached to each sub-component so the root can rank it by slot. */
-type SlottedComponent = { dashboardSlot?: SlotKey };
+type SlottedComponent = { dashboardSlot?: DashboardSlot };
+
+/**
+ * Tag a component with the Dashboard slot it occupies so the root ranks it in
+ * canonical order. The root inspects only its DIRECT children's `type`, so a
+ * page that wraps a `<Dashboard.Header>` (or any part) in its own component MUST
+ * mark that wrapper — otherwise it counts as an unrecognised child and sinks
+ * below the body. Returns the component for convenient inline use.
+ *
+ * @example
+ * ```tsx
+ * function ProductsHeader(props) {
+ *   return <Dashboard.Header title="Products">{/* … *\/}</Dashboard.Header>;
+ * }
+ * markDashboardSlot(ProductsHeader, 'header');
+ * ```
+ */
+export function markDashboardSlot<T>(component: T, slot: DashboardSlot): T {
+  (component as SlottedComponent).dashboardSlot = slot;
+  return component;
+}
 
 const Root = styled(Box)(({ theme }) => ({
   display: 'flex',

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

@@ -1,17 +1,14 @@
 'use client';
 
-import {
-  Close as CloseIcon,
-  ExpandMore as ExpandMoreIcon,
-  FileDownloadOutlined as ExportIcon,
-  FilterListRounded as FilterIcon,
-  InfoOutlined as InfoIcon,
-  SettingsOutlined as SettingsIcon,
-} from '@mui/icons-material';
+import CloseIcon from '@mui/icons-material/Close';
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import ExportIcon from '@mui/icons-material/FileDownloadOutlined';
+import FilterIcon from '@mui/icons-material/FilterListRounded';
+import InfoIcon from '@mui/icons-material/InfoOutlined';
+import SettingsIcon from '@mui/icons-material/SettingsOutlined';
 import {
   Badge,
   Box,
-  Button,
   Dialog,
   DialogContent,
   DialogTitle,
@@ -24,6 +21,7 @@ import {
 } from '@mui/material';
 import React, { useState } from 'react';
 
+import { HeaderButton } from '../../form/HeaderButton';
 import { useDashboardContext } from './DashboardContext';
 import type {
   DashboardActionProps,
@@ -175,22 +173,17 @@ export const DashboardExport = ({
   const open = Boolean(anchorEl);
   return (
     <>
-      <Button
+      <HeaderButton
         variant="outlined"
-        size="medium"
         color="inherit"
-        startIcon={<ExportIcon fontSize="small" />}
+        text={label}
+        icon={<ExportIcon fontSize="small" />}
         endIcon={<ExpandMoreIcon fontSize="small" />}
         onClick={(e) => setAnchorEl(e.currentTarget)}
         aria-haspopup="menu"
         aria-expanded={open}
-        data-testid={`${testIdPrefix}-export-trigger`}
-        // Match the sibling primary action button (repo Button `md`): same
-        // padding/height and a 1rem non-uppercased label.
-        sx={{ py: 1, px: 2, fontSize: '1rem', textTransform: 'none' }}
-      >
-        {label}
-      </Button>
+        dataTestId={`${testIdPrefix}-export-trigger`}
+      />
       <Menu anchorEl={anchorEl} open={open} onClose={() => setAnchorEl(null)} data-testid={`${testIdPrefix}-export-menu`}>
         {formats.map((format) => (
           <MenuItem

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

@@ -1,4 +1,5 @@
-export { Dashboard } from './Dashboard';
+export { Dashboard, markDashboardSlot } from './Dashboard';
+export type { DashboardSlot } from './Dashboard';
 export { DashboardContext, useDashboardContext } from './DashboardContext';
 export type { DashboardContextValue } from './DashboardContext';
 export type {

package/src/components/layout/Drawer/Drawer.stories.tsx

@@ -1,13 +1,11 @@
-import {
-  Analytics,
-  Dashboard,
-  Help,
-  Home,
-  Menu as MenuIcon,
-  Notifications,
-  Person,
-  Settings,
-} from '@mui/icons-material';
+import Analytics from '@mui/icons-material/Analytics';
+import Dashboard from '@mui/icons-material/Dashboard';
+import Help from '@mui/icons-material/Help';
+import Home from '@mui/icons-material/Home';
+import MenuIcon from '@mui/icons-material/Menu';
+import Notifications from '@mui/icons-material/Notifications';
+import Person from '@mui/icons-material/Person';
+import Settings from '@mui/icons-material/Settings';
 import {
   Box,
   Button,