@12-apps/ui 1.0.0

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

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi } from 'vitest';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+import { MultiSelectDropdown } from '../MultiSelectDropdown';
+
+const MANY_OPTIONS = [
+  { value: 'bebidas', label: 'Bebidas' },
+  { value: 'sobremesas', label: 'Sobremesas' },
+  { value: 'lanches', label: 'Lanches' },
+  { value: 'saladas', label: 'Saladas' },
+  { value: 'massas', label: 'Massas' },
+  { value: 'carnes', label: 'Carnes' },
+  { value: 'peixes', label: 'Peixes' },
+  { value: 'vegano', label: 'Vegano' },
+  { value: 'infantil', label: 'Infantil' },
+];
+
+function open(): void {
+  fireEvent.click(screen.getByTestId('cat'));
+}
+
+describe('MultiSelectDropdown search (FUT-169)', () => {
+  it('auto-shows a search box for long lists and filters options case-insensitively', async () => {
+    render(
+      <MultiSelectDropdown
+        label="Categoria"
+        options={MANY_OPTIONS}
+        selected={new Set<string>()}
+        onToggle={vi.fn()}
+        onClear={vi.fn()}
+        searchPlaceholder="Buscar…"
+        noResultsLabel="Nenhum resultado"
+        data-testid="cat"
+      />,
+    );
+    open();
+
+    const search = await screen.findByTestId('cat-search');
+    expect(screen.getByText('Lanches')).toBeInTheDocument();
+
+    fireEvent.change(search, { target: { value: 'SOBRE' } });
+
+    await waitFor(() => expect(screen.queryByText('Lanches')).not.toBeInTheDocument());
+    expect(screen.getByText('Sobremesas')).toBeInTheDocument();
+  });
+
+  it('shows the empty state when nothing matches', async () => {
+    render(
+      <MultiSelectDropdown
+        label="Categoria"
+        options={MANY_OPTIONS}
+        selected={new Set<string>()}
+        onToggle={vi.fn()}
+        onClear={vi.fn()}
+        noResultsLabel="Nenhum resultado"
+        data-testid="cat"
+      />,
+    );
+    open();
+
+    fireEvent.change(await screen.findByTestId('cat-search'), { target: { value: 'zzz' } });
+
+    expect(await screen.findByTestId('cat-no-results')).toHaveTextContent('Nenhum resultado');
+  });
+
+  it('does NOT render a search box for short lists', async () => {
+    render(
+      <MultiSelectDropdown
+        label="Ativo"
+        options={[
+          { value: 'sim', label: 'Sim' },
+          { value: 'nao', label: 'Não' },
+        ]}
+        selected={new Set<string>()}
+        onToggle={vi.fn()}
+        onClear={vi.fn()}
+        data-testid="cat"
+      />,
+    );
+    open();
+
+    // Presence evidence first (menu open), then assert the search box was never
+    // rendered — wrapped in waitFor per the anti-flake rule.
+    expect(await screen.findByText('Sim')).toBeInTheDocument();
+    await waitFor(() => expect(screen.queryByTestId('cat-search')).not.toBeInTheDocument());
+  });
+
+  it('toggles a filtered option and keeps the menu open (search still visible)', async () => {
+    const onToggle = vi.fn();
+    render(
+      <MultiSelectDropdown
+        label="Categoria"
+        options={MANY_OPTIONS}
+        selected={new Set<string>()}
+        onToggle={onToggle}
+        onClear={vi.fn()}
+        data-testid="cat"
+      />,
+    );
+    open();
+
+    const search = await screen.findByTestId('cat-search');
+    fireEvent.change(search, { target: { value: 'peix' } });
+    fireEvent.click(await screen.findByText('Peixes'));
+
+    expect(onToggle).toHaveBeenCalledWith('peixes', true);
+    // Multi-select: the menu stays open, so the search box is still mounted.
+    expect(screen.getByTestId('cat-search')).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,99 @@
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+
+import { SavedViewsMenu } from "../SavedViewsMenu";
+import type { SavedViewLike } from "../ContentToolbar.types";
+
+const views: SavedViewLike[] = [
+  { id: "v1", name: "Meus ativos", shared: false, pinned: true, isDefault: true, isOwner: true },
+  { id: "v2", name: "Da equipe", shared: true, pinned: false, isDefault: false, isOwner: false },
+];
+
+function renderMenu(overrides: Partial<React.ComponentProps<typeof SavedViewsMenu>> = {}) {
+  const handlers = {
+    onApply: vi.fn(),
+    onSelectMain: vi.fn(),
+    onSaveCurrent: vi.fn(),
+    onEdit: vi.fn(),
+    onDelete: vi.fn(),
+    onSetDefault: vi.fn(),
+    onTogglePin: vi.fn(),
+    onToggleShare: vi.fn(),
+    onManageAll: vi.fn(),
+  };
+  render(<SavedViewsMenu views={views} testIdPrefix="views" {...handlers} {...overrides} />);
+  return handlers;
+}
+
+describe("SavedViewsMenu", () => {
+  it("lists pinned + recent sections and a default badge", () => {
+    renderMenu();
+    fireEvent.click(screen.getByTestId("views-button"));
+    expect(screen.getByTestId("views-section-pinned")).toBeInTheDocument();
+    expect(screen.getByTestId("views-section-recent")).toBeInTheDocument();
+    expect(screen.getByTestId("views-default-v1")).toBeInTheDocument();
+  });
+
+  it("labels the trigger 'Visão principal' by default and the active view name when set", () => {
+    const noop = {
+      onApply: vi.fn(),
+      onSelectMain: vi.fn(),
+      onSaveCurrent: vi.fn(),
+      onEdit: vi.fn(),
+      onDelete: vi.fn(),
+      onSetDefault: vi.fn(),
+      onTogglePin: vi.fn(),
+      onToggleShare: vi.fn(),
+      onManageAll: vi.fn(),
+    };
+    const { rerender } = render(<SavedViewsMenu views={views} testIdPrefix="views" {...noop} />);
+    expect(screen.getByTestId("views-button")).toHaveTextContent("Visão principal");
+    rerender(<SavedViewsMenu views={views} activeViewName="Meus ativos" testIdPrefix="views" {...noop} />);
+    expect(screen.getByTestId("views-button")).toHaveTextContent("Meus ativos");
+  });
+
+  it("offers a Main vision default that resets to the no-filter view", () => {
+    const handlers = renderMenu();
+    fireEvent.click(screen.getByTestId("views-button"));
+    fireEvent.click(screen.getByTestId("views-main"));
+    expect(handlers.onSelectMain).toHaveBeenCalled();
+  });
+
+  it("applies a view when its name is clicked", () => {
+    const handlers = renderMenu();
+    fireEvent.click(screen.getByTestId("views-button"));
+    fireEvent.click(screen.getByTestId("views-apply-v1"));
+    expect(handlers.onApply).toHaveBeenCalledWith(expect.objectContaining({ id: "v1" }));
+  });
+
+  it("shows full owner actions (incl. Excluir) for an owned view", () => {
+    renderMenu();
+    fireEvent.click(screen.getByTestId("views-button"));
+    fireEvent.click(screen.getByTestId("views-kebab-v1"));
+    expect(screen.getByTestId("views-item-delete-v1")).toBeInTheDocument();
+    expect(screen.getByText("Excluir")).toBeInTheDocument();
+  });
+
+  it("shows apply-only for a non-owned shared view", async () => {
+    renderMenu();
+    fireEvent.click(screen.getByTestId("views-button"));
+    fireEvent.click(screen.getByTestId("views-kebab-v2"));
+    expect(screen.getByTestId("views-item-apply-v2")).toBeInTheDocument();
+    await waitFor(() => {
+      expect(screen.queryByTestId("views-item-delete-v2")).not.toBeInTheDocument();
+    });
+  });
+
+  it("offers save-current and manage-all", () => {
+    const handlers = renderMenu();
+    fireEvent.click(screen.getByTestId("views-button"));
+    fireEvent.click(screen.getByTestId("views-save-current"));
+    expect(handlers.onSaveCurrent).toHaveBeenCalled();
+  });
+
+  it("shows an empty hint when there are no views", () => {
+    renderMenu({ views: [] });
+    fireEvent.click(screen.getByTestId("views-button"));
+    expect(within(screen.getByTestId("views-popover")).getByText(/Nenhuma visão salva/i)).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,24 @@
+export { ContentToolbar } from './ContentToolbar';
+export { ViewSelector } from './ViewSelector';
+export { SortByDropdown } from './SortByDropdown';
+export { MultiSelectDropdown } from './MultiSelectDropdown';
+export { FilterTrigger } from './FilterTrigger';
+export { ColumnsMenu } from './ColumnsMenu';
+export { SavedViewsMenu } from './SavedViewsMenu';
+export type {
+  ContentToolbarProps,
+  ViewMode,
+  ViewSelectorProps,
+  SortOrderOption,
+  SortFieldDefinition,
+  SortByDropdownProps,
+  MultiSelectOption,
+  MultiSelectExtraOption,
+  MultiSelectDropdownProps,
+  FilterTriggerProps,
+  ColumnVisibilityOption,
+  ColumnsMenuProps,
+  SavedViewLike,
+  SavedViewsLabels,
+  SavedViewsMenuProps,
+} from './ContentToolbar.types';

package/src/components/layout/ContentToolbar/tests.md

@@ -0,0 +1,42 @@
+# ContentToolbar Test Status Tracking
+
+## Test Files Status
+
+- [x] ContentToolbar.test.stories.tsx created
+- [x] Core interaction categories implemented
+
+## Storybook Tests Status
+
+### Test Results
+
+| Test Name                          | Status  | Pass/Fail | Notes                                     |
+| ---------------------------------- | ------- | --------- | ----------------------------------------- |
+| Select All → chrome → Clear All    | Pending | -         | Selection count + Clear All appear/reset  |
+| Sort By opens and changes field    | Pending | -         | Menu opens; picking a field updates trigger |
+| Content Type toggles stay open     | Pending | -         | Multi-select keeps menu open; Clear shown |
+| Filter trigger toggles + dot       | Pending | -         | aria-expanded flips; active dot renders   |
+
+Legend: Pending | Running | PASS | FAIL
+
+## Static Stories Status
+
+- [x] Default (full reference bar)
+- [x] WithSelection
+
+## Lint Status
+
+- [ ] No lint errors
+- [ ] No warnings
+
+## TypeCheck Status
+
+- [ ] No type errors
+- [ ] All props properly typed
+
+## Overall Component Status
+
+- [ ] All tests passing
+- [ ] Lint clean
+- [ ] TypeCheck clean
+- [ ] Stories working
+- [ ] Ready for production

package/src/components/layout/ContentToolbar/track.md

@@ -0,0 +1,41 @@
+# ContentToolbar
+
+MUI port of a reference content-page toolbar. A bar shell (`ContentToolbar`)
+with a left selection cluster (Select All / Clear All / count / `actions`) and a
+right `rightControls` slot, plus the controls that populate that slot:
+`ViewSelector`, `SortByDropdown`, `MultiSelectDropdown`, `FilterTrigger`.
+Generic/agnostic — no domain coupling; the reference's content-item action
+dropdown is deliberately left to the consumer's `actions` slot.
+
+## Props (per component)
+
+- **ContentToolbar** — hasSelection, selectedCount, selectAll, clearSelection,
+  rightControls, actions?, selectAllTestId?, clearAllTestId?, edgeAlign?.
+- **ViewSelector** — viewMode, onViewModeChange, zoom (number[]), onZoomChange.
+- **SortByDropdown** — fields, activeField, activeOrder?, onFieldChange,
+  onOrderChange?; generic over the field type; Order/Sort sections.
+- **MultiSelectDropdown** — label, options (value/label/count), selected (Set),
+  onToggle, onClear, allLabel?, extraOptions?.
+- **FilterTrigger** — open, onOpenChange, hasActiveFilters?.
+
+## Lint
+
+- Clean (`pnpm lint:files src/components/layout/ContentToolbar`).
+
+## Type Errors
+
+- None (`pnpm typecheck`).
+
+## Testing Scenarios
+
+- Select All → count + Clear All → reset; Sort By open + field change;
+  Content-Type multi-select keeps menu open + Clear; filter funnel toggle + dot.
+
+## Storybook Tests List
+
+- Layout/ContentToolbar/Tests → 4 interaction stories.
+
+## Current
+
+- v1 ported from the reference (tabwoah `ContentPageToolbar` + controls),
+  translated to MUI. Next: wire into an admin page as the first consumer.

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

@@ -0,0 +1,71 @@
+# Dashboard
+
+A **composable page shell** for list/detail admin pages. `<Dashboard>` is a
+context provider and layout; every sub-component is **opt-in**. Compose only the
+parts a page needs — omit `<Dashboard.Filters>` and there is no filter UI at all.
+Authoring order does not matter: recognised parts always render in the slot order
+**Breadcrumb → Header → Filters → Body**.
+
+## Why
+
+Every data page (products, inventory, suppliers, …) shares the same chrome: a
+breadcrumb, a title with contextual controls (info, filter toggle, settings,
+export), a collapsible filter region, and a body. `Dashboard` captures that shape
+once so pages stay consistent and new pages are a composition, not a rebuild.
+It is framework-agnostic (pure MUI, no app coupling) so other projects can reuse it.
+
+## Composition
+
+```tsx
+import { Dashboard } from '@12-apps/ui/layout/Dashboard';
+
+<Dashboard activeFilterCount={activeCount}>
+  <Dashboard.Breadcrumb items={[{ label: 'Admin', href: '/admin' }, { label: 'Products' }]} />
+  <Dashboard.Header title="Products">
+    <Dashboard.Info title="About Products">What this page does…</Dashboard.Info>
+    <Dashboard.FilterToggle />
+    <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.Header>
+  <Dashboard.Filters>
+    <SearchInput />
+    <Dashboard.MoreFilters>
+      <MinMaxRange field="price" />
+    </Dashboard.MoreFilters>
+  </Dashboard.Filters>
+  <Dashboard.Body>{table}</Dashboard.Body>
+</Dashboard>
+```
+
+## Parts
+
+| Part | Slot | Purpose |
+| --- | --- | --- |
+| `Dashboard` | — | Provider + layout. Owns `filtersVisible` / `moreFiltersOpen` via context. |
+| `Dashboard.Breadcrumb` | breadcrumb | Breadcrumb trail. `renderLink` lets you inject a router link. |
+| `Dashboard.Header` | header | Title row hosting the action parts below. |
+| `Dashboard.Info` | (in header) | `[i]` popover summarising the page. |
+| `Dashboard.FilterToggle` | (in header) | Funnel icon; toggles the filter region, badges `activeFilterCount`. |
+| `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.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). |
+
+## State
+
+`Dashboard` owns only **UI** state (which regions are open) through
+`DashboardContext`. Search text and filter values stay owned by the page and are
+passed to whatever controls you compose inside `Dashboard.Filters`. Read the
+context directly with `useDashboardContext()` when building custom parts.
+
+## Accessibility
+
+- Icon triggers have tooltips + `aria-label`; `FilterToggle` exposes `aria-pressed`.
+- `Info`/`Settings` triggers declare `aria-haspopup`; the settings dialog and info
+  popover are focus-trapped by MUI and closable via the close button / `Esc`.
+- Breadcrumb marks the current page with `aria-current="page"`.

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

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Box, Button, TextField, Typography } from '@mui/material';
+import { fn } from 'storybook/test';
+
+import { Dashboard } from './Dashboard';
+
+const meta: Meta<typeof Dashboard> = {
+  title: 'Layout/Dashboard',
+  component: Dashboard,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Composable page shell. `<Dashboard>` is a context provider; every part — `Dashboard.Header`, `Dashboard.Breadcrumb`, `Dashboard.Filters`, `Dashboard.Info`, `Dashboard.FilterToggle`, `Dashboard.Settings`, `Dashboard.Export`, `Dashboard.MoreFilters`, `Dashboard.Body` — is opt-in. Compose only what you need; authoring order does not matter, parts render in a fixed slot order.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const table = (
+  <Box sx={{ p: 4, borderRadius: 1, border: '1px dashed', borderColor: 'divider', textAlign: 'center', color: 'text.secondary' }}>
+    Your table / grid goes here
+  </Box>
+);
+
+export const FullComposition: Story = {
+  args: { activeFilterCount: 2 },
+  render: (args) => (
+    <Dashboard {...args}>
+      <Dashboard.Breadcrumb items={[{ label: 'Admin', href: '#' }, { label: 'Products' }]} />
+      <Dashboard.Header title="Products">
+        <Dashboard.Info title="About Products">
+          Manage your catalog: create products, set prices, and control stock visibility.
+        </Dashboard.Info>
+        <Dashboard.FilterToggle />
+        <Dashboard.Settings title="Product settings">
+          <Typography>In development — coming in the next version.</Typography>
+        </Dashboard.Settings>
+        <Dashboard.Spacer />
+        <Dashboard.Export onExport={fn()} />
+        <Dashboard.Action>
+          <Button variant="contained">New product</Button>
+        </Dashboard.Action>
+      </Dashboard.Header>
+      <Dashboard.Filters>
+        <TextField size="small" placeholder="Search across all columns…" fullWidth />
+        <Dashboard.MoreFilters>
+          <Box sx={{ display: 'flex', gap: 2 }}>
+            <TextField size="small" label="Min price" type="number" />
+            <TextField size="small" label="Max price" type="number" />
+          </Box>
+        </Dashboard.MoreFilters>
+      </Dashboard.Filters>
+      <Dashboard.Body>{table}</Dashboard.Body>
+    </Dashboard>
+  ),
+};
+
+export const HeaderOnly: Story = {
+  render: () => (
+    <Dashboard>
+      <Dashboard.Header title="Simple page">
+        <Dashboard.Action>
+          <Button variant="contained">Primary action</Button>
+        </Dashboard.Action>
+      </Dashboard.Header>
+      <Dashboard.Body>{table}</Dashboard.Body>
+    </Dashboard>
+  ),
+};
+
+export const WithoutFilters: Story = {
+  render: () => (
+    <Dashboard>
+      <Dashboard.Breadcrumb items={[{ label: 'Admin', href: '#' }, { label: 'Team' }]} />
+      <Dashboard.Header title="Team">
+        <Dashboard.Info>Invite teammates and manage their roles.</Dashboard.Info>
+      </Dashboard.Header>
+      <Dashboard.Body>{table}</Dashboard.Body>
+    </Dashboard>
+  ),
+};
+
+export const OrderIndependent: Story = {
+  name: 'Order-independent authoring',
+  render: () => (
+    <Dashboard>
+      {/* Deliberately authored out of order — still renders breadcrumb → header → filters → body. */}
+      <Dashboard.Body>{table}</Dashboard.Body>
+      <Dashboard.Filters>
+        <TextField size="small" placeholder="Search…" fullWidth />
+      </Dashboard.Filters>
+      <Dashboard.Header title="Reordered">
+        <Dashboard.FilterToggle />
+      </Dashboard.Header>
+      <Dashboard.Breadcrumb items={[{ label: 'Admin', href: '#' }, { label: 'Reordered' }]} />
+    </Dashboard>
+  ),
+};

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

@@ -0,0 +1,164 @@
+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';
+
+const meta: Meta<typeof Dashboard> = {
+  title: 'Layout/Dashboard/Tests',
+  component: Dashboard,
+  parameters: {
+    layout: 'padded',
+    chromatic: { disableSnapshot: false },
+  },
+  tags: ['autodocs', 'test', 'component:Dashboard', 'checked'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const body = <Box data-testid="content">content</Box>;
+
+/** Full composition reused across tests. */
+const Composed = ({ onExport = fn() }: { onExport?: (id: string) => void }) => (
+  <Dashboard activeFilterCount={2}>
+    <Dashboard.Breadcrumb items={[{ label: 'Admin', href: '#' }, { label: 'Products' }]} />
+    <Dashboard.Header title="Products">
+      <Dashboard.Info title="About Products">Manage your catalog.</Dashboard.Info>
+      <Dashboard.FilterToggle />
+      <Dashboard.Settings title="Product settings">
+        <Typography>In development.</Typography>
+      </Dashboard.Settings>
+      <Dashboard.Spacer />
+      <Dashboard.Export onExport={onExport} />
+      <Dashboard.Action>
+        <Button variant="contained">New product</Button>
+      </Dashboard.Action>
+    </Dashboard.Header>
+    <Dashboard.Filters>
+      <TextField size="small" placeholder="Search…" fullWidth inputProps={{ 'data-testid': 'search' }} />
+      <Dashboard.MoreFilters>
+        <TextField size="small" label="Min price" type="number" />
+      </Dashboard.MoreFilters>
+    </Dashboard.Filters>
+    <Dashboard.Body>{body}</Dashboard.Body>
+  </Dashboard>
+);
+
+export const FilterToggleInteraction: Story = {
+  name: '🧪 Filter toggle shows/hides filters',
+  render: () => <Composed />,
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Filters visible by default', async () => {
+      await expect(canvas.getByTestId('search')).toBeVisible();
+    });
+    await step('Toggle hides the filter region', async () => {
+      await userEvent.click(canvas.getByTestId('dashboard-filter-toggle'));
+      await waitFor(() => expect(canvas.queryByTestId('search')).not.toBeInTheDocument());
+    });
+    await step('Toggle again restores it', async () => {
+      await userEvent.click(canvas.getByTestId('dashboard-filter-toggle'));
+      await waitFor(() => expect(canvas.getByTestId('search')).toBeVisible());
+    });
+  },
+};
+
+export const InfoPopover: Story = {
+  name: '🧪 Info popover opens',
+  render: () => <Composed />,
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Open the info popover', async () => {
+      await userEvent.click(canvas.getByTestId('dashboard-info-trigger'));
+      await waitFor(() => expect(within(document.body).getByText('About Products')).toBeVisible());
+    });
+  },
+};
+
+export const SettingsDialog: Story = {
+  name: '🧪 Settings gear opens dialog',
+  render: () => <Composed />,
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Open the settings dialog', async () => {
+      await userEvent.click(canvas.getByTestId('dashboard-settings-trigger'));
+      await waitFor(() => expect(within(document.body).getByText('In development.')).toBeVisible());
+    });
+  },
+};
+
+export const SettingsLink: Story = {
+  name: '🧪 Settings gear links to a settings route (no dialog)',
+  render: () => (
+    <Dashboard>
+      <Dashboard.Header title="Estoque">
+        <Dashboard.Settings ariaLabel="Configurações de estoque" href="/admin/acme/config/inventory" />
+      </Dashboard.Header>
+      <Dashboard.Body>{body}</Dashboard.Body>
+    </Dashboard>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Gear renders as an anchor pointing at the config route', async () => {
+      const gear = canvas.getByTestId('dashboard-settings-trigger');
+      await expect(gear.tagName).toBe('A');
+      await expect(gear).toHaveAttribute('href', '/admin/acme/config/inventory');
+    });
+    await step('Clicking it opens no dialog', async () => {
+      await userEvent.click(canvas.getByTestId('dashboard-settings-trigger'));
+      await expect(canvas.queryAllByTestId('dashboard-settings-dialog')).toHaveLength(0);
+    });
+  },
+};
+
+export const ExportMenu: Story = {
+  name: '🧪 Export menu invokes handler',
+  render: () => {
+    const onExport = fn();
+    return <Composed onExport={onExport} />;
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Open export menu and choose CSV', async () => {
+      await userEvent.click(canvas.getByTestId('dashboard-export-trigger'));
+      await waitFor(() => expect(within(document.body).getByTestId('dashboard-export-csv')).toBeVisible());
+      await userEvent.click(within(document.body).getByTestId('dashboard-export-csv'));
+    });
+  },
+};
+
+export const MoreFiltersExpands: Story = {
+  name: '🧪 More filters expands advanced panel',
+  render: () => <Composed />,
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Expand advanced filters', async () => {
+      await userEvent.click(canvas.getByTestId('dashboard-more-filters-toggle'));
+      await waitFor(() => expect(canvas.getByLabelText('Min price')).toBeVisible());
+    });
+  },
+};
+
+export const OrderIndependentRendering: Story = {
+  name: '🧪 Renders in slot order regardless of authoring order',
+  render: () => (
+    <Dashboard>
+      <Dashboard.Body>{body}</Dashboard.Body>
+      <Dashboard.Header title="Reordered" />
+      <Dashboard.Breadcrumb items={[{ label: 'Admin', href: '#' }, { label: 'Reordered' }]} />
+    </Dashboard>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Breadcrumb renders before header, header before body', async () => {
+      const breadcrumb = canvas.getByTestId('dashboard-breadcrumb');
+      const header = canvas.getByTestId('dashboard-header');
+      const content = canvas.getByTestId('dashboard-body');
+      const bcBeforeHeader = breadcrumb.compareDocumentPosition(header) & Node.DOCUMENT_POSITION_FOLLOWING;
+      const headerBeforeBody = header.compareDocumentPosition(content) & Node.DOCUMENT_POSITION_FOLLOWING;
+      await expect(Boolean(bcBeforeHeader)).toBe(true);
+      await expect(Boolean(headerBeforeBody)).toBe(true);
+    });
+  },
+};