@uselets/ui 1.3.0 → 1.4.0

package/dist/skills/uselets-ui/SKILL.md

@@ -56,6 +56,7 @@ To set up a consumer project after installing `@uselets/ui`, run `bun uselets in
 - For toast usage, mount `Toaster` near the app root before calling `toast(...)`.
 - For package theme helpers, use `ThemeProvider`, `useTheme`, and `ModeToggle` from `@uselets/ui/theme` or the root barrel.
 - For form fields, `Field` automatically shares a generated control id with `FieldLabel` and labelable controls when explicit ids are omitted; pass explicit matching `htmlFor` and `id` only when a stable custom id is required.
+- For client-side tabular data, use `DataTable` from `@uselets/ui/data-table`. Defaults are bare: `enableRowSelection`, `enableSorting`, and `showPagination` are all `false`. Set `enableRowSelection` to auto-prepend the selection checkbox column (no need to add `createDataTableSelectColumn` manually); set `enableSorting` to make `DataTableColumnHeader` clickable for sort. `filterColumns` accepts a single id or an array; with 2+ ids the toolbar renders an `InputGroup` with a column selector on the left. `toolbarActions` always sits at the right of the toolbar. All labels default to pt-BR; override any subset through `labels` (`Partial<DataTableLabels>`), with full defaults exposed as `defaultDataTableLabels`. Use `variant` on `DataTable` (or directly on the base `Table`) to switch chrome: `"line"` (default) renders only horizontal separators between rows; `"outline"` adds a rounded outer border around the table. The base `Table` from `@uselets/ui/table` renders only the `<table>` element and is striped by default (pass `striped={false}` to disable). Wrap it in `TableContainer` to control scroll; `minWidth` lives on `TableContainer`. Combine `stickyHeader` on `Table` with `max-h` + `overflow-y-auto` on the `TableContainer` to keep the `<thead>` visible during vertical scroll. `DataTable` wraps its `Table` in `TableContainer` automatically.
 
 ## Quick Routing
 

package/dist/skills/uselets-ui/references/component-catalog.md

@@ -50,6 +50,10 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Import path: `@uselets/ui/hooks/use-local-storage`
   - Exports: `useLocalStorage`, `UseLocalStorageOptions`
   - Notes: returns a `[value, setValue]` tuple, stores values with JSON serialization, and syncs storage changes between browser tabs by default (`sync: true`)
+- `use-mask`
+  - Import path: `@uselets/ui/hooks/use-mask`
+  - Exports: `useMask`, `UseMaskOptions`, `MaskOptions`, `Replacement`, `Track`, `TrackingData`, `Modify`, `ModifiedData`
+  - Notes: thin wrapper over `@react-input/mask`'s `useMask` that defaults `replacement` to `{ 9: /\d/, a: /[A-Za-z]/, '*': /./ }`; returns a `MutableRefObject<HTMLInputElement>` to attach to any input. Consumers may override `replacement`.
 - `utils`
   - Import path: `@uselets/ui/utils`
   - Exports: `cn`, `randomId`
@@ -135,6 +139,9 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Notes: compose controls with prefixes, suffixes, or inline actions
 - `input-otp`
   - Exports: `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot`, `REGEXP_ONLY_CHARS`, `REGEXP_ONLY_DIGITS`, `REGEXP_ONLY_DIGITS_AND_CHARS`
+- `mask-input`
+  - Exports: `MaskInput`
+  - Notes: formatted input backed by `@react-input/mask`. Required prop `mask`; optional `replacement` (string or `Record<string, RegExp>`), `showMask`, `separate`, `track`, `modify`. Default replacement tokens are `9` (digit), `a` (letter), `*` (any). Renders the standard `Input`, so `Field`/`FieldLabel` and all native `<input>` props work as usual.
 - `checkbox`
   - Exports: `Checkbox`
   - Notes: supports `size: 'sm' | 'md' | 'lg'`, `color: UIColor` (default `primary`), `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; composed label text follows checkbox size (`sm` 12px, `md` 14px, `lg` 20px)
@@ -213,7 +220,20 @@ Unless noted otherwise, each module also exports its public `*Props` types from
 - `center`
   - Exports: `Center`, `centerVariants`
 - `chart`
-  - Exports: `Bar`, `BarChart`, `CartesianGrid`, `XAxis`, `ChartContainer`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `ChartTooltip`, `ChartTooltipContent`
+  - Exports: `ChartContainer`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `ChartTooltip`, `ChartTooltipContent`, `ChartConfig`
+  - Notes: low-level chart primitives. For app usage prefer the high-level `area-chart`, `bar-chart`, `pie-chart`, `donut-chart` modules. Import raw recharts primitives (`Bar`, `XAxis`, etc.) directly from `recharts` when composing with `ChartContainer`.
+- `area-chart`
+  - Exports: `AreaChart`, `AreaChartSeries`, `AreaChartType`, `AreaChartCurveType`, `AreaChartGridAxis`
+  - Notes: high-level area chart. Pass `data`, `series` (array of `{ name, label?, color? }`), and `dataKey` (X axis field). Supports `type` (default/stacked/percent/split), `curveType`, `withXAxis`, `withYAxis`, `gridAxis`, `withDots`, `withTooltip`, `withLegend`. Defaults to chart colors `--chart-1..5`.
+- `bar-chart`
+  - Exports: `BarChart`, `BarChartSeries`, `BarChartType`, `BarChartOrientation`, `BarChartGridAxis`
+  - Notes: high-level bar chart. Same shape as `area-chart` plus `orientation` (vertical/horizontal), `barSize`, `radius`. Supports stacked and percent types.
+- `pie-chart`
+  - Exports: `PieChart`, `PieChartBase`, `PieChartDatum`, `buildPieConfig`
+  - Notes: high-level pie chart. Pass `data` as `Array<{ name, value, color? }>`. Supports `withLabels`, `labelsPosition`, `startAngle`, `endAngle`, `paddingAngle`, `withLegend`, `withTooltip`. `PieChartBase` is the shared internal renderer used by `donut-chart`.
+- `donut-chart`
+  - Exports: `DonutChart`
+  - Notes: same data shape as `pie-chart`. Adds `thickness` (donut hole size in px) and `withTotal` + `totalLabel` (renders sum in the center).
 - `collapsible`
   - Exports: `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`
 - `container`
@@ -223,7 +243,7 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Notes: generic flexbox layout primitive. Supports `direction: 'row' | 'row-reverse' | 'column' | 'column-reverse'`, `align: 'start' | 'end' | 'center' | 'baseline' | 'stretch'`, `justify: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'`, `wrap`, and `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`).
 - `group`
   - Exports: `Group`, `groupVariants`
-  - Notes: supports `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`) and `wrap`
+  - Notes: horizontal row primitive. Supports `align: 'start' | 'end' | 'center' | 'baseline' | 'stretch'` (default `center`), `justify: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'`, `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`), and `wrap`
 - `kbd`
   - Exports: `Kbd`, `KbdGroup`
 - `resizable`
@@ -234,9 +254,16 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `Separator`
 - `stack`
   - Exports: `Stack`, `stackVariants`
-  - Notes: supports `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`)
+  - Notes: vertical column primitive. Supports `align: 'start' | 'end' | 'center' | 'baseline' | 'stretch'`, `justify: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'`, and `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`)
 - `table`
-  - Exports: `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption`
+  - Exports: `Table`, `TableContainer`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption`, `tableVariants`
+  - Notes: `Table` renders only the `<table>` element (no auto wrapper); striped by default (`striped` prop, default `true`) and supports `stickyHeader`. `variant` (`"line"` default | `"outline"`) controls outer chrome — `"line"` has only horizontal separators between rows; `"outline"` adds a rounded outer border. Outline works standalone (chrome on the `<table>`) or wrapped in `TableContainer` (container detects `data-variant=outline` via `:has()`, applies the chrome on itself, and zeroes it on the `<table>` — keeps sticky headers from painting over the border). Wrap in `TableContainer` for horizontal scroll; `TableContainer` accepts `minWidth` (number in px or any CSS length). For sticky header, set `max-h` + `overflow-y-auto` on the `TableContainer` (via `className` or `style`)
+- `data-table`
+  - Exports: `DataTable`, `DataTableRoot`, `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, `DataTablePagination`, `DataTableColumnHeader`, `createDataTableSelectColumn`, `useDataTable`, `useDataTableContext`, `defaultDataTableLabels`, `DataTableLabels`, `UseDataTableOptions`, `DataTableRootProps`, `DataTableToolbarProps`
+  - Notes: dual API — high-level `DataTable` (monolithic, simple cases) and compound (`DataTableRoot` + sub-parts, power cases including virtualization). Both share the same underlying logic via `useDataTable`.
+  - **High-level `DataTable`:** client-side TanStack Table composition. Defaults are bare — `enableRowSelection`, `enableSorting`, `showPagination` all default to `false` and must be explicitly enabled. Setting `enableRowSelection` auto-prepends the selection column; setting `enableSorting` activates sort buttons in `DataTableColumnHeader`. `filterColumns` accepts `string | string[]`; with 2+ ids the toolbar renders an `InputGroup` with a column selector at the left. `toolbarActions` always renders at the right of the toolbar. `variant` (`"line"` default | `"outline"`) is forwarded to the internal `Table` — pass `"outline"` to wrap the table in a rounded border. All user-facing labels default to pt-BR and are overridable through the `labels` prop (`Partial<DataTableLabels>`)
+  - **Compound API:** `DataTableRoot` accepts either `{ columns, data, ...options }` (uncontrolled — creates the `table` instance internally) or `{ table }` (controlled — table instance comes from `useDataTable` called by the consumer). `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, and `DataTablePagination` read the `table` instance from context. `DataTableHeader` renders a full `<thead>`; `DataTableBody` renders a full `<tbody>` — to virtualize, omit `<DataTableBody />` and render your own `<tbody>` instead. `useDataTable(options)` is a thin wrapper around `useReactTable` that bakes in the same defaults `DataTable` uses (row models, selection auto-injection); pass `enablePagination: false` when virtualizing so `table.getRowModel()` returns all rows. `useDataTableContext<TData>()` retrieves the current `table` and merged `labels` inside a custom compound child
+  - **Virtualization:** the package is virtualizer-agnostic — it has zero runtime dependency on `@tanstack/react-virtual`. Bring your own virtualizer (TanStack Virtual, `react-window`, `virtua`, or manual). See the *Virtualized lists* section in `references/package-guide.md` for the canonical TanStack Virtual recipe
 - `timeline`
   - Exports: `Timeline`, `TimelineConnector`, `TimelineContent`, `TimelineDescription`, `TimelineEmpty`, `TimelineHeader`, `TimelineIcon`, `TimelineItem`, `TimelineTime`, `TimelineTitle`, `timelineVariants`
   - Notes: timeline flow with root `size`, inherited `iconSize`, item `status`, optional loading/error states, and semantic icon or connector colors

package/dist/skills/uselets-ui/references/package-guide.md

@@ -146,6 +146,7 @@ Use these patterns:
 ```tsx
 import { Alert, Button, UnstyledButton, cn, randomId } from '@uselets/ui'
 import type { UIColor } from '@uselets/ui'
+import { DataTable } from '@uselets/ui/data-table'
 import { Dialog } from '@uselets/ui/dialog'
 import { useIsMobile } from '@uselets/ui/hooks/use-mobile'
 import { useDisclosure } from '@uselets/ui/hooks/use-disclosure'
@@ -161,7 +162,9 @@ Guidance:
 - Use `@uselets/ui/hooks/<hook-module>` for dedicated hook subpaths.
 - Do not invent undocumented subpaths.
 
-Public hook subpaths currently include `hooks/use-mobile`, `hooks/use-disclosure`, `hooks/use-interval`, `hooks/use-idle`, `hooks/use-document-visibility`, and `hooks/use-local-storage`. Legacy `@uselets/ui/use-*` paths are not public entrypoints. Utility helpers are available from `@uselets/ui/utils`, and shared UI color helpers are available from the root barrel or `@uselets/ui/lib/color`.
+Public hook subpaths currently include `hooks/use-mobile`, `hooks/use-disclosure`, `hooks/use-interval`, `hooks/use-idle`, `hooks/use-document-visibility`, `hooks/use-local-storage`, and `hooks/use-mask`. Legacy `@uselets/ui/use-*` paths are not public entrypoints. Utility helpers are available from `@uselets/ui/utils`, and shared UI color helpers are available from the root barrel or `@uselets/ui/lib/color`.
+
+Use `DataTable` from `@uselets/ui/data-table` for client-side tables with sorting, filtering, pagination, row selection, column visibility, formatted cells, and custom action columns. All user-facing labels default to Portuguese (pt-BR) and can be overridden through the `labels` prop (`Partial<DataTableLabels>`); the full defaults are exported as `defaultDataTableLabels`.
 
 `useLocalStorage` uses an options object and returns a tuple like `useState`:
 
@@ -290,6 +293,138 @@ The `RadioGroup` component supports `color: UIColor`, with `primary` as the defa
 
 The `DateRangePicker` component is a compound popover date range picker built on `Calendar` range mode. Use `DateRange | null` for controlled values; applying an empty draft or resetting emits `null` through `onValueChange`. Fixed presets, relative-day inputs, date inputs, and the calendar all edit the same draft, and `DateRangePickerPreset` displays a selected state when its range matches the current draft by calendar day.
 
+## DataTable compound API and virtualization
+
+`DataTable` ships two complementary APIs:
+
+- **High-level `DataTable`** — monolithic, ergonomic, covers the common case (pagination, sorting, row selection, filters, toolbar actions, custom labels). Public surface is unchanged from earlier versions.
+- **Compound parts** — `DataTableRoot`, `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, `DataTablePagination`. The high-level component is itself implemented in terms of these, so behavior never diverges.
+
+Use the compound API when you need to:
+
+- Virtualize the body (large datasets).
+- Place the toolbar, pagination, or other actions in non-default positions (e.g. toolbar inside a card header, pagination in a footer slot).
+- Share the same `table` instance with code that lives outside the `DataTable` subtree (e.g. an "Export selected" button rendered above the page).
+
+### Compound shape (non-virtualized)
+
+```tsx
+import {
+  DataTableBody,
+  DataTableHeader,
+  DataTablePagination,
+  DataTableRoot,
+  DataTableToolbar
+} from '@uselets/ui/data-table'
+import { Table, TableContainer } from '@uselets/ui/table'
+
+<DataTableRoot columns={columns} data={data} enableRowSelection enableSorting>
+  <DataTableToolbar filterColumns={['name', 'email']} />
+  <TableContainer className="rounded-lg border">
+    <Table>
+      <DataTableHeader />
+      <DataTableBody />
+    </Table>
+  </TableContainer>
+  <DataTablePagination />
+</DataTableRoot>
+```
+
+`DataTableRoot` accepts either `{ columns, data, ...options }` (uncontrolled — creates the `table` instance internally) or `{ table }` (controlled — table instance comes from `useDataTable` called by the consumer). Use the controlled form whenever you need access to the `table` instance in the same scope as the JSX (e.g. for virtualization or external action buttons).
+
+### Virtualized lists (bring your own virtualizer)
+
+`@uselets/ui` has **zero runtime dependency** on any virtualization library. Pick the one you prefer (`@tanstack/react-virtual`, `react-window`, `virtua`, or even a manual implementation) and replace `<DataTableBody />` with a `<tbody>` that renders only the virtual rows.
+
+Canonical recipe using `@tanstack/react-virtual` (the most common choice in the React ecosystem):
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual'
+import {
+  DataTableHeader,
+  DataTableRoot,
+  DataTableToolbar,
+  useDataTable
+} from '@uselets/ui/data-table'
+import { Table, TableCell, TableContainer, TableRow } from '@uselets/ui/table'
+import * as React from 'react'
+
+function VirtualizedPayments({ data }: { data: Payment[] }) {
+  const table = useDataTable<Payment>({
+    columns,
+    data,
+    enableRowSelection: true,
+    enableSorting: true,
+    enablePagination: false // IMPORTANT: returns all rows from getRowModel()
+  })
+
+  const parentRef = React.useRef<HTMLDivElement>(null)
+  const rows = table.getRowModel().rows
+  const colSpan = table.getVisibleLeafColumns().length
+
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 52,
+    overscan: 8
+  })
+
+  const virtualItems = virtualizer.getVirtualItems()
+  const totalSize = virtualizer.getTotalSize()
+  const paddingTop = virtualItems[0]?.start ?? 0
+  const paddingBottom = totalSize - (virtualItems.at(-1)?.end ?? 0)
+
+  return (
+    <DataTableRoot table={table}>
+      <DataTableToolbar filterColumns={['customer']} />
+      <TableContainer ref={parentRef} className="h-[600px] rounded-lg border">
+        <Table stickyHeader>
+          <DataTableHeader />
+          <tbody>
+            {paddingTop > 0 && (
+              <tr aria-hidden>
+                <td colSpan={colSpan} style={{ height: paddingTop, padding: 0, border: 0 }} />
+              </tr>
+            )}
+            {virtualItems.map((vi) => {
+              const row = rows[vi.index]
+              return (
+                <TableRow key={row.id} data-state={row.getIsSelected() ? 'selected' : undefined}>
+                  {row.getVisibleCells().map((cell) => {
+                    const renderer = cell.column.columnDef.cell
+                    return (
+                      <TableCell key={cell.id}>
+                        {typeof renderer === 'function' ? renderer(cell.getContext()) : (cell.getValue() as React.ReactNode)}
+                      </TableCell>
+                    )
+                  })}
+                </TableRow>
+              )
+            })}
+            {paddingBottom > 0 && (
+              <tr aria-hidden>
+                <td colSpan={colSpan} style={{ height: paddingBottom, padding: 0, border: 0 }} />
+              </tr>
+            )}
+          </tbody>
+        </Table>
+      </TableContainer>
+    </DataTableRoot>
+  )
+}
+```
+
+Key points and gotchas:
+
+- **Bring your own virtualizer.** The example uses `@tanstack/react-virtual` for clarity, but any virtualizer works. Replace `useVirtualizer` and the `paddingTop`/`paddingBottom` spacer-row computation with the equivalent from `react-window`, `virtua`, or your own. The compounds (`DataTableRoot`, `DataTableToolbar`, `DataTableHeader`) and primitives (`Table`, `TableContainer`, `TableRow`, `TableCell`) do not change.
+- **`enablePagination: false`** is required so `table.getRowModel()` returns the full filtered/sorted dataset instead of just the current page. Pagination and virtualization are mutually exclusive — pick one.
+- **Sticky header.** Set `stickyHeader` on `<Table>` and a fixed height on `<TableContainer>`. The CSS-only sticky header in the primitive `Table` continues to work because `<thead>` stays in normal flow.
+- **Row height.** `estimateSize` is fine when rows are uniform. For dynamic heights, pass `measureElement={virtualizer.measureElement}` on each `TableRow`'s `ref` to let TanStack Virtual measure them.
+- **Spacer rows vs absolute positioning.** Two valid approaches exist: spacer rows (`paddingTop`/`paddingBottom` as shown — keeps rows in normal flow, simpler) or `position: absolute; transform: translateY(start)` on every row (requires `position: relative` on `<tbody>` and `height: totalSize`). The spacer-row approach is generally easier and works across virtualizers.
+- **Row selection, sorting, and filtering all work** in the virtualized mode because they live on the `table` instance — only rendering of the body is virtualized.
+
+A full working example lives in `apps/web/src/stories/data-table-virtualized.stories.tsx`.
+
 ## Component selection
 
 Choose components by intent:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uselets/ui",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "private": false,
   "description": "React component library for the LET'S design system.",
@@ -57,7 +57,9 @@
   "dependencies": {
     "@base-ui/react": "1.4.1",
     "@fontsource-variable/inter": "5.2.8",
-    "@tabler/icons-react": "3.41.1",
+    "@react-input/mask": "2.0.4",
+    "@tabler/icons-react": "3.44.0",
+    "@tanstack/react-table": "8.21.3",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
     "cmdk": "1.1.1",
@@ -69,11 +71,11 @@
     "radix-ui": "1.4.3",
     "react-day-picker": "9.14.0",
     "react-dropzone": "15.0.0",
-    "react-resizable-panels": "4.10.0",
-    "recharts": "2.15.4",
+    "react-resizable-panels": "4.11.1",
+    "recharts": "3.8.1",
     "shadcn": "4.6.0",
     "sonner": "2.0.7",
-    "tailwind-merge": "3.5.0",
+    "tailwind-merge": "3.6.0",
     "tw-animate-css": "1.4.0",
     "vaul": "1.1.2"
   },
@@ -83,17 +85,17 @@
   },
   "devDependencies": {
     "@bosh-code/tsdown-plugin-tailwindcss": "1.0.1",
-    "@tailwindcss/postcss": "4.2.4",
+    "@tailwindcss/postcss": "4.3.0",
     "@testing-library/react": "16.3.2",
-    "@tsdown/css": "0.21.10",
-    "@turbo/gen": "2.9.8",
-    "@types/node": "25.6.0",
-    "@types/react": "19.2.14",
+    "@tsdown/css": "0.22.0",
+    "@turbo/gen": "2.9.14",
+    "@types/node": "25.9.1",
+    "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",
     "jsdom": "29.1.1",
-    "tailwindcss": "4.2.4",
-    "tsdown": "0.21.10",
+    "tailwindcss": "4.3.0",
+    "tsdown": "0.22.0",
     "typescript": "6.0.3",
-    "vitest": "4.1.5"
+    "vitest": "4.1.6"
   }
 }

package/skills/uselets-ui/SKILL.md

@@ -56,6 +56,7 @@ To set up a consumer project after installing `@uselets/ui`, run `bun uselets in
 - For toast usage, mount `Toaster` near the app root before calling `toast(...)`.
 - For package theme helpers, use `ThemeProvider`, `useTheme`, and `ModeToggle` from `@uselets/ui/theme` or the root barrel.
 - For form fields, `Field` automatically shares a generated control id with `FieldLabel` and labelable controls when explicit ids are omitted; pass explicit matching `htmlFor` and `id` only when a stable custom id is required.
+- For client-side tabular data, use `DataTable` from `@uselets/ui/data-table`. Defaults are bare: `enableRowSelection`, `enableSorting`, and `showPagination` are all `false`. Set `enableRowSelection` to auto-prepend the selection checkbox column (no need to add `createDataTableSelectColumn` manually); set `enableSorting` to make `DataTableColumnHeader` clickable for sort. `filterColumns` accepts a single id or an array; with 2+ ids the toolbar renders an `InputGroup` with a column selector on the left. `toolbarActions` always sits at the right of the toolbar. All labels default to pt-BR; override any subset through `labels` (`Partial<DataTableLabels>`), with full defaults exposed as `defaultDataTableLabels`. Use `variant` on `DataTable` (or directly on the base `Table`) to switch chrome: `"line"` (default) renders only horizontal separators between rows; `"outline"` adds a rounded outer border around the table. The base `Table` from `@uselets/ui/table` renders only the `<table>` element and is striped by default (pass `striped={false}` to disable). Wrap it in `TableContainer` to control scroll; `minWidth` lives on `TableContainer`. Combine `stickyHeader` on `Table` with `max-h` + `overflow-y-auto` on the `TableContainer` to keep the `<thead>` visible during vertical scroll. `DataTable` wraps its `Table` in `TableContainer` automatically.
 
 ## Quick Routing
 

package/skills/uselets-ui/references/component-catalog.md

@@ -50,6 +50,10 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Import path: `@uselets/ui/hooks/use-local-storage`
   - Exports: `useLocalStorage`, `UseLocalStorageOptions`
   - Notes: returns a `[value, setValue]` tuple, stores values with JSON serialization, and syncs storage changes between browser tabs by default (`sync: true`)
+- `use-mask`
+  - Import path: `@uselets/ui/hooks/use-mask`
+  - Exports: `useMask`, `UseMaskOptions`, `MaskOptions`, `Replacement`, `Track`, `TrackingData`, `Modify`, `ModifiedData`
+  - Notes: thin wrapper over `@react-input/mask`'s `useMask` that defaults `replacement` to `{ 9: /\d/, a: /[A-Za-z]/, '*': /./ }`; returns a `MutableRefObject<HTMLInputElement>` to attach to any input. Consumers may override `replacement`.
 - `utils`
   - Import path: `@uselets/ui/utils`
   - Exports: `cn`, `randomId`
@@ -135,6 +139,9 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Notes: compose controls with prefixes, suffixes, or inline actions
 - `input-otp`
   - Exports: `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot`, `REGEXP_ONLY_CHARS`, `REGEXP_ONLY_DIGITS`, `REGEXP_ONLY_DIGITS_AND_CHARS`
+- `mask-input`
+  - Exports: `MaskInput`
+  - Notes: formatted input backed by `@react-input/mask`. Required prop `mask`; optional `replacement` (string or `Record<string, RegExp>`), `showMask`, `separate`, `track`, `modify`. Default replacement tokens are `9` (digit), `a` (letter), `*` (any). Renders the standard `Input`, so `Field`/`FieldLabel` and all native `<input>` props work as usual.
 - `checkbox`
   - Exports: `Checkbox`
   - Notes: supports `size: 'sm' | 'md' | 'lg'`, `color: UIColor` (default `primary`), `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; composed label text follows checkbox size (`sm` 12px, `md` 14px, `lg` 20px)
@@ -213,7 +220,20 @@ Unless noted otherwise, each module also exports its public `*Props` types from
 - `center`
   - Exports: `Center`, `centerVariants`
 - `chart`
-  - Exports: `Bar`, `BarChart`, `CartesianGrid`, `XAxis`, `ChartContainer`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `ChartTooltip`, `ChartTooltipContent`
+  - Exports: `ChartContainer`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `ChartTooltip`, `ChartTooltipContent`, `ChartConfig`
+  - Notes: low-level chart primitives. For app usage prefer the high-level `area-chart`, `bar-chart`, `pie-chart`, `donut-chart` modules. Import raw recharts primitives (`Bar`, `XAxis`, etc.) directly from `recharts` when composing with `ChartContainer`.
+- `area-chart`
+  - Exports: `AreaChart`, `AreaChartSeries`, `AreaChartType`, `AreaChartCurveType`, `AreaChartGridAxis`
+  - Notes: high-level area chart. Pass `data`, `series` (array of `{ name, label?, color? }`), and `dataKey` (X axis field). Supports `type` (default/stacked/percent/split), `curveType`, `withXAxis`, `withYAxis`, `gridAxis`, `withDots`, `withTooltip`, `withLegend`. Defaults to chart colors `--chart-1..5`.
+- `bar-chart`
+  - Exports: `BarChart`, `BarChartSeries`, `BarChartType`, `BarChartOrientation`, `BarChartGridAxis`
+  - Notes: high-level bar chart. Same shape as `area-chart` plus `orientation` (vertical/horizontal), `barSize`, `radius`. Supports stacked and percent types.
+- `pie-chart`
+  - Exports: `PieChart`, `PieChartBase`, `PieChartDatum`, `buildPieConfig`
+  - Notes: high-level pie chart. Pass `data` as `Array<{ name, value, color? }>`. Supports `withLabels`, `labelsPosition`, `startAngle`, `endAngle`, `paddingAngle`, `withLegend`, `withTooltip`. `PieChartBase` is the shared internal renderer used by `donut-chart`.
+- `donut-chart`
+  - Exports: `DonutChart`
+  - Notes: same data shape as `pie-chart`. Adds `thickness` (donut hole size in px) and `withTotal` + `totalLabel` (renders sum in the center).
 - `collapsible`
   - Exports: `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`
 - `container`
@@ -223,7 +243,7 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Notes: generic flexbox layout primitive. Supports `direction: 'row' | 'row-reverse' | 'column' | 'column-reverse'`, `align: 'start' | 'end' | 'center' | 'baseline' | 'stretch'`, `justify: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'`, `wrap`, and `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`).
 - `group`
   - Exports: `Group`, `groupVariants`
-  - Notes: supports `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`) and `wrap`
+  - Notes: horizontal row primitive. Supports `align: 'start' | 'end' | 'center' | 'baseline' | 'stretch'` (default `center`), `justify: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'`, `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`), and `wrap`
 - `kbd`
   - Exports: `Kbd`, `KbdGroup`
 - `resizable`
@@ -234,9 +254,16 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `Separator`
 - `stack`
   - Exports: `Stack`, `stackVariants`
-  - Notes: supports `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`)
+  - Notes: vertical column primitive. Supports `align: 'start' | 'end' | 'center' | 'baseline' | 'stretch'`, `justify: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'`, and `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (`4/8/16/24/32px`)
 - `table`
-  - Exports: `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption`
+  - Exports: `Table`, `TableContainer`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption`, `tableVariants`
+  - Notes: `Table` renders only the `<table>` element (no auto wrapper); striped by default (`striped` prop, default `true`) and supports `stickyHeader`. `variant` (`"line"` default | `"outline"`) controls outer chrome — `"line"` has only horizontal separators between rows; `"outline"` adds a rounded outer border. Outline works standalone (chrome on the `<table>`) or wrapped in `TableContainer` (container detects `data-variant=outline` via `:has()`, applies the chrome on itself, and zeroes it on the `<table>` — keeps sticky headers from painting over the border). Wrap in `TableContainer` for horizontal scroll; `TableContainer` accepts `minWidth` (number in px or any CSS length). For sticky header, set `max-h` + `overflow-y-auto` on the `TableContainer` (via `className` or `style`)
+- `data-table`
+  - Exports: `DataTable`, `DataTableRoot`, `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, `DataTablePagination`, `DataTableColumnHeader`, `createDataTableSelectColumn`, `useDataTable`, `useDataTableContext`, `defaultDataTableLabels`, `DataTableLabels`, `UseDataTableOptions`, `DataTableRootProps`, `DataTableToolbarProps`
+  - Notes: dual API — high-level `DataTable` (monolithic, simple cases) and compound (`DataTableRoot` + sub-parts, power cases including virtualization). Both share the same underlying logic via `useDataTable`.
+  - **High-level `DataTable`:** client-side TanStack Table composition. Defaults are bare — `enableRowSelection`, `enableSorting`, `showPagination` all default to `false` and must be explicitly enabled. Setting `enableRowSelection` auto-prepends the selection column; setting `enableSorting` activates sort buttons in `DataTableColumnHeader`. `filterColumns` accepts `string | string[]`; with 2+ ids the toolbar renders an `InputGroup` with a column selector at the left. `toolbarActions` always renders at the right of the toolbar. `variant` (`"line"` default | `"outline"`) is forwarded to the internal `Table` — pass `"outline"` to wrap the table in a rounded border. All user-facing labels default to pt-BR and are overridable through the `labels` prop (`Partial<DataTableLabels>`)
+  - **Compound API:** `DataTableRoot` accepts either `{ columns, data, ...options }` (uncontrolled — creates the `table` instance internally) or `{ table }` (controlled — table instance comes from `useDataTable` called by the consumer). `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, and `DataTablePagination` read the `table` instance from context. `DataTableHeader` renders a full `<thead>`; `DataTableBody` renders a full `<tbody>` — to virtualize, omit `<DataTableBody />` and render your own `<tbody>` instead. `useDataTable(options)` is a thin wrapper around `useReactTable` that bakes in the same defaults `DataTable` uses (row models, selection auto-injection); pass `enablePagination: false` when virtualizing so `table.getRowModel()` returns all rows. `useDataTableContext<TData>()` retrieves the current `table` and merged `labels` inside a custom compound child
+  - **Virtualization:** the package is virtualizer-agnostic — it has zero runtime dependency on `@tanstack/react-virtual`. Bring your own virtualizer (TanStack Virtual, `react-window`, `virtua`, or manual). See the *Virtualized lists* section in `references/package-guide.md` for the canonical TanStack Virtual recipe
 - `timeline`
   - Exports: `Timeline`, `TimelineConnector`, `TimelineContent`, `TimelineDescription`, `TimelineEmpty`, `TimelineHeader`, `TimelineIcon`, `TimelineItem`, `TimelineTime`, `TimelineTitle`, `timelineVariants`
   - Notes: timeline flow with root `size`, inherited `iconSize`, item `status`, optional loading/error states, and semantic icon or connector colors

package/skills/uselets-ui/references/package-guide.md

@@ -146,6 +146,7 @@ Use these patterns:
 ```tsx
 import { Alert, Button, UnstyledButton, cn, randomId } from '@uselets/ui'
 import type { UIColor } from '@uselets/ui'
+import { DataTable } from '@uselets/ui/data-table'
 import { Dialog } from '@uselets/ui/dialog'
 import { useIsMobile } from '@uselets/ui/hooks/use-mobile'
 import { useDisclosure } from '@uselets/ui/hooks/use-disclosure'
@@ -161,7 +162,9 @@ Guidance:
 - Use `@uselets/ui/hooks/<hook-module>` for dedicated hook subpaths.
 - Do not invent undocumented subpaths.
 
-Public hook subpaths currently include `hooks/use-mobile`, `hooks/use-disclosure`, `hooks/use-interval`, `hooks/use-idle`, `hooks/use-document-visibility`, and `hooks/use-local-storage`. Legacy `@uselets/ui/use-*` paths are not public entrypoints. Utility helpers are available from `@uselets/ui/utils`, and shared UI color helpers are available from the root barrel or `@uselets/ui/lib/color`.
+Public hook subpaths currently include `hooks/use-mobile`, `hooks/use-disclosure`, `hooks/use-interval`, `hooks/use-idle`, `hooks/use-document-visibility`, `hooks/use-local-storage`, and `hooks/use-mask`. Legacy `@uselets/ui/use-*` paths are not public entrypoints. Utility helpers are available from `@uselets/ui/utils`, and shared UI color helpers are available from the root barrel or `@uselets/ui/lib/color`.
+
+Use `DataTable` from `@uselets/ui/data-table` for client-side tables with sorting, filtering, pagination, row selection, column visibility, formatted cells, and custom action columns. All user-facing labels default to Portuguese (pt-BR) and can be overridden through the `labels` prop (`Partial<DataTableLabels>`); the full defaults are exported as `defaultDataTableLabels`.
 
 `useLocalStorage` uses an options object and returns a tuple like `useState`:
 
@@ -290,6 +293,138 @@ The `RadioGroup` component supports `color: UIColor`, with `primary` as the defa
 
 The `DateRangePicker` component is a compound popover date range picker built on `Calendar` range mode. Use `DateRange | null` for controlled values; applying an empty draft or resetting emits `null` through `onValueChange`. Fixed presets, relative-day inputs, date inputs, and the calendar all edit the same draft, and `DateRangePickerPreset` displays a selected state when its range matches the current draft by calendar day.
 
+## DataTable compound API and virtualization
+
+`DataTable` ships two complementary APIs:
+
+- **High-level `DataTable`** — monolithic, ergonomic, covers the common case (pagination, sorting, row selection, filters, toolbar actions, custom labels). Public surface is unchanged from earlier versions.
+- **Compound parts** — `DataTableRoot`, `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, `DataTablePagination`. The high-level component is itself implemented in terms of these, so behavior never diverges.
+
+Use the compound API when you need to:
+
+- Virtualize the body (large datasets).
+- Place the toolbar, pagination, or other actions in non-default positions (e.g. toolbar inside a card header, pagination in a footer slot).
+- Share the same `table` instance with code that lives outside the `DataTable` subtree (e.g. an "Export selected" button rendered above the page).
+
+### Compound shape (non-virtualized)
+
+```tsx
+import {
+  DataTableBody,
+  DataTableHeader,
+  DataTablePagination,
+  DataTableRoot,
+  DataTableToolbar
+} from '@uselets/ui/data-table'
+import { Table, TableContainer } from '@uselets/ui/table'
+
+<DataTableRoot columns={columns} data={data} enableRowSelection enableSorting>
+  <DataTableToolbar filterColumns={['name', 'email']} />
+  <TableContainer className="rounded-lg border">
+    <Table>
+      <DataTableHeader />
+      <DataTableBody />
+    </Table>
+  </TableContainer>
+  <DataTablePagination />
+</DataTableRoot>
+```
+
+`DataTableRoot` accepts either `{ columns, data, ...options }` (uncontrolled — creates the `table` instance internally) or `{ table }` (controlled — table instance comes from `useDataTable` called by the consumer). Use the controlled form whenever you need access to the `table` instance in the same scope as the JSX (e.g. for virtualization or external action buttons).
+
+### Virtualized lists (bring your own virtualizer)
+
+`@uselets/ui` has **zero runtime dependency** on any virtualization library. Pick the one you prefer (`@tanstack/react-virtual`, `react-window`, `virtua`, or even a manual implementation) and replace `<DataTableBody />` with a `<tbody>` that renders only the virtual rows.
+
+Canonical recipe using `@tanstack/react-virtual` (the most common choice in the React ecosystem):
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual'
+import {
+  DataTableHeader,
+  DataTableRoot,
+  DataTableToolbar,
+  useDataTable
+} from '@uselets/ui/data-table'
+import { Table, TableCell, TableContainer, TableRow } from '@uselets/ui/table'
+import * as React from 'react'
+
+function VirtualizedPayments({ data }: { data: Payment[] }) {
+  const table = useDataTable<Payment>({
+    columns,
+    data,
+    enableRowSelection: true,
+    enableSorting: true,
+    enablePagination: false // IMPORTANT: returns all rows from getRowModel()
+  })
+
+  const parentRef = React.useRef<HTMLDivElement>(null)
+  const rows = table.getRowModel().rows
+  const colSpan = table.getVisibleLeafColumns().length
+
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 52,
+    overscan: 8
+  })
+
+  const virtualItems = virtualizer.getVirtualItems()
+  const totalSize = virtualizer.getTotalSize()
+  const paddingTop = virtualItems[0]?.start ?? 0
+  const paddingBottom = totalSize - (virtualItems.at(-1)?.end ?? 0)
+
+  return (
+    <DataTableRoot table={table}>
+      <DataTableToolbar filterColumns={['customer']} />
+      <TableContainer ref={parentRef} className="h-[600px] rounded-lg border">
+        <Table stickyHeader>
+          <DataTableHeader />
+          <tbody>
+            {paddingTop > 0 && (
+              <tr aria-hidden>
+                <td colSpan={colSpan} style={{ height: paddingTop, padding: 0, border: 0 }} />
+              </tr>
+            )}
+            {virtualItems.map((vi) => {
+              const row = rows[vi.index]
+              return (
+                <TableRow key={row.id} data-state={row.getIsSelected() ? 'selected' : undefined}>
+                  {row.getVisibleCells().map((cell) => {
+                    const renderer = cell.column.columnDef.cell
+                    return (
+                      <TableCell key={cell.id}>
+                        {typeof renderer === 'function' ? renderer(cell.getContext()) : (cell.getValue() as React.ReactNode)}
+                      </TableCell>
+                    )
+                  })}
+                </TableRow>
+              )
+            })}
+            {paddingBottom > 0 && (
+              <tr aria-hidden>
+                <td colSpan={colSpan} style={{ height: paddingBottom, padding: 0, border: 0 }} />
+              </tr>
+            )}
+          </tbody>
+        </Table>
+      </TableContainer>
+    </DataTableRoot>
+  )
+}
+```
+
+Key points and gotchas:
+
+- **Bring your own virtualizer.** The example uses `@tanstack/react-virtual` for clarity, but any virtualizer works. Replace `useVirtualizer` and the `paddingTop`/`paddingBottom` spacer-row computation with the equivalent from `react-window`, `virtua`, or your own. The compounds (`DataTableRoot`, `DataTableToolbar`, `DataTableHeader`) and primitives (`Table`, `TableContainer`, `TableRow`, `TableCell`) do not change.
+- **`enablePagination: false`** is required so `table.getRowModel()` returns the full filtered/sorted dataset instead of just the current page. Pagination and virtualization are mutually exclusive — pick one.
+- **Sticky header.** Set `stickyHeader` on `<Table>` and a fixed height on `<TableContainer>`. The CSS-only sticky header in the primitive `Table` continues to work because `<thead>` stays in normal flow.
+- **Row height.** `estimateSize` is fine when rows are uniform. For dynamic heights, pass `measureElement={virtualizer.measureElement}` on each `TableRow`'s `ref` to let TanStack Virtual measure them.
+- **Spacer rows vs absolute positioning.** Two valid approaches exist: spacer rows (`paddingTop`/`paddingBottom` as shown — keeps rows in normal flow, simpler) or `position: absolute; transform: translateY(start)` on every row (requires `position: relative` on `<tbody>` and `height: totalSize`). The spacer-row approach is generally easier and works across virtualizers.
+- **Row selection, sorting, and filtering all work** in the virtualized mode because they live on the `table` instance — only rendering of the body is virtualized.
+
+A full working example lives in `apps/web/src/stories/data-table-virtualized.stories.tsx`.
+
 ## Component selection
 
 Choose components by intent: