@adamosuiteservices/ui 2.13.4 → 2.14.0

package/docs/components/ui/field.md

@@ -1,706 +1,706 @@
-# Field Component
-
-Sistema de composición para formularios que agrupa inputs con labels, descripciones, errores y validación. Soporta layouts verticales, horizontales y responsive con soporte para todos los tipos de inputs.
-
-## Descripción
-
-El componente `Field` agrupa un input con su label, mensaje de ayuda y errores de validación.
-
-## Importación
-
-```typescript
-import {
-  Field,
-  FieldLabel,
-  FieldDescription,
-  FieldError,
-  FieldGroup,
-  FieldSet,
-  FieldLegend,
-  FieldSeparator,
-  FieldContent,
-  FieldTitle,
-} from "@adamosuiteservices/ui/field";
-```
-
-## Uso Básico
-
-```tsx
-<Field label="Email" description="We'll never share your email.">
-  <Input type="email" placeholder="email@example.com" />
-</Field>
-```
-
-## Con Error
-
-```tsx
-<Field label="Username" error="Username is already taken">
-  <Input aria-invalid />
-</Field>
-```
-
-## Con Campo Requerido
-
-```tsx
-<Field label="Password" required>
-  <Input type="password" />
-</Field>
-```
-
-**Componentes**: 10 (Field, FieldLabel, FieldDescription, FieldError, FieldGroup, FieldSet, FieldLegend, FieldSeparator, FieldContent, FieldTitle)
-
-## Props Principales```
-
-### Field## Props
-
-| Prop | Tipo | Default | Descripción || Prop | Tipo | Descripción |
-
-|------|------|---------|-------------||------|------|-------------|
-
-| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | Layout del field || label | `string` | Etiqueta del campo |
-
-| `data-invalid` | `boolean` | - | Marca field como inválido (aplica estilos de error) || description | `string` | Texto de ayuda |
-
-| `data-disabled` | `boolean` | - | Marca field como deshabilitado || error | `string` | Mensaje de error |
-
-| `className` | `string` | - | Clases CSS adicionales || required | `boolean` | Marca el campo como requerido |
-
-**Orientaciones**:
-
-- `vertical`: Label arriba, input abajo
-- `horizontal`: Label e input lado a lado
-- `responsive`: Vertical en mobile, horizontal en desktop (@md/field-group)
-
-### FieldLabel
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `htmlFor`   | `string` | ID del input asociado  |
-| `className` | `string` | Clases CSS adicionales |
-
-**Hereda props de**: `Label` component
-
-### FieldDescription
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Estilos**: `text-sm`, `text-muted-foreground`, soporta links con `hover:text-primary`
-
-### FieldError
-
-| Prop        | Tipo                        | Descripción                      |
-| ----------- | --------------------------- | -------------------------------- |
-| `children`  | `ReactNode`                 | Mensaje de error custom          |
-| `errors`    | `Array<{message?: string}>` | Array de errores (auto-formatea) |
-| `className` | `string`                    | Clases CSS adicionales           |
-
-**Comportamiento**:
-
-- Si hay 1 error: muestra mensaje directo
-- Si hay múltiples: muestra lista con bullets
-- Auto-deduplica errores por mensaje
-
-### FieldSet
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Estilos**: `flex flex-col gap-6`, ajuste automático de gap para checkbox/radio groups
-
-### FieldLegend
-
-| Prop        | Tipo                  | Default    | Descripción            |
-| ----------- | --------------------- | ---------- | ---------------------- |
-| `variant`   | `"legend" \| "label"` | `"legend"` | Estilo del legend      |
-| `className` | `string`              | -          | Clases CSS adicionales |
-
-**Variantes**:
-
-- `legend`: `text-base`, `font-medium`, `mb-3`
-- `label`: `text-sm`, `font-medium`, `mb-3`
-
-### FieldGroup
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Estilos**: `@container/field-group`, `flex flex-col gap-7`, auto-ajuste para nested groups
-
-### FieldSeparator
-
-| Prop        | Tipo        | Descripción                    |
-| ----------- | ----------- | ------------------------------ |
-| `children`  | `ReactNode` | Texto opcional en el separador |
-| `className` | `string`    | Clases CSS adicionales         |
-
-**Con children**: Muestra texto centrado sobre la línea
-
-### FieldContent
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Uso**: Agrupa label + description en layouts horizontales
-
-### FieldTitle
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Uso**: Título alternativo sin asociación a input (para sliders, groups, etc.)
-
-## Patrones de Uso
-
-### Input Field Básico
-
-```tsx
-import { Input } from "@adamosuiteservices/ui/input";
-
-<Field>
-  <FieldLabel htmlFor="username">Username</FieldLabel>
-  <Input id="username" type="text" placeholder="Max Leiter" />
-  <FieldDescription>
-    Choose a unique username for your account.
-  </FieldDescription>
-</Field>;
-```
-
-### Con Error de Validación
-
-```tsx
-<Field data-invalid>
-  <FieldLabel htmlFor="email">Email</FieldLabel>
-  <Input id="email" type="email" aria-invalid />
-  <FieldError>Enter a valid email address.</FieldError>
-</Field>
-```
-
-### Múltiples Errores
-
-```tsx
-<Field data-invalid>
-  <FieldLabel htmlFor="password">Password</FieldLabel>
-  <Input id="password" type="password" aria-invalid />
-  <FieldError
-    errors={[
-      { message: "Password must be at least 8 characters long" },
-      { message: "Password must contain at least one number" },
-      { message: "Password must contain at least one special character" },
-    ]}
-  />
-</Field>
-```
-
-**Renderiza**: Lista con bullets automática
-
-### Textarea Field
-
-```tsx
-import { Textarea } from "@adamosuiteservices/ui/textarea";
-
-<Field>
-  <FieldLabel htmlFor="feedback">Feedback</FieldLabel>
-  <Textarea
-    id="feedback"
-    placeholder="Your feedback helps us improve..."
-    rows={4}
-  />
-  <FieldDescription>Share your thoughts about our service.</FieldDescription>
-</Field>;
-```
-
-### Select Field
-
-```tsx
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from "@adamosuiteservices/ui/select";
-
-<Field>
-  <FieldLabel>Department</FieldLabel>
-  <Select>
-    <SelectTrigger>
-      <SelectValue placeholder="Choose department" />
-    </SelectTrigger>
-    <SelectContent>
-      <SelectItem value="engineering">Engineering</SelectItem>
-      <SelectItem value="design">Design</SelectItem>
-      <SelectItem value="marketing">Marketing</SelectItem>
-    </SelectContent>
-  </Select>
-  <FieldDescription>Select your department or area of work.</FieldDescription>
-</Field>;
-```
-
-### Switch Field (Horizontal)
-
-```tsx
-import { Switch } from "@adamosuiteservices/ui/switch";
-
-<Field orientation="horizontal">
-  <Switch id="newsletter" />
-  <FieldLabel htmlFor="newsletter">Subscribe to the newsletter</FieldLabel>
-</Field>;
-```
-
-### Switch con Descripción (Horizontal)
-
-```tsx
-<Field orientation="horizontal">
-  <FieldContent>
-    <FieldLabel htmlFor="2fa">Multi-factor authentication</FieldLabel>
-    <FieldDescription>
-      Enable multi-factor authentication. If you do not have a two-factor
-      device, you can use a one-time code sent to your email.
-    </FieldDescription>
-  </FieldContent>
-  <Switch id="2fa" />
-</Field>
-```
-
-### Checkbox Group
-
-```tsx
-import { Checkbox } from "@adamosuiteservices/ui/checkbox";
-
-<FieldSet>
-  <FieldLegend variant="label">Show these items on the desktop</FieldLegend>
-  <FieldDescription>
-    Select the items you want to show on the desktop.
-  </FieldDescription>
-  <FieldGroup className="gap-3">
-    <Field orientation="horizontal">
-      <Checkbox id="hard-disks" />
-      <FieldLabel htmlFor="hard-disks" className="font-normal">
-        Hard disks
-      </FieldLabel>
-    </Field>
-    <Field orientation="horizontal">
-      <Checkbox id="external-disks" />
-      <FieldLabel htmlFor="external-disks" className="font-normal">
-        External disks
-      </FieldLabel>
-    </Field>
-    <Field orientation="horizontal">
-      <Checkbox id="cds-dvds" />
-      <FieldLabel htmlFor="cds-dvds" className="font-normal">
-        CDs, DVDs, and iPods
-      </FieldLabel>
-    </Field>
-  </FieldGroup>
-</FieldSet>;
-```
-
-### Radio Group
-
-```tsx
-import { RadioGroup, RadioGroupItem } from "@adamosuiteservices/ui/radio-group";
-
-<FieldSet>
-  <FieldLabel>Subscription Plan</FieldLabel>
-  <FieldDescription>
-    Yearly and lifetime plans offer significant savings.
-  </FieldDescription>
-  <RadioGroup defaultValue="monthly">
-    <Field orientation="horizontal">
-      <RadioGroupItem value="monthly" id="plan-monthly" />
-      <FieldLabel htmlFor="plan-monthly" className="font-normal">
-        Monthly ($9.99/month)
-      </FieldLabel>
-    </Field>
-    <Field orientation="horizontal">
-      <RadioGroupItem value="yearly" id="plan-yearly" />
-      <FieldLabel htmlFor="plan-yearly" className="font-normal">
-        Yearly ($99.99/year)
-      </FieldLabel>
-    </Field>
-    <Field orientation="horizontal">
-      <RadioGroupItem value="lifetime" id="plan-lifetime" />
-      <FieldLabel htmlFor="plan-lifetime" className="font-normal">
-        Lifetime ($299.99)
-      </FieldLabel>
-    </Field>
-  </RadioGroup>
-</FieldSet>;
-```
-
-### Choice Cards (Radio como Cards)
-
-```tsx
-<FieldSet>
-  <FieldLabel htmlFor="compute-environment">Compute Environment</FieldLabel>
-  <FieldDescription>
-    Select the compute environment for your cluster.
-  </FieldDescription>
-  <RadioGroup defaultValue="kubernetes">
-    <FieldLabel htmlFor="kubernetes">
-      <Field orientation="horizontal">
-        <FieldContent>
-          <FieldTitle>Kubernetes</FieldTitle>
-          <FieldDescription>
-            Run GPU workloads on a K8s configured cluster.
-          </FieldDescription>
-        </FieldContent>
-        <RadioGroupItem value="kubernetes" id="kubernetes" />
-      </Field>
-    </FieldLabel>
-    <FieldLabel htmlFor="vm">
-      <Field orientation="horizontal">
-        <FieldContent>
-          <FieldTitle>Virtual Machine</FieldTitle>
-          <FieldDescription>
-            Access a VM configured cluster to run GPU workloads.
-          </FieldDescription>
-        </FieldContent>
-        <RadioGroupItem value="vm" id="vm" />
-      </Field>
-    </FieldLabel>
-  </RadioGroup>
-</FieldSet>
-```
-
-**Estilos automáticos**: FieldLabel envuelve Field → card con border, hover, checked state
-
-### Slider Field
-
-```tsx
-import { Slider } from "@adamosuiteservices/ui/slider";
-import { useState } from "react";
-
-function PriceRange() {
-  const [value, setValue] = useState([200, 800]);
-
-  return (
-    <Field>
-      <FieldTitle>Price Range</FieldTitle>
-      <FieldDescription>
-        Set your budget range ($
-        <span className="font-medium tabular-nums">{value[0]}</span> - <span className="font-medium tabular-nums">
-          {value[1]}
-        </span>).
-      </FieldDescription>
-      <Slider
-        value={value}
-        onValueChange={setValue}
-        max={1000}
-        min={0}
-        step={10}
-        className="mt-2 w-full"
-        aria-label="Price Range"
-      />
-    </Field>
-  );
-}
-```
-
-### FieldSet con Grupos
-
-```tsx
-<FieldSet>
-  <FieldLegend>Address Information</FieldLegend>
-  <FieldDescription>
-    We need your address to deliver your order.
-  </FieldDescription>
-  <FieldGroup>
-    <Field>
-      <FieldLabel htmlFor="street">Street Address</FieldLabel>
-      <Input id="street" type="text" placeholder="123 Main St" />
-    </Field>
-    <div className="grid grid-cols-2 gap-4">
-      <Field>
-        <FieldLabel htmlFor="city">City</FieldLabel>
-        <Input id="city" type="text" placeholder="New York" />
-      </Field>
-      <Field>
-        <FieldLabel htmlFor="zip">Postal Code</FieldLabel>
-        <Input id="zip" type="text" placeholder="90502" />
-      </Field>
-    </div>
-  </FieldGroup>
-</FieldSet>
-```
-
-### Con Separadores
-
-```tsx
-<FieldGroup>
-  <Field>
-    <FieldLabel htmlFor="name">Name</FieldLabel>
-    <Input id="name" />
-  </Field>
-
-  <FieldSeparator />
-
-  <Field>
-    <FieldLabel htmlFor="email">Email</FieldLabel>
-    <Input id="email" type="email" />
-  </Field>
-
-  <FieldSeparator>or</FieldSeparator>
-
-  <Field>
-    <FieldLabel htmlFor="phone">Phone</FieldLabel>
-    <Input id="phone" type="tel" />
-  </Field>
-</FieldGroup>
-```
-
-### Layout Responsive
-
-```tsx
-<FieldGroup>
-  <Field orientation="responsive">
-    <FieldContent>
-      <FieldLabel htmlFor="name">Name</FieldLabel>
-      <FieldDescription>
-        Provide your full name for identification
-      </FieldDescription>
-    </FieldContent>
-    <Input id="name" placeholder="Evil Rabbit" />
-  </Field>
-
-  <Field orientation="responsive">
-    <FieldContent>
-      <FieldLabel htmlFor="message">Message</FieldLabel>
-      <FieldDescription>
-        You can write your message here. Keep it short.
-      </FieldDescription>
-    </FieldContent>
-    <Textarea id="message" placeholder="Hello, world!" />
-  </Field>
-</FieldGroup>
-```
-
-**Comportamiento**: Vertical en mobile, horizontal en `@md/field-group` (container query)
-
-### Formulario Completo
-
-```tsx
-<form>
-  <FieldGroup>
-    <FieldSet>
-      <FieldLegend>Payment Method</FieldLegend>
-      <FieldDescription>
-        All transactions are secure and encrypted
-      </FieldDescription>
-      <FieldGroup>
-        <Field>
-          <FieldLabel htmlFor="card-name">Name on Card</FieldLabel>
-          <Input id="card-name" placeholder="Evil Rabbit" required />
-        </Field>
-        <Field>
-          <FieldLabel htmlFor="card-number">Card Number</FieldLabel>
-          <Input id="card-number" placeholder="1234 5678 9012 3456" required />
-          <FieldDescription>Enter your 16-digit card number</FieldDescription>
-        </Field>
-        <div className="grid grid-cols-3 gap-4">
-          <Field>
-            <FieldLabel htmlFor="exp-month">Month</FieldLabel>
-            <Select>
-              <SelectTrigger id="exp-month">
-                <SelectValue placeholder="MM" />
-              </SelectTrigger>
-              <SelectContent>
-                <SelectItem value="01">01</SelectItem>
-                <SelectItem value="02">02</SelectItem>
-                {/* ... */}
-              </SelectContent>
-            </Select>
-          </Field>
-          <Field>
-            <FieldLabel htmlFor="exp-year">Year</FieldLabel>
-            <Select>
-              <SelectTrigger id="exp-year">
-                <SelectValue placeholder="YYYY" />
-              </SelectTrigger>
-              <SelectContent>
-                <SelectItem value="2024">2024</SelectItem>
-                {/* ... */}
-              </SelectContent>
-            </Select>
-          </Field>
-          <Field>
-            <FieldLabel htmlFor="cvv">CVV</FieldLabel>
-            <Input id="cvv" placeholder="123" required />
-          </Field>
-        </div>
-      </FieldGroup>
-    </FieldSet>
-
-    <FieldSeparator />
-
-    <FieldSet>
-      <FieldLegend>Billing Address</FieldLegend>
-      <FieldDescription>
-        The billing address associated with your payment method
-      </FieldDescription>
-      <FieldGroup>
-        <Field orientation="horizontal">
-          <Checkbox id="same-as-shipping" defaultChecked />
-          <FieldLabel htmlFor="same-as-shipping" className="font-normal">
-            Same as shipping address
-          </FieldLabel>
-        </Field>
-      </FieldGroup>
-    </FieldSet>
-
-    <Field orientation="horizontal">
-      <Button type="submit">Submit</Button>
-      <Button variant="outline" type="button">
-        Cancel
-      </Button>
-    </Field>
-  </FieldGroup>
-</form>
-```
-
-## Casos de Uso Comunes
-
-**Login forms**: Email/password con errores de validación  
-**Registration**: Multi-step forms con grupos de campos  
-**Settings panels**: Switches, checkboxes, selects agrupados  
-**Payment forms**: Cards, billing address, validation  
-**Profiles**: User info con descripción y ayuda  
-**Surveys**: Radio groups, checkboxes, text areas
-
-## Estados y Data Attributes
-
-### Field States
-
-- **Invalid**: `data-invalid=true` → `text-destructive`
-- **Disabled**: `data-disabled=true` → `opacity-50` en label
-
-### Orientation
-
-- **Vertical**: `data-orientation="vertical"` → `flex-col`
-- **Horizontal**: `data-orientation="horizontal"` → `flex-row items-center`
-- **Responsive**: `data-orientation="responsive"` → vertical → horizontal @md
-
-### Auto-adjustments
-
-- **Checkbox/Radio groups**: Gap reduce automáticamente a `gap-3`
-- **Nested groups**: Gap reduce a `gap-4`
-- **Choice cards**: Border, hover, checked state cuando FieldLabel envuelve Field
-
-## Container Queries
-
-FieldGroup usa `@container/field-group` para layouts responsive:
-
-```tsx
-<FieldGroup>
-  {" "}
-  {/* @container/field-group */}
-  <Field orientation="responsive">
-    {/* Vertical por defecto */}
-    {/* Horizontal en @md/field-group */}
-  </Field>
-</FieldGroup>
-```
-
-**Breakpoint**: `@md` (aproximadamente 448px de ancho del container)
-
-## Accesibilidad
-
-- ✅ **Labels**: Asociación correcta con `htmlFor` e `id`
-- ✅ **Descriptions**: Linked con `aria-describedby` implícitamente
-- ✅ **Errors**: `role="alert"` para anuncio automático
-- ✅ **Required fields**: Usa atributo `required` en inputs
-- ✅ **Invalid state**: `aria-invalid` en inputs con errores
-- ✅ **Fieldset/Legend**: Semántica correcta para grupos
-- ✅ **Screen readers**: Anuncia labels, descriptions, errores en orden
-- ✅ **Focus**: Visible en todos los inputs
-
-## Notas de Implementación
-
-- **Composable**: Cada parte es un componente independiente
-- **Class Variance Authority**: Usa CVA para orientación variants
-- **Container queries**: `@container/field-group` para responsive
-- **Auto-styling**: Detecta checkbox/radio groups y ajusta gap
-- **Choice cards**: FieldLabel detecta Field hijo y aplica card styles
-- **Error deduplication**: Auto-deduplica errores por mensaje
-- **Flexible**: Soporta cualquier tipo de input/select/textarea
-- **No wrapper div**: Field es un `role="group"`, no agrega divs innecesarios
-- **Data attributes**: `data-slot` en cada componente para CSS targeting
-- **Disabled state**: Propaga desde Field a Label con opacity
-
-## Integración con React Hook Form
-
-```tsx
-import { useForm } from "react-hook-form";
-
-function MyForm() {
-  const {
-    register,
-    handleSubmit,
-    formState: { errors },
-  } = useForm();
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <Field data-invalid={!!errors.email}>
-        <FieldLabel htmlFor="email">Email</FieldLabel>
-        <Input
-          id="email"
-          {...register("email", { required: "Email is required" })}
-          aria-invalid={!!errors.email}
-        />
-        {errors.email && <FieldError>{errors.email.message}</FieldError>}
-      </Field>
-    </form>
-  );
-}
-```
-
-## Estilos Condicionales
-
-### Links en Description
-
-```tsx
-<FieldDescription>
-  Read our <a href="/privacy">privacy policy</a> for more information.
-</FieldDescription>
-```
-
-**Auto-styling**: Links tienen `underline`, `underline-offset-4`, `hover:text-primary`
-
-### Choice Card Checked State
-
-```tsx
-<FieldLabel>
-  {" "}
-  {/* Wrapper que detecta Field hijo */}
-  <Field orientation="horizontal">
-    <FieldContent>...</FieldContent>
-    <RadioGroupItem value="option" id="option" />
-  </Field>
-</FieldLabel>
-```
-
-**Auto-styling**: `has-data-[state=checked]:bg-primary/5`, `has-data-[state=checked]:border-primary`
-
-## Troubleshooting
-
-**Label no asociado con input**: Verifica que `htmlFor` en FieldLabel coincida con `id` en Input  
-**Description no se anuncia**: Screen readers anuncian description solo si está correctamente estructurada en Field  
-**Errors no aparecen**: Asegúrate de pasar `data-invalid` a Field y `aria-invalid` a Input  
-**Layout no responsive**: Verifica que Field esté dentro de FieldGroup para container queries  
-**Choice cards no tienen estilo**: FieldLabel debe envolver Field, no al revés  
-**Gap incorrecto en checkbox group**: FieldSet detecta checkbox/radio automáticamente, no uses className custom  
-**Múltiples errores no formatean**: Usa prop `errors` array en FieldError, no `children` string  
-**Disabled no aplica**: Usa `data-disabled` en Field root, no en componentes individuales
-
-## Referencias
-
-- **shadcn/ui Form**: <https://ui.shadcn.com/docs/components/form>
-- **React Hook Form**: <https://react-hook-form.com/>
-- **ARIA Forms**: <https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/form.html>
+# Field Component
+
+Sistema de composición para formularios que agrupa inputs con labels, descripciones, errores y validación. Soporta layouts verticales, horizontales y responsive con soporte para todos los tipos de inputs.
+
+## Descripción
+
+El componente `Field` agrupa un input con su label, mensaje de ayuda y errores de validación.
+
+## Importación
+
+```typescript
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldSet,
+  FieldLegend,
+  FieldSeparator,
+  FieldContent,
+  FieldTitle,
+} from "@adamosuiteservices/ui/field";
+```
+
+## Uso Básico
+
+```tsx
+<Field label="Email" description="We'll never share your email.">
+  <Input type="email" placeholder="email@example.com" />
+</Field>
+```
+
+## Con Error
+
+```tsx
+<Field label="Username" error="Username is already taken">
+  <Input aria-invalid />
+</Field>
+```
+
+## Con Campo Requerido
+
+```tsx
+<Field label="Password" required>
+  <Input type="password" />
+</Field>
+```
+
+**Componentes**: 10 (Field, FieldLabel, FieldDescription, FieldError, FieldGroup, FieldSet, FieldLegend, FieldSeparator, FieldContent, FieldTitle)
+
+## Props Principales```
+
+### Field## Props
+
+| Prop | Tipo | Default | Descripción || Prop | Tipo | Descripción |
+
+|------|------|---------|-------------||------|------|-------------|
+
+| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | Layout del field || label | `string` | Etiqueta del campo |
+
+| `data-invalid` | `boolean` | - | Marca field como inválido (aplica estilos de error) || description | `string` | Texto de ayuda |
+
+| `data-disabled` | `boolean` | - | Marca field como deshabilitado || error | `string` | Mensaje de error |
+
+| `className` | `string` | - | Clases CSS adicionales || required | `boolean` | Marca el campo como requerido |
+
+**Orientaciones**:
+
+- `vertical`: Label arriba, input abajo
+- `horizontal`: Label e input lado a lado
+- `responsive`: Vertical en mobile, horizontal en desktop (@md/field-group)
+
+### FieldLabel
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `htmlFor`   | `string` | ID del input asociado  |
+| `className` | `string` | Clases CSS adicionales |
+
+**Hereda props de**: `Label` component
+
+### FieldDescription
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Estilos**: `text-sm`, `text-muted-foreground`, soporta links con `hover:text-primary`
+
+### FieldError
+
+| Prop        | Tipo                        | Descripción                      |
+| ----------- | --------------------------- | -------------------------------- |
+| `children`  | `ReactNode`                 | Mensaje de error custom          |
+| `errors`    | `Array<{message?: string}>` | Array de errores (auto-formatea) |
+| `className` | `string`                    | Clases CSS adicionales           |
+
+**Comportamiento**:
+
+- Si hay 1 error: muestra mensaje directo
+- Si hay múltiples: muestra lista con bullets
+- Auto-deduplica errores por mensaje
+
+### FieldSet
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Estilos**: `flex flex-col gap-6`, ajuste automático de gap para checkbox/radio groups
+
+### FieldLegend
+
+| Prop        | Tipo                  | Default    | Descripción            |
+| ----------- | --------------------- | ---------- | ---------------------- |
+| `variant`   | `"legend" \| "label"` | `"legend"` | Estilo del legend      |
+| `className` | `string`              | -          | Clases CSS adicionales |
+
+**Variantes**:
+
+- `legend`: `text-base`, `font-medium`, `mb-3`
+- `label`: `text-sm`, `font-medium`, `mb-3`
+
+### FieldGroup
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Estilos**: `@container/field-group`, `flex flex-col gap-7`, auto-ajuste para nested groups
+
+### FieldSeparator
+
+| Prop        | Tipo        | Descripción                    |
+| ----------- | ----------- | ------------------------------ |
+| `children`  | `ReactNode` | Texto opcional en el separador |
+| `className` | `string`    | Clases CSS adicionales         |
+
+**Con children**: Muestra texto centrado sobre la línea
+
+### FieldContent
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Uso**: Agrupa label + description en layouts horizontales
+
+### FieldTitle
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Uso**: Título alternativo sin asociación a input (para sliders, groups, etc.)
+
+## Patrones de Uso
+
+### Input Field Básico
+
+```tsx
+import { Input } from "@adamosuiteservices/ui/input";
+
+<Field>
+  <FieldLabel htmlFor="username">Username</FieldLabel>
+  <Input id="username" type="text" placeholder="Max Leiter" />
+  <FieldDescription>
+    Choose a unique username for your account.
+  </FieldDescription>
+</Field>;
+```
+
+### Con Error de Validación
+
+```tsx
+<Field data-invalid>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" type="email" aria-invalid />
+  <FieldError>Enter a valid email address.</FieldError>
+</Field>
+```
+
+### Múltiples Errores
+
+```tsx
+<Field data-invalid>
+  <FieldLabel htmlFor="password">Password</FieldLabel>
+  <Input id="password" type="password" aria-invalid />
+  <FieldError
+    errors={[
+      { message: "Password must be at least 8 characters long" },
+      { message: "Password must contain at least one number" },
+      { message: "Password must contain at least one special character" },
+    ]}
+  />
+</Field>
+```
+
+**Renderiza**: Lista con bullets automática
+
+### Textarea Field
+
+```tsx
+import { Textarea } from "@adamosuiteservices/ui/textarea";
+
+<Field>
+  <FieldLabel htmlFor="feedback">Feedback</FieldLabel>
+  <Textarea
+    id="feedback"
+    placeholder="Your feedback helps us improve..."
+    rows={4}
+  />
+  <FieldDescription>Share your thoughts about our service.</FieldDescription>
+</Field>;
+```
+
+### Select Field
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@adamosuiteservices/ui/select";
+
+<Field>
+  <FieldLabel>Department</FieldLabel>
+  <Select>
+    <SelectTrigger>
+      <SelectValue placeholder="Choose department" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="engineering">Engineering</SelectItem>
+      <SelectItem value="design">Design</SelectItem>
+      <SelectItem value="marketing">Marketing</SelectItem>
+    </SelectContent>
+  </Select>
+  <FieldDescription>Select your department or area of work.</FieldDescription>
+</Field>;
+```
+
+### Switch Field (Horizontal)
+
+```tsx
+import { Switch } from "@adamosuiteservices/ui/switch";
+
+<Field orientation="horizontal">
+  <Switch id="newsletter" />
+  <FieldLabel htmlFor="newsletter">Subscribe to the newsletter</FieldLabel>
+</Field>;
+```
+
+### Switch con Descripción (Horizontal)
+
+```tsx
+<Field orientation="horizontal">
+  <FieldContent>
+    <FieldLabel htmlFor="2fa">Multi-factor authentication</FieldLabel>
+    <FieldDescription>
+      Enable multi-factor authentication. If you do not have a two-factor
+      device, you can use a one-time code sent to your email.
+    </FieldDescription>
+  </FieldContent>
+  <Switch id="2fa" />
+</Field>
+```
+
+### Checkbox Group
+
+```tsx
+import { Checkbox } from "@adamosuiteservices/ui/checkbox";
+
+<FieldSet>
+  <FieldLegend variant="label">Show these items on the desktop</FieldLegend>
+  <FieldDescription>
+    Select the items you want to show on the desktop.
+  </FieldDescription>
+  <FieldGroup className="gap-3">
+    <Field orientation="horizontal">
+      <Checkbox id="hard-disks" />
+      <FieldLabel htmlFor="hard-disks" className="font-normal">
+        Hard disks
+      </FieldLabel>
+    </Field>
+    <Field orientation="horizontal">
+      <Checkbox id="external-disks" />
+      <FieldLabel htmlFor="external-disks" className="font-normal">
+        External disks
+      </FieldLabel>
+    </Field>
+    <Field orientation="horizontal">
+      <Checkbox id="cds-dvds" />
+      <FieldLabel htmlFor="cds-dvds" className="font-normal">
+        CDs, DVDs, and iPods
+      </FieldLabel>
+    </Field>
+  </FieldGroup>
+</FieldSet>;
+```
+
+### Radio Group
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@adamosuiteservices/ui/radio-group";
+
+<FieldSet>
+  <FieldLabel>Subscription Plan</FieldLabel>
+  <FieldDescription>
+    Yearly and lifetime plans offer significant savings.
+  </FieldDescription>
+  <RadioGroup defaultValue="monthly">
+    <Field orientation="horizontal">
+      <RadioGroupItem value="monthly" id="plan-monthly" />
+      <FieldLabel htmlFor="plan-monthly" className="font-normal">
+        Monthly ($9.99/month)
+      </FieldLabel>
+    </Field>
+    <Field orientation="horizontal">
+      <RadioGroupItem value="yearly" id="plan-yearly" />
+      <FieldLabel htmlFor="plan-yearly" className="font-normal">
+        Yearly ($99.99/year)
+      </FieldLabel>
+    </Field>
+    <Field orientation="horizontal">
+      <RadioGroupItem value="lifetime" id="plan-lifetime" />
+      <FieldLabel htmlFor="plan-lifetime" className="font-normal">
+        Lifetime ($299.99)
+      </FieldLabel>
+    </Field>
+  </RadioGroup>
+</FieldSet>;
+```
+
+### Choice Cards (Radio como Cards)
+
+```tsx
+<FieldSet>
+  <FieldLabel htmlFor="compute-environment">Compute Environment</FieldLabel>
+  <FieldDescription>
+    Select the compute environment for your cluster.
+  </FieldDescription>
+  <RadioGroup defaultValue="kubernetes">
+    <FieldLabel htmlFor="kubernetes">
+      <Field orientation="horizontal">
+        <FieldContent>
+          <FieldTitle>Kubernetes</FieldTitle>
+          <FieldDescription>
+            Run GPU workloads on a K8s configured cluster.
+          </FieldDescription>
+        </FieldContent>
+        <RadioGroupItem value="kubernetes" id="kubernetes" />
+      </Field>
+    </FieldLabel>
+    <FieldLabel htmlFor="vm">
+      <Field orientation="horizontal">
+        <FieldContent>
+          <FieldTitle>Virtual Machine</FieldTitle>
+          <FieldDescription>
+            Access a VM configured cluster to run GPU workloads.
+          </FieldDescription>
+        </FieldContent>
+        <RadioGroupItem value="vm" id="vm" />
+      </Field>
+    </FieldLabel>
+  </RadioGroup>
+</FieldSet>
+```
+
+**Estilos automáticos**: FieldLabel envuelve Field → card con border, hover, checked state
+
+### Slider Field
+
+```tsx
+import { Slider } from "@adamosuiteservices/ui/slider";
+import { useState } from "react";
+
+function PriceRange() {
+  const [value, setValue] = useState([200, 800]);
+
+  return (
+    <Field>
+      <FieldTitle>Price Range</FieldTitle>
+      <FieldDescription>
+        Set your budget range ($
+        <span className="font-medium tabular-nums">{value[0]}</span> - <span className="font-medium tabular-nums">
+          {value[1]}
+        </span>).
+      </FieldDescription>
+      <Slider
+        value={value}
+        onValueChange={setValue}
+        max={1000}
+        min={0}
+        step={10}
+        className="mt-2 w-full"
+        aria-label="Price Range"
+      />
+    </Field>
+  );
+}
+```
+
+### FieldSet con Grupos
+
+```tsx
+<FieldSet>
+  <FieldLegend>Address Information</FieldLegend>
+  <FieldDescription>
+    We need your address to deliver your order.
+  </FieldDescription>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="street">Street Address</FieldLabel>
+      <Input id="street" type="text" placeholder="123 Main St" />
+    </Field>
+    <div className="grid grid-cols-2 gap-4">
+      <Field>
+        <FieldLabel htmlFor="city">City</FieldLabel>
+        <Input id="city" type="text" placeholder="New York" />
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="zip">Postal Code</FieldLabel>
+        <Input id="zip" type="text" placeholder="90502" />
+      </Field>
+    </div>
+  </FieldGroup>
+</FieldSet>
+```
+
+### Con Separadores
+
+```tsx
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="name">Name</FieldLabel>
+    <Input id="name" />
+  </Field>
+
+  <FieldSeparator />
+
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" type="email" />
+  </Field>
+
+  <FieldSeparator>or</FieldSeparator>
+
+  <Field>
+    <FieldLabel htmlFor="phone">Phone</FieldLabel>
+    <Input id="phone" type="tel" />
+  </Field>
+</FieldGroup>
+```
+
+### Layout Responsive
+
+```tsx
+<FieldGroup>
+  <Field orientation="responsive">
+    <FieldContent>
+      <FieldLabel htmlFor="name">Name</FieldLabel>
+      <FieldDescription>
+        Provide your full name for identification
+      </FieldDescription>
+    </FieldContent>
+    <Input id="name" placeholder="Evil Rabbit" />
+  </Field>
+
+  <Field orientation="responsive">
+    <FieldContent>
+      <FieldLabel htmlFor="message">Message</FieldLabel>
+      <FieldDescription>
+        You can write your message here. Keep it short.
+      </FieldDescription>
+    </FieldContent>
+    <Textarea id="message" placeholder="Hello, world!" />
+  </Field>
+</FieldGroup>
+```
+
+**Comportamiento**: Vertical en mobile, horizontal en `@md/field-group` (container query)
+
+### Formulario Completo
+
+```tsx
+<form>
+  <FieldGroup>
+    <FieldSet>
+      <FieldLegend>Payment Method</FieldLegend>
+      <FieldDescription>
+        All transactions are secure and encrypted
+      </FieldDescription>
+      <FieldGroup>
+        <Field>
+          <FieldLabel htmlFor="card-name">Name on Card</FieldLabel>
+          <Input id="card-name" placeholder="Evil Rabbit" required />
+        </Field>
+        <Field>
+          <FieldLabel htmlFor="card-number">Card Number</FieldLabel>
+          <Input id="card-number" placeholder="1234 5678 9012 3456" required />
+          <FieldDescription>Enter your 16-digit card number</FieldDescription>
+        </Field>
+        <div className="grid grid-cols-3 gap-4">
+          <Field>
+            <FieldLabel htmlFor="exp-month">Month</FieldLabel>
+            <Select>
+              <SelectTrigger id="exp-month">
+                <SelectValue placeholder="MM" />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="01">01</SelectItem>
+                <SelectItem value="02">02</SelectItem>
+                {/* ... */}
+              </SelectContent>
+            </Select>
+          </Field>
+          <Field>
+            <FieldLabel htmlFor="exp-year">Year</FieldLabel>
+            <Select>
+              <SelectTrigger id="exp-year">
+                <SelectValue placeholder="YYYY" />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="2024">2024</SelectItem>
+                {/* ... */}
+              </SelectContent>
+            </Select>
+          </Field>
+          <Field>
+            <FieldLabel htmlFor="cvv">CVV</FieldLabel>
+            <Input id="cvv" placeholder="123" required />
+          </Field>
+        </div>
+      </FieldGroup>
+    </FieldSet>
+
+    <FieldSeparator />
+
+    <FieldSet>
+      <FieldLegend>Billing Address</FieldLegend>
+      <FieldDescription>
+        The billing address associated with your payment method
+      </FieldDescription>
+      <FieldGroup>
+        <Field orientation="horizontal">
+          <Checkbox id="same-as-shipping" defaultChecked />
+          <FieldLabel htmlFor="same-as-shipping" className="font-normal">
+            Same as shipping address
+          </FieldLabel>
+        </Field>
+      </FieldGroup>
+    </FieldSet>
+
+    <Field orientation="horizontal">
+      <Button type="submit">Submit</Button>
+      <Button variant="outline" type="button">
+        Cancel
+      </Button>
+    </Field>
+  </FieldGroup>
+</form>
+```
+
+## Casos de Uso Comunes
+
+**Login forms**: Email/password con errores de validación  
+**Registration**: Multi-step forms con grupos de campos  
+**Settings panels**: Switches, checkboxes, selects agrupados  
+**Payment forms**: Cards, billing address, validation  
+**Profiles**: User info con descripción y ayuda  
+**Surveys**: Radio groups, checkboxes, text areas
+
+## Estados y Data Attributes
+
+### Field States
+
+- **Invalid**: `data-invalid=true` → `text-destructive`
+- **Disabled**: `data-disabled=true` → `opacity-50` en label
+
+### Orientation
+
+- **Vertical**: `data-orientation="vertical"` → `flex-col`
+- **Horizontal**: `data-orientation="horizontal"` → `flex-row items-center`
+- **Responsive**: `data-orientation="responsive"` → vertical → horizontal @md
+
+### Auto-adjustments
+
+- **Checkbox/Radio groups**: Gap reduce automáticamente a `gap-3`
+- **Nested groups**: Gap reduce a `gap-4`
+- **Choice cards**: Border, hover, checked state cuando FieldLabel envuelve Field
+
+## Container Queries
+
+FieldGroup usa `@container/field-group` para layouts responsive:
+
+```tsx
+<FieldGroup>
+  {" "}
+  {/* @container/field-group */}
+  <Field orientation="responsive">
+    {/* Vertical por defecto */}
+    {/* Horizontal en @md/field-group */}
+  </Field>
+</FieldGroup>
+```
+
+**Breakpoint**: `@md` (aproximadamente 448px de ancho del container)
+
+## Accesibilidad
+
+- ✅ **Labels**: Asociación correcta con `htmlFor` e `id`
+- ✅ **Descriptions**: Linked con `aria-describedby` implícitamente
+- ✅ **Errors**: `role="alert"` para anuncio automático
+- ✅ **Required fields**: Usa atributo `required` en inputs
+- ✅ **Invalid state**: `aria-invalid` en inputs con errores
+- ✅ **Fieldset/Legend**: Semántica correcta para grupos
+- ✅ **Screen readers**: Anuncia labels, descriptions, errores en orden
+- ✅ **Focus**: Visible en todos los inputs
+
+## Notas de Implementación
+
+- **Composable**: Cada parte es un componente independiente
+- **Class Variance Authority**: Usa CVA para orientación variants
+- **Container queries**: `@container/field-group` para responsive
+- **Auto-styling**: Detecta checkbox/radio groups y ajusta gap
+- **Choice cards**: FieldLabel detecta Field hijo y aplica card styles
+- **Error deduplication**: Auto-deduplica errores por mensaje
+- **Flexible**: Soporta cualquier tipo de input/select/textarea
+- **No wrapper div**: Field es un `role="group"`, no agrega divs innecesarios
+- **Data attributes**: `data-slot` en cada componente para CSS targeting
+- **Disabled state**: Propaga desde Field a Label con opacity
+
+## Integración con React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form";
+
+function MyForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+  } = useForm();
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Field data-invalid={!!errors.email}>
+        <FieldLabel htmlFor="email">Email</FieldLabel>
+        <Input
+          id="email"
+          {...register("email", { required: "Email is required" })}
+          aria-invalid={!!errors.email}
+        />
+        {errors.email && <FieldError>{errors.email.message}</FieldError>}
+      </Field>
+    </form>
+  );
+}
+```
+
+## Estilos Condicionales
+
+### Links en Description
+
+```tsx
+<FieldDescription>
+  Read our <a href="/privacy">privacy policy</a> for more information.
+</FieldDescription>
+```
+
+**Auto-styling**: Links tienen `underline`, `underline-offset-4`, `hover:text-primary`
+
+### Choice Card Checked State
+
+```tsx
+<FieldLabel>
+  {" "}
+  {/* Wrapper que detecta Field hijo */}
+  <Field orientation="horizontal">
+    <FieldContent>...</FieldContent>
+    <RadioGroupItem value="option" id="option" />
+  </Field>
+</FieldLabel>
+```
+
+**Auto-styling**: `has-data-[state=checked]:bg-primary/5`, `has-data-[state=checked]:border-primary`
+
+## Troubleshooting
+
+**Label no asociado con input**: Verifica que `htmlFor` en FieldLabel coincida con `id` en Input  
+**Description no se anuncia**: Screen readers anuncian description solo si está correctamente estructurada en Field  
+**Errors no aparecen**: Asegúrate de pasar `data-invalid` a Field y `aria-invalid` a Input  
+**Layout no responsive**: Verifica que Field esté dentro de FieldGroup para container queries  
+**Choice cards no tienen estilo**: FieldLabel debe envolver Field, no al revés  
+**Gap incorrecto en checkbox group**: FieldSet detecta checkbox/radio automáticamente, no uses className custom  
+**Múltiples errores no formatean**: Usa prop `errors` array en FieldError, no `children` string  
+**Disabled no aplica**: Usa `data-disabled` en Field root, no en componentes individuales
+
+## Referencias
+
+- **shadcn/ui Form**: <https://ui.shadcn.com/docs/components/form>
+- **React Hook Form**: <https://react-hook-form.com/>
+- **ARIA Forms**: <https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/form.html>