@adamosuiteservices/ui 1.2.5 → 1.3.5

package/docs/components/ui/checkbox.md

@@ -0,0 +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/

package/docs/components/ui/collapsible.md

@@ -0,0 +1,320 @@
+# Collapsible
+
+Componente interactivo basado en Radix UI para expandir/colapsar contenido con animaciones suaves. Útil para FAQs, menús de navegación, y secciones opcionales.
+
+## Importación
+
+```tsx
+import {
+  Collapsible,
+  CollapsibleTrigger,
+  CollapsibleContent,
+} from "@adamosuiteservices/ui/collapsible";
+```
+
+## Anatomía
+
+```tsx
+<Collapsible>
+  <CollapsibleTrigger>Click to toggle</CollapsibleTrigger>
+  <CollapsibleContent>Hidden content that expands/collapses</CollapsibleContent>
+</Collapsible>
+```
+
+**Componentes**: 3 (Collapsible root, CollapsibleTrigger, CollapsibleContent)
+
+## Props Principales
+
+### Collapsible (Root)
+
+| Prop           | Tipo                      | Default | Descripción                         |
+| -------------- | ------------------------- | ------- | ----------------------------------- |
+| `open`         | `boolean`                 | -       | Estado controlado (abierto/cerrado) |
+| `defaultOpen`  | `boolean`                 | `false` | Estado inicial no controlado        |
+| `onOpenChange` | `(open: boolean) => void` | -       | Callback al cambiar estado          |
+| `disabled`     | `boolean`                 | `false` | Desactiva interacción               |
+| `className`    | `string`                  | -       | Clases CSS adicionales              |
+
+### CollapsibleTrigger
+
+| Prop        | Tipo      | Default | Descripción                         |
+| ----------- | --------- | ------- | ----------------------------------- |
+| `asChild`   | `boolean` | `false` | Usa child como trigger (Radix Slot) |
+| `className` | `string`  | -       | Clases CSS adicionales              |
+
+### CollapsibleContent
+
+| Prop         | Tipo      | Default | Descripción                               |
+| ------------ | --------- | ------- | ----------------------------------------- |
+| `forceMount` | `boolean` | `false` | Fuerza montaje en DOM aunque esté cerrado |
+| `className`  | `string`  | -       | Clases CSS adicionales                    |
+
+## Patrones de Uso
+
+### Básico (No Controlado)
+
+```tsx
+<Collapsible>
+  <CollapsibleTrigger>Show details</CollapsibleTrigger>
+  <CollapsibleContent>
+    <p>Additional information here.</p>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Controlado con Estado
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<Collapsible open={isOpen} onOpenChange={setIsOpen}>
+  <CollapsibleTrigger>{isOpen ? "Hide" : "Show"} content</CollapsibleTrigger>
+  <CollapsibleContent>
+    <p>Controlled content</p>
+  </CollapsibleContent>
+</Collapsible>;
+```
+
+### Con Botón Custom (asChild)
+
+```tsx
+import { Button } from "@adamosuiteservices/ui/button";
+import { ChevronsUpDownIcon } from "lucide-react";
+
+<Collapsible>
+  <CollapsibleTrigger asChild>
+    <Button variant="outline" size="sm">
+      <ChevronsUpDownIcon />
+      Toggle
+    </Button>
+  </CollapsibleTrigger>
+  <CollapsibleContent>
+    <p>Content</p>
+  </CollapsibleContent>
+</Collapsible>;
+```
+
+### Con Chevron Rotatorio
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<Collapsible open={isOpen} onOpenChange={setIsOpen}>
+  <CollapsibleTrigger className="flex w-full items-center justify-between p-4 border rounded-lg hover:bg-muted">
+    <span>Section Title</span>
+    <ChevronDownIcon
+      className={`h-4 w-4 transition-transform ${isOpen ? "rotate-180" : ""}`}
+    />
+  </CollapsibleTrigger>
+  <CollapsibleContent className="p-4">
+    <p>Expandable content</p>
+  </CollapsibleContent>
+</Collapsible>;
+```
+
+### FAQ Pattern
+
+```tsx
+<div className="space-y-4">
+  <Collapsible>
+    <CollapsibleTrigger className="flex w-full items-center justify-between border p-4 rounded-lg hover:bg-muted">
+      <span className="font-medium">What is this?</span>
+      <ChevronRightIcon className="h-4 w-4" />
+    </CollapsibleTrigger>
+    <CollapsibleContent className="px-4 pb-4">
+      <p className="text-sm text-muted-foreground">
+        This is a reusable UI component library.
+      </p>
+    </CollapsibleContent>
+  </Collapsible>
+
+  <Collapsible>
+    <CollapsibleTrigger className="flex w-full items-center justify-between border p-4 rounded-lg hover:bg-muted">
+      <span className="font-medium">How to install?</span>
+      <ChevronRightIcon className="h-4 w-4" />
+    </CollapsibleTrigger>
+    <CollapsibleContent className="px-4 pb-4">
+      <p className="text-sm text-muted-foreground">
+        Use: <code>npm install @adamosuiteservices/ui</code>
+      </p>
+    </CollapsibleContent>
+  </Collapsible>
+</div>
+```
+
+### Navigation Menu
+
+```tsx
+const [openSections, setOpenSections] = useState<string[]>(["settings"]);
+
+const toggleSection = (id: string) => {
+  setOpenSections((prev) =>
+    prev.includes(id) ? prev.filter((s) => s !== id) : [...prev, id]
+  );
+};
+
+<div className="space-y-2">
+  <Collapsible
+    open={openSections.includes("settings")}
+    onOpenChange={() => toggleSection("settings")}
+  >
+    <CollapsibleTrigger className="flex w-full items-center gap-2 p-3 rounded-lg hover:bg-muted">
+      <SettingsIcon className="h-4 w-4" />
+      <span className="flex-1 font-medium">Settings</span>
+      <ChevronDownIcon
+        className={`h-4 w-4 transition-transform ${
+          openSections.includes("settings") ? "rotate-180" : ""
+        }`}
+      />
+    </CollapsibleTrigger>
+    <CollapsibleContent className="ml-6 space-y-1">
+      <a href="#" className="block px-3 py-2 text-sm rounded hover:bg-muted">
+        Profile
+      </a>
+      <a href="#" className="block px-3 py-2 text-sm rounded hover:bg-muted">
+        Security
+      </a>
+    </CollapsibleContent>
+  </Collapsible>
+
+  <Collapsible
+    open={openSections.includes("account")}
+    onOpenChange={() => toggleSection("account")}
+  >
+    <CollapsibleTrigger className="flex w-full items-center gap-2 p-3 rounded-lg hover:bg-muted">
+      <UserIcon className="h-4 w-4" />
+      <span className="flex-1 font-medium">Account</span>
+      <ChevronDownIcon
+        className={`h-4 w-4 transition-transform ${
+          openSections.includes("account") ? "rotate-180" : ""
+        }`}
+      />
+    </CollapsibleTrigger>
+    <CollapsibleContent className="ml-6 space-y-1">
+      <a href="#" className="block px-3 py-2 text-sm rounded hover:bg-muted">
+        Billing
+      </a>
+      <a href="#" className="block px-3 py-2 text-sm rounded hover:bg-muted">
+        API Keys
+      </a>
+    </CollapsibleContent>
+  </Collapsible>
+</div>;
+```
+
+### Lista de Archivos
+
+```tsx
+<Collapsible defaultOpen className="w-full space-y-2">
+  <CollapsibleTrigger className="w-full border p-3 rounded-lg text-left font-medium hover:bg-muted">
+    Recent Files
+  </CollapsibleTrigger>
+  <CollapsibleContent className="space-y-1">
+    <div className="border p-3 rounded text-sm">document.pdf</div>
+    <div className="border p-3 rounded text-sm">presentation.pptx</div>
+    <div className="border p-3 rounded text-sm">spreadsheet.xlsx</div>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Sección Deshabilitada
+
+```tsx
+<Collapsible disabled>
+  <CollapsibleTrigger className="w-full border p-3 rounded-lg text-left font-medium opacity-50 cursor-not-allowed">
+    Coming Soon
+  </CollapsibleTrigger>
+  <CollapsibleContent>
+    <p className="p-3 text-sm text-muted-foreground">Not available yet.</p>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Con Layout de Tarjeta
+
+```tsx
+<Collapsible className="border rounded-lg p-4">
+  <div className="flex items-center justify-between mb-2">
+    <h4 className="font-semibold">@user starred 3 repos</h4>
+    <CollapsibleTrigger asChild>
+      <Button variant="outline" size="sm">
+        <ChevronsUpDownIcon />
+      </Button>
+    </CollapsibleTrigger>
+  </div>
+
+  <div className="border px-4 py-2 rounded font-mono text-sm">
+    @radix-ui/primitives
+  </div>
+
+  <CollapsibleContent className="mt-2 space-y-2">
+    <div className="border px-4 py-2 rounded font-mono text-sm">
+      @radix-ui/colors
+    </div>
+    <div className="border px-4 py-2 rounded font-mono text-sm">
+      @stitches/react
+    </div>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+## Casos de Uso Comunes
+
+**FAQ sections**: Lista de preguntas frecuentes expandibles  
+**Navigation menus**: Menús colapsables con subsecciones  
+**Details/Summary**: Información adicional opcional  
+**File browsers**: Estructuras de carpetas expandibles  
+**Settings panels**: Grupos de configuraciones organizadas  
+**Table rows**: Filas de tabla con detalles expandibles
+
+## Estilos y Animaciones
+
+### Data States
+
+- **Abierto**: `data-state="open"` en todos los componentes
+- **Cerrado**: `data-state="closed"` en todos los componentes
+- **Disabled**: `data-disabled` cuando `disabled={true}`
+
+### Animación Suave
+
+El contenido usa animaciones CSS automáticas (height, opacity) al expandir/colapsar. No requiere configuración adicional.
+
+### Custom Animations
+
+```tsx
+<CollapsibleContent className="data-[state=open]:animate-slideDown data-[state=closed]:animate-slideUp">
+  Content with custom animations
+</CollapsibleContent>
+```
+
+## Accesibilidad
+
+- ✅ **Navegación teclado**: Enter/Space para toggle en trigger, Tab para navegar
+- ✅ **ARIA**: `aria-expanded`, `aria-controls` automáticos en trigger
+- ✅ **Screen readers**: Anuncia estado expandido/colapsado
+- ✅ **Focus visible**: Trigger recibe focus del teclado
+- ✅ **Disabled state**: `aria-disabled` cuando disabled
+
+## Notas de Implementación
+
+- **Basado en Radix UI**: `@radix-ui/react-collapsible`
+- **No tiene estilos propios**: Wrapper limpio, agrega tus propios estilos
+- **Data slots**: `data-slot="collapsible"`, `data-slot="collapsible-trigger"`, `data-slot="collapsible-content"`
+- **asChild pattern**: CollapsibleTrigger soporta `asChild` para usar componentes custom
+- **Animaciones automáticas**: Radix maneja transiciones de height/opacity
+- **forceMount**: Útil para animaciones custom o cuando necesitas el DOM montado siempre
+- **Multiple instances**: Puedes tener múltiples Collapsibles independientes
+- **Accordion vs Collapsible**: Usa Accordion cuando solo uno debe estar abierto, Collapsible para control independiente
+
+## Troubleshooting
+
+**Animación no suave**: Radix maneja animaciones automáticamente, si no se ve suave verifica que no haya `transition` conflictivos en CSS  
+**Trigger no clickeable**: Verifica que esté dentro de `<Collapsible>`, no como hermano  
+**asChild no funciona**: Asegúrate que el child acepta props `onClick` y `aria-*`  
+**Content siempre visible**: Verifica que no tengas `forceMount` activado sin intención  
+**Estado no sincroniza**: En modo controlado, asegúrate de usar ambos `open` y `onOpenChange`
+
+## Referencias
+
+- **Radix UI Collapsible**: https://www.radix-ui.com/primitives/docs/components/collapsible
+- **ARIA Disclosure**: https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/