@adamosuiteservices/ui 2.11.15 → 2.11.17

package/docs/components/ui/checkbox.md

@@ -1,292 +1,292 @@
-# Checkbox
-
-Checkbox basado en Radix UI con 3 estados (checked, unchecked, indeterminate), validación con `aria-invalid`, focus ring, y estado disabled.
-
-## Importación
-
-```tsx
-import { Checkbox } from "@adamosuiteservices/ui/checkbox";
-import { Label } from "@adamosuiteservices/ui/label";
-```
-
-## Anatomía
-
-```tsx
-// Componente único, sin subcomponentes
-<Checkbox />
-
-// Con label (patrón recomendado)
-<div className="flex items-center gap-3">
-  <Checkbox id="terms" />
-  <Label htmlFor="terms">Accept terms</Label>
-</div>
-```
-
-## Props Principales
-
-| Prop              | Tipo                                            | Default | Descripción                                  |
-| ----------------- | ----------------------------------------------- | ------- | -------------------------------------------- |
-| `checked`         | `boolean \| "indeterminate"`                    | -       | Estado controlado (true/false/indeterminate) |
-| `defaultChecked`  | `boolean`                                       | `false` | Estado inicial no controlado                 |
-| `onCheckedChange` | `(checked: boolean \| "indeterminate") => void` | -       | Callback al cambiar estado                   |
-| `disabled`        | `boolean`                                       | `false` | Desactiva interacción                        |
-| `required`        | `boolean`                                       | `false` | Campo requerido (HTML5)                      |
-| `name`            | `string`                                        | -       | Nombre para formularios                      |
-| `value`           | `string`                                        | `"on"`  | Valor para formularios                       |
-| `aria-invalid`    | `boolean`                                       | `false` | Muestra estado error (border rojo + ring)    |
-| `className`       | `string`                                        | -       | Clases CSS adicionales                       |
-
-## Estados del Checkbox
-
-### 1. Unchecked (Default)
-
-```tsx
-<Checkbox />
-```
-
-### 2. Checked
-
-```tsx
-// No controlado
-<Checkbox defaultChecked />;
-
-// Controlado
-const [checked, setChecked] = useState(true);
-<Checkbox checked={checked} onCheckedChange={setChecked} />;
-```
-
-### 3. Indeterminate
-
-Estado especial para "select all" cuando algunos items están seleccionados.
-
-```tsx
-<Checkbox checked="indeterminate" />;
-
-// Ejemplo práctico
-const allChecked = items.every(Boolean);
-const someChecked = items.some(Boolean) && !allChecked;
-
-<Checkbox
-  checked={allChecked ? true : someChecked ? "indeterminate" : false}
-  onCheckedChange={(checked) => setItems(items.map(() => checked === true))}
-/>;
-```
-
-**Visual**: Muestra un icono de guión (`MinusIcon`) en lugar de check.
-
-### 4. Disabled
-
-```tsx
-<Checkbox disabled />
-<Checkbox disabled defaultChecked />
-```
-
-**Estilos**: `opacity-50` + `cursor-not-allowed`
-
-### 5. Invalid (Error State)
-
-```tsx
-<Checkbox aria-invalid />
-```
-
-**Estilos**: Border rojo (`border-destructive`) + ring rojo (`ring-destructive/20`)
-
-## Patrones de Uso
-
-### Con Label Simple
-
-```tsx
-<div className="flex items-center gap-3">
-  <Checkbox id="notifications" />
-  <Label htmlFor="notifications">Enable notifications</Label>
-</div>
-```
-
-### Con Label y Descripción
-
-```tsx
-<div className="flex items-start gap-3">
-  <Checkbox id="marketing" />
-  <div className="grid gap-1">
-    <Label htmlFor="marketing">Marketing emails</Label>
-    <p className="text-sm text-muted-foreground">
-      Receive updates about new products
-    </p>
-  </div>
-</div>
-```
-
-### Lista de Opciones
-
-```tsx
-const options = ["Email", "SMS", "Push"];
-
-<div className="space-y-4">
-  {options.map((option) => (
-    <div key={option} className="flex items-center gap-3">
-      <Checkbox id={option.toLowerCase()} />
-      <Label htmlFor={option.toLowerCase()}>{option} notifications</Label>
-    </div>
-  ))}
-</div>;
-```
-
-### Select All con Indeterminate
-
-```tsx
-const [items, setItems] = useState([false, true, false]);
-const allChecked = items.every(Boolean);
-const isIndeterminate = items.some(Boolean) && !allChecked;
-
-<div className="space-y-4">
-  {/* Parent checkbox */}
-  <div className="flex items-center gap-3">
-    <Checkbox
-      checked={allChecked ? true : isIndeterminate ? "indeterminate" : false}
-      onCheckedChange={(checked) => setItems(items.map(() => checked === true))}
-    />
-    <Label className="font-medium">Select all</Label>
-  </div>
-
-  {/* Child checkboxes */}
-  <div className="ml-6 space-y-3">
-    {items.map((checked, i) => (
-      <div key={i} className="flex items-center gap-3">
-        <Checkbox
-          checked={checked}
-          onCheckedChange={(newChecked) => {
-            const newItems = [...items];
-            newItems[i] = newChecked as boolean;
-            setItems(newItems);
-          }}
-        />
-        <Label>Item {i + 1}</Label>
-      </div>
-    ))}
-  </div>
-</div>;
-```
-
-### Card/Button Style
-
-Para checkboxes clickeables como botones.
-
-```tsx
-<Label className="flex items-start gap-3 rounded-lg border p-4 cursor-pointer hover:bg-accent/50 has-aria-checked:border-primary has-aria-checked:bg-primary/5 transition-colors">
-  <Checkbox id="card-option" />
-  <div className="grid gap-1.5">
-    <p className="text-sm font-medium">Enable feature</p>
-    <p className="text-sm text-muted-foreground">Description</p>
-  </div>
-</Label>
-```
-
-**Nota**: `has-aria-checked` detecta cuando el checkbox está checked para estilos.
-
-### Formulario de Preferencias
-
-```tsx
-function PreferencesForm() {
-  const [prefs, setPrefs] = useState({
-    marketing: false,
-    analytics: true,
-    social: false,
-  });
-
-  return (
-    <form className="space-y-4">
-      {Object.entries(prefs).map(([key, value]) => (
-        <div key={key} className="flex items-center gap-3">
-          <Checkbox
-            id={key}
-            checked={value}
-            onCheckedChange={(checked) =>
-              setPrefs((prev) => ({ ...prev, [key]: checked as boolean }))
-            }
-          />
-          <Label htmlFor={key}>{key} preferences</Label>
-        </div>
-      ))}
-      <Button type="submit">Save</Button>
-    </form>
-  );
-}
-```
-
-### Terms & Conditions
-
-```tsx
-const [agreed, setAgreed] = useState(false);
-
-<div className="flex items-start gap-3">
-  <Checkbox
-    id="terms"
-    checked={agreed}
-    onCheckedChange={(checked) => setAgreed(checked as boolean)}
-    aria-invalid={!agreed}
-  />
-  <Label htmlFor="terms" className="text-sm">
-    I agree to the{" "}
-    <a href="/terms" className="underline">terms and conditions</a>
-  </Label>
-</div>
-<Button disabled={!agreed}>Continue</Button>
-```
-
-## Estilos Internos (Data Attributes)
-
-### Estados Visuales
-
-- **Checked**: `data-[state=checked]` → `bg-primary`, `text-primary-foreground`, `border-primary`
-- **Unchecked**: Default → `border-input`, `bg-transparent` (dark: `bg-input/30`)
-- **Indeterminate**: `data-[state=indeterminate]` → Muestra `MinusIcon` en lugar de `CheckIcon`
-- **Focus**: `focus-visible:ring-[3px]`, `focus-visible:ring-ring/50`, `focus-visible:border-ring`
-- **Invalid**: `aria-invalid:border-destructive`, `aria-invalid:ring-destructive/20`
-
-### Iconos
-
-- **CheckIcon**: Se muestra cuando `state=checked` (oculto con `group-data-[state=indeterminate]:hidden`)
-- **MinusIcon**: Se muestra cuando `state=indeterminate` (oculto con `group-data-[state=checked]:hidden`)
-- Tamaño: `size-3.5`, color blanco (`text-white`) para check, primary para minus
-
-## Casos de Uso Comunes
-
-**Términos y condiciones**: Single checkbox requerido para continuar  
-**Preferencias de notificación**: Múltiples checkboxes independientes  
-**Select all**: Checkbox parent con estado indeterminate  
-**Filtros**: Checkboxes para filtrar listas/tablas  
-**Permisos**: Grant/revoke permissions con checkboxes  
-**Multi-select lists**: Selección múltiple en tablas/listas
-
-## Accesibilidad
-
-- ✅ **Navegación teclado**: Space para toggle, Tab para navegar
-- ✅ **ARIA**: `role="checkbox"`, `aria-checked="true|false|mixed"` (mixed = indeterminate)
-- ✅ **Labels**: Siempre usar `<Label htmlFor="id">` para clickear label
-- ✅ **Focus visible**: Ring azul en focus con teclado
-- ✅ **Screen readers**: Anuncia estado checked/unchecked/indeterminate
-- ✅ **Peer class**: Permite estilos CSS basados en estado para labels
-
-## Notas de Implementación
-
-- **Basado en Radix UI**: `@radix-ui/react-checkbox`
-- **Tamaño**: `size-5` (20px × 20px), no tiene variantes de tamaño
-- **Border radius**: `rounded-[6px]` fijo
-- **Shadow**: `shadow-xs` sutil
-- **Transition**: `transition-shadow` solo en shadow (no en background para performance)
-- **Peer utility**: Tiene clase `peer` para estilos con `peer-*:` en hermanos
-- **Data slots**: `data-slot="checkbox"` y `data-slot="checkbox-indicator"`
-- **Form integration**: Soporta `name` y `value` para formularios nativos
-- **RTL ready**: Funciona correctamente en right-to-left
-
-## Troubleshooting
-
-**Label no clickeable**: Asegúrate de usar `id` en Checkbox y `htmlFor` en Label  
-**Estado no cambia**: Verifica que uses `onCheckedChange` en modo controlado  
-**Indeterminate no se ve**: El valor debe ser string `"indeterminate"`, no boolean  
-**Focus ring no aparece**: Verifica que no haya `outline-none` sin `focus-visible:ring`
-
-## Referencias
-
-- **Radix UI Checkbox**: https://www.radix-ui.com/primitives/docs/components/checkbox
-- **ARIA Checkbox**: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/
+# Checkbox
+
+Checkbox basado en Radix UI con 3 estados (checked, unchecked, indeterminate), validación con `aria-invalid`, focus ring, y estado disabled.
+
+## Importación
+
+```tsx
+import { Checkbox } from "@adamosuiteservices/ui/checkbox";
+import { Label } from "@adamosuiteservices/ui/label";
+```
+
+## Anatomía
+
+```tsx
+// Componente único, sin subcomponentes
+<Checkbox />
+
+// Con label (patrón recomendado)
+<div className="flex items-center gap-3">
+  <Checkbox id="terms" />
+  <Label htmlFor="terms">Accept terms</Label>
+</div>
+```
+
+## Props Principales
+
+| Prop              | Tipo                                            | Default | Descripción                                  |
+| ----------------- | ----------------------------------------------- | ------- | -------------------------------------------- |
+| `checked`         | `boolean \| "indeterminate"`                    | -       | Estado controlado (true/false/indeterminate) |
+| `defaultChecked`  | `boolean`                                       | `false` | Estado inicial no controlado                 |
+| `onCheckedChange` | `(checked: boolean \| "indeterminate") => void` | -       | Callback al cambiar estado                   |
+| `disabled`        | `boolean`                                       | `false` | Desactiva interacción                        |
+| `required`        | `boolean`                                       | `false` | Campo requerido (HTML5)                      |
+| `name`            | `string`                                        | -       | Nombre para formularios                      |
+| `value`           | `string`                                        | `"on"`  | Valor para formularios                       |
+| `aria-invalid`    | `boolean`                                       | `false` | Muestra estado error (border rojo + ring)    |
+| `className`       | `string`                                        | -       | Clases CSS adicionales                       |
+
+## Estados del Checkbox
+
+### 1. Unchecked (Default)
+
+```tsx
+<Checkbox />
+```
+
+### 2. Checked
+
+```tsx
+// No controlado
+<Checkbox defaultChecked />;
+
+// Controlado
+const [checked, setChecked] = useState(true);
+<Checkbox checked={checked} onCheckedChange={setChecked} />;
+```
+
+### 3. Indeterminate
+
+Estado especial para "select all" cuando algunos items están seleccionados.
+
+```tsx
+<Checkbox checked="indeterminate" />;
+
+// Ejemplo práctico
+const allChecked = items.every(Boolean);
+const someChecked = items.some(Boolean) && !allChecked;
+
+<Checkbox
+  checked={allChecked ? true : someChecked ? "indeterminate" : false}
+  onCheckedChange={(checked) => setItems(items.map(() => checked === true))}
+/>;
+```
+
+**Visual**: Muestra un icono de guión (`MinusIcon`) en lugar de check.
+
+### 4. Disabled
+
+```tsx
+<Checkbox disabled />
+<Checkbox disabled defaultChecked />
+```
+
+**Estilos**: `opacity-50` + `cursor-not-allowed`
+
+### 5. Invalid (Error State)
+
+```tsx
+<Checkbox aria-invalid />
+```
+
+**Estilos**: Border rojo (`border-destructive`) + ring rojo (`ring-destructive/20`)
+
+## Patrones de Uso
+
+### Con Label Simple
+
+```tsx
+<div className="flex items-center gap-3">
+  <Checkbox id="notifications" />
+  <Label htmlFor="notifications">Enable notifications</Label>
+</div>
+```
+
+### Con Label y Descripción
+
+```tsx
+<div className="flex items-start gap-3">
+  <Checkbox id="marketing" />
+  <div className="grid gap-1">
+    <Label htmlFor="marketing">Marketing emails</Label>
+    <p className="text-sm text-muted-foreground">
+      Receive updates about new products
+    </p>
+  </div>
+</div>
+```
+
+### Lista de Opciones
+
+```tsx
+const options = ["Email", "SMS", "Push"];
+
+<div className="space-y-4">
+  {options.map((option) => (
+    <div key={option} className="flex items-center gap-3">
+      <Checkbox id={option.toLowerCase()} />
+      <Label htmlFor={option.toLowerCase()}>{option} notifications</Label>
+    </div>
+  ))}
+</div>;
+```
+
+### Select All con Indeterminate
+
+```tsx
+const [items, setItems] = useState([false, true, false]);
+const allChecked = items.every(Boolean);
+const isIndeterminate = items.some(Boolean) && !allChecked;
+
+<div className="space-y-4">
+  {/* Parent checkbox */}
+  <div className="flex items-center gap-3">
+    <Checkbox
+      checked={allChecked ? true : isIndeterminate ? "indeterminate" : false}
+      onCheckedChange={(checked) => setItems(items.map(() => checked === true))}
+    />
+    <Label className="font-medium">Select all</Label>
+  </div>
+
+  {/* Child checkboxes */}
+  <div className="ml-6 space-y-3">
+    {items.map((checked, i) => (
+      <div key={i} className="flex items-center gap-3">
+        <Checkbox
+          checked={checked}
+          onCheckedChange={(newChecked) => {
+            const newItems = [...items];
+            newItems[i] = newChecked as boolean;
+            setItems(newItems);
+          }}
+        />
+        <Label>Item {i + 1}</Label>
+      </div>
+    ))}
+  </div>
+</div>;
+```
+
+### Card/Button Style
+
+Para checkboxes clickeables como botones.
+
+```tsx
+<Label className="flex items-start gap-3 rounded-lg border p-4 cursor-pointer hover:bg-accent/50 has-aria-checked:border-primary has-aria-checked:bg-primary/5 transition-colors">
+  <Checkbox id="card-option" />
+  <div className="grid gap-1.5">
+    <p className="text-sm font-medium">Enable feature</p>
+    <p className="text-sm text-muted-foreground">Description</p>
+  </div>
+</Label>
+```
+
+**Nota**: `has-aria-checked` detecta cuando el checkbox está checked para estilos.
+
+### Formulario de Preferencias
+
+```tsx
+function PreferencesForm() {
+  const [prefs, setPrefs] = useState({
+    marketing: false,
+    analytics: true,
+    social: false,
+  });
+
+  return (
+    <form className="space-y-4">
+      {Object.entries(prefs).map(([key, value]) => (
+        <div key={key} className="flex items-center gap-3">
+          <Checkbox
+            id={key}
+            checked={value}
+            onCheckedChange={(checked) =>
+              setPrefs((prev) => ({ ...prev, [key]: checked as boolean }))
+            }
+          />
+          <Label htmlFor={key}>{key} preferences</Label>
+        </div>
+      ))}
+      <Button type="submit">Save</Button>
+    </form>
+  );
+}
+```
+
+### Terms & Conditions
+
+```tsx
+const [agreed, setAgreed] = useState(false);
+
+<div className="flex items-start gap-3">
+  <Checkbox
+    id="terms"
+    checked={agreed}
+    onCheckedChange={(checked) => setAgreed(checked as boolean)}
+    aria-invalid={!agreed}
+  />
+  <Label htmlFor="terms" className="text-sm">
+    I agree to the{" "}
+    <a href="/terms" className="underline">terms and conditions</a>
+  </Label>
+</div>
+<Button disabled={!agreed}>Continue</Button>
+```
+
+## Estilos Internos (Data Attributes)
+
+### Estados Visuales
+
+- **Checked**: `data-[state=checked]` → `bg-primary`, `text-primary-foreground`, `border-primary`
+- **Unchecked**: Default → `border-input`, `bg-transparent` (dark: `bg-input/30`)
+- **Indeterminate**: `data-[state=indeterminate]` → Muestra `MinusIcon` en lugar de `CheckIcon`
+- **Focus**: `focus-visible:ring-[3px]`, `focus-visible:ring-ring/50`, `focus-visible:border-ring`
+- **Invalid**: `aria-invalid:border-destructive`, `aria-invalid:ring-destructive/20`
+
+### Iconos
+
+- **CheckIcon**: Se muestra cuando `state=checked` (oculto con `group-data-[state=indeterminate]:hidden`)
+- **MinusIcon**: Se muestra cuando `state=indeterminate` (oculto con `group-data-[state=checked]:hidden`)
+- Tamaño: `size-3.5`, color blanco (`text-white`) para check, primary para minus
+
+## Casos de Uso Comunes
+
+**Términos y condiciones**: Single checkbox requerido para continuar  
+**Preferencias de notificación**: Múltiples checkboxes independientes  
+**Select all**: Checkbox parent con estado indeterminate  
+**Filtros**: Checkboxes para filtrar listas/tablas  
+**Permisos**: Grant/revoke permissions con checkboxes  
+**Multi-select lists**: Selección múltiple en tablas/listas
+
+## Accesibilidad
+
+- ✅ **Navegación teclado**: Space para toggle, Tab para navegar
+- ✅ **ARIA**: `role="checkbox"`, `aria-checked="true|false|mixed"` (mixed = indeterminate)
+- ✅ **Labels**: Siempre usar `<Label htmlFor="id">` para clickear label
+- ✅ **Focus visible**: Ring azul en focus con teclado
+- ✅ **Screen readers**: Anuncia estado checked/unchecked/indeterminate
+- ✅ **Peer class**: Permite estilos CSS basados en estado para labels
+
+## Notas de Implementación
+
+- **Basado en Radix UI**: `@radix-ui/react-checkbox`
+- **Tamaño**: `size-5` (20px × 20px), no tiene variantes de tamaño
+- **Border radius**: `rounded-[6px]` fijo
+- **Shadow**: `shadow-xs` sutil
+- **Transition**: `transition-shadow` solo en shadow (no en background para performance)
+- **Peer utility**: Tiene clase `peer` para estilos con `peer-*:` en hermanos
+- **Data slots**: `data-slot="checkbox"` y `data-slot="checkbox-indicator"`
+- **Form integration**: Soporta `name` y `value` para formularios nativos
+- **RTL ready**: Funciona correctamente en right-to-left
+
+## Troubleshooting
+
+**Label no clickeable**: Asegúrate de usar `id` en Checkbox y `htmlFor` en Label  
+**Estado no cambia**: Verifica que uses `onCheckedChange` en modo controlado  
+**Indeterminate no se ve**: El valor debe ser string `"indeterminate"`, no boolean  
+**Focus ring no aparece**: Verifica que no haya `outline-none` sin `focus-visible:ring`
+
+## Referencias
+
+- **Radix UI Checkbox**: https://www.radix-ui.com/primitives/docs/components/checkbox
+- **ARIA Checkbox**: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/