@uselets/ui 1.20.4 → 2.0.1

package/README.md

@@ -4,8 +4,8 @@ React component library for the LET'S design system.
 
 ## Requirements
 
-- React `>=19`
-- React DOM `>=19`
+- React `^19.2`
+- React DOM `^19.2`
 - Tailwind CSS 4
 
 ## Installation
@@ -26,47 +26,32 @@ yarn add @uselets/ui
 bun add @uselets/ui
 ```
 
-## Agent skill
+## Setup
 
-The package ships the `uselets-ui` agent skill for projects that want local guidance for setup, public
-imports, and the installed package API.
+### Automatic setup
 
-After installing `@uselets/ui`, run:
+Run the setup command once after installing:
 
 ```bash
-bun uselets skill
+bun uselets init
 ```
 
-The command reinstalls the skill for both Codex and Claude Code, replacing any older copy:
-
-- `.agents/skills/uselets-ui`
-- `.claude/skills/uselets-ui`
-
-To target only one agent, run `bun uselets skill --agent codex` or `bun uselets skill --agent claude`.
-
-## Project setup
+It installs the package dependencies, configures PostCSS, and prepares your global CSS file. It also:
 
-To install package dependencies, configure PostCSS, and prepare your global CSS file, run:
+- asks which theme to import and where your global CSS lives (default: `src/styles/globals.css`);
+- adds `import '@fontsource-variable/inter'` to your app entry file (`app/layout.tsx`, `pages/_app.tsx`,
+  `src/main.tsx`, `src/index.tsx`, or a `.jsx` variant), or asks for the path when none is found;
+- optionally installs the [agent skill](#agent-skill).
 
-```bash
-bun uselets init
-```
-
-The command asks which theme to import, asks for your global CSS path with `src/styles/globals.css` as the
-default, and optionally installs the agent skill. It also imports the Inter font: it detects a conventional
-app entry file (`app/layout.tsx`, `pages/_app.tsx`, `src/main.tsx`, `src/index.tsx`, and `.jsx` variants) and
-inserts `import '@fontsource-variable/inter'` there, or asks for the entry file path when none is found. This
-avoids `@import '@fontsource-variable/inter'` in the global CSS, which some bundlers (including Next.js) don't
-resolve correctly for third-party CSS — import it as a JS module instead. For non-interactive setup, pass
-options:
+For non-interactive setup, pass the options directly:
 
 ```bash
 bun uselets init --theme max --css src/styles/globals.css --entry app/layout.tsx --no-install-skill
 ```
 
-## Tailwind CSS v4 setup
+### Manual setup (Tailwind CSS v4)
 
-If your app already uses Tailwind CSS v4, you can skip this section.
+If your app already uses Tailwind CSS v4, start at step 3.
 
 1. Install Tailwind v4 and the PostCSS plugin:
 
@@ -81,7 +66,7 @@ npm install tailwindcss @tailwindcss/postcss
 export { default } from '@uselets/ui/postcss.config'
 ```
 
-> **Using Vite?** You can use the Tailwind Vite plugin instead of PostCSS — install `tailwindcss @tailwindcss/vite`,
+> **Using Vite?** You can use the Tailwind Vite plugin instead of PostCSS: install `tailwindcss @tailwindcss/vite`,
 > skip `postcss.config.mjs`, and register the plugin. Prefer this setup when your project uses isolated installs
 > (pnpm, or Bun workspaces): with PostCSS under Vite, the theme's Tailwind plugins may fail to resolve there.
 >
@@ -95,42 +80,47 @@ export { default } from '@uselets/ui/postcss.config'
 > })
 > ```
 
-3. Import Tailwind and one package theme in your global stylesheet:
+3. Import Tailwind, one package theme, and the package sources in your global stylesheet:
 
 ```css
 /* app.css */
 @import 'tailwindcss';
-@import '@uselets/ui/themes/max.css';
-```
-
-Use `@uselets/ui/themes/gomax.css` instead for GoMax apps. If your app consumes `@uselets/ui` components, add a
-source directive so Tailwind can generate classes used by the package:
+@import '@uselets/ui/themes/max.css'; /* or @uselets/ui/themes/gomax.css for GoMax apps */
 
-```css
 @source '../node_modules/@uselets/ui/dist';
 ```
 
-4. Import the Inter font once from your app's entry file (not from CSS — bundlers such as Next.js don't
-   resolve third-party CSS `@import`s reliably):
+The `@source` line lets Tailwind generate the classes used by the package components.
+
+4. Import the Inter font once from your app's entry file (not from CSS: bundlers such as Next.js don't resolve
+   third-party CSS `@import`s reliably):
 
 ```ts
 // app/layout.tsx (or src/main.tsx, pages/_app.tsx, ...)
 import '@fontsource-variable/inter'
 ```
 
-## Quick start
+### Agent skill
 
-1. Import Tailwind and one package theme once in your global stylesheet:
+The package ships the `uselets-ui` agent skill, with local guidance on setup, public imports, and the installed
+package API. Install it with:
 
-```css
-@import 'tailwindcss';
-@import '@uselets/ui/themes/max.css';
+```bash
+bun uselets skill
 ```
 
-For GoMax apps, import `@uselets/ui/themes/gomax.css` instead. Import the font once from your app's entry
-file, as shown above.
+It (re)installs the skill for both Codex and Claude Code, replacing any older copy:
+
+- `.agents/skills/uselets-ui`
+- `.claude/skills/uselets-ui`
+
+To target only one agent, run `bun uselets skill --agent codex` or `bun uselets skill --agent claude`.
 
-2. Import components from the package root:
+## Usage
+
+### Imports
+
+Import from the package root:
 
 ```tsx
 import { Alert, Button } from '@uselets/ui'
@@ -144,120 +134,66 @@ export function Example() {
 }
 ```
 
-3. You can also import through subpaths:
+Or through subpaths: components at `@uselets/ui/<component>`, hooks at `@uselets/ui/hooks/<hook>`:
 
 ```tsx
 import { Button } from '@uselets/ui/button'
-import { DataTable, DataTableColumnHeader, createDataTableSelectColumn } from '@uselets/ui/data-table'
-import { useBreakpointValue } from '@uselets/ui/hooks/use-breakpoint-value'
-import { useIsMobile } from '@uselets/ui/hooks/use-mobile'
+import { DataTable } from '@uselets/ui/data-table'
 import { useDisclosure } from '@uselets/ui/hooks/use-disclosure'
-import { useLocalStorage } from '@uselets/ui/hooks/use-local-storage'
 import { randomId } from '@uselets/ui/utils'
 ```
 
-### Data tables
-
-Use `DataTable` for client-side tables. The default render is intentionally bare — just a header and the empty
-state — and every additional feature is opt-in: `filterColumns`, `enableSorting`, `showPagination`,
-`showColumnVisibility`, `toolbarActions`, and `enableRowSelection`. When `enableRowSelection` is `true` the selection checkbox column
-is prepended automatically (use the exported `createDataTableSelectColumn` only when you need to place it
-elsewhere). `filterColumns` accepts a single column id (`"customer"`) or an array (`["customer", "email"]`);
-when there are two or more, a select rendered with `InputGroup` appears at the left of the input to pick the
-target column. `toolbarActions` always renders at the right of the toolbar, even without a filter. All
-user-facing labels default to Portuguese (pt-BR) and can be overridden through the `labels` prop.
-
-The underlying `Table` component renders only the `<table>` element (no auto wrapper) and is striped by default
-(pass `striped={false}` to disable). Use `variant` to control the outer chrome: `"line"` (default) renders only
-horizontal separators between rows; `"outline"` adds a rounded outer border. The outline chrome works in two
-modes: standalone (no `TableContainer`), the border lives on the `<table>` itself; wrapped in a `TableContainer`,
-the container detects the outline variant via `:has()`, applies the chrome on itself, and removes it from the
-`<table>` — this keeps the border sticky-safe (sticky headers can no longer paint over it) without changing
-the visible result. `DataTable` accepts the same `variant` prop and forwards it to its internal `Table`. Wrap `Table` in `TableContainer` to
-control horizontal scroll — use the `minWidth` prop (number in px or any CSS length) on `TableContainer` to
-force horizontal scroll when the parent is narrower. Combine `stickyHeader` on `Table` with `max-h` +
-`overflow-y-auto` on `TableContainer` (via `className` or `style`) to keep `<thead>` visible while the body
-scrolls vertically. `DataTable` already wraps its `Table` in a `TableContainer`.
+Each module exports its composition parts and prop types from the same path.
 
-```tsx
-import { type ColumnDef, DataTable, DataTableColumnHeader } from '@uselets/ui/data-table'
+> Upgrading from v1? See the breaking changes in the [changelog](https://storybook.uselets.com/?path=/docs/intro-changelog-ui--docs).
 
-type Payment = {
-  id: string
-  customer: string
-  amount: number
-}
-
-const columns: ColumnDef<Payment>[] = [
-  {
-    accessorKey: 'customer',
-    header: ({ column }) => <DataTableColumnHeader column={column} title="Customer" />
-  },
-  {
-    accessorKey: 'amount',
-    header: ({ column }) => <DataTableColumnHeader column={column} title="Amount" />,
-    cell: ({ row }) => new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(row.original.amount)
-  }
-]
-
-export function PaymentsTable({ payments }: { payments: Payment[] }) {
-  return (
-    <DataTable
-      columns={columns}
-      data={payments}
-      getRowId={(row) => row.id}
-      filterColumns={['customer', 'email']}
-      enableRowSelection
-      enableSorting
-      showPagination
-      variant="outline"
-      labels={{
-        filterPlaceholder: 'Buscar cliente…',
-        pageOf: (current, total) => `${current} / ${total}`
-      }}
-    />
-  )
-}
-```
-
-Override any subset of `DataTableLabels`; remaining keys fall back to the pt-BR defaults exported as
-`defaultDataTableLabels`.
+### App providers
 
-#### Compound API and virtualization
+Add these at the app root when you use the matching feature:
 
-`DataTable` also exposes a compound API for cases that need finer control — chiefly virtualization, but also
-custom layout (toolbar inside a card header, pagination in a footer slot) or sharing the `table` instance with
-code outside the table subtree. The high-level `DataTable` shown above is itself implemented in terms of these
-parts, so behavior never diverges.
+| Provider | From | Needed for |
+| --- | --- | --- |
+| `ThemeProvider` (+ `ModeToggle`, `useTheme`) | `@uselets/ui/theme` | Light/dark/system theme ([docs][themeprovider]) |
+| `TooltipProvider` | `@uselets/ui/tooltip` | Shared tooltip delays ([docs][tooltip]) |
+| `Toaster` | `@uselets/ui/sonner` | Toasts via `toast()`; place it inside the `next-themes` `ThemeProvider` ([docs][toast]) |
+| `DirectionProvider` (+ `useDirection`) | `@uselets/ui/direction` | Right-to-left apps: `<DirectionProvider direction="rtl">` (the `dir` attribute alone isn't enough) |
 
-Exports: `DataTableRoot`, `DataTableToolbar`, `DataTableHeader`, `DataTableBody`, `DataTablePagination`,
-`useDataTable`, `useDataTableContext`. `DataTableRoot` accepts either `{ columns, data, ...options }` or
-`{ table }` (instance created via `useDataTable`).
+## Theming
 
-For virtualization, `@uselets/ui` is intentionally **virtualizer-agnostic** — no runtime dependency on
-`@tanstack/react-virtual`, `react-window`, `virtua`, or any other library. Bring your own: instantiate it next
-to `useDataTable`, then render your virtual `<tbody>` in place of `<DataTableBody />`. Set
-`enablePagination: false` on `useDataTable` so `table.getRowModel()` returns the full filtered dataset.
+| Theme | Import |
+| --- | --- |
+| Max | `@uselets/ui/themes/max.css` |
+| GoMax | `@uselets/ui/themes/gomax.css` |
 
-A complete TanStack Virtual example lives in `apps/web/src/stories/data-table-virtualized.stories.tsx` and the
-recipe is documented in the `uselets-ui` skill (`packages/ui/skills/uselets-ui/references/package-guide.md`).
+Preview both themes in [Foundations/Themes](https://storybook.uselets.com/?path=/docs/foundations-themes--docs).
 
-## Theme tokens
+### Colors
 
-The package ships brand theme entrypoints:
+Each family has a complete `50..950` scale (`bg-primary-500`, `--zinc-900`) and a semantic alias (`bg-green`,
+`--red`) that maps to `500` in light mode and `400` in dark mode. The list is exported as `uiColors` / `UIColor`.
 
-- `@uselets/ui/themes/max.css`
-- `@uselets/ui/themes/gomax.css`
+| Family | Reference (`500`) |
+| --- | --- |
+| `primary` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#ff5c35;"></span> |
+| `brand` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#ff5c35;"></span> |
+| `gray` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#99afc4;"></span> |
+| `zinc` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#989898;"></span> |
+| `red` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#e02535;"></span> |
+| `yellow` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#ffa736;"></span> |
+| `blue` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#408ec5;"></span> |
+| `indigo` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#545ad4;"></span> |
+| `pink` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#bd138b;"></span> |
+| `green` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#52af4a;"></span> |
 
-Max and GoMax are maintained from their respective Figma style guides. The Storybook
-`Foundations/Themes` story reads the active stylesheet tokens, so it is the theme-backed
-palette preview for both theme entrypoints.
+Prefer the semantic tokens over palette steps in application UI: `background`, `foreground`, `card`, `popover`,
+`primary`, `secondary`, `accent`, `destructive`, `border`, `input`, `ring`, `placeholder`, `sidebar-*`, and
+`chart-1..5`.
 
-### Typography scale
+### Typography
 
-The Max theme overrides Tailwind CSS text size utilities from `text-xs` through `text-6xl` to match the
-Figma typography scale. Inter is the default sans-serif family, and each size uses a line height equal to
-`font-size * 1.5`.
+The Max theme overrides `text-xs` through `text-6xl` to match the Figma scale. Inter is the default sans-serif
+family, and every size has a line height of `font-size * 1.5`. See
+[Foundations/Typography](https://storybook.uselets.com/?path=/docs/foundations-typography--docs).
 
 | Utility | Font size | Line height |
 | --- | --- | --- |
@@ -272,293 +208,240 @@ Figma typography scale. Inter is the default sans-serif family, and each size us
 | `text-5xl` | `3rem` / `48px` | `4.5rem` / `72px` |
 | `text-6xl` | `3.75rem` / `60px` | `5.625rem` / `90px` |
 
-### Public palette families
-
-The palette follows the Tailwind and shadcn convention of complete `50..950` scales.
-
-- `primary`
-- `brand`
-- `gray`
-- `zinc`
-- `red`
-- `yellow`
-- `blue`
-- `indigo`
-- `pink`
-- `green`
-
-This same list is exported as `uiColors` and `UIColor` from `@uselets/ui` and `@uselets/ui/lib/color`.
-Color-aware components such as `Button`, `Toggle`, `Checkbox`, `RadioGroupItem`, and `Switch` use `UIColor` for their public `color` props.
-`ButtonColor` remains available as a compatibility alias for existing button consumers.
-
-Each family is exposed in four layers:
-
-- CSS variables such as `--primary-500`, `--brand-500` and `--zinc-900`
-- Semantic CSS aliases such as `--green`, `--red` and `--gray`, mapped to `500` in light mode and `400` in dark mode
-- Tailwind v4 theme utilities such as `bg-primary-500`, `text-zinc-900`, `border-red-300`
-- Tailwind v4 semantic utilities such as `bg-green`, `text-red` and `border-gray`
-
-Color-aware components use the semantic family aliases for their primary color so `color="green"` resolves to
-`--green-500` in light mode and `--green-400` in dark mode. Hover and subtle surfaces continue to use explicit
-palette steps.
-
-### Palette preview
-
-| Family | Reference token | Preview |
-| --- | --- | --- |
-| `primary` | `primary-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#ff5c35;"></span> |
-| `brand` | `brand-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#ff5c35;"></span> |
-| `gray` | `gray-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#99afc4;"></span> |
-| `zinc` | `zinc-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#989898;"></span> |
-| `red` | `red-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#e02535;"></span> |
-| `yellow` | `yellow-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#ffa736;"></span> |
-| `blue` | `blue-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#408ec5;"></span> |
-| `indigo` | `indigo-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#545ad4;"></span> |
-| `pink` | `pink-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#bd138b;"></span> |
-| `green` | `green-500` | <span style="display:inline-block;width:1.25rem;height:1.25rem;border-radius:0.375rem;border:1px solid #d9d9d9;background:#52af4a;"></span> |
-
-### Semantic tokens
-
-Use semantic tokens for application UI instead of hardcoding palette steps in components.
-
-- Surfaces and text: `background`, `foreground`, `card`, `popover`
-- Actions and emphasis: `primary`, `secondary`, `accent`, `destructive`
-- Supporting tokens: `border`, `input`, `ring`, `placeholder`
-- Sidebar tokens: `sidebar`, `sidebar-primary`, `sidebar-accent`, `sidebar-border`, `sidebar-ring`
-- Data viz tokens: `chart-1` to `chart-5`
-- Component-scoped tokens: `--logo-foreground` (used by the Intelitrack, Neutra, Kovra, and Fibonash logos' `color` tone so they stay legible in dark mode) and `--rd-logo-foreground` (used by the RD logo's wordmark for the same reason)
-
-The theme also exposes the shadcn foreground pair for destructive surfaces:
-
-- `--destructive-foreground`
-- `text-destructive-foreground`
-
-### Gradient tokens
-
-The palette includes one named gradient token:
-
-- `--gradient-primary`
-
-This gradient is a documentation and styling primitive. It is not exposed as a Tailwind color family.
-
-### Global scrollbar style
+### Scrollbar
 
-Importing either theme entrypoint applies a default page scrollbar style via the bundled
-[`tailwind-scrollbar`](https://github.com/adoxography/tailwind-scrollbar) plugin: thin width,
-transparent track, `muted` thumb with a `muted-foreground` hover state. The plugin's utilities
-(`scrollbar-thin`, `scrollbar-thumb-*`, `scrollbar-track-*`, `scrollbar-hover:*`) are available
-to override these defaults or to style internal scrollable regions. Firefox uses the standard
-`scrollbar-color` property and does not honor the pseudo-element hover variant — the thumb
-stays at the base color there.
+Both themes style the page scrollbar; override it with the bundled
+[`tailwind-scrollbar`](https://github.com/adoxography/tailwind-scrollbar) utilities.
 
 ## Components
 
-You can import from the package root (`@uselets/ui`) or by subpath (`@uselets/ui/<component>`).
-
-| Component | Exports | Key props / notes |
+Every component has a [Storybook](https://storybook.uselets.com) page with live examples, variants, and props.
+
+### Conventions
+
+- **`asChild`** renders the component as your own element. If that element isn't a `<button>`, also pass
+  `nativeButton={false}` on triggers and button-like parts:
+
+  ```tsx
+  <Button asChild>
+    <a href="/settings">Settings</a>
+  </Button>
+  ```
+
+- **`color: UIColor`** accepts any palette family on `Button`, `Badge`, `Toggle`, `Checkbox`, `RadioGroup`,
+  `Switch`, `Progress`, `RingProgress`, and `Pagination`.
+- **Sizes and spacing:** `size` usually goes from `sm` to `lg` (or `xs` to `xl`). Layout `gap` uses `xs`–`xl`
+  (`4/8/16/24/32px`).
+- **Popups** unmount when closed (pass `keepMounted` to keep them), accept `side`/`align`/`sideOffset`/`alignOffset`,
+  and accept `sticky` to stay visible after the trigger scrolls away.
+- **Forms:** wrap each control in a `Field` to wire its label, description, error, and invalid state.
+
+### Catalog
+
+**Layout**
+
+| Component | Description |
+| --- | --- |
+| [Flex][flex], [Stack][stack], [Group][group] | Flexbox layouts with `gap`, `align`, and `justify` |
+| [Grid][grid], [SimpleGrid][simplegrid] | 12-column grid with `GridItem`; equal-column grid with `cols` |
+| [Center][center], [Container][container] | Centering box; max-width page container |
+| [Visibility][visibility] | `HiddenFrom` / `VisibleFrom` a breakpoint |
+| [Card][card] | Content container with header, content, and footer parts |
+| [Accordion][accordion], [Collapsible][collapsible] | Expandable sections (`multiple` to open several) |
+| [Separator][separator], [Marker][marker] | Divider line; labeled divider or marker |
+| [ScrollArea][scrollarea], [Resizable][resizable], [Carousel][carousel] | Custom scrollbars, resizable panels, slides |
+| [Sidebar][sidebar] | App sidebar with `SidebarProvider`; collapsible to icons, optional `expandOnHover` |
+
+**Typography**
+
+| Component | Description |
+| --- | --- |
+| [Text][text], [Heading][heading] | Text and headings with `size` `xs`–`xl` |
+| [Anchor][anchor] | Styled link with `underline` modes |
+| [List][list] | Ordered/unordered list; `ListIcon` replaces the marker |
+| [Code][code], [Kbd][kbd], [Label][label] | Inline code, keyboard keys, form label |
+
+**Actions**
+
+| Component | Description |
+| --- | --- |
+| [Button][button] | `variant`, `color`, `size` (including `icon-*` sizes), `loading` |
+| [UnstyledButton][unstyledbutton] | Button with reset styles and a focus ring |
+| [ButtonGroup][buttongroup] | Groups buttons together |
+| [Toggle][toggle], [ToggleGroup][togglegroup] | Pressable toggles (`multiple` for several pressed) |
+
+**Forms**
+
+| Component | Description |
+| --- | --- |
+| [Field][field] | Label, description, error, and invalid state around a control |
+| [Input][input], [Textarea][textarea], [InputGroup][inputgroup] | Text inputs; input with addons |
+| [MaskInput][maskinput] | Formatted input (`_` digit, `#` letter, `*` any) |
+| [PhoneInput][phoneinput] | International phone number (E.164), default country `BR` |
+| [NumberField][numberfield] | Numeric stepper |
+| [InputOTP][inputotp] | One-time code input |
+| [Select][select], [NativeSelect][nativeselect] | Custom select (`items` maps values to labels); native `<select>` |
+| [Combobox][combobox] | Searchable select, with chips for multiple values |
+| [Checkbox][checkbox], [RadioGroup][radiogroup], [Switch][switch] | Choice controls with built-in `label` and `description` |
+| [Slider][slider] | Single value or range |
+| [Calendar][calendar], [DateRangePicker][daterangepicker] | Date calendar; range picker with presets and apply/reset |
+| [Dropzone][dropzone] | File upload with validation and retries (`useDropzone`) |
+
+**Overlays**
+
+| Component | Description |
+| --- | --- |
+| [Dialog][dialog], [Drawer][drawer] | Modal and side panel with `size` and `dismissible`; `DialogBody`/`DrawerBody` scroll |
+| [AlertDialog][alertdialog] | Confirmation dialog |
+| [Popover][popover] | Floating panel; `PopoverClose` closes it |
+| [Tooltip][tooltip] | `Tooltip label="…"` for the common case; needs `TooltipProvider` |
+| [HoverCard][hovercard] | Preview card on hover |
+| [DropdownMenu][dropdownmenu] | Action menu with checkbox, radio, and submenu items |
+| [Command][command] | Command palette / searchable list |
+
+**Navigation**
+
+| Component | Description |
+| --- | --- |
+| [Tabs][tabs] | `line` or `enclosed` tabs; `grow` for equal widths |
+| [NavigationMenu][navigationmenu] | Site navigation with dropdown panels |
+| [Breadcrumb][breadcrumb], [Pagination][pagination] | Path trail; page links |
+| [Stepper][stepper] | Multi-step progress navigation |
+| [BottomNav][bottomnav] | Fixed mobile tab bar; you control when it shows and which item is active |
+
+**Feedback**
+
+| Component | Description |
+| --- | --- |
+| [Alert][alert] | Inline message (`default` or `destructive`) |
+| [Toast][toast] | `Toaster` + `toast()` |
+| [Progress][progress], [RingProgress][ringprogress] | Linear and circular progress (`value` 0–100) |
+| [Spinner][spinner], [Skeleton][skeleton] | Loading indicator; loading placeholder |
+| [Empty][empty] | Empty state |
+
+**Data display**
+
+| Component | Description |
+| --- | --- |
+| [Table][table] | Styled table; `TableContainer` for scroll, `stickyHeader` for a fixed header |
+| [DataTable][datatable] | TanStack Table with opt-in filter, sorting, pagination, selection, and pt-BR labels ([virtualized][datatable-virtualized]) |
+| [Badge][badge], [Avatar][avatar] | Status label; user image with fallback and groups |
+| [Timeline][timeline] | Event list with status |
+| [AreaChart][areachart], [BarChart][barchart], [PieChart][piechart], [DonutChart][donutchart] | Recharts-based charts colored with `colorKey` |
+| [Logo][logo] | LetsDelivery product logos (`variant`, `tone`, `size`) |
+
+## Hooks
+
+Exported from the package root and from `@uselets/ui/hooks/<name>`.
+
+| Hook | What it does |
+| --- | --- |
+| [`useBreakpoint`][usebreakpoint] | Whether the viewport is at or above a Tailwind breakpoint |
+| [`useBreakpointValue`][usebreakpointvalue] | Picks a value per breakpoint: `useBreakpointValue({ base: 1, md: 2 })` |
+| [`useIsMobile`][useismobile] | Whether the viewport is below `768px` (`hooks/use-mobile`) |
+| [`useDisclosure`][usedisclosure] | Open/close state |
+| [`useLocalStorage`][uselocalstorage] | `useState` persisted in `localStorage`, synced across tabs |
+| [`useHotkeys`][usehotkeys] | Keyboard shortcuts such as `'mod+k'` |
+| [`useInterval`][useinterval] | Interval timer |
+| [`useIdle`][useidle] | Whether the user is idle |
+| [`useDocumentVisibility`][usedocumentvisibility] | The document visibility state |
+| `useMask` | Input masking for custom inputs |
+
+## Utilities
+
+| Export | Import | What it does |
 | --- | --- | --- |
-| `alert` | `Alert`, `AlertTitle`, `AlertDescription`, `AlertAction` | `Alert` supports `variant: 'default' \| 'destructive'` (default: `default`). |
-| `anchor` | `Anchor`, `anchorVariants` | Link primitive rendered as `<a>` with `size: 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`, `underline: 'always' \| 'hover' \| 'never' \| 'not-hover'` (default: `hover`), and `asChild`. |
-| `avatar` | `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarBadge`, `AvatarGroup`, `AvatarGroupCount` | `Avatar` supports `size: 'sm' \| 'md' \| 'lg'` (default: `md`). |
-| `badge` | `Badge`, `badgeVariants` | `size: 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` (default: `md`); `variant: 'solid' \| 'secondary' \| 'outline' \| 'subtle'` (default: `solid`); `color: UIColor` (default: `primary`); `asChild?: boolean`. |
-| `button` | `Button`, `buttonVariants` | `variant: 'solid' \| 'secondary' \| 'outline' \| 'subtle' \| 'ghost' \| 'link'` (default: `solid`); `color: UIColor` (default: `primary`); `size: 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg' \| 'icon-xl'`; `loading?: boolean`. |
-| `unstyled-button` | `UnstyledButton` | Button primitive with reset styles, pointer cursor, accessible focus ring, default `type="button"`, and `asChild`. |
-| `calendar` | `Calendar`, `CalendarDayButton` | Also exports the `DateRange` type. Weekends render with destructive text, week numbers are low-emphasis, and selected single/range endpoints use the `primary` palette with a subtle primary range fill. |
-| `date-range-picker` | `DateRangePicker`, `DateRangePickerTrigger`, `DateRangePickerValue`, `DateRangePickerContent`, `DateRangePickerPresets`, `DateRangePickerPreset`, `DateRangePickerCalendar`, `DateRangePickerDateFields`, `DateRangePickerActions`, `DateRangePickerApply`, `DateRangePickerReset` | Compound popover picker backed by `Calendar` range mode. Draft edits from fixed presets, relative-day inputs, date inputs, and calendar stay in sync until `Apply`; reset/clear emits `null` through `onValueChange`. |
-| `card` | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` | `Card` supports `size: 'sm' \| 'md' \| 'lg'` (default: `md`). |
-| `area-chart` / `bar-chart` / `pie-chart` / `donut-chart` | `AreaChart`, `BarChart`, `PieChart`, `DonutChart` (each with their series/datum types) | Recharts-backed charts with a mantine-shaped API. Each series/datum accepts `color` (raw CSS) or `colorKey: ChartColorKey` (`'primary' \| 'brand' \| 'gray' \| 'zinc' \| 'red' \| 'yellow' \| 'green' \| 'blue' \| 'indigo' \| 'pink'`) which resolves to `var(--{key}-500)`. Series/datum `name` is free-form and may contain spaces or non-ASCII characters. `BarChart` also accepts `color` / `colorKey` on each `data` row (`BarChartDatum`); when set, the row color wins over the series color and applies to every bar in that row. Pass `areaProps` / `barProps` / `pieProps` to forward props (e.g. `onClick`, `cursor`) to the underlying recharts series primitive (`<Area>` / `<Bar>` / `<Pie>`); pass `areaChartProps` / `barChartProps` to forward props (e.g. `margin`, `barCategoryGap`, `onClick`) to the wrapping recharts `<AreaChart>` / `<BarChart>`. `PieChart` / `DonutChart` add `strokeColor` (default: `var(--background)`) alongside `strokeWidth` so the segment gaps are now visible by default. Re-exports `ChartColorKey`, `CHART_COLOR_KEYS`, `DEFAULT_CHART_PALETTE`, and `resolveChartColor` from `@uselets/ui/chart` for custom compositions. |
-| `checkbox` | `Checkbox` | `Checkbox` supports `size: 'sm' \| 'md' \| 'lg'` (default: `md`), `color: UIColor` (default: `primary`), `label?: React.ReactNode`, and `labelProps` for the composed `Label`. When `label` is provided without `id`, it generates an id and wires `htmlFor` automatically. Label text follows checkbox size: `sm` 12px, `md` 14px, `lg` 20px. |
-| `code` | `Code` | Inline code primitive rendered as `<code>`. |
-| `combobox` | `Combobox`, `ComboboxInput`, `ComboboxContent`, `ComboboxList`, `ComboboxItem`, `ComboboxGroup`, `ComboboxLabel`, `ComboboxCollection`, `ComboboxClear`, `ComboboxEmpty`, `ComboboxSeparator`, `ComboboxChips`, `ComboboxChip`, `ComboboxChipsInput`, `ComboboxTrigger`, `ComboboxValue`, `useComboboxAnchor` | `ComboboxInput` supports `icon?: React.ReactNode`, `triggerIcon?: React.ReactNode`, `showTrigger?: boolean`, and `showClear?: boolean`; `ComboboxChips` supports `showClear?: boolean` to render a button that clears all selected chips at once; `ComboboxContent` supports `container` for rendering inside overlays such as dialogs. |
-| `dialog` | `Dialog`, `DialogTrigger`, `DialogPortal`, `DialogClose`, `DialogOverlay`, `DialogContent`, `DialogHeader`, `DialogBody`, `DialogFooter`, `DialogTitle`, `DialogDescription` | `Dialog` supports `size: 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| 'full'` (default: `md`); `full` occupies the entire viewport. `DialogContent` caps its height at `calc(100dvh - 2rem)` and arranges children as a flex column; wrap long content in `DialogBody` (`flex-1 overflow-y-auto`) so the body scrolls while `DialogHeader` and `DialogFooter` stay pinned. `DialogContent.showCloseButton` (default: `true`); `DialogFooter.showCloseButton` (default: `false`). `Dialog.dismissible` (default: `true`); when `false`, clicking outside and pressing Esc no longer close the dialog (the close button and `DialogClose` still work). `DialogOverlay` and `DialogContent` stop `click`/`submit` events from bubbling to ancestor elements, since Radix portals move them elsewhere in the DOM but React still propagates their synthetic events through the component tree. |
-| `drawer` | `Drawer`, `DrawerTrigger`, `DrawerPortal`, `DrawerClose`, `DrawerOverlay`, `DrawerContent`, `DrawerHeader`, `DrawerBody`, `DrawerFooter`, `DrawerTitle`, `DrawerDescription` | `Drawer` supports `size: 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| 'full'` (default: `md`); `DrawerBody` provides padded auto-scroll content; `DrawerFooter` stacks actions on mobile and aligns them to the end on larger breakpoints; `DrawerContent.showCloseButton` (default: `true`). `Drawer.dismissible` (default: `true`); when `false`, clicking outside and pressing Esc no longer close the drawer (the close button and `DrawerClose` still work). `Drawer.direction: 'top' \| 'right' \| 'bottom' \| 'left'` (default: `right`) controls which edge the drawer slides in from. `DrawerOverlay` and `DrawerContent` stop `click`/`submit` events from bubbling to ancestor elements, since Radix portals move them elsewhere in the DOM but React still propagates their synthetic events through the component tree. |
-| `dropzone` | `Dropzone`, `DropzoneArea`, `DropzoneDescription`, `DropzoneFileList`, `DropzoneFileListItem`, `DropzoneFileMessage`, `DropzoneMessage`, `DropzoneRemoveFile`, `DropzoneRetryFile`, `DropzoneTrigger`, `InfiniteProgress`, `useDropzone` | `useDropzone` manages upload lifecycle, validation (`accept`, `minSize`, `maxSize`, `maxFiles`), retry handling, and optional `shiftOnMaxFiles` replacement. Compose the returned state with `Dropzone` and its subcomponents. |
-| `dropdown-menu` | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent`, `DropdownMenuSeparator`, `DropdownMenuShortcut` | `DropdownMenuContent` supports `side`, `sideOffset`, `align`, `alignOffset`; items support `inset`, and `DropdownMenuItem` supports `variant: 'default' \| 'destructive'`. |
-| `empty` | `Empty`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, `EmptyContent` | `EmptyMedia` supports `variant: 'default' \| 'icon'` (default: `default`). |
-| `field` | `FieldSet`, `FieldLegend`, `FieldGroup`, `Field`, `FieldContent`, `FieldLabel`, `FieldTitle`, `FieldDescription`, `FieldSeparator`, `FieldError`, `useFieldControlId` | `Field.orientation: 'vertical' \| 'horizontal' \| 'responsive'` (default: `vertical`); `FieldLegend.variant: 'legend' \| 'label'`; `FieldError.errors` accepts an array of error objects. When a labelable control is rendered inside `Field` without an explicit `id`, `Field` provides a generated id and `FieldLabel` uses it automatically. |
-| `flex` | `Flex`, `flexVariants` | Flexbox layout primitive with `direction: 'row' \| 'row-reverse' \| 'column' \| 'column-reverse'` (default: `row`), `align: 'start' \| 'end' \| 'center' \| 'baseline' \| 'stretch'`, `justify: 'start' \| 'end' \| 'center' \| 'between' \| 'around' \| 'evenly'`, `wrap?: boolean`, and `gap: 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` (`4/8/16/24/32px`). |
-| `grid` | `Grid`, `GridItem` | `Grid` is a 12-column CSS grid by default and supports `gap`, `rowGap`, `columnGap`, `templateRows`, and `templateColumns`; spacing uses the `xs` to `xl` scale (`4/8/16/24/32px`). `GridItem` defaults to `colSpan={12}` and supports numeric `colSpan` and `rowSpan`; use `useBreakpointValue` when spans or templates need responsive values. |
-| `heading` | `Heading`, `headingVariants` | Heading primitive with `size: 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` (default: `md`) and `asChild`. |
-| `input` | `Input` | Wrapper for Base UI Input with all native `<input>` props. |
-| `input-otp` | `InputOTP`, `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator`, `REGEXP_ONLY_CHARS`, `REGEXP_ONLY_DIGITS`, `REGEXP_ONLY_DIGITS_AND_CHARS` | `InputOTP` supports all `input-otp` props plus `containerClassName`; use `maxLength` and `pattern` for validation. |
-| `number-field` | `NumberField`, `NumberFieldGroup`, `NumberFieldDecrement`, `NumberFieldIncrement`, `NumberFieldInput`, `NumberFieldScrubArea` | Base UI-backed numeric stepper input. `size: 'sm' \| 'md' \| 'lg'` (default: `md`); supports `min`, `max`, `step`, and other Base UI `NumberField.Root` props. `NumberFieldScrubArea` renders a draggable `label` (required) that scrubs the value on pointer drag. |
-| `phone-input` | `PhoneInput` | International phone input built on `react-phone-number-input`, composed from the existing `Input` and `Combobox` (country select), matching `Input`'s styling and single size. `value` / `onChange` use the E.164 `Value` string; `defaultCountry` defaults to `BR`. |
-| `mask-input` | `MaskInput` | Formatted input backed by `@react-input/mask`. Accepts `mask` plus optional `replacement`, `showMask`, `separate`, `track`, `modify`. Default replacement tokens: `_` (digit), `#` (letter), `*` (any) — chosen so the token character is never a value the user actually types. When no custom `replacement` is passed, `mask` strings written with the older `9`/`a` tokens are automatically translated to `_`/`#`, so existing masks keep working. Forwards an external `ref` prop to the underlying `<input>`, composed with the mask ref. The `useMask` hook is also exported from `@uselets/ui/hooks/use-mask` for custom inputs. |
-| `kbd` | `Kbd`, `KbdGroup` | Keyboard shortcut presentation primitives. |
-| `label` | `Label` | Styled `<label>` wrapper. |
-| `marker` | `Marker`, `MarkerContent`, `MarkerIcon`, `markerVariants` | `variant: 'default' \| 'separator' \| 'border'` (default: `default`); `asChild?: boolean`. `separator` renders divider lines on both sides of the content (for labeled dividers); `border` renders a bottom border instead. |
-| `list` | `List`, `ListItem`, `ListIcon`, `listVariants` | `List.type: 'unordered' \| 'ordered'`; `size` and `spacing` use the `xs` to `xl` scale; `ListIcon` can use `asChild` and replaces the default marker with a primary-colored icon. |
-| `logo` | `MaxLogo`, `GomaxLogo`, `BippiLogo`, `IntelitrackLogo`, `KovraLogo`, `NeutraLogo`, `RdLogo`, `FibonashLogo`, `LetsLogo` | One component per LetsDelivery product brand. `variant: 'icon' \| 'full'` (default: `full`; `LetsLogo` has no `variant`, it only renders `full`). `tone: 'color' \| 'mono'` (default: `color`); `GomaxLogo` and `BippiLogo` additionally accept `tone: 'reversed'` (their alternate white lockup with an orange accent, for dark/colored backgrounds). `color?: string` recolors `mono`/`reversed` tones (default: white); `size: 'sm' \| 'md' \| 'lg' \| number` (default: `md`) sets height, width follows each product's own aspect ratio; pass a `number` for an exact pixel height instead of a preset. |
-| `native-select` | `NativeSelect`, `NativeSelectOption`, `NativeSelectOptGroup` | Native `<select>` API with `size: 'sm' \| 'md'` (default: `md`). |
-| `popover` | `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverAnchor`, `PopoverHeader`, `PopoverTitle`, `PopoverDescription` | `PopoverContent` supports positioning props (`side`, `sideOffset`, `align`, `alignOffset`) and can be used in controlled mode via root props (`open`, `onOpenChange`). |
-| `progress` | `Progress`, `progressVariants` | Linear progress bar driven by a single `value` (0–100). Supports `size: 'sm' \| 'md' \| 'lg'` (default: `md`; bar heights `2/4/6px`) and `color: UIColor` (default: `primary`). |
-| `ring-progress` | `RingProgress`, `ringProgressVariants` | Circular progress indicator driven by a single `value` (0–100). Supports `size: 'sm' \| 'md' \| 'lg'` (default: `md`; `32/40/48px`), `thickness: 'thin' \| 'md' \| 'thick'` (default: `md`), and `color: UIColor` (default: `primary`). Uses a normalized `viewBox`, so the rendered size can also be overridden via `className` (e.g. `className="size-5"`). Rounded line caps. |
-| `radio-group` | `RadioGroup`, `RadioGroupItem` | `RadioGroup` supports `color: UIColor` (default: `primary`) for the group. `RadioGroupItem` supports `size: 'sm' \| 'md' \| 'lg'` (default: `md`), optional `color: UIColor` item overrides, `label?: React.ReactNode`, and `labelProps` for the composed `Label`. When `label` is provided without `id`, it generates an id and wires `htmlFor` automatically. Label text follows item size: `sm` 12px, `md` 14px, `lg` 20px. |
-| `select` | `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectGroup`, `SelectItem`, `SelectLabel`, `SelectSeparator`, `SelectScrollUpButton`, `SelectScrollDownButton` | `SelectTrigger.size: 'sm' \| 'md'`; `SelectContent` supports positioning props (`side`, `sideOffset`, `align`, `alignOffset`, `alignItemWithTrigger`). |
-| `separator` | `Separator` | `orientation: 'horizontal' \| 'vertical'` (default: `horizontal`). |
-| `simple-grid` | `SimpleGrid` | Simple grid with `cols`, `gap`, `rowGap`, and `columnGap`. `cols` accepts a number; spacing uses the `xs` to `xl` scale (`4/8/16/24/32px`). Use `useBreakpointValue` when column count needs responsive values. |
-| `skeleton` | `Skeleton` | Generic loading placeholder block. Supports `visible?: boolean` (default: `true`) and can wrap `children` to reserve their size while the placeholder is shown. |
-| `spinner` | `Spinner` | Loader icon (`role="status"`), accepts SVG props and supports `size: 'sm' \| 'md' \| 'lg'` (default: `md`). |
-| `switch` | `Switch` | `Switch` supports `size: 'sm' \| 'md' \| 'lg'` (default: `md`), `color: UIColor` (default: `green`), `label?: React.ReactNode`, and `labelProps` for the composed `Label`. When `label` is provided without `id`, it generates an id and wires `htmlFor` automatically. Track size is `sm` 34x16px, `md` 42x20px, and `lg` 48x22px; the thumb and internal indicator scale with the switch. Label text follows switch size: `sm` 14px, `md` 16px, `lg` 18px. |
-| `stepper` | `Stepper`, `StepperNav`, `StepperItem`, `StepperTrigger`, `StepperIndicator`, `StepperSeparator`, `StepperTitle`, `StepperDescription`, `StepperPanel`, `StepperContent`, `useStepper`, `useStepItem` | Multi-step progress navigation. `Stepper.orientation: 'horizontal' \| 'vertical'` (default: `horizontal`); supports controlled (`value` / `onValueChange`) and uncontrolled (`defaultValue`) active step, plus custom per-state `indicators` (`active`, `completed`, `inactive`, `loading`). `StepperItem` accepts `completed`, `disabled`, and `loading`. Arrow-key and Home/End keyboard navigation between triggers is built in. |
-| `tabs` | `Tabs`, `TabsContent`, `TabsList`, `TabsTrigger`, `tabsListVariants` | `TabsList.variant: 'line' \| 'enclosed'` (default: `line`); `TabsList.grow?: boolean` makes horizontal tabs share the available width equally; `line` uses a neutral border line with a `primary` active indicator. |
-| `text` | `Text`, `textVariants` | Text primitive with `size: 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` (default: `md`) and `asChild`. |
-| `timeline` | `Timeline`, `TimelineItem`, `TimelineConnector`, `TimelineContent`, `TimelineDescription`, `TimelineEmpty`, `TimelineHeader`, `TimelineIcon`, `TimelineTime`, `TimelineTitle`, `timelineVariants` | `Timeline.size: 'sm' \| 'md' \| 'lg'` (default: `md`); `Timeline.iconSize: 'sm' \| 'md' \| 'lg'`; `TimelineItem.status: 'completed' \| 'in-progress' \| 'pending'`; icon and connector colors use the semantic palette (`primary`, `secondary`, `muted`, `accent`, `destructive`). |
-| `tooltip` | `TooltipProvider`, `Tooltip`, `TooltipRoot`, `TooltipTrigger`, `TooltipContent` | `Tooltip` composes a trigger and label for common usage and supports `disabled`; `TooltipRoot` is the low-level root for manual composition; `TooltipContent` supports positioning props like `side`, `align`, and `sideOffset`. |
-| `visibility` | `HiddenFrom`, `VisibleFrom` | Breakpoint visibility helpers. `HiddenFrom breakpoint="md"` hides at `md` and above; `VisibleFrom breakpoint="md"` shows at `md` and above. |
-| `sonner` | `Toaster`, `toast` | Toaster wrapper around Sonner with theme integration from `next-themes` and custom icons. |
-
-### Additional components
-
-The package also exports the following modules through the root entrypoint and subpaths:
-
-- Layout and disclosure: `Accordion`, `Carousel`, `Center`, `Collapsible`, `Container`, `Flex`, `Group`, `Resizable`, `ScrollArea`, `Sidebar`, `Stack`, `Tabs`
-- Inputs and selection: `Calendar`, `DateRangePicker`, `InputGroup`, `RadioGroup`, `Slider`, `Switch`, `Textarea`, `Toggle`, `ToggleGroup`
-- Navigation and feedback: `AlertDialog`, `BottomNav`, `Breadcrumb`, `NavigationMenu`, `Pagination`, `Progress`
-- Data display and utilities: `Badge`, `ButtonGroup`, `Chart`, `Command`, `HoverCard`, `Table`, `ThemeProvider`, `useTheme`, `ModeToggle`
-
-Each module exports its public composition parts and prop types from the same import path, for example `@uselets/ui/accordion` or `@uselets/ui`. `Carousel` includes the composed `CarouselIndicators` subcomponent for opt-in slide indicators.
-
-Layout primitives follow the same pattern: `Stack`, `Group`, and `Flex` support `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'`, mapping to `4/8/16/24/32px`, plus typed `align: 'start' | 'end' | 'center' | 'baseline' | 'stretch'` and `justify: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'` props; `Group` also supports `wrap` (and defaults `align` to `center`); `Flex` additionally supports typed `direction` and `wrap`; `Center` supports `size: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` and `direction: 'horizontal' | 'vertical'`; and `Container` supports `size: 'sm' | 'md' | 'lg' | 'full'`. `SimpleGrid`, `Grid`, and `GridItem` accept direct layout values; use `useBreakpointValue` to derive responsive values when needed. `HiddenFrom` and `VisibleFrom` provide breakpoint-based visibility wrappers.
-
-`Pagination` highlights the current page and keeps the other links neutral. Its `color` prop (`UIColor`, default `primary`) controls only the current page's color. `PaginationLink`/`PaginationPrevious`/`PaginationNext` also accept `color` individually, but the value set on `Pagination` wins whenever it's provided.
-
-`BottomNav`/`BottomNavItem` render a fixed, safe-area-aware mobile tab bar (`env(safe-area-inset-bottom)` via the `--spacing-safe-bottom` token). The component has no built-in responsive/breakpoint logic — consumers decide when it's shown (e.g. wrapping it in `md:hidden`). `BottomNavItem` accepts `asChild` to render a routing library's link, and its active state is fully external via `isActive` (mirrored onto `data-active`/`aria-current="page"`) — there's no internal state, context, or navigation logic.
-
-Public hooks are exported from the package root and from the `@uselets/ui/hooks/*` namespace:
-
-- `useBreakpoint` from `@uselets/ui/hooks/use-breakpoint`
-- `useBreakpointValue` from `@uselets/ui/hooks/use-breakpoint-value`
-- `useDisclosure` from `@uselets/ui/hooks/use-disclosure`
-- `useInterval` from `@uselets/ui/hooks/use-interval`
-- `useIdle` from `@uselets/ui/hooks/use-idle`
-- `useDocumentVisibility` from `@uselets/ui/hooks/use-document-visibility`
-- `useHotkeys` from `@uselets/ui/hooks/use-hotkeys`
-- `useLocalStorage` from `@uselets/ui/hooks/use-local-storage`
-- `useMask` from `@uselets/ui/hooks/use-mask`
-- `useIsMobile` from `@uselets/ui/hooks/use-mobile`
-
-Legacy hook subpaths such as `@uselets/ui/use-mobile` are not public entrypoints.
-
-`useBreakpoint` checks Tailwind's default breakpoints (`base`, `sm`, `md`, `lg`, `xl`, `2xl`) and returns whether the current viewport is at or above the requested breakpoint. `useBreakpointValue` accepts a breakpoint map and returns the largest active value:
-
-```tsx
-const cols = useBreakpointValue({ base: 1, md: 2, lg: 3 }) ?? 1
-
-return <SimpleGrid cols={cols} gap="md" />
-```
-
-`useLocalStorage` returns a tuple like `useState`, persists values as JSON, and syncs changes between browser tabs and between other instances using the same key in the same tab by default:
-
-```tsx
-const [settings, setSettings] = useLocalStorage('settings', {
-  defaultValue: { compact: false }
-})
-
-const [draft, setDraft] = useLocalStorage('draft', {
-  defaultValue: '',
-  sync: false
-})
-```
-
-`useHotkeys` registers global keyboard shortcuts on the document. Each item is a tuple `[hotkey, handler, options?]`, where `hotkey` is a string like `'mod+k'` (`mod` matches `ctrl` on Windows/Linux and `meta` on macOS). Events fired from `INPUT`, `TEXTAREA`, and `SELECT` are ignored by default (configurable via the `tagsToIgnore` and `triggerOnContentEditable` arguments), and `options` accepts `preventDefault` (default `true`) and `usePhysicalKeys`. The `getHotkeyHandler` helper is also exported for binding shortcuts to a single element instead of the document:
-
-```tsx
-useHotkeys([
-  ['mod+k', () => openCommandPalette()],
-  ['escape', () => close(), { preventDefault: false }]
-])
-
-// or scoped to one element
-<input onKeyDown={getHotkeyHandler([['mod+enter', submit]])} />
-```
-
-Utilities are exported from the package root and `@uselets/ui/utils`, including `cn` and `randomId`. The package also exports `composeRefs` (and `setRef`) from `@uselets/ui/lib/compose-refs` for composing multiple refs into a single callback ref — handy when a component needs to merge a forwarded `ref` with an internal one (for example `MaskInput`).
-
-`ThemeProvider` stores the active `Theme` (`'dark' | 'light' | 'system'`) in `localStorage` under `storageKey` (default `'vite-ui-theme'`) and toggles the `dark`/`light` class on `document.documentElement`. Pass `defaultTheme` to set the initial theme when none is stored yet, and `disableTransitionOnChange` to suppress CSS transitions for the moment the class swaps, matching `next-themes`'s prop of the same name:
-
-```tsx
-import { ModeToggle, ThemeProvider } from '@uselets/ui/theme'
-
-export function AppRoot({ children }: { children: React.ReactNode }) {
-  return (
-    <ThemeProvider defaultTheme="system" disableTransitionOnChange>
-      <ModeToggle />
-      {children}
-    </ThemeProvider>
-  )
-}
-```
-
-### Sonner example
-
-```tsx
-import { ThemeProvider } from 'next-themes'
-import { Toaster, toast } from '@uselets/ui/sonner'
-
-export function App() {
-  return (
-    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
-      <button onClick={() => toast.success('Saved')}>Notify</button>
-      <Toaster />
-    </ThemeProvider>
-  )
-}
-```
-
-## Tooltip setup
-
-For consistent tooltip behavior across the app, wrap your application root with `TooltipProvider`.
-
-```tsx
-import { Tooltip, TooltipProvider } from '@uselets/ui/tooltip'
-
-export function AppRoot() {
-  return <TooltipProvider delayDuration={200}>{/* app */}</TooltipProvider>
-}
-
-export function SaveButton() {
-  return (
-    <Tooltip label="Salva as alterações" side="bottom">
-      <button type="button">Salvar</button>
-    </Tooltip>
-  )
-}
-```
-
-## Sidebar setup
-
-`SidebarProvider` owns the sidebar's open/collapsed state; `Sidebar` renders the structure and
-accepts `collapsible: 'offcanvas' | 'icon' | 'none'`. Set `expandOnHover` on `SidebarProvider` to let
-a `collapsible="icon"` sidebar reveal a floating preview (an overlay, not a layout push) on pointer
-hover or keyboard focus while collapsed. During that preview, clicking `SidebarRail` pins the sidebar
-open, while clicking `SidebarTrigger` closes the preview. Once a toggle collapses the sidebar, the
-preview stays closed until the pointer leaves the sidebar (or keyboard focus moves into it), so it
-doesn't reopen under a cursor that is still over it. `useSidebar()` exposes `isHoverExpanded`
-for components that need to react to the preview themselves. The preview's open/close debounce
-defaults to 150ms/300ms and can be tuned per app via `hoverExpandOpenDelay`/`hoverExpandCloseDelay`.
-
-```tsx
-import { Sidebar, SidebarContent, SidebarProvider, SidebarRail, SidebarTrigger } from '@uselets/ui/sidebar'
-
-export function AppShell({ children }: { children: React.ReactNode }) {
-  return (
-    <SidebarProvider expandOnHover>
-      <Sidebar collapsible="icon">
-        <SidebarContent>{/* menu */}</SidebarContent>
-        <SidebarRail />
-      </Sidebar>
-      <SidebarTrigger />
-      {children}
-    </SidebarProvider>
-  )
-}
-```
-
-To use your own element as the trigger, pass `asChild` — it still toggles the sidebar, no `onClick` needed:
-
-```tsx
-<SidebarTrigger asChild>
-  <Button variant="ghost">Menu</Button>
-</SidebarTrigger>
-```
+| `cn` | `@uselets/ui/utils` | Merges class names |
+| `randomId` | `@uselets/ui/utils` | Generates a random id |
+| `composeRefs`, `setRef` | `@uselets/ui/lib/compose-refs` | Combine several refs into one callback ref |
+| `uiColors`, `UIColor` | `@uselets/ui/lib/color` | Palette family names |
+
+[accordion]: https://storybook.uselets.com/?path=/docs/components-layout-accordion--docs
+[alert]: https://storybook.uselets.com/?path=/docs/components-feedback-alert--docs
+[alertdialog]: https://storybook.uselets.com/?path=/docs/components-overlay-alertdialog--docs
+[anchor]: https://storybook.uselets.com/?path=/docs/components-typography-anchor--docs
+[areachart]: https://storybook.uselets.com/?path=/docs/components-charts-areachart--docs
+[avatar]: https://storybook.uselets.com/?path=/docs/components-data-display-avatar--docs
+[badge]: https://storybook.uselets.com/?path=/docs/components-data-display-badge--docs
+[barchart]: https://storybook.uselets.com/?path=/docs/components-charts-barchart--docs
+[bottomnav]: https://storybook.uselets.com/?path=/docs/components-navigation-bottomnav--docs
+[breadcrumb]: https://storybook.uselets.com/?path=/docs/components-navigation-breadcrumb--docs
+[button]: https://storybook.uselets.com/?path=/docs/components-button-button--docs
+[buttongroup]: https://storybook.uselets.com/?path=/docs/components-button-buttongroup--docs
+[calendar]: https://storybook.uselets.com/?path=/docs/components-forms-calendar--docs
+[card]: https://storybook.uselets.com/?path=/docs/components-data-display-card--docs
+[carousel]: https://storybook.uselets.com/?path=/docs/components-layout-carousel--docs
+[center]: https://storybook.uselets.com/?path=/docs/components-layout-center--docs
+[checkbox]: https://storybook.uselets.com/?path=/docs/components-forms-checkbox--docs
+[code]: https://storybook.uselets.com/?path=/docs/components-typography-code--docs
+[collapsible]: https://storybook.uselets.com/?path=/docs/components-layout-collapsible--docs
+[combobox]: https://storybook.uselets.com/?path=/docs/components-forms-combobox--docs
+[command]: https://storybook.uselets.com/?path=/docs/components-overlay-command--docs
+[container]: https://storybook.uselets.com/?path=/docs/components-layout-container--docs
+[datatable]: https://storybook.uselets.com/?path=/docs/components-data-display-datatable--docs
+[datatable-virtualized]: https://storybook.uselets.com/?path=/docs/components-data-display-datatable-virtualized--docs
+[daterangepicker]: https://storybook.uselets.com/?path=/docs/components-forms-daterangepicker--docs
+[dialog]: https://storybook.uselets.com/?path=/docs/components-overlay-dialog--docs
+[donutchart]: https://storybook.uselets.com/?path=/docs/components-charts-donutchart--docs
+[drawer]: https://storybook.uselets.com/?path=/docs/components-overlay-drawer--docs
+[dropdownmenu]: https://storybook.uselets.com/?path=/docs/components-overlay-dropdownmenu--docs
+[dropzone]: https://storybook.uselets.com/?path=/docs/components-forms-dropzone--docs
+[empty]: https://storybook.uselets.com/?path=/docs/components-feedback-empty--docs
+[field]: https://storybook.uselets.com/?path=/docs/components-forms-field--docs
+[flex]: https://storybook.uselets.com/?path=/docs/components-layout-flex--docs
+[grid]: https://storybook.uselets.com/?path=/docs/components-layout-grid--docs
+[group]: https://storybook.uselets.com/?path=/docs/components-layout-group--docs
+[heading]: https://storybook.uselets.com/?path=/docs/components-typography-heading--docs
+[hovercard]: https://storybook.uselets.com/?path=/docs/components-overlay-hovercard--docs
+[input]: https://storybook.uselets.com/?path=/docs/components-forms-input--docs
+[inputgroup]: https://storybook.uselets.com/?path=/docs/components-forms-inputgroup--docs
+[inputotp]: https://storybook.uselets.com/?path=/docs/components-forms-input-otp--docs
+[kbd]: https://storybook.uselets.com/?path=/docs/components-data-display-kbd--docs
+[label]: https://storybook.uselets.com/?path=/docs/components-forms-label--docs
+[list]: https://storybook.uselets.com/?path=/docs/components-typography-list--docs
+[logo]: https://storybook.uselets.com/?path=/docs/components-media-logo--docs
+[marker]: https://storybook.uselets.com/?path=/docs/components-layout-marker--docs
+[maskinput]: https://storybook.uselets.com/?path=/docs/components-forms-maskinput--docs
+[nativeselect]: https://storybook.uselets.com/?path=/docs/components-forms-native-select--docs
+[navigationmenu]: https://storybook.uselets.com/?path=/docs/components-navigation-navigationmenu--docs
+[numberfield]: https://storybook.uselets.com/?path=/docs/components-forms-number-field--docs
+[pagination]: https://storybook.uselets.com/?path=/docs/components-navigation-pagination--docs
+[phoneinput]: https://storybook.uselets.com/?path=/docs/components-forms-phone-input--docs
+[piechart]: https://storybook.uselets.com/?path=/docs/components-charts-piechart--docs
+[popover]: https://storybook.uselets.com/?path=/docs/components-overlay-popover--docs
+[progress]: https://storybook.uselets.com/?path=/docs/components-feedback-progress--docs
+[radiogroup]: https://storybook.uselets.com/?path=/docs/components-forms-radiogroup--docs
+[resizable]: https://storybook.uselets.com/?path=/docs/components-layout-resizable--docs
+[ringprogress]: https://storybook.uselets.com/?path=/docs/components-feedback-ring-progress--docs
+[scrollarea]: https://storybook.uselets.com/?path=/docs/components-layout-scrollarea--docs
+[select]: https://storybook.uselets.com/?path=/docs/components-forms-select--docs
+[separator]: https://storybook.uselets.com/?path=/docs/components-layout-separator--docs
+[sidebar]: https://storybook.uselets.com/?path=/docs/components-layout-sidebar--docs
+[simplegrid]: https://storybook.uselets.com/?path=/docs/components-layout-simplegrid--docs
+[skeleton]: https://storybook.uselets.com/?path=/docs/components-feedback-skeleton--docs
+[slider]: https://storybook.uselets.com/?path=/docs/components-forms-slider--docs
+[spinner]: https://storybook.uselets.com/?path=/docs/components-feedback-spinner--docs
+[stack]: https://storybook.uselets.com/?path=/docs/components-layout-stack--docs
+[stepper]: https://storybook.uselets.com/?path=/docs/components-navigation-stepper--docs
+[switch]: https://storybook.uselets.com/?path=/docs/components-forms-switch--docs
+[table]: https://storybook.uselets.com/?path=/docs/components-data-display-table--docs
+[tabs]: https://storybook.uselets.com/?path=/docs/components-navigation-tabs--docs
+[text]: https://storybook.uselets.com/?path=/docs/components-typography-text--docs
+[textarea]: https://storybook.uselets.com/?path=/docs/components-forms-textarea--docs
+[themeprovider]: https://storybook.uselets.com/?path=/docs/components-utilities-themeprovider--docs
+[timeline]: https://storybook.uselets.com/?path=/docs/components-data-display-timeline--docs
+[toast]: https://storybook.uselets.com/?path=/docs/components-feedback-toast--docs
+[toggle]: https://storybook.uselets.com/?path=/docs/components-button-toggle--docs
+[togglegroup]: https://storybook.uselets.com/?path=/docs/components-button-togglegroup--docs
+[tooltip]: https://storybook.uselets.com/?path=/docs/components-overlay-tooltip--docs
+[unstyledbutton]: https://storybook.uselets.com/?path=/docs/components-button-unstyledbutton--docs
+[usebreakpoint]: https://storybook.uselets.com/?path=/docs/hooks-browser-usebreakpoint--docs
+[usebreakpointvalue]: https://storybook.uselets.com/?path=/docs/hooks-browser-usebreakpointvalue--docs
+[usedisclosure]: https://storybook.uselets.com/?path=/docs/hooks-state-usedisclosure--docs
+[usedocumentvisibility]: https://storybook.uselets.com/?path=/docs/hooks-browser-usedocumentvisibility--docs
+[usehotkeys]: https://storybook.uselets.com/?path=/docs/hooks-keyboard-usehotkeys--docs
+[useidle]: https://storybook.uselets.com/?path=/docs/hooks-timing-useidle--docs
+[useinterval]: https://storybook.uselets.com/?path=/docs/hooks-timing-useinterval--docs
+[useismobile]: https://storybook.uselets.com/?path=/docs/hooks-browser-useismobile--docs
+[uselocalstorage]: https://storybook.uselets.com/?path=/docs/hooks-state-uselocalstorage--docs
+[visibility]: https://storybook.uselets.com/?path=/docs/components-layout-visibility--docs