@uselets/ui 0.6.1 → 1.0.0

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

@@ -26,6 +26,14 @@ Unless noted otherwise, each module also exports its public `*Props` types from
 - `use-mobile`
   - Import path: `@uselets/ui/hooks/use-mobile`
   - Exports: `useIsMobile`
+- `use-breakpoint`
+  - Import path: `@uselets/ui/hooks/use-breakpoint`
+  - Exports: `useBreakpoint`, `Breakpoint`, `breakpointValues`
+  - Notes: returns whether the current viewport is at or above a Tailwind default breakpoint (`base`, `sm`, `md`, `lg`, `xl`, `2xl`)
+- `use-breakpoint-value`
+  - Import path: `@uselets/ui/hooks/use-breakpoint-value`
+  - Exports: `useBreakpointValue`, `ResponsiveValueMap`
+  - Notes: accepts a breakpoint value map such as `{ base: 1, md: 2 }` and returns the largest active value
 - `use-disclosure`
   - Import path: `@uselets/ui/hooks/use-disclosure`
   - Exports: `useDisclosure`
@@ -45,6 +53,10 @@ Unless noted otherwise, each module also exports its public `*Props` types from
 - `utils`
   - Import path: `@uselets/ui/utils`
   - Exports: `cn`, `randomId`
+- `color`
+  - Import path: `@uselets/ui/lib/color`
+  - Exports: `uiColors`, `UIColor`, `selectionControlColorVariants`
+  - Notes: canonical public color list used by `Button`, `Toggle`, `Checkbox`, `RadioGroupItem`, and `Switch`; `ButtonColor` is a compatibility alias for `UIColor`; `selectionControlColorVariants` is an internal styling map for checked selection controls
 - `sonner`
   - Import path: `@uselets/ui/sonner`
   - Exports: `Toaster`, `toast`
@@ -82,7 +94,7 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `Badge`, `badgeVariants`
 - `button`
   - Exports: `Button`, `buttonVariants`
-  - Notes: action button with `solid`, `outline`, `subtle`, `ghost`, `destructive`, and `link` variants, theme color families (`brand` default), and icon sizes
+  - Notes: action button with `solid`, `outline`, `subtle`, `ghost`, and `link` variants, `color: UIColor` (`primary` default), sizes from `xs` through `xl` plus icon sizes through `icon-xl`, and `loading`
 - `button-group`
   - Exports: `ButtonGroup`, `ButtonGroupSeparator`, `ButtonGroupText`, `buttonGroupVariants`
 - `empty`
@@ -99,6 +111,15 @@ Unless noted otherwise, each module also exports its public `*Props` types from
 - `field`
   - Exports: `Field`, `FieldContent`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldLabel`, `FieldLegend`, `FieldSeparator`, `FieldSet`, `FieldTitle`
   - Notes: form layout and validation helpers
+- `grid`
+  - Exports: `Grid`, `GridItem`
+  - Notes: 12-column CSS grid by default. `Grid` supports spacing props plus direct `templateRows` and `templateColumns`; `GridItem` defaults to `colSpan={12}` and supports numeric `colSpan` and `rowSpan`. Use `useBreakpointValue` when these values need to change by breakpoint.
+- `simple-grid`
+  - Exports: `SimpleGrid`
+  - Notes: simple grid with `cols`, `gap`, `rowGap`, and `columnGap`. `cols` accepts a number; spacing uses the `xs` to `xl` scale. Use `useBreakpointValue` when column count needs responsive values.
+- `visibility`
+  - Exports: `HiddenFrom`, `VisibleFrom`
+  - Notes: breakpoint visibility wrappers. `HiddenFrom breakpoint="md"` hides at `md` and above; `VisibleFrom breakpoint="md"` shows at `md` and above.
 - `input`
   - Exports: `Input`
 - `textarea`
@@ -110,28 +131,36 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot`, `REGEXP_ONLY_CHARS`, `REGEXP_ONLY_DIGITS`, `REGEXP_ONLY_DIGITS_AND_CHARS`
 - `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)
 - `switch`
   - Exports: `Switch`
+  - Notes: supports `size: 'sm' | 'md' | 'lg'`, `color: UIColor` (default `green`), `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; `color` controls the checked track and indicator color only; track size is `sm` 34x16px, `md` 42x20px, and `lg` 48x22px; the thumb and internal indicator scale with the switch; composed label text follows switch size (`sm` 12px, `md` 14px, `lg` 20px)
 - `radio-group`
   - Exports: `RadioGroup`, `RadioGroupItem`
+  - Notes: `RadioGroup` supports `color: UIColor` (default `primary`) for the group; `RadioGroupItem` supports `size: 'sm' | 'md' | 'lg'`, optional `color: UIColor` item overrides, `label?: React.ReactNode`, `labelProps`, and automatic `id`/`htmlFor` wiring when a label is provided without an explicit `id`; composed label text follows item size (`sm` 12px, `md` 14px, `lg` 20px)
 - `select`
   - Exports: `Select`, `SelectContent`, `SelectGroup`, `SelectItem`, `SelectLabel`, `SelectScrollDownButton`, `SelectScrollUpButton`, `SelectSeparator`, `SelectTrigger`, `SelectValue`
 - `native-select`
   - Exports: `NativeSelect`, `NativeSelectOptGroup`, `NativeSelectOption`
 - `combobox`
   - Exports: `Combobox`, `ComboboxInput`, `ComboboxContent`, `ComboboxList`, `ComboboxItem`, `ComboboxGroup`, `ComboboxLabel`, `ComboboxCollection`, `ComboboxClear`, `ComboboxEmpty`, `ComboboxSeparator`, `ComboboxChips`, `ComboboxChip`, `ComboboxChipsInput`, `ComboboxTrigger`, `ComboboxValue`, `useComboboxAnchor`
+  - Notes: `ComboboxInput` supports `icon?: React.ReactNode`, `triggerIcon?: React.ReactNode`, `showTrigger?: boolean`, and `showClear?: boolean`; the trigger icon defaults to `IconSelector`
 - `dropzone`
   - Exports: `Dropzone`, `DropzoneArea`, `DropzoneDescription`, `DropzoneFileList`, `DropzoneFileListItem`, `DropzoneFileMessage`, `DropzoneMessage`, `DropzoneRemoveFile`, `DropzoneRetryFile`, `DropzoneTrigger`, `InfiniteProgress`, `useDropzone`
   - Notes: upload composition with validation, retry handling, status list UI, and optional `shiftOnMaxFiles`
 - `calendar`
   - Exports: `Calendar`, `CalendarDayButton`
-  - Notes: also exports the `DateRange` type
+  - Notes: 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`
+  - Exports: `DateRangePicker`, `DateRangePickerTrigger`, `DateRangePickerValue`, `DateRangePickerContent`, `DateRangePickerPresets`, `DateRangePickerPreset`, `DateRangePickerCalendar`, `DateRangePickerDateFields`, `DateRangePickerActions`, `DateRangePickerApply`, `DateRangePickerReset`
+  - Notes: compound popover picker using `Calendar` range mode with two months; draft changes from fixed presets, relative-day inputs, date inputs, and calendar stay synchronized until apply; reset and applied clear emit `null` through `onValueChange`; preset buttons show selected state when the draft range matches by calendar day
 - `slider`
   - Exports: `Slider`
 - `label`
   - Exports: `Label`
 - `toggle`
   - Exports: `Toggle`, `toggleVariants`
+  - Notes: supports `color: UIColor` using the same color variants as `Button`
 - `toggle-group`
   - Exports: `ToggleGroup`, `ToggleGroupItem`
 
@@ -141,8 +170,6 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `Dialog`, `DialogClose`, `DialogContent`, `DialogDescription`, `DialogFooter`, `DialogHeader`, `DialogOverlay`, `DialogPortal`, `DialogTitle`, `DialogTrigger`
 - `drawer`
   - Exports: `Drawer`, `DrawerClose`, `DrawerContent`, `DrawerDescription`, `DrawerFooter`, `DrawerHeader`, `DrawerOverlay`, `DrawerPortal`, `DrawerTitle`, `DrawerTrigger`
-- `sheet`
-  - Exports: `Sheet`, `SheetPortal`, `SheetTrigger`, `SheetClose`, `SheetOverlay`, `SheetContent`, `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`
 - `popover`
   - Exports: `Popover`, `PopoverAnchor`, `PopoverContent`, `PopoverDescription`, `PopoverHeader`, `PopoverTitle`, `PopoverTrigger`
 - `hover-card`
@@ -164,6 +191,7 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `Sidebar`, `SidebarContent`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupAction`, `SidebarGroupContent`, `SidebarGroupLabel`, `SidebarHeader`, `SidebarInput`, `SidebarInset`, `SidebarMenu`, `SidebarMenuAction`, `SidebarMenuBadge`, `SidebarMenuButton`, `SidebarMenuItem`, `SidebarMenuSkeleton`, `SidebarMenuSub`, `SidebarMenuSubButton`, `SidebarMenuSubItem`, `SidebarProvider`, `SidebarRail`, `SidebarSeparator`, `SidebarTrigger`, `useSidebar`
 - `tabs`
   - Exports: `Tabs`, `TabsContent`, `TabsList`, `tabsListVariants`, `TabsTrigger`
+  - Notes: `TabsList.variant` supports `line` and `enclosed`, defaults to `line`, accepts `grow?: boolean` for equal-width horizontal tabs, and uses the `primary` color for the active line indicator
 
 ## Layout and display
 
@@ -185,6 +213,7 @@ Unless noted otherwise, each module also exports its public `*Props` types from
   - Exports: `Container`, `containerVariants`
 - `group`
   - Exports: `Group`, `groupVariants`
+  - Notes: supports `gap: 'xs' | 'sm' | 'md' | 'lg' | 'xl'` and `wrap`
 - `kbd`
   - Exports: `Kbd`, `KbdGroup`
 - `resizable`
@@ -195,6 +224,7 @@ 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'`
 - `table`
   - Exports: `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption`
 - `timeline`

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

@@ -88,12 +88,14 @@ Use `bun uselets skill --agent codex` or `bun uselets skill --agent claude` to i
   - subpath import for dedicated hooks such as `use-mobile`, `use-disclosure`, or `use-local-storage`
 - `@uselets/ui/utils`
   - utility helpers such as `cn` and `randomId`
+- `@uselets/ui/lib/color`
+  - shared UI color list and type: `uiColors`, `UIColor`
 - `@uselets/ui/styles.css`
   - legacy compatibility stylesheet equivalent to the Max theme
 - `@uselets/ui/themes/max.css`
   - Max theme tokens and component styles
 - `@uselets/ui/themes/gomax.css`
-  - Gomax theme tokens and component styles
+  - GoMax theme tokens and component styles backed by the GoMax Figma palette
 - `@uselets/ui/postcss.config`
   - reusable PostCSS preset for Tailwind v4 setups
 
@@ -106,7 +108,7 @@ import '@uselets/ui/themes/max.css'
 import '@fontsource-variable/inter'
 ```
 
-For Gomax apps, import `@uselets/ui/themes/gomax.css` instead. The legacy `@uselets/ui/styles.css` entrypoint remains available as a Max-theme alias.
+For GoMax apps, import `@uselets/ui/themes/gomax.css` instead. The legacy `@uselets/ui/styles.css` entrypoint remains available as a Max-theme alias.
 
 If the app needs Tailwind v4 PostCSS setup, reuse the package preset:
 
@@ -120,12 +122,31 @@ Make sure Tailwind itself is imported in the app stylesheet:
 @import 'tailwindcss';
 ```
 
+## Typography scale
+
+The Max theme uses Inter as `font-sans` and overrides Tailwind CSS text size utilities from `text-xs` through
+`text-6xl`. Each size includes a default line height equal to `font-size * 1.5`.
+
+| Utility | Font size | Line height |
+| --- | --- | --- |
+| `text-xs` | `0.75rem` / `12px` | `1.125rem` / `18px` |
+| `text-sm` | `0.875rem` / `14px` | `1.3125rem` / `21px` |
+| `text-base` | `1rem` / `16px` | `1.5rem` / `24px` |
+| `text-lg` | `1.125rem` / `18px` | `1.6875rem` / `27px` |
+| `text-xl` | `1.25rem` / `20px` | `1.875rem` / `30px` |
+| `text-2xl` | `1.5rem` / `24px` | `2.25rem` / `36px` |
+| `text-3xl` | `1.875rem` / `30px` | `2.8125rem` / `45px` |
+| `text-4xl` | `2.25rem` / `36px` | `3.375rem` / `54px` |
+| `text-5xl` | `3rem` / `48px` | `4.5rem` / `72px` |
+| `text-6xl` | `3.75rem` / `60px` | `5.625rem` / `90px` |
+
 ## Import patterns
 
 Use these patterns:
 
 ```tsx
 import { Alert, Button, cn, randomId } from '@uselets/ui'
+import type { UIColor } from '@uselets/ui'
 import { Dialog } from '@uselets/ui/dialog'
 import { useIsMobile } from '@uselets/ui/hooks/use-mobile'
 import { useDisclosure } from '@uselets/ui/hooks/use-disclosure'
@@ -140,7 +161,7 @@ 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`.
+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`.
 
 `useLocalStorage` uses an options object and returns a tuple like `useState`:
 
@@ -208,18 +229,23 @@ export function AppRoot({ children }: { children: React.ReactNode }) {
 
 The package stylesheet exposes these palette families:
 
+- `primary`
 - `brand`
+- `gray`
 - `zinc`
 - `red`
+- `yellow`
 - `blue`
 - `indigo`
 - `pink`
 - `green`
 
+The same palette family names are exported as `uiColors` and `UIColor`. `Button`, `Toggle`, `Checkbox`, `RadioGroupItem`, and `Switch` use `UIColor` for color props. `ButtonColor` remains available as a compatibility alias, but new public APIs should use `UIColor`.
+
 Each palette family is exposed as:
 
-- CSS variables such as `--brand-500`
-- Tailwind v4 utilities such as `bg-brand-500`, `text-zinc-900`, `border-red-300`
+- CSS variables such as `--primary-500`, `--brand-500`, and `--zinc-900`
+- Tailwind v4 utilities such as `bg-primary-500`, `text-zinc-900`, `border-red-300`
 
 Primary semantic tokens:
 
@@ -234,9 +260,18 @@ Additional tokens:
 - `--destructive-foreground`
 - `text-destructive-foreground`
 - `--gradient-primary`
-- `--gradient-secondary`
 
-The `Button` component can apply those palette families directly through `color: 'brand' | 'zinc' | 'red' | 'blue' | 'indigo' | 'pink' | 'green'`, with `brand` as the default. Its public variants are `solid`, `outline`, `subtle`, `ghost`, `destructive`, and `link`, with `solid` as the default.
+The `Button` component can apply those palette families directly through `color: UIColor`, with `primary` as the default. Its public variants are `solid`, `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 `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 `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 `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.
 
 ## Component selection
 
@@ -245,9 +280,9 @@ Choose components by intent:
 - actions and status:
   - `Button`, `Badge`, `Alert`, `Progress`, `Skeleton`, `Spinner`, `toast`
 - forms and inputs:
-  - `Field`, `Input`, `Textarea`, `Checkbox`, `Switch`, `RadioGroup`, `Select`, `NativeSelect`, `Combobox`, `Dropzone`, `InputGroup`, `InputOTP`, `Slider`
+  - `Field`, `Input`, `Textarea`, `Checkbox`, `Switch`, `RadioGroup`, `Select`, `NativeSelect`, `Combobox`, `Dropzone`, `InputGroup`, `InputOTP`, `Slider`, `DateRangePicker`
 - overlays and floating UI:
-  - `Dialog`, `Drawer`, `Sheet`, `Popover`, `Tooltip`, `HoverCard`, `AlertDialog`
+  - `Dialog`, `Drawer`, `Popover`, `Tooltip`, `HoverCard`, `AlertDialog`
 - navigation:
   - `Breadcrumb`, `NavigationMenu`, `Pagination`, `Sidebar`, `Tabs`, `DropdownMenu`, `Command`
 - typography: