@adamosuiteservices/ui 2.13.3 → 2.14.0

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

@@ -1,311 +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**: Icon `circle` con `text-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 Icon component con symbol `circle` y `text-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>
+# 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**: Icon `circle` con `text-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 Icon component con symbol `circle` y `text-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>