@uselets/ui 1.20.3 → 2.0.0

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

@@ -21,8 +21,8 @@ If the package is not installed yet, use the bundled references as a snapshot an
 
 ## Requirements
 
-- React `>=19`
-- React DOM `>=19`
+- React `^19.2`
+- React DOM `^19.2`
 - Tailwind CSS 4
 
 ## Installation
@@ -121,6 +121,22 @@ If the app needs Tailwind v4 PostCSS setup, reuse the package preset:
 export { default } from '@uselets/ui/postcss.config'
 ```
 
+Vite apps may use `@tailwindcss/vite` instead of PostCSS (use one integration, never both):
+
+- Install `tailwindcss` and `@tailwindcss/vite`; register `tailwindcss()` in `plugins` of `vite.config.ts`; do not create `postcss.config.mjs`.
+- Prefer `@tailwindcss/vite` when the project uses isolated installs (pnpm, Bun workspaces). With `@tailwindcss/postcss` under Vite plus isolated installs, the build fails with `Can't resolve 'tailwind-scrollbar'` because the theme's `@plugin` is resolved from the app's stylesheet. Fix by switching to `@tailwindcss/vite` (or adding `tailwind-scrollbar` to the app's dependencies).
+- Non-Vite bundlers (for example Next.js) keep `@tailwindcss/postcss` with `@uselets/ui/postcss.config`.
+
+```ts
+// vite.config.ts
+import tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [tailwindcss()]
+})
+```
+
 When the app uses installed `@uselets/ui` components, add a Tailwind source directive so component classes from the package are generated:
 
 ```css
@@ -218,7 +234,7 @@ Examples:
 import { Tooltip, TooltipProvider } from '@uselets/ui/tooltip'
 
 export function AppRoot({ children }: { children: React.ReactNode }) {
-  return <TooltipProvider delayDuration={200}>{children}</TooltipProvider>
+  return <TooltipProvider delay={200}>{children}</TooltipProvider>
 }
 
 export function SaveButton() {
@@ -302,13 +318,13 @@ Additional tokens:
 
 The `Button` component can apply those palette families directly through `color: UIColor`, with `primary` as the default. Its public variants are `solid`, `secondary`, `outline`, `subtle`, `ghost`, and `link`, with `solid` as the default. Its public sizes are `xs`, `sm`, `md`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, and `icon-xl`; `loading` shows a centered spinner, keeps native button content invisible to preserve size, and disables the button without dimming it.
 
-The `Checkbox` component can be used as a bare checkbox or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `primary` as the default color. When `label` is provided, it composes the package `Label`, accepts `labelProps` for that label, and generates an accessible `id`/`htmlFor` pair when no `id` prop is passed. Composed label text follows checkbox size: `sm` 12px, `md` 14px, and `lg` 20px.
+The `Checkbox` component can be used as a bare checkbox or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `primary` as the default color. When `label` is provided, it composes the package `Label`, accepts `labelProps` for that label, and generates an accessible `id`/`htmlFor` pair when no `id` prop is passed. Composed label text follows checkbox size: `sm` 12px, `md` 14px, and `lg` 18px. Pass `description?: React.ReactNode` (and `descriptionProps`) to render muted helper text (a `<p>`) below the label, linked to the control via `aria-describedby`; description text is `sm` 12px, `md` 12px, `lg` 14px.
 
-The `Switch` component can be used as a bare switch or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `green` as the default color. The `color` prop controls only the checked track and indicator color; unchecked remains neutral. Track size is `sm` 34x16px, `md` 42x20px, and `lg` 48x22px. The thumb and its internal indicator scale with the selected size. Composed label text follows switch size: `sm` 12px, `md` 14px, and `lg` 20px.
+The `Switch` component can be used as a bare switch or with `label?: React.ReactNode`. It supports `size: 'sm' | 'md' | 'lg'` and `color: UIColor`, with `green` as the default color. The `color` prop controls only the checked track and indicator color; unchecked remains neutral. Track size is `sm` 30x14px, `md` 34x16px, and `lg` 42x20px (control heights match `Checkbox`). The thumb and its internal indicator scale with the selected size. Composed label text follows switch size: `sm` 12px, `md` 14px, and `lg` 18px. `description?: React.ReactNode` (and `descriptionProps`) works the same as on `Checkbox`.
 
 The `TabsList` component supports `variant: 'line' | 'enclosed'`, with `line` as the default, and `grow?: boolean` for equal-width horizontal tabs. The `line` variant keeps a neutral border line across tabs and uses the `primary` color for the active indicator; use `enclosed` for the filled container treatment.
 
-The `RadioGroup` component supports `color: UIColor`, with `primary` as the default group color. `RadioGroupItem` can be used as a bare radio item inside `RadioGroup` or with `label?: React.ReactNode`; it supports `size: 'sm' | 'md' | 'lg'` and optional `color: UIColor` item overrides. Composed label text follows item size: `sm` 12px, `md` 14px, and `lg` 20px.
+The `RadioGroup` component supports `color: UIColor`, with `primary` as the default group color. `RadioGroupItem` can be used as a bare radio item inside `RadioGroup` or with `label?: React.ReactNode`; it supports `size: 'sm' | 'md' | 'lg'` and optional `color: UIColor` item overrides. Composed label text follows item size: `sm` 12px, `md` 14px, and `lg` 18px. `description?: React.ReactNode` (and `descriptionProps`) works the same as on `Checkbox`.
 
 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.
 
@@ -349,7 +365,7 @@ import { Table, TableContainer } from '@uselets/ui/table'
 </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).
+`DataTableRoot` accepts either `{ columns, data, ...options }` (uncontrolled — creates the `table` instance internally) or `{ table }` (controlled — table instance comes from `useDataTable` called by the consumer). In the uncontrolled form, pagination is on while a `<DataTablePagination />` is rendered inside the root and off otherwise (all rows); an explicit `enablePagination` overrides that. In the controlled form, `useDataTable` defaults to `enablePagination: false` — pass `true` when rendering `<DataTablePagination />`. 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)