@adamosuiteservices/ui 2.13.2 → 2.13.4

package/docs/components/layout/sidebar.md

@@ -1,399 +1,399 @@
-# 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,
-  SidebarTopBar,
-  SidebarTrigger,
-  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 className="adm:items-center">
-      {/* Logo o título */}
-    </SidebarHeader>
-
-    <SidebarMenu>
-      <SidebarMenuItem>
-        <Icon symbol="home" /> Dashboard
-      </SidebarMenuItem>
-      <SidebarMenuItem>
-        <Icon symbol="folder" /> Projects
-      </SidebarMenuItem>
-      <SidebarMenuItem>
-        <Icon symbol="settings" /> Settings
-      </SidebarMenuItem>
-    </SidebarMenu>
-
-    <SidebarFooter>
-      <SidebarMenuItem>
-        <Icon symbol="account_circle" /> Profile
-      </SidebarMenuItem>
-    </SidebarFooter>
-  </SidebarContent>
-
-  <SidebarInset>
-    <SidebarTopBar>
-      <h1 className="adm:text-lg adm:font-semibold">Dashboard</h1>
-      <SidebarTrigger />
-    </SidebarTopBar>
-    {/* Contenido principal */}
-  </SidebarInset>
-</Sidebar>
-```
-
-## 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.
-
-### SidebarTopBar
-
-Barra superior sticky para el contenido principal, ideal para incluir el trigger del sidebar y el título de la página.
-
-### SidebarTrigger
-
-Botón hamburguesa que abre/cierra el sidebar en mobile. Automáticamente oculto en desktop (xl+).
-
-### 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                 |
-
-### SidebarTopBar
-
-| Prop      | Tipo                    | Descripción                                       |
-| --------- | ----------------------- | ------------------------------------------------- |
-| className | `string`                | Clases adicionales                                |
-| children  | `ReactNode`             | Contenido de la barra (trigger, título, acciones) |
-| ...props  | `ComponentProps<"div">` | Props nativas de div                              |
-
-**Estilos por defecto**: sticky, top-0, flex, gap-2, items-center, justify-between, bg-background, p-4, border-b
-
-### SidebarTrigger
-
-| Prop      | Tipo                       | Descripción             |
-| --------- | -------------------------- | ----------------------- |
-| className | `string`                   | Clases adicionales      |
-| ...props  | `ComponentProps<"button">` | Props nativas de button |
-
-**Comportamiento**: Oculto automáticamente en desktop (xl:hidden). Incluye icono menu de Material Symbols.
-
-### 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
-import {
-  Sidebar,
-  SidebarContent,
-  SidebarFooter,
-  SidebarHeader,
-  SidebarInset,
-  SidebarMenu,
-  SidebarMenuItem,
-  SidebarTopBar,
-  SidebarTrigger,
-} from "@adamosuiteservices/ui/sidebar";
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-export default function AppLayout() {
-  return (
-    <Sidebar>
-      <SidebarContent>
-        <SidebarHeader className="adm:items-center">
-          <Logo />
-        </SidebarHeader>
-
-        <SidebarMenu>
-          <SidebarMenuItem>
-            <Icon symbol="home" /> Dashboard
-          </SidebarMenuItem>
-          <SidebarMenuItem>
-            <Icon symbol="folder" /> Projects
-          </SidebarMenuItem>
-          <SidebarMenuItem>
-            <Icon symbol="settings" /> Settings
-          </SidebarMenuItem>
-        </SidebarMenu>
-
-        <SidebarFooter>
-          <SidebarMenuItem>
-            <Icon symbol="account_circle" /> Profile
-          </SidebarMenuItem>
-        </SidebarFooter>
-      </SidebarContent>
-
-      <SidebarInset>
-        <SidebarTopBar>
-          <h1 className="adm:text-lg adm:font-semibold">Dashboard</h1>
-          <SidebarTrigger />
-        </SidebarTopBar>
-        <main className="adm:p-6">{/* Tu contenido aquí */}</main>
-      </SidebarInset>
-    </Sidebar>
-  );
-}
-```
-
-## 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, sheetOpen, setSheetOpen } = useSidebarContext();
-
-  return (
-    <div>
-      {isXl ? "Desktop" : "Mobile"}
-      <span>Height: {sidebarHeight}</span>
-      <button onClick={() => setSheetOpen(!sheetOpen)}>Toggle Sidebar</button>
-    </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 |
-| sheetOpen | `boolean` | Estado del Sheet en mobile (abierto/cerrado) |
-| setSheetOpen | `Dispatch<SetStateAction<boolean>>` | Setter para controlar el estado del Sheet |
-
-**Nota**: Este hook debe usarse dentro de un componente que sea hijo de `<Sidebar>`.
-
-## Ejemplos Adicionales
-
-### Items Básicos con Iconos
-
-El ejemplo principal muestra el uso más simple - items como buttons con iconos:
-
-```tsx
-<SidebarMenu>
-  <SidebarMenuItem>
-    <Icon symbol="home" /> Dashboard
-  </SidebarMenuItem>
-  <SidebarMenuItem>
-    <Icon symbol="folder" /> Projects
-  </SidebarMenuItem>
-  <SidebarMenuItem>
-    <Icon symbol="settings" /> Settings
-  </SidebarMenuItem>
-</SidebarMenu>
-```
-
-### Con React Router (usando asChild)
-
-```tsx
-import { Link } from "react-router-dom";
-
-<SidebarMenu>
-  <SidebarMenuItem asChild>
-    <Link to="/dashboard">
-      <Icon symbol="home" /> Dashboard
-    </Link>
-  </SidebarMenuItem>
-  <SidebarMenuItem asChild>
-    <Link to="/settings">
-      <Icon symbol="settings" /> Settings
-    </Link>
-  </SidebarMenuItem>
-</SidebarMenu>;
-```
-
-### Con Next.js (usando asChild)
-
-```tsx
-import Link from "next/link";
-
-<SidebarMenu>
-  <SidebarMenuItem asChild>
-    <Link href="/dashboard">
-      <Icon symbol="home" /> Dashboard
-    </Link>
-  </SidebarMenuItem>
-</SidebarMenu>;
-```
-
-### Estados Activos
-
-```tsx
-const pathname = usePathname(); // Next.js o similar
-
-<SidebarMenu>
-  <SidebarMenuItem
-    className={pathname === "/dashboard" ? "adm:bg-white/20" : ""}
-  >
-    <Icon symbol="home" /> Dashboard
-  </SidebarMenuItem>
-  <SidebarMenuItem
-    className={pathname === "/settings" ? "adm:bg-white/20" : ""}
-  >
-    <Icon symbol="settings" /> Settings
-  </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:
-  - `sidebar` - Contenedor root
-  - `sidebar-content` - Contenido principal del sidebar
-  - `sidebar-trigger` - Botón hamburguesa para mobile
-  - `sidebar-inset` - Contenedor del contenido principal
-  - `sidebar-top-bar` - Barra superior (si se usa)
-  - `sidebar-header` - Header del sidebar
-  - `sidebar-footer` - Footer del sidebar
-  - `sidebar-menu` - Contenedor de items del menú
-  - `sidebar-menu-item` - Item individual del menú
-
-## 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
+# 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,
+  SidebarTopBar,
+  SidebarTrigger,
+  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 className="adm:items-center">
+      {/* Logo o título */}
+    </SidebarHeader>
+
+    <SidebarMenu>
+      <SidebarMenuItem>
+        <Icon symbol="home" /> Dashboard
+      </SidebarMenuItem>
+      <SidebarMenuItem>
+        <Icon symbol="folder" /> Projects
+      </SidebarMenuItem>
+      <SidebarMenuItem>
+        <Icon symbol="settings" /> Settings
+      </SidebarMenuItem>
+    </SidebarMenu>
+
+    <SidebarFooter>
+      <SidebarMenuItem>
+        <Icon symbol="account_circle" /> Profile
+      </SidebarMenuItem>
+    </SidebarFooter>
+  </SidebarContent>
+
+  <SidebarInset>
+    <SidebarTopBar>
+      <h1 className="adm:text-lg adm:font-semibold">Dashboard</h1>
+      <SidebarTrigger />
+    </SidebarTopBar>
+    {/* Contenido principal */}
+  </SidebarInset>
+</Sidebar>
+```
+
+## 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.
+
+### SidebarTopBar
+
+Barra superior sticky para el contenido principal, ideal para incluir el trigger del sidebar y el título de la página.
+
+### SidebarTrigger
+
+Botón hamburguesa que abre/cierra el sidebar en mobile. Automáticamente oculto en desktop (xl+).
+
+### 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                 |
+
+### SidebarTopBar
+
+| Prop      | Tipo                    | Descripción                                       |
+| --------- | ----------------------- | ------------------------------------------------- |
+| className | `string`                | Clases adicionales                                |
+| children  | `ReactNode`             | Contenido de la barra (trigger, título, acciones) |
+| ...props  | `ComponentProps<"div">` | Props nativas de div                              |
+
+**Estilos por defecto**: sticky, top-0, flex, gap-2, items-center, justify-between, bg-background, p-4, border-b
+
+### SidebarTrigger
+
+| Prop      | Tipo                       | Descripción             |
+| --------- | -------------------------- | ----------------------- |
+| className | `string`                   | Clases adicionales      |
+| ...props  | `ComponentProps<"button">` | Props nativas de button |
+
+**Comportamiento**: Oculto automáticamente en desktop (xl:hidden). Incluye icono menu de Material Symbols.
+
+### 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
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarHeader,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarTopBar,
+  SidebarTrigger,
+} from "@adamosuiteservices/ui/sidebar";
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+export default function AppLayout() {
+  return (
+    <Sidebar>
+      <SidebarContent>
+        <SidebarHeader className="adm:items-center">
+          <Logo />
+        </SidebarHeader>
+
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <Icon symbol="home" /> Dashboard
+          </SidebarMenuItem>
+          <SidebarMenuItem>
+            <Icon symbol="folder" /> Projects
+          </SidebarMenuItem>
+          <SidebarMenuItem>
+            <Icon symbol="settings" /> Settings
+          </SidebarMenuItem>
+        </SidebarMenu>
+
+        <SidebarFooter>
+          <SidebarMenuItem>
+            <Icon symbol="account_circle" /> Profile
+          </SidebarMenuItem>
+        </SidebarFooter>
+      </SidebarContent>
+
+      <SidebarInset>
+        <SidebarTopBar>
+          <h1 className="adm:text-lg adm:font-semibold">Dashboard</h1>
+          <SidebarTrigger />
+        </SidebarTopBar>
+        <main className="adm:p-6">{/* Tu contenido aquí */}</main>
+      </SidebarInset>
+    </Sidebar>
+  );
+}
+```
+
+## 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, sheetOpen, setSheetOpen } = useSidebarContext();
+
+  return (
+    <div>
+      {isXl ? "Desktop" : "Mobile"}
+      <span>Height: {sidebarHeight}</span>
+      <button onClick={() => setSheetOpen(!sheetOpen)}>Toggle Sidebar</button>
+    </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 |
+| sheetOpen | `boolean` | Estado del Sheet en mobile (abierto/cerrado) |
+| setSheetOpen | `Dispatch<SetStateAction<boolean>>` | Setter para controlar el estado del Sheet |
+
+**Nota**: Este hook debe usarse dentro de un componente que sea hijo de `<Sidebar>`.
+
+## Ejemplos Adicionales
+
+### Items Básicos con Iconos
+
+El ejemplo principal muestra el uso más simple - items como buttons con iconos:
+
+```tsx
+<SidebarMenu>
+  <SidebarMenuItem>
+    <Icon symbol="home" /> Dashboard
+  </SidebarMenuItem>
+  <SidebarMenuItem>
+    <Icon symbol="folder" /> Projects
+  </SidebarMenuItem>
+  <SidebarMenuItem>
+    <Icon symbol="settings" /> Settings
+  </SidebarMenuItem>
+</SidebarMenu>
+```
+
+### Con React Router (usando asChild)
+
+```tsx
+import { Link } from "react-router-dom";
+
+<SidebarMenu>
+  <SidebarMenuItem asChild>
+    <Link to="/dashboard">
+      <Icon symbol="home" /> Dashboard
+    </Link>
+  </SidebarMenuItem>
+  <SidebarMenuItem asChild>
+    <Link to="/settings">
+      <Icon symbol="settings" /> Settings
+    </Link>
+  </SidebarMenuItem>
+</SidebarMenu>;
+```
+
+### Con Next.js (usando asChild)
+
+```tsx
+import Link from "next/link";
+
+<SidebarMenu>
+  <SidebarMenuItem asChild>
+    <Link href="/dashboard">
+      <Icon symbol="home" /> Dashboard
+    </Link>
+  </SidebarMenuItem>
+</SidebarMenu>;
+```
+
+### Estados Activos
+
+```tsx
+const pathname = usePathname(); // Next.js o similar
+
+<SidebarMenu>
+  <SidebarMenuItem
+    className={pathname === "/dashboard" ? "adm:bg-white/20" : ""}
+  >
+    <Icon symbol="home" /> Dashboard
+  </SidebarMenuItem>
+  <SidebarMenuItem
+    className={pathname === "/settings" ? "adm:bg-white/20" : ""}
+  >
+    <Icon symbol="settings" /> Settings
+  </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:
+  - `sidebar` - Contenedor root
+  - `sidebar-content` - Contenido principal del sidebar
+  - `sidebar-trigger` - Botón hamburguesa para mobile
+  - `sidebar-inset` - Contenedor del contenido principal
+  - `sidebar-top-bar` - Barra superior (si se usa)
+  - `sidebar-header` - Header del sidebar
+  - `sidebar-footer` - Footer del sidebar
+  - `sidebar-menu` - Contenedor de items del menú
+  - `sidebar-menu-item` - Item individual del menú
+
+## 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