@adamosuiteservices/ui 1.2.4 → 1.3.5

package/docs/components/ui/progress.md

@@ -0,0 +1,182 @@
+# Progress
+
+Indicador de progreso basado en Radix UI. Muestra el avance de una tarea con barra animada y variantes de color.
+
+## Descripción
+
+El componente `Progress` muestra una barra de progreso para indicar el estado de una tarea.
+
+## Importación
+
+```typescript
+import { Progress } from "@adamosuiteservices/ui/progress";
+```
+
+## Anatomía
+
+```tsx
+<Progress value={33} />
+```
+
+**Componentes**: 1 (Progress)
+
+## Props
+
+| Prop        | Tipo                                                   | Default     | Descripción            |
+| ----------- | ------------------------------------------------------ | ----------- | ---------------------- |
+| `value`     | `number`                                               | `0`         | Progreso (0-100)       |
+| `variant`   | `"default" \| "destructive" \| "success" \| "warning"` | `"default"` | Variante de color      |
+| `max`       | `number`                                               | `100`       | Valor máximo           |
+| `className` | `string`                                               | -           | Clases CSS adicionales |
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+<Progress value={33} />
+```
+
+### Con Label
+
+```tsx
+<div className="space-y-2">
+  <div className="flex items-center justify-between">
+    <Label>File Upload</Label>
+    <span className="text-sm text-muted-foreground">45%</span>
+  </div>
+  <Progress value={45} />
+  <p className="text-xs text-muted-foreground">
+    Uploading document.pdf (2.3 MB of 5.1 MB)
+  </p>
+</div>
+```
+
+### Variantes
+
+```tsx
+<Progress value={70} variant="default" />
+<Progress value={100} variant="success" />
+<Progress value={40} variant="warning" />
+<Progress value={90} variant="destructive" />
+```
+
+### Animado
+
+```tsx
+import { useState, useEffect } from "react";
+
+function App() {
+  const [progress, setProgress] = useState(13);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setProgress(66), 500);
+    return () => clearTimeout(timer);
+  }, []);
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center justify-between">
+        <Label>Loading...</Label>
+        <span className="text-sm text-muted-foreground">{progress}%</span>
+      </div>
+      <Progress value={progress} />
+    </div>
+  );
+}
+```
+
+### Tamaños Custom
+
+```tsx
+<Progress value={60} className="h-1" />  {/* Small */}
+<Progress value={60} />                    {/* Default h-2 */}
+<Progress value={60} className="h-4" />  {/* Large */}
+```
+
+### Con Iconos
+
+```tsx
+import { Download } from "lucide-react";
+
+<div className="space-y-2">
+  <div className="flex items-center gap-2">
+    <Download className="h-4 w-4" />
+    <Label>Download</Label>
+    <span className="ml-auto text-sm text-muted-foreground">65%</span>
+  </div>
+  <Progress value={65} />
+</div>;
+```
+
+### Multi-Step
+
+```tsx
+import { useState } from "react";
+
+function App() {
+  const [currentStep, setCurrentStep] = useState(2);
+  const totalSteps = 5;
+  const progress = (currentStep / totalSteps) * 100;
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center justify-between">
+        <Label>Setup Progress</Label>
+        <span className="text-sm text-muted-foreground">
+          Step {currentStep} of {totalSteps}
+        </span>
+      </div>
+      <Progress value={progress} />
+    </div>
+  );
+}
+```
+
+## Casos de Uso
+
+**File uploads**: Progreso de subida de archivos  
+**Downloads**: Descarga de contenido  
+**Multi-step forms**: Wizards con pasos  
+**System resources**: CPU, memoria, disco  
+**Installation**: Instalación de paquetes/apps  
+**Processing**: Tareas de procesamiento
+
+## Estilos Base
+
+- **Height**: `h-2` default
+- **Border radius**: `rounded-full`
+- **Transition**: `transition-all` en indicator
+- **Transform**: `translateX` para animación
+
+### Estilos de Variantes
+
+- **default**: `bg-primary/20` → `bg-primary`
+- **destructive**: `bg-destructive/20` → `bg-destructive`
+- **success**: `bg-success/20` → `bg-success`
+- **warning**: `bg-warning/20` → `bg-warning`
+
+## Accesibilidad
+
+- ✅ **ARIA**: `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
+- ✅ **Screen readers**: Anuncia progreso automáticamente
+- ✅ **Live region**: Actualizaciones en tiempo real
+
+## Notas de Implementación
+
+- **Radix UI**: Basado en `@radix-ui/react-progress`
+- **CVA**: Variantes con class-variance-authority
+- **Animation**: CSS transform para transición suave
+- **Value clamp**: Valor se limita entre 0-100 automáticamente
+
+## Troubleshooting
+
+**No se ve progreso**: Verifica que `value` esté entre 0-100  
+**No anima**: Asegúrate de que value cambie, usa `transition-all`  
+**Variante no cambia color**: Verifica prop `variant` correcta  
+**Muy fino**: Ajusta `className="h-3"` o mayor
+
+## Referencias
+
+- **Radix UI Progress**: <https://www.radix-ui.com/primitives/docs/components/progress>
+- **shadcn/ui Progress**: <https://ui.shadcn.com/docs/components/progress>

package/docs/components/ui/radio-group.md

@@ -0,0 +1,311 @@
+# Radio Group
+
+Grupo de opciones mutuamente excluyentes. Usuario selecciona una opción. Basado en Radix UI.
+
+## Descripción
+
+El componente `RadioGroup` permite seleccionar una opción de un conjunto de opciones mutuamente excluyentes.
+
+## Importación
+
+```typescript
+import { RadioGroup, RadioGroupItem } from "@adamosuiteservices/ui/radio-group";
+```
+
+## Anatomía
+
+```tsx
+<RadioGroup defaultValue="option-one">
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option-one" id="option-one" />
+    <Label htmlFor="option-one">Option One</Label>
+  </div>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option-two" id="option-two" />
+    <Label htmlFor="option-two">Option Two</Label>
+  </div>
+</RadioGroup>
+```
+
+**Componentes**: 2 (RadioGroup, RadioGroupItem)
+
+## Props
+
+### RadioGroup
+
+| Prop            | Tipo                      | Descripción                    |
+| --------------- | ------------------------- | ------------------------------ |
+| `defaultValue`  | `string`                  | Valor inicial (uncontrolled)   |
+| `value`         | `string`                  | Valor controlado               |
+| `onValueChange` | `(value: string) => void` | Callback al cambiar valor      |
+| `disabled`      | `boolean`                 | Deshabilita todo el grupo      |
+| `required`      | `boolean`                 | Campo requerido                |
+| `name`          | `string`                  | Nombre del grupo (formularios) |
+| `className`     | `string`                  | Clases CSS adicionales         |
+
+**Nota**: Acepta todas las props de Radix UI RadioGroup.Root
+
+### RadioGroupItem
+
+| Prop        | Tipo      | Descripción               |
+| ----------- | --------- | ------------------------- |
+| `value`     | `string`  | Valor único del item      |
+| `id`        | `string`  | ID para asociar con Label |
+| `disabled`  | `boolean` | Deshabilita este item     |
+| `className` | `string`  | Clases CSS adicionales    |
+
+**Nota**: Acepta todas las props de Radix UI RadioGroup.Item
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@adamosuiteservices/ui/radio-group";
+import { Label } from "@adamosuiteservices/ui/label";
+
+<RadioGroup defaultValue="option-one">
+  <div className="flex items-center gap-3">
+    <RadioGroupItem value="option-one" id="option-one" />
+    <Label htmlFor="option-one">Option One</Label>
+  </div>
+  <div className="flex items-center gap-3">
+    <RadioGroupItem value="option-two" id="option-two" />
+    <Label htmlFor="option-two">Option Two</Label>
+  </div>
+</RadioGroup>;
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react";
+
+function App() {
+  const [value, setValue] = useState("red");
+
+  return (
+    <RadioGroup value={value} onValueChange={setValue}>
+      <div className="flex items-center gap-3">
+        <RadioGroupItem value="red" id="red" />
+        <Label htmlFor="red">Red</Label>
+      </div>
+      <div className="flex items-center gap-3">
+        <RadioGroupItem value="green" id="green" />
+        <Label htmlFor="green">Green</Label>
+      </div>
+    </RadioGroup>
+  );
+}
+```
+
+### Con Descripciones
+
+```tsx
+<RadioGroup defaultValue="comfortable">
+  <div className="flex items-start gap-3">
+    <RadioGroupItem value="default" id="default" />
+    <div className="grid gap-2">
+      <Label htmlFor="default">Default</Label>
+      <p className="text-muted-foreground text-sm">
+        Recommended for most users. Provides a balanced experience.
+      </p>
+    </div>
+  </div>
+  <div className="flex items-start gap-3">
+    <RadioGroupItem value="comfortable" id="comfortable" />
+    <div className="grid gap-2">
+      <Label htmlFor="comfortable">Comfortable</Label>
+      <p className="text-muted-foreground text-sm">
+        More spacing and larger elements for better accessibility.
+      </p>
+    </div>
+  </div>
+</RadioGroup>
+```
+
+### Layout Horizontal
+
+```tsx
+<RadioGroup defaultValue="medium" className="flex gap-6">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem value="small" id="small" />
+    <Label htmlFor="small">Small</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem value="medium" id="medium" />
+    <Label htmlFor="medium">Medium</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem value="large" id="large" />
+    <Label htmlFor="large">Large</Label>
+  </div>
+</RadioGroup>
+```
+
+### Con Badges
+
+```tsx
+import { Badge } from "@adamosuiteservices/ui/badge";
+
+<RadioGroup defaultValue="pro">
+  <div className="flex items-center gap-3">
+    <RadioGroupItem value="free" id="free" />
+    <div className="flex items-center gap-2">
+      <Label htmlFor="free">Free Plan</Label>
+      <Badge variant="secondary">$0/month</Badge>
+    </div>
+  </div>
+  <div className="flex items-center gap-3">
+    <RadioGroupItem value="pro" id="pro" />
+    <div className="flex items-center gap-2">
+      <Label htmlFor="pro">Pro Plan</Label>
+      <Badge variant="default">$9/month</Badge>
+    </div>
+  </div>
+</RadioGroup>;
+```
+
+### En Formularios
+
+```tsx
+import { Button } from "@adamosuiteservices/ui/button";
+
+function App() {
+  const [formData, setFormData] = useState({
+    notification: "email",
+    frequency: "weekly",
+  });
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    console.log("Form submitted:", formData);
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-6">
+      <div className="space-y-3">
+        <p className="text-sm font-medium">Notification method</p>
+        <RadioGroup
+          value={formData.notification}
+          onValueChange={(value) =>
+            setFormData((prev) => ({ ...prev, notification: value }))
+          }
+        >
+          <div className="flex items-center gap-3">
+            <RadioGroupItem value="email" id="email" />
+            <Label htmlFor="email">Email notifications</Label>
+          </div>
+          <div className="flex items-center gap-3">
+            <RadioGroupItem value="sms" id="sms" />
+            <Label htmlFor="sms">SMS notifications</Label>
+          </div>
+        </RadioGroup>
+      </div>
+      <Button type="submit">Save preferences</Button>
+    </form>
+  );
+}
+```
+
+### Nested (Conditional)
+
+```tsx
+function App() {
+  const [paymentMethod, setPaymentMethod] = useState("card");
+  const [cardType, setCardType] = useState("visa");
+
+  return (
+    <div className="space-y-6">
+      <RadioGroup value={paymentMethod} onValueChange={setPaymentMethod}>
+        <div className="flex items-center gap-3">
+          <RadioGroupItem value="card" id="card" />
+          <Label htmlFor="card">Credit/Debit Card</Label>
+        </div>
+        <div className="flex items-center gap-3">
+          <RadioGroupItem value="bank" id="bank" />
+          <Label htmlFor="bank">Bank Transfer</Label>
+        </div>
+      </RadioGroup>
+
+      {paymentMethod === "card" && (
+        <div className="ml-6 space-y-3">
+          <p className="text-sm font-medium">Card type</p>
+          <RadioGroup value={cardType} onValueChange={setCardType}>
+            <div className="flex items-center gap-3">
+              <RadioGroupItem value="visa" id="visa" />
+              <Label htmlFor="visa">Visa</Label>
+            </div>
+            <div className="flex items-center gap-3">
+              <RadioGroupItem value="mastercard" id="mastercard" />
+              <Label htmlFor="mastercard">Mastercard</Label>
+            </div>
+          </RadioGroup>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Deshabilitado
+
+```tsx
+<RadioGroup defaultValue="option-one" disabled>
+  <div className="flex items-center gap-3">
+    <RadioGroupItem value="option-one" id="disabled-one" />
+    <Label htmlFor="disabled-one">Option One</Label>
+  </div>
+  <div className="flex items-center gap-3">
+    <RadioGroupItem value="option-two" id="disabled-two" />
+    <Label htmlFor="disabled-two">Option Two</Label>
+  </div>
+</RadioGroup>
+```
+
+## Casos de Uso
+
+**Opciones mutuamente excluyentes**: Una sola selección de múltiples opciones  
+**Settings**: Preferencias de configuración (theme, size, mode)  
+**Formularios**: Selección de método de pago, envío, categoría  
+**Surveys**: Preguntas con opciones de respuesta única  
+**Filtros**: Filtrado por categoría, tipo, estado
+
+## Estilos Base
+
+- **Size**: `size-5` (20px)
+- **Border**: `border-input` con `shadow-xs`
+- **Checked**: `CircleIcon` con `fill-primary`
+- **Focus**: `ring-ring/50` con `ring-[3px]`
+- **Invalid**: `border-destructive` con `ring-destructive/20`
+- **Spacing**: `gap-3` default entre item y label
+
+## Accesibilidad
+
+- ✅ **Role**: `role="radio"` y `role="radiogroup"`
+- ✅ **ARIA**: `aria-checked`, `aria-disabled`, `aria-invalid`
+- ✅ **Keyboard**: Arrow keys para navegar, Space para seleccionar
+- ✅ **Label**: Asociar con `htmlFor` e `id`
+- ✅ **Focus**: Focus ring visible en navegación por teclado
+
+## Notas de Implementación
+
+- **Radix UI**: Basado en `@radix-ui/react-radio-group`
+- **Indicador**: Usa `CircleIcon` de lucide-react con `fill-primary`
+- **Grid layout**: Default usa `grid gap-3` para vertical spacing
+- **Data attributes**: `data-slot` para identificar componentes
+- **Controlled**: Usa `value` + `onValueChange`
+- **Uncontrolled**: Usa `defaultValue`
+
+## Troubleshooting
+
+**No se puede seleccionar**: Verifica que cada item tenga `value` único  
+**Label no clickeable**: Asegura `htmlFor` en Label coincida con `id` del RadioGroupItem  
+**Grupo deshabilitado**: `disabled` en RadioGroup deshabilita todos los items  
+**Item individual disabled**: `disabled` en RadioGroupItem específico  
+**Estado no actualiza**: En modo controlado usa `value` + `onValueChange`, no `defaultValue`
+
+## Referencias
+
+- **Radix UI Radio Group**: <https://www.radix-ui.com/primitives/docs/components/radio-group>
+- **shadcn/ui Radio Group**: <https://ui.shadcn.com/docs/components/radio-group>