@adamosuiteservices/ui 2.18.6 → 2.19.1

package/docs/components/ui/calendar.md

@@ -143,32 +143,32 @@ The main component that renders the complete calendar.
 
 #### Props
 
-| Prop              | Type                                                             | Default       | Description                               |
-| ----------------- | ---------------------------------------------------------------- | ------------- | ----------------------------------------- |
-| `mode`            | `"single" \| "multiple" \| "range" \| "default"`                 | `"default"`   | Date selection mode                       |
-| `selected`        | `Date \| Date[] \| DateRange \| undefined`                       | `undefined`   | Selected date(s) according to mode        |
-| `onSelect`        | `(date) => void`                                                 | -             | Callback when selection changes           |
-| `defaultMonth`    | `Date`                                                           | Current month | Initial month to show                     |
-| `numberOfMonths`  | `number`                                                         | `1`           | Number of months to show simultaneously   |
-| `captionLayout`   | `"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"` | `"label"`     | Header navigation type                    |
-| `showOutsideDays` | `boolean`                                                        | `true`        | Show days from adjacent months            |
-| `showWeekNumber`  | `boolean`                                                        | `false`       | Show week numbers                         |
-| `disabled`        | `Date \| Date[] \| DateRange \| ((date: Date) => boolean)`       | -             | Disabled dates                            |
-| `hidden`          | `Date \| Date[] \| DateRange \| ((date: Date) => boolean)`       | -             | Completely hidden dates                   |
-| `fromDate`        | `Date`                                                           | -             | Minimum selectable date                   |
-| `toDate`          | `Date`                                                           | -             | Maximum selectable date                   |
-| `fromMonth`       | `Date`                                                           | -             | Minimum navigable month                   |
-| `toMonth`         | `Date`                                                           | -             | Maximum navigable month                   |
-| `fromYear`        | `number`                                                         | -             | Minimum navigable year                    |
-| `toYear`          | `number`                                                         | -             | Maximum navigable year                    |
-| `timeZone`        | `string`                                                         | System        | Time zone (e.g., `"America/New_York"`)    |
-| `locale`          | `Locale`                                                         | System        | Locale object from `date-fns` for i18n    |
-| `weekStartsOn`    | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`                                | `0`           | Week start day (0=Sunday, 1=Monday)       |
-| `buttonVariant`   | `ButtonProps["variant"]`                                         | `"secondary"` | Variant for navigation buttons            |
-| `className`       | `string`                                                         | -             | Additional CSS classes for container      |
-| `classNames`      | `ClassNames`                                                     | -             | Object with classes for internal elements |
-| `components`      | `Components`                                                     | -             | Custom components for override            |
-| `formatters`      | `Formatters`                                                     | -             | Custom formatting functions               |
+| Prop              | Type                                                             | Default          | Description                               |
+| ----------------- | ---------------------------------------------------------------- | ---------------- | ----------------------------------------- |
+| `mode`            | `"single" \| "multiple" \| "range" \| "default"`                 | `"default"`      | Date selection mode                       |
+| `selected`        | `Date \| Date[] \| DateRange \| undefined`                       | `undefined`      | Selected date(s) according to mode        |
+| `onSelect`        | `(date) => void`                                                 | -                | Callback when selection changes           |
+| `defaultMonth`    | `Date`                                                           | Current month    | Initial month to show                     |
+| `numberOfMonths`  | `number`                                                         | `1`              | Number of months to show simultaneously   |
+| `captionLayout`   | `"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"` | `"label"`        | Header navigation type                    |
+| `showOutsideDays` | `boolean`                                                        | `true`           | Show days from adjacent months            |
+| `showWeekNumber`  | `boolean`                                                        | `false`          | Show week numbers                         |
+| `disabled`        | `Date \| Date[] \| DateRange \| ((date: Date) => boolean)`       | -                | Disabled dates                            |
+| `hidden`          | `Date \| Date[] \| DateRange \| ((date: Date) => boolean)`       | -                | Completely hidden dates                   |
+| `fromDate`        | `Date`                                                           | -                | Minimum selectable date                   |
+| `toDate`          | `Date`                                                           | -                | Maximum selectable date                   |
+| `fromMonth`       | `Date`                                                           | -                | Minimum navigable month                   |
+| `toMonth`         | `Date`                                                           | -                | Maximum navigable month                   |
+| `fromYear`        | `number`                                                         | -                | Minimum navigable year                    |
+| `toYear`          | `number`                                                         | -                | Maximum navigable year                    |
+| `timeZone`        | `string`                                                         | System           | Time zone (e.g., `"America/New_York"`)    |
+| `locale`          | `Locale`                                                         | System           | Locale object from `date-fns` for i18n    |
+| `weekStartsOn`    | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`                                | `0`              | Week start day (0=Sunday, 1=Monday)       |
+| `buttonVariant`   | `ButtonProps["variant"]`                                         | `"link-neutral"` | Variant for navigation buttons            |
+| `className`       | `string`                                                         | -                | Additional CSS classes for container      |
+| `classNames`      | `ClassNames`                                                     | -                | Object with classes for internal elements |
+| `components`      | `Components`                                                     | -                | Custom components for override            |
+| `formatters`      | `Formatters`                                                     | -                | Custom formatting functions               |
 
 ### CalendarDayButton
 
@@ -268,6 +268,30 @@ Only year dropdown, month with arrows.
 <Calendar captionLayout="dropdown-years" />
 ```
 
+## Internationalization (i18n)
+
+Pass any `date-fns/locale` object via the `locale` prop to translate month names, weekday names and the dropdown formatter. Use `labels` to translate the ARIA labels for navigation buttons.
+
+```tsx
+import { es } from "date-fns/locale";
+
+<Calendar
+  mode="single"
+  locale={es}
+  captionLayout="dropdown"
+  labels={{
+    labelPrevious: () => "Mes anterior",
+    labelNext: () => "Mes siguiente",
+    labelMonthDropdown: () => "Seleccionar mes",
+    labelYearDropdown: () => "Seleccionar año",
+  }}
+  selected={date}
+  onSelect={setDate}
+/>;
+```
+
+`date-fns` is a peer dependency of this library — no extra installation needed. Browse available locales at [date-fns.org/docs/I18n](https://date-fns.org/docs/I18n).
+
 ## Advanced patterns
 
 ### Disabled dates (multiple ways)
@@ -962,7 +986,10 @@ const handleSelect = (selectedRange: DateRange | undefined) => {
 - **Grid Layout**: Uses CSS Grid internally for calendar layout
 - **Focus Management**: CalendarDayButton uses `useEffect` for automatic focus on day with `focused` modifier
 - **Data Attributes**: Days use `data-selected-single`, `data-range-start`, `data-range-end`, `data-range-middle` for specific styles
-- **Aspect Ratio**: Days have `aspect-square` for perfectly square cells
+- **Aspect Ratio**: Day cells and buttons use `aspect-41/34` (wider than tall) for a compact rectangular shape
+- **Gap between cells**: `gap-0.5` between columns prevents hover ring from touching adjacent cells
+- **Selected day**: Uses `bg-primary-400` (slightly lighter than primary) for the selected single day
+- **Hover state**: Shows a `ring-1 ring-primary-300` outline on hover instead of a background fill
 - **Button Variants**: Navigation uses `buttonVariants()` from Button component for visual consistency
 - **Dropdown with Overlay**: Dropdowns use native select with invisible overlay (`opacity-0`) for accessibility
 - **Responsive**: Multiple months change from `flex-row` to `flex-col` on mobile with `md:flex-row`

package/docs/components/ui/card.md

@@ -7,10 +7,10 @@ Versatile container with rounded borders, configurable padding, shadow, and bord
 - **6 color variants**: Default, Primary, Muted, Success, Warning, Destructive
 - **2 shadow variants**: Default (with elevation) and None (flat design, default)
 - **2 border variants**: Default (visible) and Transparent (invisible but maintains space)
-- **Modular composition**: 6 subcomponents (Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter)
+- **Modular composition**: 7 subcomponents (Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter)
 - **Automatic header grid**: Detects `CardAction` and automatically adjusts layout with `has-data-[slot=card-action]:grid-cols-[1fr_auto]`
 - **Container queries**: CardHeader uses `@container/card-header` for responsive layouts
-- **Flexible spacing**: `gap-6` between main sections, auto spacing in header/footer with borders
+- **Flexible spacing**: `gap-8` between main sections, auto spacing in header/footer with borders
 - **Optional borders**: `.border-b` and `.border-t` classes add separators with automatic padding
 - **Data slots**: Each subcomponent has `data-slot` for specific CSS targeting
 - **Integration with other components**: Transparent background for Calendar/other nested components
@@ -26,6 +26,7 @@ import {
   CardAction,
   CardContent,
   CardFooter,
+  cardVariants,
 } from "@adamosuiteservices/ui/card";
 ```
 
@@ -143,7 +144,7 @@ Main card title.
 | `className` | `string`    | Additional CSS classes |
 | `children`  | `ReactNode` | Title text             |
 
-**Default styles**: `leading-none font-semibold`
+**Default styles**: `text-sm font-bold text-foreground`
 
 ### CardDescription
 
@@ -156,7 +157,7 @@ Card description or subtitle.
 | `className` | `string`    | Additional CSS classes |
 | `children`  | `ReactNode` | Description text       |
 
-**Default styles**: `text-muted-foreground text-sm`
+**Default styles**: `text-foreground text-sm`
 
 ### CardAction
 

package/docs/components/ui/checkbox.md

@@ -72,7 +72,7 @@ const someChecked = items.some(Boolean) && !allChecked;
 />;
 ```
 
-**Visual**: Shows a minus icon (`MinusIcon`) instead of check.
+**Visual**: Shows a `remove` icon (Material Symbols) instead of check.
 
 ### 4. Disabled
 
@@ -81,7 +81,7 @@ const someChecked = items.some(Boolean) && !allChecked;
 <Checkbox disabled defaultChecked />
 ```
 
-**Styles**: `opacity-50` + `cursor-not-allowed`
+**Styles**: `bg-disabled opacity-100` + `cursor-not-allowed`
 
 ### 5. Invalid (error state)
 
@@ -102,7 +102,7 @@ const someChecked = items.some(Boolean) && !allChecked;
 </div>
 ```
 
-**Styles**: Red border (`border-destructive`) + red ring (`ring-destructive/20`)
+**Styles**: Red border (`border-destructive`) + red ring on focus (`ring-4 ring-destructive/10`)
 
 ## Fieldset disabled
 

package/docs/components/ui/combobox.md

@@ -15,6 +15,11 @@ import { Combobox } from "@adamosuiteservices/ui/combobox";
   options={[
     { value: "option1", label: "Option 1" },
     { value: "option2", label: "Option 2", disabled: true },
+    {
+      value: "option3",
+      label: "Option 3",
+      supportiveText: "Additional context",
+    },
   ]}
   value={selectedValue}
   onValueChange={setSelectedValue}
@@ -27,7 +32,7 @@ import { Combobox } from "@adamosuiteservices/ui/combobox";
 
 | Prop                    | Type                                  | Default      | Description                                                                                                                     |
 | ----------------------- | ------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| `options`               | `ComboboxOption[]`                    | **required** | Array of options `{ value, label, disabled? }`                                                                                  |
+| `options`               | `ComboboxOption[]`                    | **required** | Array of options `{ value, label, disabled?, supportiveText? }`                                                                 |
 | `value`                 | `string \| string[]`                  | -            | Controlled value (string for single, array for multiple)                                                                        |
 | `onValueChange`         | `(value: string \| string[]) => void` | -            | Callback when selection changes                                                                                                 |
 | `searchable`            | `boolean`                             | `false`      | Enables search input                                                                                                            |
@@ -422,6 +427,34 @@ const options = [
 />;
 ```
 
+### With supportive text
+
+Each option can display a secondary line of supporting text below the label.
+
+```tsx
+<Combobox
+  searchable
+  options={[
+    {
+      value: "ne",
+      label: "Next.js",
+      supportiveText: "React framework with SSR and SSG support",
+    },
+    {
+      value: "sv",
+      label: "SvelteKit",
+      supportiveText: "Full-stack framework built on Svelte",
+    },
+    {
+      value: "nu",
+      label: "Nuxt.js",
+      supportiveText: "Vue framework for server-side rendering",
+    },
+  ]}
+  labels={{ placeholder: "Select framework..." }}
+/>
+```
+
 ### Invalid state
 
 ```tsx
@@ -740,6 +773,7 @@ The `renders` prop allows complete UI customization using the render prop patter
 ## Implementation notes
 
 - **Composition**: Uses Popover + Command + Button + Checkbox internally
+- **`ComboboxOption`**: Supports `value`, `label`, `disabled?` and `supportiveText?`. When `supportiveText` is provided, the item uses a two-row layout: label row on top and supporting text below in `text-muted-foreground`.
 - **Search**:
   - Uses custom filter function that searches by label and/or value
   - Case-insensitive by default

package/docs/components/ui/command.md

@@ -40,7 +40,7 @@ import {
 </Command>
 ```
 
-**Components**: 8 (Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut)
+**Components**: 9 (Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut)
 
 ## Main props
 
@@ -390,7 +390,7 @@ function CustomFilter() {
 
 ### CommandItem states
 
-- **Selected**: `data-[selected=true]` → `bg-accent`, `text-accent-foreground`
+- **Selected**: `data-[selected=true]` → `bg-muted`, `text-foreground`
 - **Disabled**: `data-[disabled=true]` → `opacity-50`, `pointer-events-none`
 
 ### Empty state
@@ -441,12 +441,12 @@ function CustomFilter() {
 
 ### CommandItem
 
-- **Height**: `h-10` (40px)
-- **Padding**: `px-3` horizontal, no vertical padding
-- **Border**: `border-b` between items
+- **Min-height**: `min-h-11` (44px)
+- **Padding**: `px-4` horizontal, no vertical padding
+- **Border**: `border-b border-divider` between items
 - **Rounded corners**: Last item has `rounded-b-[calc(var(--radius)-1px)]` and no bottom border
-- **Gap**: `gap-2` between content elements
-- **Icon constraints**: None - icons use natural sizes
+- **Gap**: `gap-3` between content elements
+- **SVG icons**: auto `size-4` and `text-muted-foreground` if no `size-*`/`text-*` class is set
 
 ### CommandGroup
 

package/docs/components/ui/context-menu.md

@@ -95,7 +95,7 @@ import {
 
 **Variants**:
 
-- `default`: `focus:bg-accent`, `focus:text-accent-foreground`
+- `default`: `focus:bg-muted`, `focus:text-foreground`
 - `destructive`: `text-destructive`, `focus:bg-destructive/10`, `focus:text-destructive`
 
 ### ContextMenuCheckboxItem
@@ -107,7 +107,7 @@ import {
 | `disabled`        | `boolean`                    | Disables the item        |
 | `className`       | `string`                     | Additional CSS classes   |
 
-**Indicator**: Check icon (Material Symbol "check") automatic when `checked={true}`, positioned with `pl-8`
+**Indicator**: Check icon (Material Symbol "check") automatic when `checked={true}`, `text-xl text-success`, positioned with `pl-8`
 
 ### ContextMenuRadioGroup
 
@@ -150,7 +150,7 @@ import {
 | `inset`     | `boolean` | Left padding (`pl-8`)  |
 | `className` | `string`  | Additional CSS classes |
 
-**Styles**: `text-foreground`, `font-medium`
+**Styles**: `text-xs`, `text-muted-foreground`, `px-2 py-1.5`
 
 ### ContextMenuShortcut
 
@@ -456,23 +456,22 @@ function App() {
 
 ### Items (MenuItem, SubTrigger)
 
-- **Height**: `min-h-10` (40px minimum, can grow with content)
-- **Padding**: `px-3` (horizontal), no vertical padding (height defines size)
+- **Height**: `h-11` (44px fixed)
+- **Padding**: `pl-4 pr-10` (left/right for icon alignment)
 - **Rounded corners**: `first:rounded-t-sm`, `last:rounded-b-sm` (only first/last items)
 - **Icon constraints**: None - icons use their natural sizes
-- **Gap**: `gap-2` between content elements
+- **Gap**: `gap-3` between content elements
 
 ### CheckboxItem and RadioItem
 
-- **Height**: `min-h-10` (40px minimum)
+- **Height**: `h-11` (44px fixed)
 - **Padding**: `pl-8` (left), `pr-10` (right) - space for indicators
 - **Rounded corners**: `first:rounded-t-sm`, `last:rounded-b-sm`
 
 ### Label
 
-- **Height**: `min-h-10` (40px minimum)
-- **Padding**: `px-3` horizontal
-- **Display**: `flex items-center` for vertical centering
+- **Padding**: `px-2 py-1.5`
+- **Text**: `text-xs text-muted-foreground`
 
 ### Content
 
@@ -490,13 +489,13 @@ function App() {
 
 ### ContextMenuItem states
 
-- **Focus**: `data-[highlighted]` → `bg-accent`, `text-accent-foreground`
+- **Focus**: `data-[highlighted]` → `bg-muted`, `text-foreground`
 - **Disabled**: `data-[disabled=true]` → `opacity-50`, `pointer-events-none`
 - **Destructive**: `data-[variant=destructive]` → `text-destructive`
 
 ### ContextMenuSubTrigger states
 
-- **Open**: `data-[state=open]` → `bg-accent`, `text-accent-foreground`
+- **Open**: `data-[state=open]` → `bg-muted`, `text-foreground`
 
 ### Content animations
 
@@ -569,6 +568,6 @@ By default, the menu appears at cursor position. Can be customized:
 
 ## References
 
-- **Radix UI Context Menu**: https://www.radix-ui.com/primitives/docs/components/context-menu
-- **shadcn/ui Context Menu**: https://ui.shadcn.com/docs/components/context-menu
-- **ARIA Menu Pattern**: https://www.w3.org/WAI/ARIA/apg/patterns/menu/
+- **Radix UI Context Menu**: <https://www.radix-ui.com/primitives/docs/components/context-menu>
+- **shadcn/ui Context Menu**: <https://ui.shadcn.com/docs/components/context-menu>
+- **ARIA Menu Pattern**: <https://www.w3.org/WAI/ARIA/apg/patterns/menu/>

package/docs/components/ui/date-picker-selector.md

@@ -33,13 +33,13 @@ The component manages two Popovers simultaneously:
 **Implemented solution:**
 
 ```tsx
-// 1. El Combobox recibe un ref que apunta a su botón trigger
+// 1. The Combobox receives a ref pointing to its trigger button
 <Combobox
   ref={(node) => { comboboxRef.current = node; }}
   // ...
 />
 
-// 2. El Popover del calendario usa virtualRef para posicionarse
+// 2. The calendar Popover uses virtualRef to position itself
 <Popover open={calendarOpen}>
   <PopoverAnchor virtualRef={comboboxRef} />
   <PopoverContent>
@@ -94,15 +94,15 @@ function MyComponent() {
 
 ## Props
 
-| Prop                | Tipo                             | Default | Description                                 |
-| ------------------- | -------------------------------- | ------- | ------------------------------------------- |
-| `dateRange`         | `DateRange`                      | -       | **Required**. Current date range            |
-| `onDateRangeChange` | `(dateRange: DateRange) => void` | -       | **Required**. Callback when range changes   |
-| `labels`            | `DatePickerSelectorLabels`       | -       | Customizable labels for all UI text         |
-| `combobox`          | `ComboboxProps`                  | -       | Additional props for the Combobox component |
-| `calendar`          | `CalendarProps`                  | -       | Additional props for the Calendar component |
-| `aria-invalid`      | `"true" \| "false" \| boolean`   | -       | Indicates invalid state (red border)        |
-| `disabled`          | `boolean`                        | `false` | Disables the date selector                  |
+| Prop                | Tipo                                                        | Default | Description                                 |
+| ------------------- | ----------------------------------------------------------- | ------- | ------------------------------------------- |
+| `dateRange`         | `DateRange`                                                 | -       | **Required**. Current date range            |
+| `onDateRangeChange` | `(dateRange: DateRange) => void`                            | -       | **Required**. Callback when range changes   |
+| `labels`            | `DatePickerSelectorLabels`                                  | -       | Customizable labels for all UI text         |
+| `combobox`          | `Omit<ComboboxProps, "options">`                            | -       | Additional props for the Combobox component |
+| `calendar`          | `Omit<CalendarProps, "mode" \| "selected" \| "onSelected">` | -       | Additional props for the Calendar component |
+| `aria-invalid`      | `"true" \| "false" \| boolean`                              | -       | Indicates invalid state (red border)        |
+| `disabled`          | `boolean`                                                   | `false` | Disables the date selector                  |
 
 ### DateRange Type
 
@@ -357,23 +357,23 @@ The date selector inside a `<fieldset disabled>` automatically inherits the disa
 
 ### State synchronization
 
-El componente sincroniza automáticamente su estado interno con el prop `dateRange` mediante un `useEffect`. Esto significa que:
+The component automatically synchronizes its internal state with the `dateRange` prop via a `useEffect`. This means that:
 
-- ✅ Cambios externos a `dateRange` actualizan el combobox automáticamente
-- ✅ Resetear el rango externamente (e.g., botón Reset) actualiza la UI correctamente
-- ✅ Formularios que limpian campos funcionan sin configuración adicional
-- ✅ No requiere controlar manualmente el estado del combobox
+- ✅ External changes to `dateRange` update the combobox automatically
+- ✅ Resetting the range externally (e.g., a Reset button) updates the UI correctly
+- ✅ Forms that clear fields work without additional configuration
+- ✅ Does not require manually controlling the combobox state
 
-**Ejemplo de sincronización:**
+**Synchronization example:**
 
 ```tsx
-// Resetear desde código externo
+// Reset from external code
 setDateRange({ from: undefined, to: undefined });
-// → El combobox mostrará automáticamente el placeholder
+// → The combobox will automatically show the placeholder
 
-// Establecer un rango predefinido
+// Set a preset range
 setDateRange({ from: subDays(new Date(), 7), to: new Date() });
-// → El combobox detectará y mostrará "Last 7 days"
+// → The combobox will detect and display "Last 7 days"
 ```
 
 ### Preset ranges
@@ -415,11 +415,11 @@ This ensures the user never ends up with "Custom" selected without having comple
 
 ## Use cases
 
-**Filtros de reportes**: Seleccionar rango de fechas para generar reportes  
-**Dashboards**: Filtrar datos por períodos de tiempo  
-**Analytics**: Comparar métricas en diferentes rangos  
-**Búsquedas**: Filtrar resultados por rango de fechas  
-**Logs**: Visualizar registros en períodos específicos
+**Report filters**: Select date range to generate reports  
+**Dashboards**: Filter data by time periods  
+**Analytics**: Compare metrics across different ranges  
+**Search**: Filter results by date range  
+**Logs**: View records in specific periods
 
 ## Dependencies
 
@@ -452,7 +452,7 @@ This component uses internally:
 ### State management
 
 ```tsx
-// ✅ Correcto - Estado controlado
+// ✅ Correct - Controlled state
 const [dateRange, setDateRange] = useState<DateRange>({
   from: undefined,
   to: undefined,
@@ -460,7 +460,7 @@ const [dateRange, setDateRange] = useState<DateRange>({
 
 <DatePickerSelector dateRange={dateRange} onDateRangeChange={setDateRange} />;
 
-// ❌ Incorrecto - Estado no inicializado
+// ❌ Incorrect - Uninitialized state
 const [dateRange, setDateRange] = useState();
 ```
 
@@ -488,19 +488,19 @@ const handleChange = (range: DateRange) => {
 ```tsx
 import { format } from "date-fns";
 
-// ✅ Correcto - Formatear con date-fns
+// ✅ Correct - Format with date-fns
 const displayDate = dateRange.from
   ? format(dateRange.from, "PP")
   : "Not selected";
 
-// ❌ Evitar - toString() no es user-friendly
+// ❌ Avoid - toString() is not user-friendly
 const displayDate = dateRange.from?.toString();
 ```
 
 ### Internationalization
 
 ```tsx
-// ✅ Correcto - Proporcionar todos los labels
+// ✅ Correct - Provide all labels
 <DatePickerSelector
   labels={{
     last7Days: t("dateRange.last7Days"),