@adamosuiteservices/ui 2.11.14 → 2.11.16

package/docs/AI-GUIDE.md

@@ -1,321 +1,321 @@
-# Guía para IA: Cómo usar la documentación de Adamo UI
-
-## Propósito de esta Documentación
-
-Esta documentación está diseñada para ayudar a una IA a entender y utilizar correctamente todos los componentes de la biblioteca Adamo UI. Cada componente tiene su propia documentación detallada con ejemplos de código y explicaciones.
-
-## Estructura de la Documentación
-
-```bash
-docs/
-├── AI-GUIDE.md                  # Esta guía (para IA)
-└── components/
-    ├── ui/                      # Componentes de interfaz
-    │   ├── accordion.md
-    │   ├── button.md
-    │   ├── input.md
-    └── layout/                  # Componentes de layout
-        ├── sidebar.md
-        └── toaster.md
-```
-
-## Convenciones Importantes
-
-### 1. Estilos Incorporados
-
-**IMPORTANTE**: Los componentes vienen con todos los estilos necesarios incorporados. El prefijo `` es INTERNO de la biblioteca y los usuarios NO deben usarlo.
-
-✅ **Correcto** (uso normal):
-
-```tsx
-<Button className="custom-class">Click</Button>
-<div className="flex gap-4">
-  <Button variant="outline">Cancel</Button>
-  <Button>Submit</Button>
-</div>
-```
-
-**Nota Técnica**: Internamente la biblioteca usa el prefijo `` en Tailwind para evitar conflictos con los estilos de las aplicaciones que la consumen, pero esto es transparente para el usuario final.
-
-### 2. Importaciones
-
-Los componentes se importan desde rutas específicas:
-
-```typescript
-// ✅ Correcto
-import { Button } from "@adamosuiteservices/ui/button";
-import { Input } from "@adamosuiteservices/ui/input";
-
-// ❌ Incorrecto
-import { Button, Input } from "@adamosuiteservices/ui";
-```
-
-### 3. Estilos CSS
-
-Importar los estilos en el punto de entrada de la aplicación:
-
-```typescript
-import "@adamosuiteservices/ui/styles.css";
-```
-
-## Patrones Comunes
-
-### Componentes con Variantes
-
-Muchos componentes soportan la prop `variant`:
-
-- `default` - Estilo primario
-- `secondary` - Estilo secundario
-- `success` - Verde para acciones exitosas
-- `warning` - Naranja para advertencias
-- `destructive` - Rojo para acciones peligrosas
-- `outline` - Borde sin relleno
-- `ghost` - Mínimo, aparece en hover
-
-Variantes `-medium` están disponibles para estilos más suaves.
-
-### Componentes Compuestos
-
-Muchos componentes tienen sub-componentes que deben usarse juntos:
-
-```tsx
-// Accordion
-<Accordion>
-  <AccordionItem>
-    <AccordionTrigger>...</AccordionTrigger>
-    <AccordionContent>...</AccordionContent>
-  </AccordionItem>
-</Accordion>
-
-// Dialog
-<Dialog>
-  <DialogTrigger>...</DialogTrigger>
-  <DialogContent>
-    <DialogHeader>
-      <DialogTitle>...</DialogTitle>
-      <DialogDescription>...</DialogDescription>
-    </DialogHeader>
-  </DialogContent>
-</Dialog>
-```
-
-### Componentes Controlados vs No Controlados
-
-La mayoría de los componentes soportan ambos modos:
-
-**No Controlado:**
-
-```tsx
-<Input defaultValue="Hello" />
-<Select defaultValue="option1">...</Select>
-```
-
-**Controlado:**
-
-```tsx
-const [value, setValue] = useState("");
-<Input value={value} onChange={(e) => setValue(e.target.value)} />;
-
-const [selected, setSelected] = useState("");
-<Select value={selected} onValueChange={setSelected}>
-  ...
-</Select>;
-```
-
-## Casos de Uso Frecuentes
-
-### Formularios
-
-```tsx
-<div className="space-y-4">
-  <Field label="Email" error={emailError}>
-    <Input
-      type="email"
-      value={email}
-      onChange={(e) => setEmail(e.target.value)}
-      aria-invalid={!!emailError}
-    />
-  </Field>
-
-  <Field label="Password">
-    <Input type="password" />
-  </Field>
-
-  <Button type="submit">Submit</Button>
-</div>
-```
-
-### Modales/Diálogos
-
-```tsx
-<Dialog>
-  <DialogTrigger asChild>
-    <Button>Open</Button>
-  </DialogTrigger>
-  <DialogContent>
-    <DialogHeader>
-      <DialogTitle>Title</DialogTitle>
-      <DialogDescription>Description</DialogDescription>
-    </DialogHeader>
-    {/* Contenido */}
-    <DialogFooter>
-      <DialogClose asChild>
-        <Button variant="outline">Cancel</Button>
-      </DialogClose>
-      <Button>Confirm</Button>
-    </DialogFooter>
-  </DialogContent>
-</Dialog>
-```
-
-### Navegación
-
-```tsx
-<Tabs defaultValue="tab1">
-  <TabsList>
-    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
-    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
-  </TabsList>
-  <TabsContent value="tab1">Content 1</TabsContent>
-  <TabsContent value="tab2">Content 2</TabsContent>
-</Tabs>
-```
-
-### Feedback al Usuario
-
-```tsx
-// Toasts
-const { toast } = useToast();
-
-toast({
-  title: "Success",
-  description: "Operation completed",
-  variant: "success",
-});
-
-// Alertas
-<Alert variant="destructive">
-  <AlertCircleIcon />
-  <AlertTitle>Error</AlertTitle>
-  <AlertDescription>Something went wrong</AlertDescription>
-</Alert>;
-```
-
-## Accesibilidad
-
-### Labels
-
-Siempre asocia labels con inputs:
-
-```tsx
-<Label htmlFor="email">Email</Label>
-<Input id="email" type="email" />
-```
-
-### ARIA Attributes
-
-Usa atributos ARIA apropiados:
-
-```tsx
-<Input aria-invalid={hasError} aria-describedby="error-message" />;
-{
-  hasError && <p id="error-message">{errorMessage}</p>;
-}
-```
-
-### Botones de Solo Icono
-
-Siempre incluye `aria-label`:
-
-```tsx
-<Button size="icon" aria-label="Settings">
-  <SettingsIcon />
-</Button>
-```
-
-## Responsive Design
-
-Usa los breakpoints estándar de Tailwind con el prefijo ``:
-
-```tsx
-<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
-  {/* Contenido responsive */}
-</div>
-```
-
-## Errores Comunes a Evitar
-
-### 1. Olvidar el prefijo
-
-```tsx
-// ❌ Incorrecto
-<Button className="px-4 py-2">Click</Button>
-
-// ✅ Correcto
-<Button className="px-4 py-2">Click</Button>
-```
-
-### 2. No usar asChild para elementos personalizados
-
-```tsx
-// ❌ Incorrecto
-<Button>
-  <a href="#">Link</a>
-</Button>
-
-// ✅ Correcto
-<Button asChild>
-  <a href="#">Link</a>
-</Button>
-```
-
-### 3. No cerrar componentes compuestos
-
-```tsx
-// ❌ Incorrecto
-<Dialog>
-  <DialogTrigger>Open</DialogTrigger>
-  {/* Falta DialogContent */}
-</Dialog>
-
-// ✅ Correcto
-<Dialog>
-  <DialogTrigger>Open</DialogTrigger>
-  <DialogContent>...</DialogContent>
-</Dialog>
-```
-
-## Recursos Adicionales
-
-### Para cada componente, consulta
-
-1. **Descripción**: Qué hace el componente y cuándo usarlo
-2. **Importación**: Cómo importar correctamente
-3. **Uso Básico**: Ejemplo mínimo funcional
-4. **Props**: Tabla completa de propiedades
-5. **Casos de Uso**: Ejemplos prácticos reales
-6. **Referencias**: Enlaces a shadcn/ui y Radix UI
-
-### Documentación de Referencia Externa
-
-- shadcn/ui: [https://ui.shadcn.com](https://ui.shadcn.com)
-- Radix UI: [https://www.radix-ui.com/primitives](https://www.radix-ui.com/primitives)
-- Tailwind CSS: [https://tailwindcss.com](https://tailwindcss.com)
-
-## Flujo de Trabajo Recomendado
-
-1. **Identificar el componente necesario** → Consultar /docs/components
-2. **Leer la documentación específica** → Archivo .md del componente
-3. **Copiar el ejemplo básico** → Modificar según necesidad
-4. **Verificar props disponibles** → Tabla de props
-5. **Validar accesibilidad** → Labels, ARIA attributes, etc.
-6. **Probar responsive** → Diferentes tamaños de pantalla
-
-## Soporte y Preguntas
-
-Si un componente no tiene documentación o necesitas más información:
-
-1. Revisa los archivos `.stories.tsx` en `src/components/ui/[componente]/`
-2. Consulta el código fuente en `src/components/ui/[componente]/[componente].tsx`
-3. Revisa la documentación de shadcn/ui para el componente equivalente
-4. Consulta Radix UI Primitives para comportamiento bajo nivel
+# Guía para IA: Cómo usar la documentación de Adamo UI
+
+## Propósito de esta Documentación
+
+Esta documentación está diseñada para ayudar a una IA a entender y utilizar correctamente todos los componentes de la biblioteca Adamo UI. Cada componente tiene su propia documentación detallada con ejemplos de código y explicaciones.
+
+## Estructura de la Documentación
+
+```bash
+docs/
+├── AI-GUIDE.md                  # Esta guía (para IA)
+└── components/
+    ├── ui/                      # Componentes de interfaz
+    │   ├── accordion.md
+    │   ├── button.md
+    │   ├── input.md
+    └── layout/                  # Componentes de layout
+        ├── sidebar.md
+        └── toaster.md
+```
+
+## Convenciones Importantes
+
+### 1. Estilos Incorporados
+
+**IMPORTANTE**: Los componentes vienen con todos los estilos necesarios incorporados. El prefijo `` es INTERNO de la biblioteca y los usuarios NO deben usarlo.
+
+✅ **Correcto** (uso normal):
+
+```tsx
+<Button className="custom-class">Click</Button>
+<div className="flex gap-4">
+  <Button variant="outline">Cancel</Button>
+  <Button>Submit</Button>
+</div>
+```
+
+**Nota Técnica**: Internamente la biblioteca usa el prefijo `` en Tailwind para evitar conflictos con los estilos de las aplicaciones que la consumen, pero esto es transparente para el usuario final.
+
+### 2. Importaciones
+
+Los componentes se importan desde rutas específicas:
+
+```typescript
+// ✅ Correcto
+import { Button } from "@adamosuiteservices/ui/button";
+import { Input } from "@adamosuiteservices/ui/input";
+
+// ❌ Incorrecto
+import { Button, Input } from "@adamosuiteservices/ui";
+```
+
+### 3. Estilos CSS
+
+Importar los estilos en el punto de entrada de la aplicación:
+
+```typescript
+import "@adamosuiteservices/ui/styles.css";
+```
+
+## Patrones Comunes
+
+### Componentes con Variantes
+
+Muchos componentes soportan la prop `variant`:
+
+- `default` - Estilo primario
+- `secondary` - Estilo secundario
+- `success` - Verde para acciones exitosas
+- `warning` - Naranja para advertencias
+- `destructive` - Rojo para acciones peligrosas
+- `outline` - Borde sin relleno
+- `ghost` - Mínimo, aparece en hover
+
+Variantes `-medium` están disponibles para estilos más suaves.
+
+### Componentes Compuestos
+
+Muchos componentes tienen sub-componentes que deben usarse juntos:
+
+```tsx
+// Accordion
+<Accordion>
+  <AccordionItem>
+    <AccordionTrigger>...</AccordionTrigger>
+    <AccordionContent>...</AccordionContent>
+  </AccordionItem>
+</Accordion>
+
+// Dialog
+<Dialog>
+  <DialogTrigger>...</DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>...</DialogTitle>
+      <DialogDescription>...</DialogDescription>
+    </DialogHeader>
+  </DialogContent>
+</Dialog>
+```
+
+### Componentes Controlados vs No Controlados
+
+La mayoría de los componentes soportan ambos modos:
+
+**No Controlado:**
+
+```tsx
+<Input defaultValue="Hello" />
+<Select defaultValue="option1">...</Select>
+```
+
+**Controlado:**
+
+```tsx
+const [value, setValue] = useState("");
+<Input value={value} onChange={(e) => setValue(e.target.value)} />;
+
+const [selected, setSelected] = useState("");
+<Select value={selected} onValueChange={setSelected}>
+  ...
+</Select>;
+```
+
+## Casos de Uso Frecuentes
+
+### Formularios
+
+```tsx
+<div className="space-y-4">
+  <Field label="Email" error={emailError}>
+    <Input
+      type="email"
+      value={email}
+      onChange={(e) => setEmail(e.target.value)}
+      aria-invalid={!!emailError}
+    />
+  </Field>
+
+  <Field label="Password">
+    <Input type="password" />
+  </Field>
+
+  <Button type="submit">Submit</Button>
+</div>
+```
+
+### Modales/Diálogos
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+      <DialogDescription>Description</DialogDescription>
+    </DialogHeader>
+    {/* Contenido */}
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="outline">Cancel</Button>
+      </DialogClose>
+      <Button>Confirm</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Navegación
+
+```tsx
+<Tabs defaultValue="tab1">
+  <TabsList>
+    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">Content 1</TabsContent>
+  <TabsContent value="tab2">Content 2</TabsContent>
+</Tabs>
+```
+
+### Feedback al Usuario
+
+```tsx
+// Toasts
+const { toast } = useToast();
+
+toast({
+  title: "Success",
+  description: "Operation completed",
+  variant: "success",
+});
+
+// Alertas
+<Alert variant="destructive">
+  <AlertCircleIcon />
+  <AlertTitle>Error</AlertTitle>
+  <AlertDescription>Something went wrong</AlertDescription>
+</Alert>;
+```
+
+## Accesibilidad
+
+### Labels
+
+Siempre asocia labels con inputs:
+
+```tsx
+<Label htmlFor="email">Email</Label>
+<Input id="email" type="email" />
+```
+
+### ARIA Attributes
+
+Usa atributos ARIA apropiados:
+
+```tsx
+<Input aria-invalid={hasError} aria-describedby="error-message" />;
+{
+  hasError && <p id="error-message">{errorMessage}</p>;
+}
+```
+
+### Botones de Solo Icono
+
+Siempre incluye `aria-label`:
+
+```tsx
+<Button size="icon" aria-label="Settings">
+  <SettingsIcon />
+</Button>
+```
+
+## Responsive Design
+
+Usa los breakpoints estándar de Tailwind con el prefijo ``:
+
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
+  {/* Contenido responsive */}
+</div>
+```
+
+## Errores Comunes a Evitar
+
+### 1. Olvidar el prefijo
+
+```tsx
+// ❌ Incorrecto
+<Button className="px-4 py-2">Click</Button>
+
+// ✅ Correcto
+<Button className="px-4 py-2">Click</Button>
+```
+
+### 2. No usar asChild para elementos personalizados
+
+```tsx
+// ❌ Incorrecto
+<Button>
+  <a href="#">Link</a>
+</Button>
+
+// ✅ Correcto
+<Button asChild>
+  <a href="#">Link</a>
+</Button>
+```
+
+### 3. No cerrar componentes compuestos
+
+```tsx
+// ❌ Incorrecto
+<Dialog>
+  <DialogTrigger>Open</DialogTrigger>
+  {/* Falta DialogContent */}
+</Dialog>
+
+// ✅ Correcto
+<Dialog>
+  <DialogTrigger>Open</DialogTrigger>
+  <DialogContent>...</DialogContent>
+</Dialog>
+```
+
+## Recursos Adicionales
+
+### Para cada componente, consulta
+
+1. **Descripción**: Qué hace el componente y cuándo usarlo
+2. **Importación**: Cómo importar correctamente
+3. **Uso Básico**: Ejemplo mínimo funcional
+4. **Props**: Tabla completa de propiedades
+5. **Casos de Uso**: Ejemplos prácticos reales
+6. **Referencias**: Enlaces a shadcn/ui y Radix UI
+
+### Documentación de Referencia Externa
+
+- shadcn/ui: [https://ui.shadcn.com](https://ui.shadcn.com)
+- Radix UI: [https://www.radix-ui.com/primitives](https://www.radix-ui.com/primitives)
+- Tailwind CSS: [https://tailwindcss.com](https://tailwindcss.com)
+
+## Flujo de Trabajo Recomendado
+
+1. **Identificar el componente necesario** → Consultar /docs/components
+2. **Leer la documentación específica** → Archivo .md del componente
+3. **Copiar el ejemplo básico** → Modificar según necesidad
+4. **Verificar props disponibles** → Tabla de props
+5. **Validar accesibilidad** → Labels, ARIA attributes, etc.
+6. **Probar responsive** → Diferentes tamaños de pantalla
+
+## Soporte y Preguntas
+
+Si un componente no tiene documentación o necesitas más información:
+
+1. Revisa los archivos `.stories.tsx` en `src/components/ui/[componente]/`
+2. Consulta el código fuente en `src/components/ui/[componente]/[componente].tsx`
+3. Revisa la documentación de shadcn/ui para el componente equivalente
+4. Consulta Radix UI Primitives para comportamiento bajo nivel