@adamosuiteservices/ui 1.2.4 → 1.3.5

package/docs/components/ui/select.md

@@ -0,0 +1,352 @@
+# Select
+
+Dropdown de selección con búsqueda y scroll. Basado en Radix UI con 10 subcomponentes.
+
+## Descripción
+
+El componente `Select` muestra una lista de opciones en las que el usuario puede seleccionar una opción de la lista.
+
+## Importación
+
+```typescript
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from "@adamosuiteservices/ui/select";
+```
+
+## Anatomía
+
+```tsx
+<Select>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Select option" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="option1">Option 1</SelectItem>
+    <SelectItem value="option2">Option 2</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+**Componentes**: 10 (Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton)
+
+## Props
+
+### Select (Root)
+
+| Prop            | Tipo                      | Descripción                  |
+| --------------- | ------------------------- | ---------------------------- |
+| `defaultValue`  | `string`                  | Valor inicial (uncontrolled) |
+| `value`         | `string`                  | Valor controlado             |
+| `onValueChange` | `(value: string) => void` | Callback al cambiar valor    |
+| `disabled`      | `boolean`                 | Deshabilita el select        |
+| `required`      | `boolean`                 | Campo requerido              |
+| `name`          | `string`                  | Nombre (formularios)         |
+
+### SelectTrigger
+
+| Prop        | Tipo                | Descripción            |
+| ----------- | ------------------- | ---------------------- |
+| `size`      | `"sm" \| "default"` | Tamaño del trigger     |
+| `className` | `string`            | Clases CSS adicionales |
+
+**Nota**: `size="sm"` = h-8, `size="default"` = h-9
+
+### SelectValue
+
+| Prop          | Tipo     | Descripción                   |
+| ------------- | -------- | ----------------------------- |
+| `placeholder` | `string` | Texto cuando no hay selección |
+
+### SelectContent
+
+| Prop        | Tipo                           | Descripción            |
+| ----------- | ------------------------------ | ---------------------- |
+| `position`  | `"popper" \| "item-aligned"`   | Posición del dropdown  |
+| `align`     | `"start" \| "center" \| "end"` | Alineación horizontal  |
+| `className` | `string`                       | Clases CSS adicionales |
+
+### SelectItem
+
+| Prop        | Tipo      | Descripción            |
+| ----------- | --------- | ---------------------- |
+| `value`     | `string`  | Valor único del item   |
+| `disabled`  | `boolean` | Deshabilita este item  |
+| `className` | `string`  | Clases CSS adicionales |
+
+### SelectLabel
+
+| Prop        | Tipo     | Descripción                        |
+| ----------- | -------- | ---------------------------------- |
+| `className` | `string` | Clases CSS para el label del grupo |
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@adamosuiteservices/ui/select";
+
+<Select>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Select a theme" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="light">Light</SelectItem>
+    <SelectItem value="dark">Dark</SelectItem>
+    <SelectItem value="system">System</SelectItem>
+  </SelectContent>
+</Select>;
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react";
+
+function App() {
+  const [value, setValue] = useState("");
+
+  return (
+    <Select value={value} onValueChange={setValue}>
+      <SelectTrigger className="w-[180px]">
+        <SelectValue placeholder="Select a language" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="javascript">JavaScript</SelectItem>
+        <SelectItem value="typescript">TypeScript</SelectItem>
+        <SelectItem value="python">Python</SelectItem>
+      </SelectContent>
+    </Select>
+  );
+}
+```
+
+### Con Label
+
+```tsx
+import { Label } from "@adamosuiteservices/ui/label";
+
+<div className="grid w-full max-w-sm items-center gap-2">
+  <Label htmlFor="email-provider">Email provider</Label>
+  <Select>
+    <SelectTrigger id="email-provider">
+      <SelectValue placeholder="Select a provider" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="gmail">Gmail</SelectItem>
+      <SelectItem value="outlook">Outlook</SelectItem>
+      <SelectItem value="yahoo">Yahoo</SelectItem>
+    </SelectContent>
+  </Select>
+</div>;
+```
+
+### Con Grupos
+
+```tsx
+import { SelectGroup, SelectLabel } from "@adamosuiteservices/ui/select";
+
+<Select>
+  <SelectTrigger className="w-[200px]">
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>Fruits</SelectLabel>
+      <SelectItem value="apple">Apple</SelectItem>
+      <SelectItem value="banana">Banana</SelectItem>
+      <SelectItem value="blueberry">Blueberry</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>;
+```
+
+### Con Iconos
+
+```tsx
+import { Apple, Banana, Cherry } from "lucide-react";
+
+<Select>
+  <SelectTrigger className="w-[200px]">
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">
+      <Apple className="mr-2 h-4 w-4" />
+      Apple
+    </SelectItem>
+    <SelectItem value="banana">
+      <Banana className="mr-2 h-4 w-4" />
+      Banana
+    </SelectItem>
+    <SelectItem value="cherry">
+      <Cherry className="mr-2 h-4 w-4" />
+      Cherry
+    </SelectItem>
+  </SelectContent>
+</Select>;
+```
+
+### Tamaño Pequeño
+
+```tsx
+<Select>
+  <SelectTrigger size="sm" className="w-[160px]">
+    <SelectValue placeholder="Small select" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="xs">Extra Small</SelectItem>
+    <SelectItem value="sm">Small</SelectItem>
+    <SelectItem value="md">Medium</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Scrollable
+
+```tsx
+<Select>
+  <SelectTrigger className="w-[280px]">
+    <SelectValue placeholder="Select a timezone" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>North America</SelectLabel>
+      <SelectItem value="est">Eastern Standard Time (EST)</SelectItem>
+      <SelectItem value="cst">Central Standard Time (CST)</SelectItem>
+      <SelectItem value="mst">Mountain Standard Time (MST)</SelectItem>
+      <SelectItem value="pst">Pacific Standard Time (PST)</SelectItem>
+    </SelectGroup>
+    <SelectGroup>
+      <SelectLabel>Europe & Africa</SelectLabel>
+      <SelectItem value="gmt">Greenwich Mean Time (GMT)</SelectItem>
+      <SelectItem value="cet">Central European Time (CET)</SelectItem>
+      <SelectItem value="eet">Eastern European Time (EET)</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+### Con Validación
+
+```tsx
+import { Button } from "@adamosuiteservices/ui/button";
+
+function App() {
+  const [value, setValue] = useState("");
+  const [error, setError] = useState("");
+
+  const handleValidate = () => {
+    if (!value) {
+      setError("Please select a priority level");
+    } else {
+      setError("");
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <div className="grid w-full max-w-sm items-center gap-2">
+        <Label htmlFor="priority">
+          Priority level <span className="text-destructive">*</span>
+        </Label>
+        <Select value={value} onValueChange={setValue}>
+          <SelectTrigger
+            id="priority"
+            className={error ? "border-destructive" : ""}
+          >
+            <SelectValue placeholder="Select priority" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="low">Low</SelectItem>
+            <SelectItem value="medium">Medium</SelectItem>
+            <SelectItem value="high">High</SelectItem>
+          </SelectContent>
+        </Select>
+        {error && <p className="text-destructive text-sm">{error}</p>}
+      </div>
+      <Button onClick={handleValidate} variant="outline">
+        Validate Selection
+      </Button>
+    </div>
+  );
+}
+```
+
+### Deshabilitado
+
+```tsx
+<Select disabled>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Select a theme" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="light">Light</SelectItem>
+    <SelectItem value="dark">Dark</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## Casos de Uso### Configuración
+
+```tsx## Casos de Uso
+
+**Selección simple**: Elegir una opción de lista larga
+**Formularios**: País, estado, categoría, idioma
+**Filtros**: Ordenar por, filtrar por tipo
+**Settings**: Theme, tamaño de texto, timezone
+**Navegación**: Cambio rápido entre secciones/vistas
+
+## Estilos Base
+
+- **Trigger height**: `h-9` (default), `h-8` (sm)
+- **Border**: `border-input` con `shadow-xs`
+- **Focus**: `ring-ring/50` con `ring-[3px]`
+- **Content**: `bg-popover` con `shadow-md` y `border`
+- **Item hover**: `bg-accent text-accent-foreground`
+- **Check icon**: `CheckIcon` size-4 en item seleccionado
+
+## Accesibilidad
+
+- ✅ **Role**: `role="combobox"` en trigger, `role="option"` en items
+- ✅ **ARIA**: `aria-expanded`, `aria-controls`, `aria-selected`
+- ✅ **Keyboard**: Arrow keys, Enter, Escape, Type-ahead search
+- ✅ **Focus**: Focus trap en content abierto
+- ✅ **Label**: Asociar con `id` en SelectTrigger
+
+## Notas de Implementación
+
+- **Radix UI**: Basado en `@radix-ui/react-select`
+- **Portal**: SelectContent se renderiza en portal
+- **Iconos**: ChevronDown en trigger, CheckIcon en items seleccionados
+- **Scroll buttons**: Auto-mostrados cuando content es scrollable
+- **Position**: `popper` (default) para absolute positioning
+- **Type-ahead**: Buscar items escribiendo
+
+## Troubleshooting
+
+**Dropdown no abre**: Verifica que SelectContent esté dentro de Select
+**No muestra valor**: Asegura que `value` del item seleccionado coincida con `value` del Select
+**Portal issues**: SelectContent usa Portal, puede afectar z-index
+**Width mismatch**: SelectTrigger necesita `className="w-[Xpx]"` explícito
+**Scroll no funciona**: Scroll automático cuando items exceden max-height
+**Placeholder no desaparece**: SelectValue.placeholder solo visible cuando no hay valor
+
+## Referencias
+
+- **Radix UI Select**: <https://www.radix-ui.com/primitives/docs/components/select>
+- **shadcn/ui Select**: <https://ui.shadcn.com/docs/components/select>
+```

package/docs/components/ui/separator.md

@@ -0,0 +1,214 @@
+# Separator
+
+Separador visual basado en Radix UI. Divide secciones con línea horizontal o vertical, con semántica accesible.
+
+## Descripción
+
+El componente `Separator` muestra una línea divisoria visual entre secciones de contenido.
+
+## Importación
+
+```typescript
+import { Separator } from "@adamosuiteservices/ui/separator";
+```
+
+## Anatomía
+
+```tsx
+<div>
+  <div>Section 1</div>
+  <Separator />
+  <div>Section 2</div>
+</div>
+```
+
+**Componentes**: 1 (Separator)
+
+## Props
+
+| Prop          | Tipo                         | Default        | Descripción                     |
+| ------------- | ---------------------------- | -------------- | ------------------------------- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Orientación del separador       |
+| `decorative`  | `boolean`                    | `true`         | Si es decorativo (no semántico) |
+| `className`   | `string`                     | -              | Clases CSS adicionales          |
+
+## Patrones de Uso
+
+### Horizontal (Default)
+
+```tsx
+<div>
+  <h4 className="text-sm font-medium">Radix Primitives</h4>
+  <p className="text-sm text-muted-foreground">
+    An open-source UI component library.
+  </p>
+</div>
+<Separator className="my-4" />
+<div>
+  <h4 className="text-sm font-medium">Next Section</h4>
+  <p className="text-sm text-muted-foreground">More content here.</p>
+</div>
+```
+
+### Vertical
+
+```tsx
+<div className="flex h-5 items-center space-x-4 text-sm">
+  <div>Blog</div>
+  <Separator orientation="vertical" />
+  <div>Docs</div>
+  <Separator orientation="vertical" />
+  <div>Source</div>
+</div>
+```
+
+### En Navegación
+
+```tsx
+<nav className="flex items-center space-x-4 text-sm">
+  <a href="#" className="font-medium hover:underline">
+    Home
+  </a>
+  <Separator orientation="vertical" className="h-4" />
+  <a href="#" className="font-medium hover:underline">
+    About
+  </a>
+  <Separator orientation="vertical" className="h-4" />
+  <a href="#" className="font-medium hover:underline">
+    Contact
+  </a>
+</nav>
+```
+
+### En Cards
+
+```tsx
+import {
+  Card,
+  CardHeader,
+  CardContent,
+  CardTitle,
+} from "@adamosuiteservices/ui/card";
+
+<Card>
+  <CardHeader>
+    <CardTitle>User Profile</CardTitle>
+  </CardHeader>
+  <CardContent className="space-y-4">
+    <div>
+      <p className="text-sm">John Doe</p>
+      <p className="text-xs text-muted-foreground">john@example.com</p>
+    </div>
+    <Separator />
+    <div className="space-y-2">
+      <div className="flex justify-between text-sm">
+        <span>Status</span>
+        <span className="text-muted-foreground">Active</span>
+      </div>
+      <div className="flex justify-between text-sm">
+        <span>Role</span>
+        <span className="text-muted-foreground">Admin</span>
+      </div>
+    </div>
+  </CardContent>
+</Card>;
+```
+
+### Con Spacing Custom
+
+```tsx
+<Separator className="my-2" />  {/* Tight */}
+<Separator className="my-4" />  {/* Normal */}
+<Separator className="my-8" />  {/* Loose */}
+```
+
+### En Listas
+
+```tsx
+const items = [
+  { id: 1, title: "First Item" },
+  { id: 2, title: "Second Item" },
+  { id: 3, title: "Third Item" },
+];
+
+<div className="space-y-0">
+  {items.map((item, index) => (
+    <div key={item.id}>
+      <div className="py-3">
+        <h4 className="text-sm font-medium">{item.title}</h4>
+      </div>
+      {index < items.length - 1 && <Separator />}
+    </div>
+  ))}
+</div>;
+```
+
+### Con Colores Custom
+
+```tsx
+<Separator className="bg-muted" />           {/* Subtle */}
+<Separator className="bg-primary h-0.5" />  {/* Accent */}
+<Separator className="bg-border" />          {/* Default */}
+```
+
+## Casos de Uso
+
+**Section dividers**: Separar secciones de contenido  
+**Navigation**: Dividir items de navegación  
+**Cards**: Separar contenido en cards  
+**Lists**: Dividir items en listas  
+**Sidebars**: Separar grupos de opciones  
+**Stats**: Dividir métricas verticalmente
+
+## Estilos Base
+
+### Estilos Horizontal
+
+- **Height**: `h-px` (1px)
+- **Width**: `w-full`
+- **Color**: `bg-border`
+
+### Estilos Vertical
+
+- **Width**: `w-px` (1px)
+- **Height**: `h-full`
+- **Color**: `bg-border`
+
+## Accesibilidad
+
+- ✅ **ARIA**: `role="separator"` si `decorative=false`
+- ✅ **Decorative**: Por defecto `decorative=true` (no anunciado por screen readers)
+- ✅ **Semantic**: Usa `decorative=false` para separadores semánticos
+
+## Notas de Implementación
+
+- **Radix UI**: Basado en `@radix-ui/react-separator`
+- **Data attributes**: `data-[orientation=horizontal|vertical]` para estilos
+- **Shrink**: `shrink-0` para evitar colapso en flex
+- **Decorative**: Por defecto no tiene rol semántico (solo visual)
+
+## Decorative vs Semantic
+
+```tsx
+{
+  /* Decorative (default) - solo visual */
+}
+<Separator />;
+
+{
+  /* Semantic - anunciado por screen readers */
+}
+<Separator decorative={false} />;
+```
+
+## Troubleshooting
+
+**No se ve**: Verifica `bg-border` o color custom aplicado  
+**Muy alto/ancho**: Horizontal usa `h-px`, vertical usa `w-px`  
+**No divide verticalmente**: Verifica `orientation="vertical"` y altura del contenedor  
+**Spacing inconsistente**: Usa `my-*` o `mx-*` para spacing uniforme
+
+## Referencias
+
+- **Radix UI Separator**: <https://www.radix-ui.com/primitives/docs/components/separator>
+- **shadcn/ui Separator**: <https://ui.shadcn.com/docs/components/separator>

package/docs/components/ui/sheet.md

@@ -0,0 +1,142 @@
+# Sheet
+
+Panel lateral deslizable (drawer). Basado en Radix UI Dialog con 4 direcciones.
+
+## Descripción
+
+El componente `Sheet` muestra un panel lateral deslizante, similar a un drawer.
+
+## Importación
+
+```typescript
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+  SheetFooter,
+  SheetClose,
+} from "@adamosuiteservices/ui/sheet";
+```
+
+## Anatomía
+
+```tsx
+<Sheet>
+  <SheetTrigger>Open</SheetTrigger>
+  <SheetContent>
+    <SheetHeader>
+      <SheetTitle>Are you sure?</SheetTitle>
+      <SheetDescription>This action cannot be undone.</SheetDescription>
+    </SheetHeader>
+  </SheetContent>
+</Sheet>
+```
+
+**Componentes**: 8 (Sheet, SheetTrigger, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, SheetClose)
+
+## Props
+
+### Sheet (Root)
+
+| Prop           | Tipo                      | Descripción         |
+| -------------- | ------------------------- | ------------------- |
+| `open`         | `boolean`                 | Estado controlado   |
+| `defaultOpen`  | `boolean`                 | Estado inicial      |
+| `onOpenChange` | `(open: boolean) => void` | Callback al cambiar |
+
+### SheetContent
+
+| Prop              | Tipo                                     | Descripción                      |
+| ----------------- | ---------------------------------------- | -------------------------------- |
+| `side`            | `"top" \| "right" \| "bottom" \| "left"` | Dirección (default: "right")     |
+| `showCloseButton` | `boolean`                                | Mostrar X button (default: true) |
+
+## Patrones de Uso
+
+### Desde Derecha (Default)
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>Open Sheet</Button>
+  </SheetTrigger>
+  <SheetContent>
+    <SheetHeader>
+      <SheetTitle>Settings</SheetTitle>
+      <SheetDescription>Configure your preferences</SheetDescription>
+    </SheetHeader>
+  </SheetContent>
+</Sheet>
+```
+
+### Desde Izquierda
+
+```tsx
+<Sheet>
+  <SheetTrigger>Open Left</SheetTrigger>
+  <SheetContent side="left">
+    <SheetHeader>
+      <SheetTitle>Navigation</SheetTitle>
+    </SheetHeader>
+  </SheetContent>
+</Sheet>
+```
+
+### Desde Arriba/Abajo
+
+```tsx
+<Sheet>
+  <SheetTrigger>Open Top</SheetTrigger>
+  <SheetContent side="top">
+    <SheetHeader>
+      <SheetTitle>Top Sheet</SheetTitle>
+    </SheetHeader>
+  </SheetContent>
+</Sheet>
+
+<Sheet>
+  <SheetTrigger>Open Bottom</SheetTrigger>
+  <SheetContent side="bottom">
+    <SheetHeader>
+      <SheetTitle>Bottom Sheet</SheetTitle>
+    </SheetHeader>
+  </SheetContent>
+</Sheet>
+```
+
+### Con Footer
+
+```tsx
+<Sheet>
+  <SheetTrigger>Edit Profile</SheetTrigger>
+  <SheetContent>
+    <SheetHeader>
+      <SheetTitle>Edit profile</SheetTitle>
+      <SheetDescription>Make changes to your profile here.</SheetDescription>
+    </SheetHeader>
+    {/* Form fields */}
+    <SheetFooter>
+      <SheetClose asChild>
+        <Button variant="outline">Cancel</Button>
+      </SheetClose>
+      <Button type="submit">Save changes</Button>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+## Casos de Uso
+
+**Navigation menu**: Menú móvil  
+**Filters**: Panel de filtros  
+**Details**: Vista de detalles  
+**Forms**: Formularios laterales  
+**Settings**: Panel de configuración
+
+## Referencias
+
+- **Radix UI Dialog**: <https://www.radix-ui.com/primitives/docs/components/dialog>
+- **shadcn/ui Sheet**: <https://ui.shadcn.com/docs/components/sheet>