@adamosuiteservices/ui 2.14.1 → 2.15.0

package/docs/components/ui/combobox.md

@@ -39,6 +39,9 @@ import { Combobox } from "@adamosuiteservices/ui/combobox";
 | `labels`                | `ComboboxLabels`                      | -            | Textos personalizables (ver tabla abajo)                    |
 | `classNames`            | `ComboboxClassNames`                  | -            | Clases CSS por sección (ver tabla abajo)                    |
 | `renders`               | `ComboboxRenderProps`                 | -            | Funciones de renderizado personalizadas (ver tabla abajo)   |
+| `ref`                   | `React.Ref<HTMLButtonElement>`        | -            | Ref al botón trigger para posicionamiento externo           |
+| `aria-invalid`          | `"true" \| "false" \| boolean`        | -            | Indica estado inválido (borde rojo)                         |
+| `disabled`              | `boolean`                             | `false`      | Deshabilita el combobox                                     |
 
 ### ComboboxLabels
 
@@ -99,6 +102,45 @@ const frameworks = [
 
 ### Con Icono
 
+```tsx
+<Combobox
+  icon="search"
+  options={frameworks}
+  labels={{ placeholder: "Search framework..." }}
+/>
+```
+
+### Con Ref (Para Posicionamiento Externo)
+
+El Combobox puede recibir un ref que apunta directamente al botón trigger. Esto es útil para posicionar otros elementos relativos al Combobox usando `virtualRef` de Radix UI.
+
+```tsx
+import { useRef } from "react";
+
+function MyComponent() {
+  const comboboxRef = useRef<HTMLButtonElement>(null);
+
+  return (
+    <>
+      <Combobox ref={comboboxRef} options={options} />
+      {/* Usar comboboxRef para posicionar otros elementos */}
+      <Popover>
+        <PopoverAnchor virtualRef={comboboxRef} />
+        <PopoverContent>...</PopoverContent>
+      </Popover>
+    </>
+  );
+}
+```
+
+**Notas importantes sobre el ref:**
+
+- El ref apunta directamente al botón trigger (`<Button>`), no a un wrapper
+- Internamente, el Combobox mantiene su propio ref para medir el ancho del popover
+- Cuando pasas un ref externo, ambos refs se sincronizan automáticamente
+- Compatible con callback refs y object refs (`React.RefObject`)
+- Útil para componentes como `DatePickerSelector` que usan `PopoverAnchor` con `virtualRef`
+
 ```tsx
 <Combobox
   searchable
@@ -246,6 +288,63 @@ const options = [
 />;
 ```
 
+### Estado Inválido
+
+```tsx
+const [value, setValue] = useState("");
+const isInvalid = !value; // Required validation
+
+<div className="space-y-2">
+  <Combobox
+    searchable
+    options={frameworks}
+    value={value}
+    onValueChange={(newValue) => setValue(newValue as string)}
+    aria-invalid={isInvalid}
+    labels={{ placeholder: "Select framework..." }}
+  />
+  {isInvalid && (
+    <p className="text-sm text-destructive">
+      Please select a framework to continue
+    </p>
+  )}
+</div>;
+```
+
+**Estilos**: Cuando `aria-invalid="true"`, el trigger muestra borde rojo (heredado del componente Button).
+
+### Estado Deshabilitado
+
+```tsx
+// Usando disabled
+<Combobox
+  searchable
+  options={frameworks}
+  value="next.js"
+  disabled
+  labels={{ placeholder: "Select framework..." }}
+/>
+```
+
+### En Fieldset Disabled
+
+```tsx
+<fieldset disabled>
+  <legend>Preferences (Disabled)</legend>
+  <Field>
+    <FieldLabel>Framework</FieldLabel>
+    <Combobox
+      searchable
+      options={frameworks}
+      value="next.js"
+      labels={{ placeholder: "Select framework..." }}
+    />
+  </Field>
+</fieldset>
+```
+
+Los comboboxes dentro de un `<fieldset disabled>` automáticamente heredan el estado disabled del navegador.
+
 ### Labels Personalizadas
 
 ```tsx
@@ -542,6 +641,7 @@ El prop `renders` permite personalizar completamente la UI usando el patrón ren
 ### Command Components
 
 Hereda estilos de Command component:
+
 - **Input wrapper**: `h-10`, `px-3`, `border-b`
 - **List**: `max-h-[300px]` con scroll
 - **Empty state**: Centrado con padding vertical

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

@@ -15,6 +15,53 @@ El componente `DatePickerSelector` proporciona una interfaz intuitiva para selec
 - ✅ Integración con Combobox y Calendar
 - ✅ Props personalizables para Combobox y Calendar
 - ✅ Estado controlado con callback onChange
+- ✅ Posicionamiento preciso del calendario mediante `virtualRef`
+
+## Arquitectura
+
+### Gestión de Dos Popovers Independientes
+
+El componente maneja dos Popovers simultáneamente:
+
+1. **Popover del Combobox** - Muestra las opciones de rango (7/30/90 días, Personalizado)
+2. **Popover del Calendario** - Se abre al seleccionar "Personalizado", permite elegir fechas específicas
+
+### Posicionamiento con `virtualRef`
+
+**Problema original:** Un componente no puede ser simultáneamente `PopoverTrigger` (para su propio popover) y `PopoverAnchor` (para otro popover).
+
+**Solución implementada:**
+
+```tsx
+// 1. El Combobox recibe un ref que apunta a su botón trigger
+<Combobox
+  ref={(node) => { comboboxRef.current = node; }}
+  // ...
+/>
+
+// 2. El Popover del calendario usa virtualRef para posicionarse
+<Popover open={calendarOpen}>
+  <PopoverAnchor virtualRef={comboboxRef} />
+  <PopoverContent>
+    <Calendar />
+  </PopoverContent>
+</Popover>
+```
+
+**Ventajas de este enfoque:**
+
+- ✅ Sin elementos wrapper innecesarios en el DOM
+- ✅ Referencia directa al botón trigger del Combobox
+- ✅ Posicionamiento preciso del calendario
+- ✅ El Combobox funciona como trigger y como ancla simultáneamente
+- ✅ Type-safe con el tipo `Measurable` (cualquier elemento con `getBoundingClientRect()`)
+
+**Detalles técnicos:**
+
+- `comboboxRef` tiene tipo `RefObject<Measurable | null>` para compatibilidad con Radix UI
+- El callback ref captura el elemento button cuando se monta
+- Se usa type assertion `as React.RefObject<Measurable>` para satisfacer el tipo de Radix
+- El calendario siempre se posiciona correctamente porque el ref está poblado al abrir el popover
 
 ## Importación
 
@@ -47,13 +94,15 @@ function MyComponent() {
 
 ## Props
 
-| Prop               | Tipo                     | Default     | Descripción                                                    |
-| ------------------ | ------------------------ | ----------- | -------------------------------------------------------------- |
-| `dateRange`        | `DateRange`              | -           | **Requerido**. Rango de fechas actual                          |
-| `onDateRangeChange`| `(dateRange: DateRange) => void` | - | **Requerido**. Callback al cambiar el rango                    |
-| `labels`           | `DatePickerSelectorLabels` | -         | Labels personalizables para todos los textos de UI             |
-| `combobox`         | `ComboboxProps`          | -           | Props adicionales para el componente Combobox                  |
-| `calendar`         | `CalendarProps`          | -           | Props adicionales para el componente Calendar                  |
+| Prop                | Tipo                             | Default | Descripción                                        |
+| ------------------- | -------------------------------- | ------- | -------------------------------------------------- |
+| `dateRange`         | `DateRange`                      | -       | **Requerido**. Rango de fechas actual              |
+| `onDateRangeChange` | `(dateRange: DateRange) => void` | -       | **Requerido**. Callback al cambiar el rango        |
+| `labels`            | `DatePickerSelectorLabels`       | -       | Labels personalizables para todos los textos de UI |
+| `combobox`          | `ComboboxProps`                  | -       | Props adicionales para el componente Combobox      |
+| `calendar`          | `CalendarProps`                  | -       | Props adicionales para el componente Calendar      |
+| `aria-invalid`      | `"true" \| "false" \| boolean`   | -       | Indica estado inválido (borde rojo)                |
+| `disabled`          | `boolean`                        | `false` | Deshabilita el selector de fechas                  |
 
 ### DateRange Type
 
@@ -68,13 +117,13 @@ type DateRange = {
 
 ```typescript
 type DatePickerSelectorLabels = {
-  last30Days?: string;   // Default: "Last 30 days"
-  last7Days?: string;    // Default: "Last 7 days"
-  last90Days?: string;   // Default: "Last 90 days"
-  custom?: string;       // Default: "Custom"
-  placeholder?: string;  // Default: "Date"
-  cancel?: string;       // Default: "Cancel"
-  apply?: string;        // Default: "Apply"
+  last30Days?: string; // Default: "Last 30 days"
+  last7Days?: string; // Default: "Last 7 days"
+  last90Days?: string; // Default: "Last 90 days"
+  custom?: string; // Default: "Custom"
+  placeholder?: string; // Default: "Date"
+  cancel?: string; // Default: "Cancel"
+  apply?: string; // Default: "Apply"
 };
 ```
 
@@ -159,7 +208,10 @@ function MyComponent() {
 
   const formatDateRange = () => {
     if (!dateRange.from || !dateRange.to) return "No date selected";
-    return `${format(dateRange.from, "MMM d, yyyy")} - ${format(dateRange.to, "MMM d, yyyy")}`;
+    return `${format(dateRange.from, "MMM d, yyyy")} - ${format(
+      dateRange.to,
+      "MMM d, yyyy"
+    )}`;
   };
 
   return (
@@ -208,6 +260,61 @@ function MyComponent() {
 }
 ```
 
+### Estado Inválido
+
+```tsx
+function MyComponent() {
+  const [dateRange, setDateRange] = useState<DateRange>({
+    from: undefined,
+    to: undefined,
+  });
+
+  const isInvalid = !dateRange.from || !dateRange.to;
+
+  return (
+    <div className="space-y-2">
+      <DatePickerSelector
+        dateRange={dateRange}
+        onDateRangeChange={setDateRange}
+        aria-invalid={isInvalid}
+        labels={{
+          placeholder: "Date (Required)",
+        }}
+      />
+      {isInvalid && (
+        <p className="text-sm text-destructive">
+          Please select a date range to continue
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+**Estilos**: Cuando `aria-invalid="true"`, el combobox muestra borde rojo (heredado del componente Button).
+
+### Estado Deshabilitado
+
+```tsx
+// Usando disabled
+<DatePickerSelector
+  dateRange={dateRange}
+  onDateRangeChange={setDateRange}
+  disabled
+/>
+```
+
+### En Fieldset Disabled
+
+```tsx
+<fieldset disabled>
+  <legend>Date Range (Disabled)</legend>
+  <DatePickerSelector dateRange={dateRange} onDateRangeChange={setDateRange} />
+</fieldset>
+```
+
+El selector de fechas dentro de un `<fieldset disabled>` automáticamente hereda el estado disabled del navegador.
+
 ## Comportamiento
 
 ### Rangos Predefinidos
@@ -219,6 +326,7 @@ El componente ofrece tres rangos predefinidos:
 - **Last 90 days**: Desde hace 90 días hasta hoy
 
 Todos los rangos predefinidos:
+
 - Usan `date-fns` para cálculos precisos
 - Establecen las fechas a medianoche (00:00:00)
 - Se calculan dinámicamente basándose en la fecha actual
@@ -226,10 +334,19 @@ Todos los rangos predefinidos:
 ### Rango Personalizado
 
 Al seleccionar la opción "Custom":
+
 1. Se abre un popover con un calendario
-2. El usuario selecciona un rango de fechas
+2. El usuario selecciona un rango de fechas (from y to)
 3. Los botones "Cancel" y "Apply" permiten confirmar o descartar la selección
-4. El rango personalizado se mantiene independiente de los rangos predefinidos
+
+**Comportamiento de cancelación:**
+
+- **Botón Cancel**: Restaura la selección anterior y cierra el calendario
+- **Botón Apply sin rango completo**: Si no se seleccionó un rango completo (ambas fechas), restaura la selección anterior
+- **Botón Apply con rango completo**: Aplica el rango personalizado y mantiene "Custom" seleccionado
+- **Click fuera del popover**: Restaura automáticamente la selección anterior si se cierra sin aplicar
+
+Esto asegura que el usuario nunca quede con "Custom" seleccionado sin haber completado la selección de un rango válido.
 
 ### Separación de Estados
 
@@ -243,7 +360,7 @@ Al seleccionar la opción "Custom":
 **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  
+**Logs**: Visualizar registros en períodos específicos
 
 ## Dependencias
 
@@ -282,10 +399,7 @@ const [dateRange, setDateRange] = useState<DateRange>({
   to: undefined,
 });
 
-<DatePickerSelector
-  dateRange={dateRange}
-  onDateRangeChange={setDateRange}
-/>
+<DatePickerSelector dateRange={dateRange} onDateRangeChange={setDateRange} />;
 
 // ❌ Incorrecto - Estado no inicializado
 const [dateRange, setDateRange] = useState();
@@ -303,9 +417,11 @@ const handleChange = (range: DateRange) => {
 };
 
 // ✅ Correcto - Mostrar feedback de validación
-{!dateRange.from || !dateRange.to ? (
-  <p className="text-destructive">Please select both dates</p>
-) : null}
+{
+  !dateRange.from || !dateRange.to ? (
+    <p className="text-destructive">Please select both dates</p>
+  ) : null;
+}
 ```
 
 ### Formateo de Fechas
@@ -314,7 +430,7 @@ const handleChange = (range: DateRange) => {
 import { format } from "date-fns";
 
 // ✅ Correcto - Formatear con date-fns
-const displayDate = dateRange.from 
+const displayDate = dateRange.from
   ? format(dateRange.from, "PP")
   : "Not selected";
 
@@ -366,9 +482,12 @@ const normalizedRange = {
 **Problema**: Los rangos predefinidos no funcionan  
 **Solución**: Asegúrate de que `onDateRangeChange` esté actualizando el estado correctamente.
 
+**Problema**: El calendario se posiciona incorrectamente  
+**Solución**: Este problema fue resuelto en la versión actual usando `virtualRef`. Si usas una versión antigua, actualiza el componente. El calendario ahora se posiciona automáticamente respecto al Combobox usando referencias directas al botón trigger.
+
 ## Referencias
 
 - **Combobox**: [Ver documentación](./combobox.md)
 - **Calendar**: [Ver documentación](./calendar.md)
-- **date-fns**: https://date-fns.org/
-- **react-day-picker**: https://react-day-picker.js.org/
+- **date-fns**: <https://date-fns.org/>
+- **react-day-picker**: <https://react-day-picker.js.org/>