@adamosuiteservices/ui 2.13.4 → 2.14.0

package/docs/components/ui/collapsible.md

@@ -1,323 +1,323 @@
-# 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 { Icon } from "@adamosuiteservices/ui/icon";
-
-<Collapsible>
-  <CollapsibleTrigger asChild>
-    <Button variant="outline" size="sm">
-      <Icon symbol="unfold_more" className="text-base" />
-      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>
-    <Icon
-      symbol="expand_more"
-      className={`text-lg 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>
-      <Icon symbol="chevron_right" className="text-lg" />
-    </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>
-      <Icon symbol="chevron_right" className="text-lg" />
-    </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">
-      <Icon symbol="settings" className="text-lg" />
-      <span className="flex-1 font-medium">Settings</span>
-      <Icon
-        symbol="expand_more"
-        className={`text-lg 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">
-      <Icon symbol="person" className="text-lg" />
-      <span className="flex-1 font-medium">Account</span>
-      <Icon
-        symbol="expand_more"
-        className={`text-lg 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">
-        <Icon symbol="unfold_more" className="text-base" />
-      </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/
+# 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 { Icon } from "@adamosuiteservices/ui/icon";
+
+<Collapsible>
+  <CollapsibleTrigger asChild>
+    <Button variant="outline" size="sm">
+      <Icon symbol="unfold_more" className="text-base" />
+      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>
+    <Icon
+      symbol="expand_more"
+      className={`text-lg 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>
+      <Icon symbol="chevron_right" className="text-lg" />
+    </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>
+      <Icon symbol="chevron_right" className="text-lg" />
+    </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">
+      <Icon symbol="settings" className="text-lg" />
+      <span className="flex-1 font-medium">Settings</span>
+      <Icon
+        symbol="expand_more"
+        className={`text-lg 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">
+      <Icon symbol="person" className="text-lg" />
+      <span className="flex-1 font-medium">Account</span>
+      <Icon
+        symbol="expand_more"
+        className={`text-lg 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">
+        <Icon symbol="unfold_more" className="text-base" />
+      </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/