@adamosuiteservices/ui 1.2.4 → 1.3.5

package/docs/components/ui/skeleton.md

@@ -0,0 +1,140 @@
+# Skeleton
+
+Placeholder animado para contenido en carga. Simula la estructura del contenido final con bloques pulsantes.
+
+## Descripción
+
+El componente `Skeleton` muestra placeholders de carga para contenido que está siendo cargado.
+
+## Importación
+
+```typescript
+import { Skeleton } from "@adamosuiteservices/ui/skeleton";
+```
+
+## Anatomía
+
+```tsx
+<Skeleton className="w-full h-12" />
+```
+
+**Componentes**: 1 (Skeleton)
+
+## Props
+
+| Prop        | Tipo     | Descripción                    |
+| ----------- | -------- | ------------------------------ |
+| `className` | `string` | Clases CSS para tamaño y forma |
+
+**Nota**: Acepta todas las props de `<div>`
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+<Skeleton className="h-4 w-[250px]" />
+```
+
+### Avatar + Text
+
+```tsx
+<div className="flex items-center space-x-4">
+  <Skeleton className="h-12 w-12 rounded-full" />
+  <div className="space-y-2">
+    <Skeleton className="h-4 w-[250px]" />
+    <Skeleton className="h-4 w-[200px]" />
+  </div>
+</div>
+```
+
+### Card
+
+```tsx
+<div className="flex flex-col space-y-3">
+  <Skeleton className="h-[125px] w-[250px] rounded-xl" />
+  <div className="space-y-2">
+    <Skeleton className="h-4 w-[250px]" />
+    <Skeleton className="h-4 w-[200px]" />
+  </div>
+</div>
+```
+
+### Text Lines
+
+```tsx
+<div className="space-y-2">
+  <Skeleton className="h-4 w-full" />
+  <Skeleton className="h-4 w-[90%]" />
+  <Skeleton className="h-4 w-[80%]" />
+</div>
+```
+
+### Form
+
+```tsx
+<div className="space-y-4 max-w-md">
+  <div className="space-y-2">
+    <Skeleton className="h-4 w-16" />
+    <Skeleton className="h-10 w-full rounded-md" />
+  </div>
+  <div className="space-y-2">
+    <Skeleton className="h-4 w-20" />
+    <Skeleton className="h-10 w-full rounded-md" />
+  </div>
+  <Skeleton className="h-10 w-24 rounded-md" />
+</div>
+```
+
+### List Items
+
+```tsx
+<div className="space-y-4">
+  {Array.from({ length: 4 }).map((_, i) => (
+    <div key={i} className="flex items-center space-x-4">
+      <Skeleton className="h-10 w-10 rounded-full" />
+      <div className="space-y-2 flex-1">
+        <Skeleton className="h-4 w-[200px]" />
+        <Skeleton className="h-3 w-[150px]" />
+      </div>
+      <Skeleton className="h-8 w-16 rounded-md" />
+    </div>
+  ))}
+</div>
+```
+
+## Casos de Uso
+
+**Loading states**: Placeholder mientras carga contenido  
+**Lazy loading**: Imágenes/contenido que carga progresivamente  
+**Optimistic UI**: Simular contenido antes de respuesta  
+**Infinite scroll**: Items mientras cargan más
+
+## Estilos Base
+
+- **Background**: `bg-accent`
+- **Animation**: `animate-pulse`
+- **Border radius**: `rounded-md` default
+
+## Accesibilidad
+
+- ✅ **ARIA**: Usa `aria-busy="true"` en contenedor padre
+- ✅ **Screen readers**: Anuncia estado de carga en contenedor
+- ⚠️ **Replace**: Reemplaza skeleton con contenido real al cargar
+
+## Notas de Implementación
+
+- **HTML nativo**: Simple `<div>` con estilos
+- **Pulse animation**: Tailwind `animate-pulse`
+- **Customizable**: Totalmente personalizable con className
+- **No state**: Stateless, solo visual
+
+## Troubleshooting
+
+**No pulsa**: Verifica que `animate-pulse` esté aplicado  
+**Tamaño inconsistente**: Usa height/width específicos con className  
+**Forma incorrecta**: Ajusta `rounded-*` para avatars, cards, etc.
+
+## Referencias
+
+- **shadcn/ui Skeleton**: <https://ui.shadcn.com/docs/components/skeleton>

package/docs/components/ui/slider.md

@@ -0,0 +1,341 @@
+# Slider
+
+Control de rango con thumbs deslizables. Soporta valores simples y rangos. Basado en Radix UI.
+
+## Descripción
+
+El componente `Slider` permite seleccionar un valor arrastrando un control deslizante.
+
+## Importación
+
+```typescript
+import { Slider } from "@adamosuiteservices/ui/slider";
+```
+
+## Anatomía
+
+```tsx
+<Slider defaultValue={[50]} max={100} step={1} />
+```
+
+**Componentes**: 1 (Slider) con 3 partes internas (Root, Track, Range, Thumb)
+
+## Props
+
+| Prop            | Tipo                         | Descripción                         |
+| --------------- | ---------------------------- | ----------------------------------- |
+| `defaultValue`  | `number[]`                   | Valor inicial (uncontrolled)        |
+| `value`         | `number[]`                   | Valor controlado (array de números) |
+| `onValueChange` | `(value: number[]) => void`  | Callback al cambiar valor           |
+| `min`           | `number`                     | Valor mínimo (default: 0)           |
+| `max`           | `number`                     | Valor máximo (default: 100)         |
+| `step`          | `number`                     | Incremento (default: 1)             |
+| `disabled`      | `boolean`                    | Deshabilita el slider               |
+| `orientation`   | `"horizontal" \| "vertical"` | Orientación (default: horizontal)   |
+| `theme`         | `Theme`                      | Tema personalizado                  |
+| `className`     | `string`                     | Clases CSS adicionales              |
+
+**Nota**: `value` y `defaultValue` siempre son arrays. Single value = `[50]`, range = `[20, 80]`
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+import { Slider } from "@adamosuiteservices/ui/slider";
+
+<Slider defaultValue={[33]} max={100} step={1} className="w-[60%]" />;
+```
+
+### Con Label
+
+```tsx
+import { Label } from "@adamosuiteservices/ui/label";
+import { useState } from "react";
+
+function App() {
+  const [value, setValue] = useState([50]);
+
+  return (
+    <div className="grid w-full max-w-sm items-center gap-2">
+      <Label htmlFor="volume">Volume: {value[0]}%</Label>
+      <Slider
+        id="volume"
+        max={100}
+        step={1}
+        value={value}
+        onValueChange={setValue}
+        className="w-full"
+      />
+    </div>
+  );
+}
+```
+
+### Range (Dos Valores)
+
+```tsx
+function App() {
+  const [value, setValue] = useState([20, 80]);
+
+  return (
+    <div className="grid w-full max-w-sm items-center gap-2">
+      <Label>
+        Price Range: ${value[0]} - ${value[1]}
+      </Label>
+      <Slider
+        max={100}
+        step={1}
+        value={value}
+        onValueChange={setValue}
+        className="w-full"
+      />
+    </div>
+  );
+}
+```
+
+### Con Steps
+
+```tsx
+function App() {
+  const [value, setValue] = useState([25]);
+  const stepSize = 25;
+
+  return (
+    <div className="grid w-full max-w-sm items-center gap-2">
+      <Label>Progress: {value[0]}%</Label>
+      <Slider
+        max={100}
+        step={stepSize}
+        value={value}
+        onValueChange={setValue}
+        className="w-full"
+      />
+      <div className="flex justify-between text-xs text-muted-foreground">
+        <span>0%</span>
+        <span>25%</span>
+        <span>50%</span>
+        <span>75%</span>
+        <span>100%</span>
+      </div>
+    </div>
+  );
+}
+```
+
+### Vertical
+
+```tsx
+function App() {
+  const [value, setValue] = useState([60]);
+
+  return (
+    <div className="flex h-64 items-center space-x-6">
+      <div className="flex flex-col items-center space-y-2">
+        <Label>Volume</Label>
+        <Slider
+          orientation="vertical"
+          max={100}
+          step={1}
+          value={value}
+          onValueChange={setValue}
+          className="h-48"
+        />
+        <span className="text-sm text-muted-foreground">{value[0]}%</span>
+      </div>
+    </div>
+  );
+}
+```
+
+### Con Botones
+
+```tsx
+import { Button } from "@adamosuiteservices/ui/button";
+
+function App() {
+  const [value, setValue] = useState([50]);
+
+  const decrease = () => setValue([Math.max(0, value[0] - 10)]);
+  const increase = () => setValue([Math.min(100, value[0] + 10)]);
+
+  return (
+    <div className="grid w-full max-w-sm items-center gap-4">
+      <Label>Volume: {value[0]}%</Label>
+      <div className="flex items-center space-x-2">
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={decrease}
+          disabled={value[0] === 0}
+        >
+          -
+        </Button>
+        <Slider
+          value={value}
+          onValueChange={setValue}
+          max={100}
+          step={1}
+          className="flex-1"
+        />
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={increase}
+          disabled={value[0] === 100}
+        >
+          +
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Price Filter
+
+```tsx
+import {
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from "@adamosuiteservices/ui/card";
+import { Button } from "@adamosuiteservices/ui/button";
+
+function PriceFilter() {
+  const [priceRange, setPriceRange] = useState([25, 75]);
+
+  return (
+    <Card className="w-full max-w-sm">
+      <CardHeader>
+        <CardTitle>Filter by Price</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="space-y-2">
+          <Label>Price Range</Label>
+          <Slider
+            value={priceRange}
+            onValueChange={setPriceRange}
+            max={100}
+            step={1}
+            className="w-full"
+          />
+        </div>
+        <div className="flex justify-between text-sm">
+          <span>${priceRange[0]}</span>
+          <span>${priceRange[1]}</span>
+        </div>
+        <Button className="w-full">Apply Filter</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+### RGB Color Picker
+
+```tsx
+function ColorPicker() {
+  const [red, setRed] = useState([128]);
+  const [green, setGreen] = useState([200]);
+  const [blue, setBlue] = useState([75]);
+
+  const rgbColor = `rgb(${red[0]}, ${green[0]}, ${blue[0]})`;
+
+  return (
+    <Card className="w-full max-w-sm">
+      <CardHeader>
+        <CardTitle>RGB Color Picker</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-6">
+        <div
+          className="w-full h-20 rounded-lg border"
+          style={{ backgroundColor: rgbColor }}
+        />
+
+        <div className="space-y-4">
+          <div className="space-y-2">
+            <div className="flex justify-between">
+              <Label>Red</Label>
+              <span className="text-sm text-muted-foreground">{red[0]}</span>
+            </div>
+            <Slider value={red} onValueChange={setRed} max={255} step={1} />
+          </div>
+
+          <div className="space-y-2">
+            <div className="flex justify-between">
+              <Label>Green</Label>
+              <span className="text-sm text-muted-foreground">{green[0]}</span>
+            </div>
+            <Slider value={green} onValueChange={setGreen} max={255} step={1} />
+          </div>
+
+          <div className="space-y-2">
+            <div className="flex justify-between">
+              <Label>Blue</Label>
+              <span className="text-sm text-muted-foreground">{blue[0]}</span>
+            </div>
+            <Slider value={blue} onValueChange={setBlue} max={255} step={1} />
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+### Deshabilitado
+
+```tsx
+<Slider defaultValue={[50]} max={100} step={1} disabled className="w-full" />
+```
+
+## Casos de Uso
+
+**Volume control**: Audio, música, efectos de sonido  
+**Price filters**: Rango de precios en e-commerce  
+**Color pickers**: RGB, HSL sliders  
+**Brightness/Contrast**: Ajustes de imagen  
+**Temperature**: Termostatos, controles de clima  
+**Range selection**: Filtros de fecha, edad, tamaño
+
+## Estilos Base
+
+- **Track height**: `h-1.5` (horizontal), `w-1.5` (vertical)
+- **Track bg**: `bg-muted`
+- **Range bg**: `bg-primary`
+- **Thumb**: `size-4` con `border-primary`, `bg-white`, `shadow-sm`
+- **Thumb hover/focus**: `ring-4` con `ring-ring/50`
+- **Vertical**: `min-h-44` default, `flex-col`
+
+## Accesibilidad
+
+- ✅ **Role**: `role="slider"` con `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
+- ✅ **Keyboard**: Arrow keys para ajustar valor, Home/End para min/max
+- ✅ **Focus**: Focus ring visible en thumbs
+- ✅ **Label**: Asociar con `id` para screen readers
+
+## Notas de Implementación
+
+- **Radix UI**: Basado en `@radix-ui/react-slider`
+- **Multiple thumbs**: Array length determina número de thumbs
+- **Value format**: Siempre array, ej: `[50]` para single, `[20, 80]` para range
+- **Auto-thumbs**: Genera thumbs automáticamente basado en `value.length`
+- **Data attributes**: `data-orientation` para estilos horizontal/vertical
+- **Theme support**: Prop `theme` para personalización
+
+## Troubleshooting
+
+**Thumb no se mueve**: Verifica `max`, `min` y `step` son números válidos  
+**Value no actualiza**: En modo controlado usa `value` + `onValueChange`, no `defaultValue`  
+**Range invertido**: Asegura `value[0] < value[1]` en ranges  
+**Vertical no funciona**: Agrega `className="h-[Xpx]"` para altura explícita  
+**Step no funciona**: `step` debe ser divisor válido del rango (max - min)  
+**Multiple thumbs**: `value={[10, 50, 90]}` crea 3 thumbs
+
+## Referencias
+
+- **Radix UI Slider**: <https://www.radix-ui.com/primitives/docs/components/slider>
+- **shadcn/ui Slider**: <https://ui.shadcn.com/docs/components/slider>

package/docs/components/ui/spinner.md

@@ -0,0 +1,170 @@
+# Spinner
+
+Indicador de carga animado basado en Loader2 icon de Lucide. Icono giratorio para estados de loading.
+
+## Descripción
+
+El componente `Spinner` muestra un indicador de carga animado.
+
+## Importación
+
+```typescript
+import { Spinner } from "@adamosuiteservices/ui/spinner";
+```
+
+## Anatomía
+
+```tsx
+<Spinner />
+```
+
+**Componentes**: 1 (Spinner)
+
+## Props
+
+| Prop        | Tipo     | Descripción                    |
+| ----------- | -------- | ------------------------------ |
+| `className` | `string` | Clases CSS para tamaño y color |
+
+**Nota**: Acepta todas las props de `<svg>`
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+<Spinner />
+```
+
+### Tamaños
+
+```tsx
+<Spinner className="size-3" />
+<Spinner className="size-4" />  {/* Default */}
+<Spinner className="size-6" />
+<Spinner className="size-8" />
+```
+
+### Colores
+
+```tsx
+<Spinner className="text-primary" />
+<Spinner className="text-destructive" />
+<Spinner className="text-blue-500" />
+```
+
+### En Botones
+
+```tsx
+import { Button } from "@adamosuiteservices/ui/button";
+
+<Button disabled>
+  <Spinner />
+  Loading...
+</Button>
+
+<Button variant="outline" disabled>
+  <Spinner />
+  Please wait
+</Button>
+```
+
+### Con Estado
+
+```tsx
+import { useState } from "react";
+import { Button } from "@adamosuiteservices/ui/button";
+
+function App() {
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleClick = () => {
+    setIsLoading(true);
+    setTimeout(() => setIsLoading(false), 2000);
+  };
+
+  return (
+    <Button onClick={handleClick} disabled={isLoading}>
+      {isLoading ? (
+        <>
+          <Spinner />
+          Submitting...
+        </>
+      ) : (
+        "Submit Form"
+      )}
+    </Button>
+  );
+}
+```
+
+### En Badges
+
+```tsx
+import { Badge } from "@adamosuiteservices/ui/badge";
+
+<Badge>
+  <Spinner />
+  Syncing
+</Badge>;
+```
+
+### En Cards
+
+```tsx
+import { Card, CardContent } from "@adamosuiteservices/ui/card";
+
+<Card>
+  <CardContent className="flex items-center space-x-3 p-6">
+    <Spinner className="size-5" />
+    <span>Processing your payment...</span>
+  </CardContent>
+</Card>;
+```
+
+### Inline
+
+```tsx
+<p>
+  Loading data <Spinner className="inline size-4" />
+</p>
+```
+
+## Casos de Uso
+
+**Button loading**: Estados de carga en botones  
+**Badge status**: Indicador de sincronización/procesamiento  
+**Inline loading**: Texto con loading inline  
+**Cards**: Contenido de cards en proceso  
+**Global loading**: Indicadores globales de app
+
+## Estilos Base
+
+- **Size**: `size-4` default
+- **Animation**: `animate-spin`
+- **Role**: `role="status"`
+- **ARIA**: `aria-label="Loading"`
+
+## Accesibilidad
+
+- ✅ **Role**: `role="status"`
+- ✅ **ARIA**: `aria-label="Loading"` para screen readers
+- ✅ **Screen readers**: Anuncia estado de carga
+
+## Notas de Implementación
+
+- **Lucide React**: Usa `Loader2Icon` de lucide-react
+- **Spin animation**: Tailwind `animate-spin`
+- **SVG**: Componente SVG nativo
+- **Customizable**: Tamaño y color via className
+
+## Troubleshooting
+
+**No gira**: Verifica `animate-spin` aplicado  
+**Muy pequeño/grande**: Ajusta `size-*` en className  
+**Color incorrecto**: Usa `text-*` para cambiar color  
+**No se ve en button**: Asegúrate de espaciado con gap
+
+## Referencias
+
+- **Lucide Icons**: <https://lucide.dev/icons/loader-2>