@12-apps/ui 1.0.0

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

@@ -0,0 +1,87 @@
+import { Box } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+import { useState } from 'react';
+
+import { FilterTrigger } from '../ContentToolbar/FilterTrigger';
+import { TableFilter } from './TableFilter';
+import type { TableFilterRange } from './TableFilter.types';
+
+const meta: Meta<typeof TableFilter> = {
+  title: 'Layout/TableFilter/Tests',
+  component: TableFilter,
+  parameters: { layout: 'fullscreen', chromatic: { disableSnapshot: false } },
+  tags: ['autodocs', 'test', 'component:TableFilter', 'checked'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const CATEGORIES = [
+  { value: 'drinks', label: 'Drinks' },
+  { value: 'snacks', label: 'Snacks' },
+];
+
+function Harness(): React.JSX.Element {
+  const [open, setOpen] = useState(false);
+  const [cats, setCats] = useState<Set<string>>(new Set());
+  const [price, setPrice] = useState<TableFilterRange>({});
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', height: 360 }}>
+      <FilterTrigger open={open} onOpenChange={setOpen} hasActiveFilters={cats.size > 0} data-testid="funnel" />
+      <TableFilter open={open} onOpenChange={setOpen} hasActiveFilters={cats.size > 0}>
+        <TableFilter.Layout>
+          <TableFilter.Main>
+            <Box data-testid="main">main</Box>
+          </TableFilter.Main>
+          <TableFilter.Panel onClearAll={() => setCats(new Set())} clearTestId="clear-all">
+            <TableFilter.Section title="Attributes">
+              <TableFilter.CheckboxField
+                label="Category"
+                options={CATEGORIES}
+                selected={cats}
+                onToggle={(value, checked) =>
+                  setCats((prev) => {
+                    const next = new Set(prev);
+                    if (checked) next.add(value);
+                    else next.delete(value);
+                    return next;
+                  })
+                }
+                testId="cat-field"
+              />
+              <TableFilter.RangeField label="Price" value={price} onChange={setPrice} testId="price-range" />
+            </TableFilter.Section>
+          </TableFilter.Panel>
+        </TableFilter.Layout>
+      </TableFilter>
+    </Box>
+  );
+}
+
+export const OpenPanelAndFilter: Story = {
+  name: '🧪 Funnel opens panel; checkbox + range work',
+  render: () => <Harness />,
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    await step('Funnel toggles the panel open', async () => {
+      await expect(canvas.getByTestId('funnel')).toHaveAttribute('aria-expanded', 'false');
+      await userEvent.click(canvas.getByTestId('funnel'));
+      await waitFor(() => expect(canvas.getByTestId('funnel')).toHaveAttribute('aria-expanded', 'true'));
+    });
+    await step('Toggle a category checkbox', async () => {
+      const drinks = canvas.getByTestId('cat-field-drinks').querySelector('input')!;
+      await userEvent.click(drinks);
+      await waitFor(() => expect(drinks).toBeChecked());
+    });
+    await step('Type a min price', async () => {
+      const min = canvas.getByTestId('price-range-min');
+      await userEvent.type(min, '10');
+      await waitFor(() => expect(min).toHaveValue(10));
+    });
+    await step('Clear All Filters resets the checkbox', async () => {
+      await userEvent.click(canvas.getByTestId('clear-all'));
+      await waitFor(() => expect(canvas.getByTestId('cat-field-drinks').querySelector('input')).not.toBeChecked());
+    });
+  },
+};

package/src/components/layout/TableFilter/TableFilter.tsx

@@ -0,0 +1,383 @@
+'use client';
+
+import { Close as CloseIcon, Search as SearchIcon } from '@mui/icons-material';
+import {
+  Box,
+  Checkbox,
+  Divider,
+  FormControlLabel,
+  IconButton,
+  InputAdornment,
+  Link,
+  TextField,
+  Typography,
+} from '@mui/material';
+import React, { useRef, useState } from 'react';
+
+import { TableFilterContext, useTableFilterContext } from './TableFilterContext';
+import type {
+  TableFilterCheckboxFieldProps,
+  TableFilterKeywordProps,
+  TableFilterLayoutProps,
+  TableFilterMainProps,
+  TableFilterPanelProps,
+  TableFilterProps,
+  TableFilterRangeFieldProps,
+  TableFilterSectionProps,
+} from './TableFilter.types';
+
+const PANEL_WIDTH = 280;
+
+/**
+ * Compound filter-panel system, MUI port of the reference `TableFilter`. Provides
+ * open/close state; `Panel` slides in from the right beside `Main` (no overlap).
+ *
+ * @example
+ * ```tsx
+ * <TableFilter open={open} onOpenChange={setOpen} hasActiveFilters={n > 0}>
+ *   <TableFilter.Layout>
+ *     <TableFilter.Main>{table}</TableFilter.Main>
+ *     <TableFilter.Panel onClearAll={clearAll}>
+ *       <TableFilter.Keyword value={q} onChange={setQ} />
+ *       <TableFilter.Section title="Attributes">
+ *         <TableFilter.CheckboxField label="Category" options={cats} selected={sel} onToggle={toggle} />
+ *         <TableFilter.RangeField label="Price" unit="R$" value={price} onChange={setPrice} />
+ *       </TableFilter.Section>
+ *     </TableFilter.Panel>
+ *   </TableFilter.Layout>
+ * </TableFilter>
+ * ```
+ */
+export function TableFilter({
+  children,
+  open,
+  onOpenChange,
+  hasActiveFilters = false,
+}: TableFilterProps): React.JSX.Element {
+  return (
+    <TableFilterContext.Provider value={{ open, onOpenChange, hasActiveFilters }}>
+      {children}
+    </TableFilterContext.Provider>
+  );
+}
+TableFilter.displayName = 'TableFilter';
+
+const TableFilterLayout = ({ children, className }: TableFilterLayoutProps): React.JSX.Element => {
+  const { open } = useTableFilterContext();
+  return (
+    <Box
+      className={className}
+      sx={{
+        display: 'flex',
+        minHeight: 0,
+        minWidth: 0,
+        flex: 1,
+        alignItems: 'stretch',
+        overflow: 'hidden',
+        gap: open ? 2 : 0,
+      }}
+    >
+      {children}
+    </Box>
+  );
+};
+TableFilterLayout.displayName = 'TableFilter.Layout';
+
+const TableFilterMain = ({ children, className }: TableFilterMainProps): React.JSX.Element => (
+  <Box className={className} sx={{ minWidth: 0, flex: 1, overflowY: 'auto', overflowX: 'hidden' }}>
+    {children}
+  </Box>
+);
+TableFilterMain.displayName = 'TableFilter.Main';
+
+const TableFilterPanel = ({
+  children,
+  onClearAll,
+  ariaLabel = 'Filters',
+  clearTestId,
+}: TableFilterPanelProps): React.JSX.Element => {
+  const { open } = useTableFilterContext();
+  return (
+    <Box
+      component="aside"
+      aria-label={ariaLabel}
+      aria-hidden={!open}
+      sx={{
+        display: 'flex',
+        minHeight: 0,
+        flexShrink: 0,
+        flexDirection: 'column',
+        alignSelf: 'stretch',
+        overflow: 'hidden',
+        bgcolor: 'background.paper',
+        width: open ? PANEL_WIDTH : 0,
+        borderLeft: open ? 1 : 0,
+        borderColor: 'divider',
+        transition: 'width 300ms ease-in-out',
+        '@media (prefers-reduced-motion: reduce)': { transition: 'none' },
+      }}
+    >
+      <Box
+        sx={{
+          display: 'flex',
+          minHeight: 0,
+          flex: 1,
+          flexDirection: 'column',
+          overflowY: 'auto',
+          overflowX: 'hidden',
+          visibility: open ? 'visible' : 'hidden',
+          opacity: open ? 1 : 0,
+          pointerEvents: open ? 'auto' : 'none',
+          transition: 'opacity 200ms ease-out',
+        }}
+      >
+        <Box sx={{ boxSizing: 'border-box', display: 'flex', width: '100%', minWidth: 0, flexDirection: 'column', gap: 2.5, p: 2 }}>
+          <Box sx={{ display: 'flex', justifyContent: 'flex-end' }}>
+            <Link
+              component="button"
+              type="button"
+              underline="hover"
+              data-testid={clearTestId}
+              onClick={onClearAll}
+              sx={{ fontSize: '0.75rem', color: 'text.secondary' }}
+            >
+              Clear All Filters
+            </Link>
+          </Box>
+          {children}
+        </Box>
+      </Box>
+    </Box>
+  );
+};
+TableFilterPanel.displayName = 'TableFilter.Panel';
+
+const TableFilterKeyword = ({
+  value,
+  onChange,
+  placeholder = 'Press Enter to filter',
+  label = 'Filter by keyword',
+  testId,
+}: TableFilterKeywordProps): React.JSX.Element => {
+  const [draft, setDraft] = useState(value);
+  const prevValue = useRef(value);
+  if (prevValue.current !== value) {
+    prevValue.current = value;
+    if (draft !== value) setDraft(value);
+  }
+
+  const commit = (): void => {
+    if (draft !== value) onChange(draft);
+  };
+  const clearKeyword = (): void => {
+    setDraft('');
+    if (value !== '') onChange('');
+  };
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1 }}>
+      <Typography component="label" sx={{ fontSize: '0.75rem', fontWeight: 500, color: 'text.secondary' }}>
+        {label}
+      </Typography>
+      <TextField
+        size="small"
+        name="keyword"
+        placeholder={placeholder}
+        value={draft}
+        onChange={(event) => setDraft(event.target.value)}
+        onBlur={commit}
+        onKeyDown={(event) => {
+          if (event.key !== 'Enter') return;
+          event.preventDefault();
+          commit();
+        }}
+        inputProps={{ 'aria-label': label, 'data-testid': testId }}
+        InputProps={{
+          startAdornment: (
+            <InputAdornment position="start">
+              <SearchIcon sx={{ fontSize: 16, color: 'text.secondary' }} />
+            </InputAdornment>
+          ),
+          endAdornment:
+            draft !== '' ? (
+              <InputAdornment position="end">
+                <IconButton
+                  size="small"
+                  aria-label="Clear keyword filter"
+                  data-testid={testId ? `${testId}-clear` : undefined}
+                  onMouseDown={(event) => event.preventDefault()}
+                  onClick={clearKeyword}
+                >
+                  <CloseIcon sx={{ fontSize: 16 }} />
+                </IconButton>
+              </InputAdornment>
+            ) : null,
+        }}
+      />
+    </Box>
+  );
+};
+TableFilterKeyword.displayName = 'TableFilter.Keyword';
+
+const TableFilterSection = ({ title, children }: TableFilterSectionProps): React.JSX.Element => (
+  <Box>
+    <Divider sx={{ mb: 2.5 }} />
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1.5 }}>
+      <Typography component="h2" sx={{ fontSize: '0.875rem', fontWeight: 600, color: 'text.primary' }}>
+        {title}
+      </Typography>
+      <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>{children}</Box>
+    </Box>
+  </Box>
+);
+TableFilterSection.displayName = 'TableFilter.Section';
+
+function TableFilterCheckboxField<TValue extends string = string>({
+  label,
+  options,
+  selected,
+  onToggle,
+  testId,
+}: TableFilterCheckboxFieldProps<TValue>): React.JSX.Element {
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1 }} data-testid={testId}>
+      <Typography sx={{ fontSize: '0.75rem', fontWeight: 500, color: 'text.secondary' }}>{label}</Typography>
+      <Box sx={{ display: 'flex', flexDirection: 'column' }}>
+        {options.map((option) => {
+          const checked = selected.has(option.value);
+          return (
+            <FormControlLabel
+              key={option.value}
+              control={
+                <Checkbox
+                  size="small"
+                  checked={checked}
+                  onChange={(event) => onToggle(option.value, event.target.checked)}
+                  data-testid={testId ? `${testId}-${option.value}` : undefined}
+                  sx={{ py: 0.25 }}
+                />
+              }
+              label={
+                <Box component="span" sx={{ fontSize: '0.875rem' }}>
+                  {option.label}
+                  {option.count != null && (
+                    <Box component="span" sx={{ color: 'text.secondary' }}>
+                      {' '}
+                      ({option.count})
+                    </Box>
+                  )}
+                </Box>
+              }
+              sx={{ ml: -0.5, mr: 0 }}
+            />
+          );
+        })}
+      </Box>
+    </Box>
+  );
+}
+TableFilterCheckboxField.displayName = 'TableFilter.CheckboxField';
+
+function parseBound(text: string): number | undefined {
+  if (text.trim() === '') return undefined;
+  const parsed = Number(text);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+/** One numeric bound input (min or max) for {@link TableFilterRangeField}. */
+function RangeBound({
+  bound,
+  error,
+  placeholder,
+  step,
+  ariaLabel,
+  testId,
+  onChange,
+}: {
+  bound: number | undefined;
+  error: boolean;
+  placeholder: string;
+  step?: number;
+  ariaLabel: string;
+  testId?: string;
+  onChange: (next: number | undefined) => void;
+}): React.JSX.Element {
+  return (
+    <TextField
+      size="small"
+      type="number"
+      error={error}
+      placeholder={placeholder}
+      value={bound != null ? String(bound) : ''}
+      onChange={(event) => onChange(parseBound(event.target.value))}
+      inputProps={{ step, 'aria-label': ariaLabel, 'data-testid': testId }}
+    />
+  );
+}
+
+/** Inverted range: both ends set and max < min (surfaced to the user as an error). */
+const isRangeInverted = (value: { min?: number; max?: number }): boolean =>
+  value.min != null && value.max != null && value.max < value.min;
+
+const TableFilterRangeField = ({
+  label,
+  value,
+  onChange,
+  unit,
+  step,
+  minPlaceholder = 'min',
+  maxPlaceholder = 'max',
+  invalidLabel = 'O máximo deve ser maior ou igual ao mínimo.',
+  testId,
+}: TableFilterRangeFieldProps): React.JSX.Element => {
+  const invalid = isRangeInverted(value);
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1 }} data-testid={testId}>
+      <Typography sx={{ fontSize: '0.75rem', fontWeight: 500, color: 'text.secondary' }}>
+        {label}
+        {unit ? ` (${unit})` : ''}
+      </Typography>
+      <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+        <RangeBound
+          bound={value.min}
+          error={invalid}
+          placeholder={minPlaceholder}
+          step={step}
+          ariaLabel={`${label} ${minPlaceholder}`}
+          testId={testId ? `${testId}-min` : undefined}
+          onChange={(min) => onChange({ ...value, min })}
+        />
+        <Typography component="span" sx={{ color: 'text.secondary' }}>
+          –
+        </Typography>
+        <RangeBound
+          bound={value.max}
+          error={invalid}
+          placeholder={maxPlaceholder}
+          step={step}
+          ariaLabel={`${label} ${maxPlaceholder}`}
+          testId={testId ? `${testId}-max` : undefined}
+          onChange={(max) => onChange({ ...value, max })}
+        />
+      </Box>
+      {invalid && (
+        <Typography
+          role="alert"
+          data-testid={testId ? `${testId}-error` : undefined}
+          sx={{ fontSize: '0.7rem', color: 'error.main' }}
+        >
+          {invalidLabel}
+        </Typography>
+      )}
+    </Box>
+  );
+};
+TableFilterRangeField.displayName = 'TableFilter.RangeField';
+
+TableFilter.Layout = TableFilterLayout;
+TableFilter.Main = TableFilterMain;
+TableFilter.Panel = TableFilterPanel;
+TableFilter.Keyword = TableFilterKeyword;
+TableFilter.Section = TableFilterSection;
+TableFilter.CheckboxField = TableFilterCheckboxField;
+TableFilter.RangeField = TableFilterRangeField;

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

@@ -0,0 +1,87 @@
+import type { ReactNode } from 'react';
+
+/** Props for the `<TableFilter>` root (provider). */
+export interface TableFilterProps {
+  children: ReactNode;
+  /** Whether the panel is open. */
+  open: boolean;
+  /** Toggle the panel. */
+  onOpenChange: (open: boolean) => void;
+  /** Shows a filled dot on the trigger when filters are active. */
+  hasActiveFilters?: boolean;
+}
+
+/** Props for `<TableFilter.Layout>`. */
+export interface TableFilterLayoutProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/** Props for `<TableFilter.Main>`. */
+export interface TableFilterMainProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/** Props for `<TableFilter.Panel>`. */
+export interface TableFilterPanelProps {
+  children: ReactNode;
+  /** Clears every filter. Rendered as the panel's "Clear All Filters" link. */
+  onClearAll: () => void;
+  /** Accessible label for the panel `<aside>`. */
+  ariaLabel?: string;
+  clearTestId?: string;
+}
+
+/** Props for `<TableFilter.Keyword>`. */
+export interface TableFilterKeywordProps {
+  value: string;
+  /** Committed on blur or Enter (not on every keystroke). */
+  onChange: (value: string) => void;
+  placeholder?: string;
+  label?: string;
+  testId?: string;
+}
+
+/** Props for `<TableFilter.Section>`. */
+export interface TableFilterSectionProps {
+  title: string;
+  children: ReactNode;
+}
+
+/** A checkbox option for `<TableFilter.CheckboxField>`. */
+export interface TableFilterCheckboxOption<TValue extends string = string> {
+  value: TValue;
+  label: string;
+  count?: number;
+}
+
+/** Props for `<TableFilter.CheckboxField>` — a labelled multi-select group. */
+export interface TableFilterCheckboxFieldProps<TValue extends string = string> {
+  label: string;
+  options: TableFilterCheckboxOption<TValue>[];
+  selected: ReadonlySet<TValue>;
+  onToggle: (value: TValue, checked: boolean) => void;
+  testId?: string;
+}
+
+/** A numeric min/max range value. */
+export interface TableFilterRange {
+  min?: number;
+  max?: number;
+}
+
+/** Props for `<TableFilter.RangeField>` — a labelled min/max pair. */
+export interface TableFilterRangeFieldProps {
+  label: string;
+  value: TableFilterRange;
+  onChange: (range: TableFilterRange) => void;
+  /** Optional unit suffix (e.g. "R$", "un"). */
+  unit?: string;
+  step?: number;
+  minPlaceholder?: string;
+  maxPlaceholder?: string;
+  /** Error text shown when the range is inverted (max < min). */
+  invalidLabel?: string;
+  testId?: string;
+}

package/src/components/layout/TableFilter/TableFilterContext.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+/** Open/close + active state shared by every `TableFilter` compound part. */
+export interface TableFilterContextValue {
+  /** Whether the filter panel is expanded. */
+  open: boolean;
+  /** Toggle the panel open/closed. */
+  onOpenChange: (open: boolean) => void;
+  /** When true, the trigger shows a filled indicator dot. */
+  hasActiveFilters: boolean;
+}
+
+/** Backing context. `null` outside a `<TableFilter>` root. */
+export const TableFilterContext = createContext<TableFilterContextValue | null>(null);
+
+/**
+ * Reads the nearest {@link TableFilterContext}.
+ *
+ * @throws If used outside `<TableFilter>`.
+ */
+export function useTableFilterContext(): TableFilterContextValue {
+  const context = useContext(TableFilterContext);
+  if (!context) {
+    throw new Error('TableFilter compound components must be rendered inside <TableFilter>');
+  }
+  return context;
+}

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

@@ -0,0 +1,15 @@
+export { TableFilter } from './TableFilter';
+export { TableFilterContext, useTableFilterContext } from './TableFilterContext';
+export type { TableFilterContextValue } from './TableFilterContext';
+export type {
+  TableFilterProps,
+  TableFilterLayoutProps,
+  TableFilterMainProps,
+  TableFilterPanelProps,
+  TableFilterKeywordProps,
+  TableFilterSectionProps,
+  TableFilterCheckboxOption,
+  TableFilterCheckboxFieldProps,
+  TableFilterRange,
+  TableFilterRangeFieldProps,
+} from './TableFilter.types';

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

@@ -0,0 +1,37 @@
+# TableFilter Test Status Tracking
+
+## Test Files Status
+
+- [x] TableFilter.test.stories.tsx created
+- [x] Core interaction covered
+
+## Storybook Tests Status
+
+### Test Results
+
+| Test Name                              | Status  | Pass/Fail | Notes                                        |
+| -------------------------------------- | ------- | --------- | -------------------------------------------- |
+| Funnel opens panel; checkbox + range   | Pending | -         | aria-expanded flips; checkbox + min work; Clear All resets |
+
+Legend: Pending | Running | PASS | FAIL
+
+## Static Stories Status
+
+- [x] Default (keyword + category checkbox + price range)
+
+## Lint Status
+
+- [ ] No lint errors
+- [ ] No warnings
+
+## TypeCheck Status
+
+- [ ] No type errors
+
+## Overall Component Status
+
+- [ ] All tests passing
+- [ ] Lint clean
+- [ ] TypeCheck clean
+- [ ] Stories working
+- [ ] Ready for production

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

@@ -0,0 +1,36 @@
+# TableFilter
+
+MUI port of the reference `TableFilter` compound panel. Provider + `Layout` /
+`Main` / `Panel` (slide-in aside) + field parts (`Keyword`, `Section`,
+`CheckboxField`, `RangeField`). Generic/agnostic — consumer owns filter state and
+row filtering. Pairs with `ContentToolbar`'s `FilterTrigger`.
+
+## Parts / props
+
+- **TableFilter** — open, onOpenChange, hasActiveFilters?.
+- **Layout / Main / Panel** — Panel: onClearAll, ariaLabel?, clearTestId?.
+- **Keyword** — value, onChange (blur/Enter), placeholder?, label?.
+- **Section** — title.
+- **CheckboxField** — label, options (value/label/count), selected (Set), onToggle.
+- **RangeField** — label, value {min,max}, onChange, unit?, step?.
+
+## Lint
+
+- Clean (`pnpm lint:files src/components/layout/TableFilter`).
+
+## Type Errors
+
+- None (`pnpm typecheck`).
+
+## Testing Scenarios
+
+- Funnel toggles panel; category checkbox; min-price range; Clear All resets.
+
+## Storybook Tests List
+
+- Layout/TableFilter/Tests → OpenPanelAndFilter.
+
+## Current
+
+- v1 ported. Next: replace the admin `FilterBar` on Products/Inventory/Suppliers
+  with `ContentToolbar` + this panel (Phase 2/3).

package/src/components/layout/index.ts

@@ -0,0 +1,14 @@
+export * from './Accordion';
+export * from './Card';
+export * from './Collapsible/Collapsible';
+export * from './Container';
+export * from './ContentToolbar';
+export * from './Dashboard';
+export * from './Drawer';
+export * from './Resizable';
+export * from './ScrollArea';
+export * from './Separator';
+export * from './Sidebar';
+export * from './Skeleton/Skeleton';
+export * from './TableFilter';
+export * from './Spacer/Spacer';