@adamosuiteservices/ui 1.2.5 → 1.3.5

package/docs/components/ui/breadcrumb.md

@@ -0,0 +1,614 @@
+# Breadcrumb Component
+
+## Descripción
+
+Componente de navegación que muestra la **ubicación actual del usuario dentro de una jerarquía navegacional**. Ayuda a los usuarios a comprender su posición en el sitio y navegar fácilmente a páginas superiores. Incluye soporte para separadores personalizables, iconos, elipsis para rutas largas, y menús desplegables para navegación colapsada.
+
+## Características
+
+- ✅ Estructura semántica con `<nav>` y `<ol>`
+- ✅ Separadores personalizables (chevron por defecto)
+- ✅ Soporte para iconos en cada nivel
+- ✅ Elipsis para indicar elementos colapsados
+- ✅ Integración con Dropdown Menu para rutas largas
+- ✅ Prop `asChild` para componentes de link personalizados (React Router, Next.js)
+- ✅ Responsive y adaptable a móviles
+- ✅ Accesibilidad completa (aria-label, aria-current, role)
+- ✅ Dark mode automático
+- ✅ Estilos con transiciones suaves
+
+## Importación
+
+```typescript
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+} from "@adamosuiteservices/ui/breadcrumb";
+```
+
+## Uso Básico
+
+### Breadcrumb Simple
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### Con Iconos
+
+```tsx
+import { HomeIcon, FolderIcon, FileIcon } from "lucide-react";
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <HomeIcon className="h-4 w-4" />
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <FolderIcon className="h-4 w-4" />
+      <BreadcrumbLink href="/projects">Projects</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <FileIcon className="h-4 w-4" />
+      <BreadcrumbPage>Document.pdf</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>;
+```
+
+**Nota**: Los iconos mejoran el reconocimiento visual de diferentes tipos de páginas.
+
+### Con React Router / Next.js Link
+
+```tsx
+import { Link } from "react-router-dom";
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink asChild>
+        <Link to="/">Home</Link>
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Settings</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>;
+```
+
+**Uso de asChild**: Permite usar componentes de navegación personalizados mientras mantiene los estilos del breadcrumb.
+
+## Componentes
+
+### Breadcrumb
+
+Contenedor principal del breadcrumb. Se renderiza como `<nav>` con `aria-label="breadcrumb"`.
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>{/* items */}</BreadcrumbList>
+</Breadcrumb>
+```
+
+**Props**: Hereda todas las props de `React.ComponentProps<"nav">`.
+
+### BreadcrumbList
+
+Lista ordenada que contiene los elementos del breadcrumb.
+
+```tsx
+<BreadcrumbList>
+  <BreadcrumbItem>{/* ... */}</BreadcrumbItem>
+  <BreadcrumbSeparator />
+  <BreadcrumbItem>{/* ... */}</BreadcrumbItem>
+</BreadcrumbList>
+```
+
+**Estilos**:
+
+- Text: `text-muted-foreground`, `text-sm`
+- Layout: `flex`, `flex-wrap`, `items-center`
+- Spacing: `gap-1.5`, `sm:gap-2.5`
+- Utility: `break-words` para texto largo
+
+**Props**: Hereda todas las props de `React.ComponentProps<"ol">`.
+
+### BreadcrumbItem
+
+Elemento individual del breadcrumb (un nivel de navegación).
+
+```tsx
+<BreadcrumbItem>
+  <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
+</BreadcrumbItem>
+```
+
+**Estilos**:
+
+- Layout: `inline-flex`, `items-center`
+- Spacing: `gap-1.5` entre icono y texto
+
+**Props**: Hereda todas las props de `React.ComponentProps<"li">`.
+
+### BreadcrumbLink
+
+Link navegable dentro del breadcrumb.
+
+```tsx
+<BreadcrumbLink href="/docs">Documentation</BreadcrumbLink>
+
+// Con asChild
+<BreadcrumbLink asChild>
+  <Link to="/docs">Documentation</Link>
+</BreadcrumbLink>
+```
+
+**Estilos**:
+
+- Text: `text-muted-foreground`
+- Hover: `hover:text-foreground`
+- Transition: `transition-colors`
+
+**Props**:
+
+- Hereda todas las props de `React.ComponentProps<"a">`
+- `asChild?: boolean` - Usar Radix UI Slot para renderizar como elemento hijo
+
+### BreadcrumbPage
+
+Página actual (no navegable).
+
+```tsx
+<BreadcrumbPage>Breadcrumb</BreadcrumbPage>
+```
+
+**Estilos**:
+
+- Text: `text-foreground`, `font-normal`
+
+**Atributos de accesibilidad**:
+
+- `role="link"`
+- `aria-disabled="true"`
+- `aria-current="page"`
+
+**Props**: Hereda todas las props de `React.ComponentProps<"span">`.
+
+### BreadcrumbSeparator
+
+Separador visual entre elementos del breadcrumb.
+
+```tsx
+// Separador por defecto (ChevronRight)
+<BreadcrumbSeparator />
+
+// Separador personalizado
+<BreadcrumbSeparator>
+  <SlashIcon />
+</BreadcrumbSeparator>
+```
+
+**Estilos**:
+
+- Icon size: `[&>svg]:size-3.5` (14px)
+
+**Atributos de accesibilidad**:
+
+- `role="presentation"`
+- `aria-hidden="true"`
+
+**Props**: Hereda todas las props de `React.ComponentProps<"li">`.
+
+### BreadcrumbEllipsis
+
+Indicador de elementos colapsados (tres puntos).
+
+```tsx
+<BreadcrumbEllipsis />
+```
+
+**Estilos**:
+
+- Layout: `flex`, `items-center`, `justify-center`
+- Size: `size-9` (36x36px)
+- Icon: `size-4` (16px MoreHorizontal)
+
+**Incluye**:
+
+- Icono `MoreHorizontal` de lucide-react
+- `<span className="sr-only">More</span>` para accesibilidad
+
+**Props**: Hereda todas las props de `React.ComponentProps<"span">`.
+
+## Patrones de Uso
+
+### Ruta Larga con Elipsis
+
+Para rutas de navegación largas, usa `BreadcrumbEllipsis` para indicar elementos ocultos:
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbEllipsis />
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/components">Components</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### Ruta Larga con Dropdown
+
+Para mejor UX en rutas largas, combina con `DropdownMenu`:
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@adamosuiteservices/ui/dropdown-menu";
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <DropdownMenu>
+        <DropdownMenuTrigger className="flex items-center gap-1">
+          <BreadcrumbEllipsis />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="start">
+          <DropdownMenuItem>
+            <a href="/docs">Documentation</a>
+          </DropdownMenuItem>
+          <DropdownMenuItem>
+            <a href="/components">Components</a>
+          </DropdownMenuItem>
+          <DropdownMenuItem>
+            <a href="/themes">Themes</a>
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>;
+```
+
+### Breadcrumb Responsive
+
+Colapsa elementos en móvil para ahorrar espacio:
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem className="hidden md:block">
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator className="hidden md:block" />
+    <BreadcrumbItem>
+      <DropdownMenu>
+        <DropdownMenuTrigger className="flex items-center gap-1 md:hidden">
+          <BreadcrumbEllipsis />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="start">
+          <DropdownMenuItem>
+            <a href="/">Home</a>
+          </DropdownMenuItem>
+          <DropdownMenuItem>
+            <a href="/docs">Documentation</a>
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <BreadcrumbLink href="/docs" className="hidden md:block">
+        Documentation
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### Separadores Personalizados
+
+Usa cualquier icono o elemento como separador:
+
+```tsx
+import { SlashIcon, ChevronRight, ArrowRight } from "lucide-react";
+
+// Slash
+<BreadcrumbSeparator>
+  <SlashIcon />
+</BreadcrumbSeparator>
+
+// Texto
+<BreadcrumbSeparator>
+  /
+</BreadcrumbSeparator>
+
+// Arrow
+<BreadcrumbSeparator>
+  <ArrowRight />
+</BreadcrumbSeparator>
+```
+
+## Casos de Uso
+
+### E-commerce
+
+Navegación de categorías de productos:
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/products">Products</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/products/electronics">Electronics</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Laptops</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### Documentación
+
+Navegación de documentos anidados:
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Docs</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/components">Components</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/components/navigation">Navigation</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### Gestión de Archivos
+
+Sistema de archivos o carpetas:
+
+```tsx
+import { FolderIcon, FileIcon } from "lucide-react";
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/files">
+        <FolderIcon className="h-4 w-4" />
+        My Files
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/files/documents">
+        <FolderIcon className="h-4 w-4" />
+        Documents
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>
+        <FileIcon className="h-4 w-4" />
+        Report.pdf
+      </BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>;
+```
+
+## Accesibilidad
+
+### Estructura Semántica
+
+- `<nav aria-label="breadcrumb">`: Identifica el breadcrumb para screen readers
+- `<ol>`: Lista ordenada que refleja la jerarquía
+- `<li>`: Elementos individuales del breadcrumb
+
+### Página Actual
+
+```tsx
+<BreadcrumbPage>Current Page</BreadcrumbPage>
+```
+
+**Atributos**:
+
+- `role="link"`: Indica que es un elemento de navegación
+- `aria-disabled="true"`: No es interactivo
+- `aria-current="page"`: Marca la página actual
+
+### Separadores
+
+```tsx
+<BreadcrumbSeparator />
+```
+
+**Atributos**:
+
+- `role="presentation"`: Decorativo, no semántico
+- `aria-hidden="true"`: Oculto de screen readers
+
+### Elipsis
+
+```tsx
+<BreadcrumbEllipsis />
+```
+
+**Incluye**:
+
+- `<span className="sr-only">More</span>`: Texto descriptivo para screen readers
+
+## Mejores Prácticas
+
+### ✅ Hacer
+
+- **Usar en navegación jerárquica**: Sitios con estructura de páginas anidadas
+- **Mostrar ruta completa**: Incluir todos los niveles relevantes
+- **Primera letra mayúscula**: Consistencia en nombres de páginas
+- **Responsive**: Colapsar en móvil si hay muchos niveles
+- **Links funcionales**: Todos los links deben navegar correctamente
+- **Página actual no clickeable**: Usar `BreadcrumbPage` para el nivel actual
+
+### ❌ Evitar
+
+- **En sitios planos**: Si no hay jerarquía clara
+- **Redundancia con navegación principal**: No duplicar menús
+- **Demasiados niveles visibles**: Usar dropdown o elipsis para >5 niveles
+- **Solo en desktop**: Debe funcionar en móvil
+- **Página actual como link**: Usar `BreadcrumbPage` sin `href`
+
+## Personalización
+
+### Estilos Personalizados
+
+```tsx
+<Breadcrumb className="my-custom-breadcrumb">
+  <BreadcrumbList className="gap-4">
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/" className="text-lg font-semibold">
+        Home
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator className="text-primary" />
+    <BreadcrumbItem>
+      <BreadcrumbPage className="text-lg">Current</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### Separador Custom
+
+```tsx
+<BreadcrumbSeparator className="text-primary">
+  <span>•</span>
+</BreadcrumbSeparator>
+```
+
+### Dark Mode
+
+Los estilos de dark mode están incluidos automáticamente:
+
+- Links: `text-muted-foreground` → colores ajustados en dark
+- Hover: `hover:text-foreground` → transición suave
+- Página actual: `text-foreground` → contraste adecuado
+
+## Data Slots
+
+Cada componente incluye un atributo `data-slot` para facilitar el targeting con CSS:
+
+```tsx
+data-slot="breadcrumb"          // Breadcrumb
+data-slot="breadcrumb-list"     // BreadcrumbList
+data-slot="breadcrumb-item"     // BreadcrumbItem
+data-slot="breadcrumb-link"     // BreadcrumbLink
+data-slot="breadcrumb-page"     // BreadcrumbPage
+data-slot="breadcrumb-separator" // BreadcrumbSeparator
+data-slot="breadcrumb-ellipsis"  // BreadcrumbEllipsis
+```
+
+**Uso en CSS**:
+
+```css
+[data-slot="breadcrumb-link"]:hover {
+  color: var(--primary);
+}
+
+[data-slot="breadcrumb-separator"] {
+  color: var(--muted-foreground);
+}
+```
+
+## TypeScript
+
+Todos los componentes incluyen tipos completos:
+
+```typescript
+import type { ComponentProps } from "react";
+
+type BreadcrumbProps = ComponentProps<"nav">;
+type BreadcrumbListProps = ComponentProps<"ol">;
+type BreadcrumbItemProps = ComponentProps<"li">;
+type BreadcrumbLinkProps = ComponentProps<"a"> & { asChild?: boolean };
+type BreadcrumbPageProps = ComponentProps<"span">;
+type BreadcrumbSeparatorProps = ComponentProps<"li">;
+type BreadcrumbEllipsisProps = ComponentProps<"span">;
+```
+
+## Dependencias
+
+- **@radix-ui/react-slot**: Para el patrón `asChild`
+- **lucide-react**: Iconos por defecto (ChevronRight, MoreHorizontal)
+- **@src/lib/utils**: Utilidad `cn` para combinar clases
+
+## Recursos
+
+- [ARIA Breadcrumb Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)
+- [MDN: Breadcrumb Navigation](https://developer.mozilla.org/en-US/docs/Web/CSS/Layout_cookbook/Breadcrumb_Navigation)
+- [Nielsen Norman Group: Breadcrumb Navigation](https://www.nngroup.com/articles/breadcrumbs/)