@adamosuiteservices/ui 2.11.20 → 2.12.0

package/docs/components/ui/input.md

@@ -1,362 +1,362 @@
-# Input Component
-
-Campo de entrada de formulario estilizado. Wrapper sobre `<input>` HTML nativo con estilos consistentes, validación visual y soporte para todos los tipos nativos.
-
-## Descripción
-
-El componente `Input` muestra un campo de entrada de formulario o un componente que luce como un campo de entrada.
-
-## Importación
-
-```typescript
-import { Input } from "@adamosuiteservices/ui/input";
-```
-
-## Uso Básico
-
-```tsx
-<Input type="email" placeholder="Email" />
-```
-
-**Componentes**: 1 (Input)
-
-## Con Label
-
-```tsx
-<div className="grid w-full max-w-sm items-center gap-2">
-  <Label htmlFor="email">Email</Label>
-  <Input type="email" id="email" placeholder="Email" />
-</div>
-```
-
-## Con Botón
-
-```tsx
-<div className="flex w-full max-w-sm items-center gap-2">
-  <Input type="email" placeholder="Email" />
-  <Button type="submit" variant="outline">
-    Subscribe
-  </Button>
-</div>
-```
-
-## Tipos de Input
-
-### Email
-
-```tsx
-<Input type="email" placeholder="correo@ejemplo.com" />
-```
-
-### Password
-
-```tsx
-<Input type="password" placeholder="Contraseña" />
-```
-
-### Number
-
-```tsx
-<Input type="number" placeholder="Edad" />
-```
-
-### Text
-
-```tsx
-<Input type="text" placeholder="Nombre" />
-```
-
-### Search
-
-```tsx
-<Input type="search" placeholder="Buscar..." />
-```
-
-### URL
-
-```tsx
-<Input type="url" placeholder="https://ejemplo.com" />
-```
-
-### Tel
-
-```tsx
-<Input type="tel" placeholder="+1 (555) 123-4567" />
-```
-
-### Date
-
-```tsx
-<Input type="date" />
-```
-
-### File
-
-```tsx
-<div className="grid w-full max-w-sm items-center gap-2">
-  <Label htmlFor="picture">Picture</Label>
-  <Input id="picture" type="file" />
-</div>
-```
-
-## Estados
-
-### Disabled
-
-```tsx
-<Input disabled type="email" placeholder="Email" />
-```
-
-### ReadOnly
-
-```tsx
-<Input readOnly value="Solo lectura" />
-```
-
-### Invalid
-
-```tsx
-<Input
-  type="email"
-  placeholder="Enter email"
-  aria-invalid
-  defaultValue="invalid-email"
-/>
-```
-
-## Tamaños Personalizados
-
-```tsx
-{
-  /* Pequeño */
-}
-<Input type="text" placeholder="Small input" className="h-8 text-sm" />;
-
-{
-  /* Por defecto */
-}
-<Input type="text" placeholder="Default input" />;
-
-{
-  /* Grande */
-}
-<Input type="text" placeholder="Large input" className="h-10" />;
-```
-
-## Con Validación
-
-```tsx
-<div className="space-y-2">
-  <Label htmlFor="email">Email</Label>
-  <Input
-    id="email"
-    type="email"
-    placeholder="correo@ejemplo.com"
-    aria-invalid={hasError}
-  />
-  {hasError && <p className="text-destructive text-sm">Email inválido</p>}
-</div>
-```
-
-## Props
-
-| Prop         | Tipo                                                                                                    | Default  | Descripción                  |
-| ------------ | ------------------------------------------------------------------------------------------------------- | -------- | ---------------------------- |
-| type         | `"text" \| "email" \| "password" \| "number" \| "file" \| "search" \| "url" \| "tel" \| "date" \| etc.` | `"text"` | Tipo de input HTML nativo    |
-| placeholder  | `string`                                                                                                | -        | Texto placeholder            |
-| disabled     | `boolean`                                                                                               | `false`  | Desactiva el input           |
-| readOnly     | `boolean`                                                                                               | `false`  | Input solo lectura           |
-| value        | `string \| number`                                                                                      | -        | Valor controlado             |
-| defaultValue | `string \| number`                                                                                      | -        | Valor inicial no controlado  |
-| onChange     | `(e) => void`                                                                                           | -        | Callback al cambiar valor    |
-| aria-invalid | `boolean`                                                                                               | `false`  | Marca el input como inválido |
-| className    | `string`                                                                                                | -        | Clases CSS adicionales       |
-
-## Características del Estilo
-
-### Focus
-
-El input tiene un anillo de enfoque visible:
-
-```css
-focus-visible:ring-ring/50
-focus-visible:ring-[3px]
-```
-
-### Estados de Validación
-
-- Borde normal: `border-input`
-- Inválido: `aria-invalid:border-destructive` con anillo rojo
-
-### Modo Oscuro
-
-```css
-dark: bg-input/30;
-```
-
-### File Input
-
-Los file inputs tienen estilos especiales para el botón:
-
-```css
-file:h-7
-file:text-sm
-file:font-medium
-```
-
-## Casos de Uso Comunes
-
-### Formulario de Login
-
-```tsx
-<form className="space-y-4">
-  <div className="space-y-2">
-    <Label htmlFor="email">Email</Label>
-    <Input id="email" type="email" placeholder="correo@ejemplo.com" />
-  </div>
-  <div className="space-y-2">
-    <Label htmlFor="password">Password</Label>
-    <Input id="password" type="password" />
-  </div>
-  <Button type="submit">Iniciar Sesión</Button>
-</form>
-```
-
-### Búsqueda
-
-```tsx
-<div className="flex items-center gap-2">
-  <SearchIcon className="h-4 w-4 text-muted-foreground" />
-  <Input type="search" placeholder="Buscar..." className="flex-1" />
-</div>
-```
-
-### Input con Contador
-
-```tsx
-const [text, setText] = useState("");
-const maxLength = 100;
-
-<div className="space-y-2">
-  <Label htmlFor="bio">Bio</Label>
-  <Input
-    id="bio"
-    value={text}
-    onChange={(e) => setText(e.target.value)}
-    maxLength={maxLength}
-    placeholder="Escribe tu bio..."
-  />
-  <p className="text-sm text-muted-foreground">
-    {text.length} / {maxLength}
-  </p>
-</div>;
-```
-
-## Accesibilidad
-
-- Siempre usa un `<Label>` asociado con el input
-- Usa `aria-invalid` para estados de error
-- Usa `aria-describedby` para mensajes de ayuda
-- Los placeholders no reemplazan a los labels
-- El input soporta navegación por teclado nativa
-
-## Notas de Implementación
-
-- Usa el prefijo `` en todos los estilos
-- Basado en el elemento HTML `<input>` nativo
-- Soporta todas las props nativas de HTML input
-- Los iconos SVG internos se redimensionan automáticamente
-- Tiene transición suave en color y box-shadow
-
-## Referencias
-
-- Documentación de shadcn/ui: <https://ui.shadcn.com/docs/components/input>
-- MDN Input: <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input>
-
-## Características Avanzadas
-
-**Forms**: Inputs en formularios de registro, login, contacto  
-**Search**: Barras de búsqueda con `type="search"`  
-**File upload**: Selección de archivos con `type="file"`  
-**Numbers**: Cantidades, precios, edades con `type="number"`  
-**Dates**: Selección de fechas con `type="date"`  
-**Validation**: Campos con validación visual via `aria-invalid`
-
-## Estados y Data Attributes
-
-### Focus
-
-- **Focused**: `focus-visible:ring-ring/50`, `focus-visible:ring-[3px]`, `focus-visible:border-ring`
-
-### Validation
-
-- **Invalid**: `aria-invalid:border-destructive`, `aria-invalid:ring-destructive/20`
-- **Valid**: Border normal `border-input`
-
-### Estado Disabled
-
-- **Disabled**: `opacity-50`, `pointer-events-none`, `cursor-not-allowed`
-
-### Estilos File Input
-
-- **File button**: `file:h-7`, `file:text-sm`, `file:font-medium`, `file:bg-transparent`
-
-## Estilos Base
-
-- **Height**: `h-9` (~36px) por defecto
-- **Border**: `border`, `border-input`, `rounded-md`
-- **Padding**: `px-3 py-1`
-- **Font**: `text-base md:text-sm`
-- **Shadow**: `shadow-xs`
-- **Background**: `bg-transparent`, `dark:bg-input/30`
-- **Transitions**: `transition-[color,box-shadow]`
-- **Selection**: `selection:bg-primary selection:text-primary-foreground`
-
-## Guía de Accesibilidad
-
-- ✅ **Label**: Siempre usa `<Label>` asociado con `htmlFor` e `id`
-- ✅ **ARIA**: Usa `aria-invalid` para estados de error
-- ✅ **Description**: Usa `aria-describedby` para mensajes de ayuda
-- ✅ **Placeholder**: No reemplaza label, solo ayuda visual
-- ✅ **Keyboard**: Navegación nativa (Tab, Arrow keys en number/date)
-- ✅ **Required**: Usa `required` para campos obligatorios
-- ✅ **Autocomplete**: Usa `autoComplete` para mejorar UX
-- ⚠️ **Error messages**: Asocia con `aria-describedby` para screen readers
-
-## Detalles de Implementación
-
-- **HTML nativo**: Wrapper sobre `<input>` con estilos aplicados
-- **Props forwarding**: Acepta todas las props HTML nativas
-- **Validation**: Usa atributos nativos (`required`, `pattern`, `min`, `max`) + `aria-invalid`
-- **File input**: Estilos especiales para el botón "Choose file"
-- **Focus ring**: 3px con 50% opacity para visibilidad sin ser invasivo
-- **Shadow**: Sutil `shadow-xs` para profundidad
-- **Responsive**: `text-base` en mobile, `text-sm` en desktop (`md:`)
-- **Dark mode**: Background semi-transparente `dark:bg-input/30`
-
-## Diferencias con Textarea
-
-| Aspecto    | Input                             | Textarea                  |
-| ---------- | --------------------------------- | ------------------------- |
-| **Líneas** | Single-line                       | Multi-line                |
-| **Height** | Fijo (h-9)                        | Variable (min-h-20)       |
-| **Resize** | No                                | Sí (vertical por defecto) |
-| **Tipos**  | Múltiples (email, password, etc.) | Solo text                 |
-| **Uso**    | Datos cortos                      | Texto largo               |
-
-## Troubleshooting
-
-**Placeholder no se ve**: Verifica color con `placeholder:text-muted-foreground`  
-**Focus ring no aparece**: Usa `:focus-visible` no `:focus`, asegúrate de no override con `outline-none` sin ring  
-**Estilos no aplican**: Verifica que uses `className` con Tailwind válido  
-**File input no se ve bien**: Usa clases `file:*` para estilizar botón  
-**Invalid state no funciona**: Asegúrate de usar `aria-invalid` no solo `invalid`  
-**Height inconsistente**: Input tiene `h-9` default, usa `className` para override  
-**Dark mode no funciona**: Verifica tema configurado y clase `dark:` aplicándose  
-**Number input permite texto**: Navegador valida, pero usa validación JS adicional
-
-## Referencias Adicionales
-
-- **shadcn/ui Input**: <https://ui.shadcn.com/docs/components/input>
-- **MDN Input**: <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input>
-- **WAI-ARIA Input**: <https://www.w3.org/WAI/ARIA/apg/patterns/input/>
+# Input Component
+
+Campo de entrada de formulario estilizado. Wrapper sobre `<input>` HTML nativo con estilos consistentes, validación visual y soporte para todos los tipos nativos.
+
+## Descripción
+
+El componente `Input` muestra un campo de entrada de formulario o un componente que luce como un campo de entrada.
+
+## Importación
+
+```typescript
+import { Input } from "@adamosuiteservices/ui/input";
+```
+
+## Uso Básico
+
+```tsx
+<Input type="email" placeholder="Email" />
+```
+
+**Componentes**: 1 (Input)
+
+## Con Label
+
+```tsx
+<div className="grid w-full max-w-sm items-center gap-2">
+  <Label htmlFor="email">Email</Label>
+  <Input type="email" id="email" placeholder="Email" />
+</div>
+```
+
+## Con Botón
+
+```tsx
+<div className="flex w-full max-w-sm items-center gap-2">
+  <Input type="email" placeholder="Email" />
+  <Button type="submit" variant="outline">
+    Subscribe
+  </Button>
+</div>
+```
+
+## Tipos de Input
+
+### Email
+
+```tsx
+<Input type="email" placeholder="correo@ejemplo.com" />
+```
+
+### Password
+
+```tsx
+<Input type="password" placeholder="Contraseña" />
+```
+
+### Number
+
+```tsx
+<Input type="number" placeholder="Edad" />
+```
+
+### Text
+
+```tsx
+<Input type="text" placeholder="Nombre" />
+```
+
+### Search
+
+```tsx
+<Input type="search" placeholder="Buscar..." />
+```
+
+### URL
+
+```tsx
+<Input type="url" placeholder="https://ejemplo.com" />
+```
+
+### Tel
+
+```tsx
+<Input type="tel" placeholder="+1 (555) 123-4567" />
+```
+
+### Date
+
+```tsx
+<Input type="date" />
+```
+
+### File
+
+```tsx
+<div className="grid w-full max-w-sm items-center gap-2">
+  <Label htmlFor="picture">Picture</Label>
+  <Input id="picture" type="file" />
+</div>
+```
+
+## Estados
+
+### Disabled
+
+```tsx
+<Input disabled type="email" placeholder="Email" />
+```
+
+### ReadOnly
+
+```tsx
+<Input readOnly value="Solo lectura" />
+```
+
+### Invalid
+
+```tsx
+<Input
+  type="email"
+  placeholder="Enter email"
+  aria-invalid
+  defaultValue="invalid-email"
+/>
+```
+
+## Tamaños Personalizados
+
+```tsx
+{
+  /* Pequeño */
+}
+<Input type="text" placeholder="Small input" className="h-9 text-sm" />;
+
+{
+  /* Por defecto */
+}
+<Input type="text" placeholder="Default input" />; {/* h-10 por defecto */}
+
+{
+  /* Grande */
+}
+<Input type="text" placeholder="Large input" className="h-11" />;
+```
+
+## Con Validación
+
+```tsx
+<div className="space-y-2">
+  <Label htmlFor="email">Email</Label>
+  <Input
+    id="email"
+    type="email"
+    placeholder="correo@ejemplo.com"
+    aria-invalid={hasError}
+  />
+  {hasError && <p className="text-destructive text-sm">Email inválido</p>}
+</div>
+```
+
+## Props
+
+| Prop         | Tipo                                                                                                    | Default  | Descripción                  |
+| ------------ | ------------------------------------------------------------------------------------------------------- | -------- | ---------------------------- |
+| type         | `"text" \| "email" \| "password" \| "number" \| "file" \| "search" \| "url" \| "tel" \| "date" \| etc.` | `"text"` | Tipo de input HTML nativo    |
+| placeholder  | `string`                                                                                                | -        | Texto placeholder            |
+| disabled     | `boolean`                                                                                               | `false`  | Desactiva el input           |
+| readOnly     | `boolean`                                                                                               | `false`  | Input solo lectura           |
+| value        | `string \| number`                                                                                      | -        | Valor controlado             |
+| defaultValue | `string \| number`                                                                                      | -        | Valor inicial no controlado  |
+| onChange     | `(e) => void`                                                                                           | -        | Callback al cambiar valor    |
+| aria-invalid | `boolean`                                                                                               | `false`  | Marca el input como inválido |
+| className    | `string`                                                                                                | -        | Clases CSS adicionales       |
+
+## Características del Estilo
+
+### Focus
+
+El input tiene un anillo de enfoque visible:
+
+```css
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+```
+
+### Estados de Validación
+
+- Borde normal: `border-input`
+- Inválido: `aria-invalid:border-destructive` con anillo rojo
+
+### Modo Oscuro
+
+```css
+dark: bg-input/30;
+```
+
+### File Input
+
+Los file inputs tienen estilos especiales para el botón:
+
+```css
+file:h-7
+file:text-sm
+file:font-medium
+```
+
+## Casos de Uso Comunes
+
+### Formulario de Login
+
+```tsx
+<form className="space-y-4">
+  <div className="space-y-2">
+    <Label htmlFor="email">Email</Label>
+    <Input id="email" type="email" placeholder="correo@ejemplo.com" />
+  </div>
+  <div className="space-y-2">
+    <Label htmlFor="password">Password</Label>
+    <Input id="password" type="password" />
+  </div>
+  <Button type="submit">Iniciar Sesión</Button>
+</form>
+```
+
+### Búsqueda
+
+```tsx
+<div className="flex items-center gap-2">
+  <SearchIcon className="h-4 w-4 text-muted-foreground" />
+  <Input type="search" placeholder="Buscar..." className="flex-1" />
+</div>
+```
+
+### Input con Contador
+
+```tsx
+const [text, setText] = useState("");
+const maxLength = 100;
+
+<div className="space-y-2">
+  <Label htmlFor="bio">Bio</Label>
+  <Input
+    id="bio"
+    value={text}
+    onChange={(e) => setText(e.target.value)}
+    maxLength={maxLength}
+    placeholder="Escribe tu bio..."
+  />
+  <p className="text-sm text-muted-foreground">
+    {text.length} / {maxLength}
+  </p>
+</div>;
+```
+
+## Accesibilidad
+
+- Siempre usa un `<Label>` asociado con el input
+- Usa `aria-invalid` para estados de error
+- Usa `aria-describedby` para mensajes de ayuda
+- Los placeholders no reemplazan a los labels
+- El input soporta navegación por teclado nativa
+
+## Notas de Implementación
+
+- Usa el prefijo `` en todos los estilos
+- Basado en el elemento HTML `<input>` nativo
+- Soporta todas las props nativas de HTML input
+- Los iconos SVG internos se redimensionan automáticamente
+- Tiene transición suave en color y box-shadow
+
+## Referencias
+
+- Documentación de shadcn/ui: <https://ui.shadcn.com/docs/components/input>
+- MDN Input: <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input>
+
+## Características Avanzadas
+
+**Forms**: Inputs en formularios de registro, login, contacto  
+**Search**: Barras de búsqueda con `type="search"`  
+**File upload**: Selección de archivos con `type="file"`  
+**Numbers**: Cantidades, precios, edades con `type="number"`  
+**Dates**: Selección de fechas con `type="date"`  
+**Validation**: Campos con validación visual via `aria-invalid`
+
+## Estados y Data Attributes
+
+### Focus
+
+- **Focused**: `focus-visible:ring-ring/50`, `focus-visible:ring-[3px]`, `focus-visible:border-ring`
+
+### Validation
+
+- **Invalid**: `aria-invalid:border-destructive`, `aria-invalid:ring-destructive/20`
+- **Valid**: Border normal `border-input`
+
+### Estado Disabled
+
+- **Disabled**: `opacity-50`, `pointer-events-none`, `cursor-not-allowed`
+
+### Estilos File Input
+
+- **File button**: `file:h-full`, `file:items-center`, `file:-ml-3`, `file:pl-3`, `file:mr-3`, `file:text-sm`, `file:font-medium`, `file:bg-transparent`
+
+## Estilos Base
+
+- **Height**: `h-10` (~40px) por defecto
+- **Border**: `border`, `border-input`, `rounded-md`
+- **Padding**: `px-3` (sin padding vertical, el height define la altura)
+- **Font**: `text-base md:text-sm`
+- **Shadow**: `shadow-xs`
+- **Background**: `bg-transparent`, `dark:bg-input/30`
+- **Transitions**: `transition-[color,box-shadow]`
+- **Selection**: `selection:bg-primary selection:text-primary-foreground`
+
+## Guía de Accesibilidad
+
+- ✅ **Label**: Siempre usa `<Label>` asociado con `htmlFor` e `id`
+- ✅ **ARIA**: Usa `aria-invalid` para estados de error
+- ✅ **Description**: Usa `aria-describedby` para mensajes de ayuda
+- ✅ **Placeholder**: No reemplaza label, solo ayuda visual
+- ✅ **Keyboard**: Navegación nativa (Tab, Arrow keys en number/date)
+- ✅ **Required**: Usa `required` para campos obligatorios
+- ✅ **Autocomplete**: Usa `autoComplete` para mejorar UX
+- ⚠️ **Error messages**: Asocia con `aria-describedby` para screen readers
+
+## Detalles de Implementación
+
+- **HTML nativo**: Wrapper sobre `<input>` con estilos aplicados
+- **Props forwarding**: Acepta todas las props HTML nativas
+- **Validation**: Usa atributos nativos (`required`, `pattern`, `min`, `max`) + `aria-invalid`
+- **File input**: Estilos especiales para el botón "Choose file"
+- **Focus ring**: 3px con 50% opacity para visibilidad sin ser invasivo
+- **Shadow**: Sutil `shadow-xs` para profundidad
+- **Responsive**: `text-base` en mobile, `text-sm` en desktop (`md:`)
+- **Dark mode**: Background semi-transparente `dark:bg-input/30`
+
+## Diferencias con Textarea
+
+| Aspecto    | Input                             | Textarea                  |
+| ---------- | --------------------------------- | ------------------------- |
+| **Líneas** | Single-line                       | Multi-line                |
+| **Height** | Fijo (h-9)                        | Variable (min-h-20)       |
+| **Resize** | No                                | Sí (vertical por defecto) |
+| **Tipos**  | Múltiples (email, password, etc.) | Solo text                 |
+| **Uso**    | Datos cortos                      | Texto largo               |
+
+## Troubleshooting
+
+**Placeholder no se ve**: Verifica color con `placeholder:text-muted-foreground`  
+**Focus ring no aparece**: Usa `:focus-visible` no `:focus`, asegúrate de no override con `outline-none` sin ring  
+**Estilos no aplican**: Verifica que uses `className` con Tailwind válido  
+**File input no se ve bien**: Usa clases `file:*` para estilizar botón  
+**Invalid state no funciona**: Asegúrate de usar `aria-invalid` no solo `invalid`  
+**Height inconsistente**: Input tiene `h-9` default, usa `className` para override  
+**Dark mode no funciona**: Verifica tema configurado y clase `dark:` aplicándose  
+**Number input permite texto**: Navegador valida, pero usa validación JS adicional
+
+## Referencias Adicionales
+
+- **shadcn/ui Input**: <https://ui.shadcn.com/docs/components/input>
+- **MDN Input**: <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input>
+- **WAI-ARIA Input**: <https://www.w3.org/WAI/ARIA/apg/patterns/input/>