@12-apps/ui 1.0.0

package/src/components/layout/Container/Container.tsx

@@ -0,0 +1,72 @@
+import { Container as MuiContainer, useTheme } from '@mui/material';
+import type { SxProps, Theme } from '@mui/material/styles';
+import React from 'react';
+
+import type { ContainerProps } from './Container.types';
+
+export const Container: React.FC<ContainerProps> = ({
+  children,
+  maxWidth = 'lg',
+  variant = 'default',
+  padding = 'md',
+  responsive = true,
+  dataTestId,
+  sx,
+  ...props
+}) => {
+  const theme = useTheme();
+
+  const getPadding = () => {
+    const paddingMap = {
+      none: 0,
+      xs: theme.spacing(1),
+      sm: theme.spacing(2),
+      md: theme.spacing(3),
+      lg: theme.spacing(4),
+      xl: theme.spacing(6),
+    };
+    return paddingMap[padding] || theme.spacing(3);
+  };
+
+  const getMaxWidth = (): 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false => {
+    if (variant === 'fluid') return false;
+    if (variant === 'centered') return 'md';
+    if (typeof maxWidth === 'string' && ['xs', 'sm', 'md', 'lg', 'xl'].includes(maxWidth)) {
+      return maxWidth as 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    }
+    if (maxWidth === false) return false;
+    return 'lg'; // default fallback
+  };
+
+  const containerStyles: SxProps<Theme> = {
+    ...(variant === 'centered' && {
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+      justifyContent: 'center',
+      minHeight: '100vh',
+    }),
+    ...(variant === 'padded' && {
+      paddingTop: theme.spacing(8),
+      paddingBottom: theme.spacing(8),
+    }),
+    padding: getPadding(),
+    ...(responsive && {
+      [theme.breakpoints.down('sm')]: {
+        padding: theme.spacing(2),
+      },
+    }),
+    ...(sx || {}),
+  };
+
+  return (
+    <MuiContainer
+      maxWidth={getMaxWidth()}
+      sx={containerStyles}
+      data-testid={dataTestId || 'container'}
+      {...props}
+    >
+      {children}
+    </MuiContainer>
+  );
+};

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

@@ -0,0 +1,11 @@
+import type { ContainerProps as MuiContainerProps } from '@mui/material';
+import type { ReactNode } from 'react';
+
+export interface ContainerProps extends Omit<MuiContainerProps, 'maxWidth'> {
+  children: ReactNode;
+  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false | string;
+  variant?: 'default' | 'fluid' | 'centered' | 'padded';
+  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  responsive?: boolean;
+  dataTestId?: string;
+}

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

@@ -0,0 +1,2 @@
+export { Container } from './Container';
+export type { ContainerProps } from './Container.types';

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

@@ -0,0 +1,99 @@
+'use client';
+
+import { ViewColumnRounded as ColumnsIcon } from '@mui/icons-material';
+import { Box, Checkbox, IconButton, ListSubheader, Menu, MenuItem } from '@mui/material';
+import React, { useState } from 'react';
+
+import type { ColumnVisibilityOption, ColumnsMenuProps } from './ContentToolbar.types';
+
+/** One column checkbox row; toggling never closes the menu. */
+function ColumnRow({
+  option,
+  onToggle,
+  testId,
+}: {
+  option: ColumnVisibilityOption;
+  onToggle: (id: string, visible: boolean) => void;
+  testId?: string;
+}): React.JSX.Element {
+  return (
+    <MenuItem
+      data-testid={testId}
+      onClick={() => onToggle(option.id, !option.visible)}
+      disabled={option.locked}
+      sx={{ gap: 1 }}
+    >
+      <Checkbox
+        checked={option.visible}
+        size="small"
+        disableRipple
+        sx={{ p: 0, pointerEvents: 'none' }}
+        tabIndex={-1}
+      />
+      <Box component="span" sx={{ flex: 1, minWidth: 0, textAlign: 'left' }}>
+        {option.label}
+      </Box>
+    </MenuItem>
+  );
+}
+
+/**
+ * Stateless column-visibility selector: a neutral icon button (matching
+ * {@link FilterTrigger}/{@link SortByDropdown}) opening a checkbox list of the
+ * hideable columns. Purely presentational — the caller owns the visibility state
+ * and is notified via `onToggle`. The menu stays open while toggling so several
+ * columns can be flipped at once.
+ */
+export function ColumnsMenu({
+  columns,
+  onToggle,
+  title = 'Columns',
+  ariaLabel = 'Toggle columns',
+  'data-testid': testId,
+}: ColumnsMenuProps): React.JSX.Element {
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
+  const open = Boolean(anchorEl);
+  const close = (): void => setAnchorEl(null);
+
+  return (
+    <>
+      <IconButton
+        size="small"
+        data-testid={testId}
+        aria-label={ariaLabel}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={(event) => setAnchorEl(event.currentTarget)}
+        sx={{
+          width: 32,
+          height: 32,
+          borderRadius: 1,
+          color: 'text.secondary',
+          bgcolor: open ? 'action.selected' : 'transparent',
+        }}
+      >
+        <ColumnsIcon sx={{ fontSize: 16 }} />
+      </IconButton>
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={close}
+        anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+        transformOrigin={{ vertical: 'top', horizontal: 'right' }}
+        slotProps={{ paper: { sx: { minWidth: 200 } } }}
+      >
+        <ListSubheader sx={{ px: 1.5, py: 0.75, fontSize: '0.75rem', fontWeight: 600, color: 'text.primary', lineHeight: 1.5 }}>
+          {title}
+        </ListSubheader>
+        {columns.map((option) => (
+          <ColumnRow
+            key={option.id}
+            option={option}
+            onToggle={onToggle}
+            testId={testId ? `${testId}-${option.id}` : undefined}
+          />
+        ))}
+      </Menu>
+    </>
+  );
+}

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

@@ -0,0 +1,75 @@
+# ContentToolbar
+
+The shared **content-page toolbar** — the bar that sits under a page's title on
+list/content pages (Favorites, Personal Space, Recents, Collections…). Ported to
+MUI from a reference design so the same bar is reusable and consistent across
+pages and projects.
+
+## Anatomy
+
+```
+[Select All] [Clear All] | N items selected  <actions>      (o)══  ▦▾   Sort By: … ▾   Content Type: … ▾   ⨏
+└──────────────── 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.
+- **Right cluster** — a free `rightControls` node. Compose it from the shipped
+  controls below (or anything else).
+
+## Components
+
+| Component | Purpose |
+| --- | --- |
+| `ContentToolbar` | The bar shell (selection chrome + `rightControls` slot). |
+| `ViewSelector` | Grid/List dropdown + a card-size zoom `Slider` (grid mode only). |
+| `SortByDropdown` | "Sort By:" trigger with **Order** + **Sort** menu sections; generic over the field type. |
+| `MultiSelectDropdown` | Checkbox multi-select with counts, an optional "Options" section, and a Clear action (e.g. "Content Type"). |
+| `FilterTrigger` | Funnel toggle button with an active-filters indicator dot. |
+
+## Usage
+
+```tsx
+import {
+  ContentToolbar,
+  ViewSelector,
+  SortByDropdown,
+  MultiSelectDropdown,
+  FilterTrigger,
+} from '@12-apps/ui/layout/ContentToolbar';
+
+<ContentToolbar
+  hasSelection={selected.size > 0}
+  selectedCount={selected.size}
+  selectAll={selectAll}
+  clearSelection={clear}
+  actions={<DeleteButton />}
+  rightControls={
+    <>
+      <ViewSelector viewMode={view} onViewModeChange={setView} zoom={zoom} onZoomChange={setZoom} />
+      <SortByDropdown fields={FIELDS} activeField={field} activeOrder={order} onFieldChange={setField} onOrderChange={setOrder} />
+      <MultiSelectDropdown label="Content Type" options={types} selected={typeSet} onToggle={toggle} onClear={clearTypes} />
+      <FilterTrigger open={panelOpen} onOpenChange={setPanelOpen} hasActiveFilters={hasFilters} />
+    </>
+  }
+/>;
+```
+
+## Notes
+
+- **Generic & agnostic** — the toolbar knows nothing about your domain. The
+  reference's built-in "content-item actions" dropdown is intentionally *not*
+  ported; pass whatever you need through the `actions` slot instead.
+- **`SortByDropdown`** hides its Order section when the active field defines no
+  `orderOptions`. `triggerLabelStyle: 'range'` renders "Size (large–small)" and
+  drops the direction arrow; the default `'single'` shows e.g. "Name (a–z) ↓".
+- **`MultiSelectDropdown`** keeps its menu open while toggling; empty *or* full
+  selection both display `allLabel` (default "All").
+- **`edgeAlign`** trims the leading/trailing button padding so the bar aligns
+  flush inside a padded (`px-N`) wrapper.
+
+## Accessibility
+
+Triggers expose `aria-haspopup`/`aria-expanded`; the filter funnel toggles
+`aria-expanded` and has an open/close `aria-label`. Menus are keyboard-navigable
+and focus-trapped by MUI.

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

@@ -0,0 +1,129 @@
+import { Box, Button, Typography } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+
+import { ContentToolbar } from './ContentToolbar';
+import { FilterTrigger } from './FilterTrigger';
+import { MultiSelectDropdown } from './MultiSelectDropdown';
+import { SortByDropdown } from './SortByDropdown';
+import { ViewSelector } from './ViewSelector';
+import type { SortFieldDefinition, ViewMode } from './ContentToolbar.types';
+
+const meta: Meta<typeof ContentToolbar> = {
+  title: 'Layout/ContentToolbar',
+  component: ContentToolbar,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Shared content-page toolbar (Favorites / Personal Space / Recents style): a Select All / Clear All / count / actions cluster on the left and a free `rightControls` slot on the right. Ships with `ViewSelector`, `SortByDropdown`, `MultiSelectDropdown` and `FilterTrigger` to compose that slot.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const SORT_FIELDS: SortFieldDefinition[] = [
+  {
+    value: 'size',
+    label: 'Size',
+    triggerLabelStyle: 'range',
+    orderOptions: [
+      { value: 'large', label: 'Large' },
+      { value: 'small', label: 'Small' },
+    ],
+  },
+  {
+    value: 'name',
+    label: 'Name',
+    orderOptions: [
+      { value: 'asc', label: 'A–Z' },
+      { value: 'desc', label: 'Z–A' },
+    ],
+  },
+  { value: 'modified', label: 'Modified', showOrderInTrigger: false },
+];
+
+const CONTENT_TYPES = [
+  { value: 'workbooks', label: 'Workbooks', count: 12 },
+  { value: 'views', label: 'Views', count: 8 },
+  { value: 'datasources', label: 'Data Sources', count: 3 },
+];
+
+/** A full reference toolbar with page title/description above it. */
+function ToolbarHarness({ withSelection }: { withSelection: boolean }): React.JSX.Element {
+  const [view, setView] = useState<ViewMode>('grid');
+  const [zoom, setZoom] = useState<number[]>([50]);
+  const [sortField, setSortField] = useState('size');
+  const [sortOrder, setSortOrder] = useState('large');
+  const [types, setTypes] = useState<Set<string>>(new Set());
+  const [panelOpen, setPanelOpen] = useState(false);
+  const [selected, setSelected] = useState<Set<string>>(withSelection ? new Set(['a', 'b']) : new Set());
+
+  return (
+    <Box sx={{ maxWidth: 1100 }}>
+      <Box sx={{ borderBottom: 1, borderColor: 'divider', pb: 2, mb: 2 }}>
+        <Typography variant="h5" sx={{ fontWeight: 600 }}>
+          Favorites
+        </Typography>
+        <Typography sx={{ fontSize: '0.875rem', color: 'text.secondary', mt: 0.5 }}>
+          Drag and drop items in grid view to reorder your favorites. Access your custom order using the Sort By menu.
+        </Typography>
+      </Box>
+      <ContentToolbar
+        hasSelection={selected.size > 0}
+        selectedCount={selected.size}
+        selectAll={() => setSelected(new Set(['a', 'b', 'c', 'd']))}
+        clearSelection={() => setSelected(new Set())}
+        selectAllTestId="fav-select-all"
+        clearAllTestId="fav-clear-all"
+        actions={
+          <Button variant="text" size="small" color="inherit" sx={{ textTransform: 'none' }}>
+            Delete
+          </Button>
+        }
+        rightControls={
+          <>
+            <ViewSelector viewMode={view} onViewModeChange={setView} zoom={zoom} onZoomChange={setZoom} />
+            <SortByDropdown
+              fields={SORT_FIELDS}
+              activeField={sortField}
+              activeOrder={sortOrder}
+              onFieldChange={setSortField}
+              onOrderChange={setSortOrder}
+              data-testid="sort-trigger"
+            />
+            <MultiSelectDropdown
+              label="Content Type"
+              options={CONTENT_TYPES}
+              selected={types}
+              onToggle={(value, checked) =>
+                setTypes((prev) => {
+                  const next = new Set(prev);
+                  if (checked) next.add(value);
+                  else next.delete(value);
+                  return next;
+                })
+              }
+              onClear={() => setTypes(new Set())}
+              data-testid="content-type-trigger"
+            />
+            <FilterTrigger open={panelOpen} onOpenChange={setPanelOpen} hasActiveFilters={types.size > 0} />
+          </>
+        }
+      />
+    </Box>
+  );
+}
+
+export const Default: Story = {
+  render: () => <ToolbarHarness withSelection={false} />,
+};
+
+export const WithSelection: Story = {
+  render: () => <ToolbarHarness withSelection />,
+};

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

@@ -0,0 +1,251 @@
+import { Box } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+import { useState } from 'react';
+
+import { ContentToolbar } from './ContentToolbar';
+import { FilterTrigger } from './FilterTrigger';
+import { MultiSelectDropdown } from './MultiSelectDropdown';
+import { SortByDropdown } from './SortByDropdown';
+import type { SortFieldDefinition } from './ContentToolbar.types';
+
+const meta: Meta<typeof ContentToolbar> = {
+  title: 'Layout/ContentToolbar/Tests',
+  component: ContentToolbar,
+  parameters: { layout: 'padded', chromatic: { disableSnapshot: false } },
+  tags: ['autodocs', 'test', 'component:ContentToolbar', 'checked'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const SORT_FIELDS: SortFieldDefinition[] = [
+  {
+    value: 'name',
+    label: 'Name',
+    orderOptions: [
+      { value: 'asc', label: 'A–Z' },
+      { value: 'desc', label: 'Z–A' },
+    ],
+  },
+  { value: 'modified', label: 'Modified', showOrderInTrigger: false },
+];
+
+const CONTENT_TYPES = [
+  { value: 'workbooks', label: 'Workbooks', count: 12 },
+  { value: 'views', label: 'Views', count: 8 },
+];
+
+export const SelectAndClear: Story = {
+  name: '🧪 Select All → selection chrome → Clear All',
+  render: () => {
+    const [selected, setSelected] = useState<Set<string>>(new Set());
+    return (
+      <ContentToolbar
+        hasSelection={selected.size > 0}
+        selectedCount={selected.size}
+        selectAll={() => setSelected(new Set(['a', 'b', 'c']))}
+        clearSelection={() => setSelected(new Set())}
+        selectAllTestId="t-select-all"
+        clearAllTestId="t-clear-all"
+        rightControls={<Box data-testid="right-slot">right</Box>}
+      />
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('No selection: no count indicator', async () => {
+      await waitFor(() => expect(canvas.queryByTestId('selected-count-indicator')).not.toBeInTheDocument());
+    });
+    await step('Select All shows count + Clear All', async () => {
+      await userEvent.click(canvas.getByTestId('t-select-all'));
+      await waitFor(() => expect(canvas.getByTestId('selected-count-indicator')).toHaveTextContent('3 items selected'));
+      await expect(canvas.getByTestId('t-clear-all')).toBeVisible();
+    });
+    await step('Clear All resets', async () => {
+      await userEvent.click(canvas.getByTestId('t-clear-all'));
+      await waitFor(() => expect(canvas.queryByTestId('selected-count-indicator')).not.toBeInTheDocument());
+    });
+  },
+};
+
+export const SortByInteraction: Story = {
+  name: '🧪 Sort By opens and changes field',
+  render: () => {
+    const onField = fn();
+    const [field, setField] = useState('name');
+    return (
+      <ContentToolbar
+        hasSelection={false}
+        selectedCount={0}
+        selectAll={fn()}
+        clearSelection={fn()}
+        rightControls={
+          <SortByDropdown
+            fields={SORT_FIELDS}
+            activeField={field}
+            activeOrder="asc"
+            onFieldChange={(value) => {
+              onField(value);
+              setField(value);
+            }}
+            onOrderChange={fn()}
+            data-testid="sort-trigger"
+          />
+        }
+      />
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Open the Sort By menu', async () => {
+      await userEvent.click(canvas.getByTestId('sort-trigger'));
+      await waitFor(() => expect(within(document.body).getByTestId('sort-modified-option')).toBeVisible());
+    });
+    await step('Pick Modified', async () => {
+      await userEvent.click(within(document.body).getByTestId('sort-modified-option'));
+      await waitFor(() => expect(canvas.getByTestId('sort-trigger')).toHaveTextContent('Modified'));
+    });
+  },
+};
+
+export const ContentTypeMultiSelect: Story = {
+  name: '🧪 Content Type toggles stay open',
+  render: () => {
+    const [types, setTypes] = useState<Set<string>>(new Set());
+    return (
+      <ContentToolbar
+        hasSelection={false}
+        selectedCount={0}
+        selectAll={fn()}
+        clearSelection={fn()}
+        rightControls={
+          <MultiSelectDropdown
+            label="Content Type"
+            options={CONTENT_TYPES}
+            selected={types}
+            onToggle={(value, checked) =>
+              setTypes((prev) => {
+                const next = new Set(prev);
+                if (checked) next.add(value);
+                else next.delete(value);
+                return next;
+              })
+            }
+            onClear={() => setTypes(new Set())}
+            data-testid="content-type-trigger"
+          />
+        }
+      />
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const body = within(document.body);
+    await step('Open and select one type; menu stays open; trigger reflects it', async () => {
+      await userEvent.click(canvas.getByTestId('content-type-trigger'));
+      await waitFor(() => expect(body.getByText('Workbooks')).toBeVisible());
+      await userEvent.click(body.getByText('Workbooks'));
+      await waitFor(() => expect(canvas.getByTestId('content-type-trigger')).toHaveTextContent('Workbooks'));
+      // Menu is still open (multi-select), so the Clear control is present.
+      await expect(body.getByTestId('content-type-trigger-clear')).toBeVisible();
+    });
+  },
+};
+
+const CATEGORY_TYPES = [
+  { value: 'bebidas', label: 'Bebidas', count: 12 },
+  { value: 'sobremesas', label: 'Sobremesas', count: 8 },
+  { value: 'lanches', label: 'Lanches', count: 23 },
+  { value: 'saladas', label: 'Saladas', count: 5 },
+  { value: 'massas', label: 'Massas', count: 9 },
+  { value: 'carnes', label: 'Carnes', count: 14 },
+  { value: 'peixes', label: 'Peixes', count: 3 },
+  { value: 'vegano', label: 'Vegano', count: 7 },
+  { value: 'infantil', label: 'Infantil', count: 4 },
+];
+
+export const MultiSelectSearch: Story = {
+  name: '🧪 Long list auto-shows search + filters options',
+  render: () => {
+    const [types, setTypes] = useState<Set<string>>(new Set());
+    return (
+      <ContentToolbar
+        hasSelection={false}
+        selectedCount={0}
+        selectAll={fn()}
+        clearSelection={fn()}
+        rightControls={
+          <MultiSelectDropdown
+            label="Categoria"
+            options={CATEGORY_TYPES}
+            selected={types}
+            onToggle={(value, checked) =>
+              setTypes((prev) => {
+                const next = new Set(prev);
+                if (checked) next.add(value);
+                else next.delete(value);
+                return next;
+              })
+            }
+            onClear={() => setTypes(new Set())}
+            allLabel="Todas"
+            searchPlaceholder="Buscar…"
+            noResultsLabel="Nenhum resultado"
+            data-testid="category-trigger"
+          />
+        }
+      />
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const body = within(document.body);
+    await step('Open: 9 options auto-render a search box', async () => {
+      await userEvent.click(canvas.getByTestId('category-trigger'));
+      await waitFor(() => expect(body.getByTestId('category-trigger-search')).toBeVisible());
+      await expect(body.getByText('Sobremesas')).toBeVisible();
+      await expect(body.getByText('Lanches')).toBeVisible();
+    });
+    await step('Typing filters the list case-insensitively', async () => {
+      await userEvent.type(body.getByTestId('category-trigger-search'), 'sobre');
+      await waitFor(() => expect(body.queryByText('Lanches')).not.toBeInTheDocument());
+      await expect(body.getByText('Sobremesas')).toBeVisible();
+    });
+    await step('Selecting a filtered option keeps the menu open', async () => {
+      await userEvent.click(body.getByText('Sobremesas'));
+      await waitFor(() => expect(canvas.getByTestId('category-trigger')).toHaveTextContent('Sobremesas'));
+      await expect(body.getByTestId('category-trigger-search')).toBeVisible();
+    });
+    await step('A non-matching query shows the empty state', async () => {
+      await userEvent.clear(body.getByTestId('category-trigger-search'));
+      await userEvent.type(body.getByTestId('category-trigger-search'), 'zzz');
+      await waitFor(() => expect(body.getByTestId('category-trigger-no-results')).toBeVisible());
+    });
+  },
+};
+
+export const FilterTriggerActiveDot: Story = {
+  name: '🧪 Filter trigger toggles + shows active dot',
+  render: () => {
+    const [open, setOpen] = useState(false);
+    return (
+      <ContentToolbar
+        hasSelection={false}
+        selectedCount={0}
+        selectAll={fn()}
+        clearSelection={fn()}
+        rightControls={<FilterTrigger open={open} onOpenChange={setOpen} hasActiveFilters data-testid="filter-btn" />}
+      />
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Toggle opens the filter', async () => {
+      const btn = canvas.getByTestId('filter-btn');
+      await expect(btn).toHaveAttribute('aria-expanded', 'false');
+      await userEvent.click(btn);
+      await waitFor(() => expect(canvas.getByTestId('filter-btn')).toHaveAttribute('aria-expanded', 'true'));
+    });
+  },
+};