@adamosuiteservices/ui 1.2.5 → 1.3.5

package/docs/AI-GUIDE.md

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

package/docs/components/layout/sidebar.md

@@ -0,0 +1,330 @@
+# Sidebar Component
+
+## Descripción
+
+El componente `Sidebar` es un layout component que proporciona navegación lateral responsive. En desktop muestra un sidebar fijo lateral, mientras que en mobile se convierte automáticamente en un menú Sheet desplegable con icono hamburguesa.
+
+## Importación
+
+```typescript
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarInset,
+  SidebarHeader,
+  SidebarFooter,
+  SidebarMenu,
+  SidebarMenuItem,
+} from "@adamosuiteservices/ui/sidebar";
+```
+
+**Nota**: Si usas `SidebarMenuItem` con `asChild`, también puedes importar componentes de navegación:
+
+```typescript
+import { Link } from "react-router-dom"; // o Next.js Link
+```
+
+## Uso Básico
+
+```tsx
+<Sidebar>
+  <SidebarContent>
+    <SidebarHeader>
+      {/* Logo o título */}
+    </SidebarHeader>
+
+    <SidebarMenu>
+      <SidebarMenuItem>
+        <HomeIcon />
+        Dashboard
+      </SidebarMenuItem>
+      <SidebarMenuItem>
+        <SettingsIcon />
+        Settings
+      </SidebarMenuItem>
+    </SidebarMenu>
+
+    <SidebarFooter>
+      {/* Usuario o acciones */}
+    </SidebarFooter>
+  </SidebarContent>
+</Sidebar>
+
+<SidebarInset>
+  {/* Contenido principal */}
+</SidebarInset>
+```
+
+## Componentes
+
+### Sidebar (Root)
+
+Contenedor principal con context provider.
+
+### SidebarContent
+
+Contenido del sidebar con Portal para posicionamiento fijo.
+
+### SidebarInset
+
+Contenedor para el contenido principal que se ajusta al sidebar.
+
+### SidebarHeader
+
+Sección superior del sidebar.
+
+### SidebarFooter
+
+Sección inferior del sidebar.
+
+### SidebarMenu
+
+Contenedor para items de menú con scroll.
+
+### SidebarMenuItem
+
+Item individual del menú con hover effects.
+
+## Responsive
+
+- **Desktop (xl+)**: Sidebar fijo lateral (256px de ancho)
+- **Mobile**: Sidebar en Sheet (modal lateral)
+- Incluye icono hamburguesa automático en mobile
+
+## Props
+
+### Sidebar
+
+| Prop     | Tipo        | Descripción                                         |
+| -------- | ----------- | --------------------------------------------------- |
+| children | `ReactNode` | Contenido del sidebar (debe incluir SidebarContent) |
+
+### SidebarContent
+
+| Prop      | Tipo                    | Descripción                           |
+| --------- | ----------------------- | ------------------------------------- |
+| className | `string`                | Clases adicionales para el contenedor |
+| children  | `ReactNode`             | Contenido del sidebar                 |
+| ...props  | `ComponentProps<"div">` | Props nativas de div                  |
+
+### SidebarInset
+
+| Prop      | Tipo                    | Descripción                          |
+| --------- | ----------------------- | ------------------------------------ |
+| className | `string`                | Clases adicionales                   |
+| children  | `ReactNode`             | Contenido principal de la aplicación |
+| ...props  | `ComponentProps<"div">` | Props nativas de div                 |
+
+### SidebarHeader
+
+| Prop      | Tipo                       | Descripción                         |
+| --------- | -------------------------- | ----------------------------------- |
+| className | `string`                   | Clases adicionales                  |
+| children  | `ReactNode`                | Contenido del header (logo, título) |
+| ...props  | `ComponentProps<"header">` | Props nativas de header             |
+
+### SidebarFooter
+
+| Prop      | Tipo                       | Descripción                            |
+| --------- | -------------------------- | -------------------------------------- |
+| className | `string`                   | Clases adicionales                     |
+| children  | `ReactNode`                | Contenido del footer (usuario, logout) |
+| ...props  | `ComponentProps<"footer">` | Props nativas de footer                |
+
+### SidebarMenu
+
+| Prop      | Tipo                    | Descripción                      |
+| --------- | ----------------------- | -------------------------------- |
+| className | `string`                | Clases adicionales               |
+| children  | `ReactNode`             | Items del menú (SidebarMenuItem) |
+| ...props  | `ComponentProps<"div">` | Props nativas de div             |
+
+### SidebarMenuItem
+
+| Prop      | Tipo                       | Default | Descripción                                                 |
+| --------- | -------------------------- | ------- | ----------------------------------------------------------- |
+| asChild   | `boolean`                  | `false` | Si es true, renderiza el hijo directo en lugar de un button |
+| className | `string`                   | -       | Clases adicionales                                          |
+| ...props  | `ComponentProps<"button">` | -       | Props nativas de button                                     |
+
+## Características Principales
+
+- **Responsive automático**: Desktop muestra sidebar fijo, mobile usa Sheet con hamburger
+- **Auto-manejo del height**: Previene layout shifts al calcular altura automáticamente
+- **Breakpoint xl (1280px)**: Usa `useMediaQuery` para detectar el cambio
+- **Portal rendering**: Usa Radix Portal para z-index correcto
+- **Sheet integration**: Integración nativa con componente Sheet para mobile
+- **Accesibilidad**: Incluye VisuallyHidden para screen readers
+- **Sticky positioning**: Sidebar fijo en desktop con scroll independiente del contenido
+
+## Ejemplo Completo
+
+```tsx
+<Sidebar>
+  <SidebarContent>
+    <SidebarHeader>
+      <div className="p-4">
+        <h2 className="text-lg font-bold">My App</h2>
+      </div>
+    </SidebarHeader>
+
+    <SidebarMenu>
+      <SidebarMenuItem asChild>
+        <a href="/dashboard">
+          <HomeIcon />
+          Dashboard
+        </a>
+      </SidebarMenuItem>
+      <SidebarMenuItem asChild>
+        <a href="/projects">
+          <FolderIcon />
+          Projects
+        </a>
+      </SidebarMenuItem>
+      <SidebarMenuItem asChild>
+        <a href="/settings">
+          <SettingsIcon />
+          Settings
+        </a>
+      </SidebarMenuItem>
+    </SidebarMenu>
+
+    <SidebarFooter>
+      <div className="p-4">
+        <Button variant="outline" className="w-full">
+          <UserIcon />
+          Profile
+        </Button>
+      </div>
+    </SidebarFooter>
+  </SidebarContent>
+</Sidebar>
+
+<SidebarInset>
+  <main className="p-6">
+    {/* Tu contenido aquí */}
+  </main>
+</SidebarInset>
+```
+
+## Hook Personalizado
+
+### useSidebarContext()
+
+Hook para acceder al contexto del Sidebar desde componentes hijos.
+
+```tsx
+import { useSidebarContext } from "@adamosuiteservices/ui/sidebar";
+
+function CustomSidebarComponent() {
+  const { isXl, sidebarHeight, setSidebarHeight } = useSidebarContext();
+
+  return (
+    <div>
+      {isXl ? "Desktop" : "Mobile"}
+      <span>Height: {sidebarHeight}</span>
+    </div>
+  );
+}
+```
+
+**Retorna**:
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| isXl | `boolean` | True si el viewport es >= 1280px |
+| sidebarHeight | `string` | Altura calculada del sidebar ("auto" en desktop, px en mobile) |
+| setSidebarHeight | `Dispatch<SetStateAction<string>>` | Setter para actualizar la altura |
+
+**Nota**: Este hook debe usarse dentro de un componente que sea hijo de `<Sidebar>`.
+
+## Ejemplos Adicionales
+
+### Con React Router
+
+```tsx
+import { Link } from "react-router-dom";
+
+<SidebarMenu>
+  <SidebarMenuItem asChild>
+    <Link to="/dashboard">
+      <HomeIcon />
+      Dashboard
+    </Link>
+  </SidebarMenuItem>
+  <SidebarMenuItem asChild>
+    <Link to="/settings">
+      <SettingsIcon />
+      Settings
+    </Link>
+  </SidebarMenuItem>
+</SidebarMenu>;
+```
+
+### Con Next.js
+
+```tsx
+import Link from "next/link";
+
+<SidebarMenu>
+  <SidebarMenuItem asChild>
+    <Link href="/dashboard">
+      <HomeIcon />
+      Dashboard
+    </Link>
+  </SidebarMenuItem>
+</SidebarMenu>;
+```
+
+### Sidebar con Estados Activos
+
+```tsx
+const pathname = usePathname(); // Next.js o similar
+
+<SidebarMenu>
+  <SidebarMenuItem
+    asChild
+    className={pathname === "/dashboard" ? "bg-white/20" : ""}
+  >
+    <Link href="/dashboard">
+      <HomeIcon />
+      Dashboard
+    </Link>
+  </SidebarMenuItem>
+</SidebarMenu>;
+```
+
+### Personalización de Colores
+
+El sidebar usa variables CSS de tema. Puedes personalizarlas:
+
+```css
+:root {
+  --sidebar-primary: 220 13% 18%;
+  --sidebar-primary-foreground: 210 20% 98%;
+}
+```
+
+## Notas de Implementación
+
+- El componente usa internamente las clases con prefijo `adm:` para evitar conflictos de estilos
+- `SidebarContent` usa Portal de Radix para renderizar en el top level del DOM
+- El cambio responsive ocurre automáticamente en el breakpoint xl (1280px)
+- En mobile, el Sheet se abre desde la izquierda
+- `SidebarMenuItem` tiene hover effects y padding predefinidos
+- `SidebarMenu` incluye scroll automático si el contenido excede la altura
+- Los componentes usan `data-slot` attributes para debugging y testing
+
+## Accesibilidad
+
+- ✅ El Sheet en mobile incluye SheetTitle y SheetDescription (ocultos visualmente)
+- ✅ Navegación por teclado soportada en todos los items
+- ✅ Focus visible en items del menú
+- ✅ Semántica HTML correcta (nav, header, footer)
+- ✅ ARIA labels automáticos en el Sheet trigger
+
+## Referencias
+
+- Similar a shadcn/ui Sidebar pattern
+- Usa Radix UI Portal para rendering
+- Usa Radix UI Sheet para modal mobile
+- Implementa useMediaQuery de @uidotdev/usehooks