@adamosuiteservices/ui 1.2.4 → 1.3.5

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

@@ -0,0 +1,509 @@
+# Input Group Component
+
+Combina inputs/textareas con addons (texto, iconos, botones). Perfecto para campos con unidades, prefijos, acciones integradas o información contextual adicional.
+
+## Descripción
+
+El componente `InputGroup` combina inputs con prefijos, sufijos y addons.
+
+## Importación
+
+```typescript
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupText,
+  InputGroupInput,
+  InputGroupTextarea,
+} from "@adamosuiteservices/ui/input-group";
+```
+
+## Uso Básico
+
+```tsx
+<InputGroup>
+  <InputGroup.Addon>https://</InputGroup.Addon>
+  <Input placeholder="example.com" />
+</InputGroup>
+```
+
+## Con Icono
+
+```tsx
+<InputGroup>
+  <InputGroup.Icon>
+    <SearchIcon />
+  </InputGroup.Icon>
+  <Input placeholder="Search..." />
+</InputGroup>
+```
+
+## Con Botón
+
+```tsx
+<InputGroup>
+  <Input placeholder="Enter email" />
+  <InputGroup.Button>
+    <Button>Subscribe</Button>
+  </InputGroup.Button>
+</InputGroup>
+```
+
+**Componentes**: 6 (InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupInput, InputGroupTextarea)
+
+## Props Principales
+
+### InputGroup (Root)
+
+| Prop            | Tipo      | Descripción                           |
+| --------------- | --------- | ------------------------------------- |
+| `data-disabled` | `boolean` | Marca el grupo como disabled (visual) |
+| `className`     | `string`  | Clases CSS adicionales                |
+
+**Nota**: Acepta todas las props de `<div>`
+
+### InputGroupAddon
+
+| Prop        | Tipo                                                             | Default          | Descripción            |
+| ----------- | ---------------------------------------------------------------- | ---------------- | ---------------------- |
+| `align`     | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` | Posición del addon     |
+| `className` | `string`                                                         | -                | Clases CSS adicionales |
+
+**Positions**:
+
+- `inline-start`: Izquierda (horizontal)
+- `inline-end`: Derecha (horizontal)
+- `block-start`: Arriba (vertical)
+- `block-end`: Abajo (vertical)
+
+### InputGroupButton
+
+| Prop      | Tipo                                     | Default    | Descripción                              |
+| --------- | ---------------------------------------- | ---------- | ---------------------------------------- |
+| `size`    | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | `"xs"`     | Tamaño del botón                         |
+| `variant` | Button variants                          | `"ghost"`  | Variante del botón                       |
+| `type`    | `string`                                 | `"button"` | Tipo HTML del botón                      |
+| ...rest   | -                                        | -          | Todas las props de Button excepto `size` |
+
+**Sizes**:
+
+- `xs`: h-6, px-2
+- `sm`: h-8, px-2.5
+- `icon-xs`: size-6 (solo icono)
+- `icon-sm`: size-8 (solo icono)
+
+### InputGroupText
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Uso**: Wrapper para texto estático, iconos, labels, etc.
+
+### InputGroupInput
+
+| Prop        | Tipo     | Descripción                          |
+| ----------- | -------- | ------------------------------------ |
+| ...props    | -        | Todas las props nativas de `<input>` |
+| `className` | `string` | Clases CSS adicionales               |
+
+**Nota**: Estilos internos: sin border, sin shadow, bg-transparent
+
+### InputGroupTextarea
+
+| Prop        | Tipo     | Descripción                             |
+| ----------- | -------- | --------------------------------------- |
+| ...props    | -        | Todas las props nativas de `<textarea>` |
+| `className` | `string` | Clases CSS adicionales                  |
+
+**Nota**: Estilos internos: sin border, sin shadow, bg-transparent, resize-none, py-3
+
+## Patrones de Uso
+
+### Básico con Icono
+
+```tsx
+import { Search } from "lucide-react";
+
+<InputGroup>
+  <InputGroupInput placeholder="Search..." />
+  <InputGroupAddon>
+    <Search />
+  </InputGroupAddon>
+</InputGroup>;
+```
+
+### Con Texto (Precio)
+
+```tsx
+<InputGroup>
+  <InputGroupAddon>
+    <InputGroupText>$</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="0.00" type="number" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>USD</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Con Prefijo URL
+
+```tsx
+<InputGroup>
+  <InputGroupAddon>
+    <InputGroupText>https://</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="example.com" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>.com</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Con Email Domain
+
+```tsx
+<InputGroup>
+  <InputGroupInput placeholder="Enter your username" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>@company.com</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Con Botón Copy
+
+```tsx
+import { useState } from "react";
+import { Copy, Check } from "lucide-react";
+
+function App() {
+  const [isCopied, setIsCopied] = useState(false);
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText("https://x.com/shadcn");
+    setIsCopied(true);
+    setTimeout(() => setIsCopied(false), 2000);
+  };
+
+  return (
+    <InputGroup>
+      <InputGroupInput
+        placeholder="https://x.com/shadcn"
+        readOnly
+        defaultValue="https://x.com/shadcn"
+      />
+      <InputGroupAddon align="inline-end">
+        <InputGroupButton aria-label="Copy" size="icon-xs" onClick={handleCopy}>
+          {isCopied ? <Check /> : <Copy />}
+        </InputGroupButton>
+      </InputGroupAddon>
+    </InputGroup>
+  );
+}
+```
+
+### Con Botón Search
+
+```tsx
+<InputGroup>
+  <InputGroupInput placeholder="Type to search..." />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton variant="secondary">Search</InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Con Tooltip
+
+```tsx
+import { Info } from "lucide-react";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@adamosuiteservices/ui/tooltip";
+
+<InputGroup>
+  <InputGroupInput placeholder="Enter password" type="password" />
+  <InputGroupAddon align="inline-end">
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <InputGroupButton variant="ghost" size="icon-xs">
+          <Info />
+        </InputGroupButton>
+      </TooltipTrigger>
+      <TooltipContent>
+        <p>Password must be at least 8 characters</p>
+      </TooltipContent>
+    </Tooltip>
+  </InputGroupAddon>
+</InputGroup>;
+```
+
+### Password Toggle
+
+```tsx
+import { useState } from "react";
+import { Eye, EyeOff } from "lucide-react";
+import { Label } from "@adamosuiteservices/ui/label";
+
+function App() {
+  const [showPassword, setShowPassword] = useState(false);
+
+  return (
+    <div className="w-full max-w-sm">
+      <Label htmlFor="password">Password</Label>
+      <InputGroup className="mt-2">
+        <InputGroupInput
+          id="password"
+          type={showPassword ? "text" : "password"}
+          placeholder="Enter your password"
+        />
+        <InputGroupAddon align="inline-end">
+          <InputGroupButton
+            variant="ghost"
+            size="icon-xs"
+            onClick={() => setShowPassword(!showPassword)}
+            aria-label={showPassword ? "Hide password" : "Show password"}
+          >
+            {showPassword ? <EyeOff /> : <Eye />}
+          </InputGroupButton>
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  );
+}
+```
+
+### Con Spinner (Loading)
+
+```tsx
+import { Spinner } from "@adamosuiteservices/ui/spinner";
+
+<InputGroup data-disabled>
+  <InputGroupInput placeholder="Searching..." disabled />
+  <InputGroupAddon align="inline-end">
+    <Spinner />
+  </InputGroupAddon>
+</InputGroup>;
+```
+
+### Con Dropdown
+
+```tsx
+import { MoreHorizontal } from "lucide-react";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@adamosuiteservices/ui/dropdown-menu";
+
+<InputGroup>
+  <InputGroupInput placeholder="Enter file name" />
+  <InputGroupAddon align="inline-end">
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <InputGroupButton variant="ghost" size="icon-xs">
+          <MoreHorizontal />
+        </InputGroupButton>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end">
+        <DropdownMenuItem>Settings</DropdownMenuItem>
+        <DropdownMenuItem>Copy path</DropdownMenuItem>
+        <DropdownMenuItem>Open location</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  </InputGroupAddon>
+</InputGroup>;
+```
+
+### Con Textarea
+
+```tsx
+<InputGroup>
+  <InputGroupTextarea
+    placeholder="console.log('Hello, world!');"
+    className="min-h-[200px]"
+  />
+  <InputGroupAddon align="block-end" className="border-t">
+    <InputGroupText>Line 1, Column 1</InputGroupText>
+    <InputGroupButton size="sm" className="ml-auto" variant="default">
+      Run <Send />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Con Label (Block Start)
+
+```tsx
+import { Label } from "@adamosuiteservices/ui/label";
+import { Info } from "lucide-react";
+
+<InputGroup>
+  <InputGroupInput id="email" placeholder="shadcn@vercel.com" />
+  <InputGroupAddon align="block-start">
+    <Label htmlFor="email" className="text-foreground">
+      Email
+    </Label>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <InputGroupButton
+          variant="ghost"
+          className="ml-auto rounded-full"
+          size="icon-xs"
+        >
+          <Info />
+        </InputGroupButton>
+      </TooltipTrigger>
+      <TooltipContent>
+        <p>We'll use this to send you notifications</p>
+      </TooltipContent>
+    </Tooltip>
+  </InputGroupAddon>
+</InputGroup>;
+```
+
+### Chat Input Complex
+
+```tsx
+import { useState } from "react";
+import { Plus, Forward } from "lucide-react";
+import { Spinner } from "@adamosuiteservices/ui/spinner";
+
+function App() {
+  const [message, setMessage] = useState("");
+  const [isLoading, setIsLoading] = useState(false);
+
+  const handleSend = () => {
+    if (!message.trim()) return;
+    setIsLoading(true);
+    setTimeout(() => {
+      setMessage("");
+      setIsLoading(false);
+    }, 1000);
+  };
+
+  return (
+    <InputGroup>
+      <InputGroupTextarea
+        placeholder="Ask, Search or Chat..."
+        value={message}
+        onChange={(e) => setMessage(e.target.value)}
+        className="min-h-[60px]"
+      />
+      <InputGroupAddon align="block-end">
+        <InputGroupButton
+          variant="outline"
+          className="rounded-full"
+          size="icon-xs"
+        >
+          <Plus />
+        </InputGroupButton>
+
+        <InputGroupText className="ml-auto">
+          {message.length}/280
+        </InputGroupText>
+
+        <InputGroupButton
+          variant="default"
+          className="rounded-full"
+          size="icon-xs"
+          onClick={handleSend}
+          disabled={!message.trim() || isLoading}
+        >
+          {isLoading ? <Spinner /> : <Forward />}
+        </InputGroupButton>
+      </InputGroupAddon>
+    </InputGroup>
+  );
+}
+```
+
+## Casos de Uso Comunes
+
+**Price inputs**: Con $ prefix y USD suffix  
+**URL inputs**: Con https:// prefix y dominio suffix  
+**Email inputs**: Con @domain.com suffix  
+**Search bars**: Con icono search y resultados count  
+**Copy fields**: Con botón copy integrado  
+**Password fields**: Con toggle show/hide  
+**Chat inputs**: Con múltiples controles y contador  
+**Code editors**: Con textarea y toolbars en block-start/end
+
+## Estados y Data Attributes
+
+### InputGroup States
+
+- **Disabled**: `data-disabled` → `opacity-50` en addons
+- **Focus**: `has-[input:focus-visible]` → ring y border aplicados al grupo
+- **Invalid**: `has-[input[aria-invalid=true]]` → ring destructive y border
+
+### Focus Behavior
+
+El grupo aplica estilos focus cuando el input/textarea interno recibe focus, no el grupo en sí.
+
+### Click Behavior (Addon)
+
+Los addons hacen focus al input cuando se hace click en el addon (no en botones).
+
+## Interacción
+
+- ✅ **Click addon**: Focus automático en el input (excepto botones)
+- ✅ **Keyboard**: Navegación normal del input/textarea
+- ✅ **Disabled**: Visual `data-disabled`, input debe estar `disabled` también
+- ✅ **Auto-height**: Con textarea, el grupo ajusta altura automáticamente
+
+## Accesibilidad
+
+- ✅ **Role**: `role="group"` en InputGroup y InputGroupAddon
+- ✅ **Labels**: Usa Label dentro de InputGroupAddon o externo con `htmlFor`
+- ✅ **ARIA**: Input/textarea maneja `aria-invalid`, `aria-describedby`
+- ✅ **Focus**: Focus visible en el grupo cuando input interno tiene focus
+- ✅ **Keyboard**: Navegación nativa del input/textarea
+- ⚠️ **Buttons**: Usa `aria-label` en InputGroupButton para iconos
+
+## Notas de Implementación
+
+- **Container**: InputGroup es el wrapper con border, shadow, focus ring
+- **Input/Textarea**: Sin border, sin shadow, sin focus ring (aplicado al grupo)
+- **Auto-height**: Grupo tiene `has-[>textarea]:h-auto` para textareas
+- **Alignment**: CVA con 4 posiciones (inline-start, inline-end, block-start, block-end)
+- **Click delegation**: Addon hace focus al input al click (excepto en botones)
+- **Variants**: InputGroupButton usa CVA para 4 tamaños custom
+- **Order**: Addon usa `order-first` o `order-last` para posicionamiento
+- **Focus detection**: CSS `:has()` para aplicar focus ring al grupo
+- **Portal**: No usa portal, todo inline
+
+## Alineamiento Detallado
+
+### Inline (Horizontal)
+
+- **inline-start**: `pl-3`, botones con `ml-[-0.45rem]`, orden `order-first`
+- **inline-end**: `pr-3`, botones con `mr-[-0.45rem]`, orden `order-last`
+
+### Block (Vertical)
+
+- **block-start**: `w-full`, `px-3 pt-3`, `order-first`, borders con `border-b`
+- **block-end**: `w-full`, `px-3 pb-3`, `order-last`, borders con `border-t`
+
+## Troubleshooting
+
+**Addon no clickea al input**: Verifica que InputGroupAddon tenga el onClick handler (default)  
+**Focus ring no aparece**: El input interno debe tener `data-slot="input-group-control"`  
+**Textarea no ajusta altura**: Verifica que uses `InputGroupTextarea` no `InputGroupInput`  
+**Botón muy grande**: Usa `size="xs"` o `size="icon-xs"` en InputGroupButton  
+**Addon mal posicionado**: Verifica `align` prop (inline-start/end, block-start/end)  
+**Border doble**: InputGroupInput/Textarea tienen `border-0`, no uses Input/Textarea directamente  
+**Invalid state no funciona**: El input interno necesita `aria-invalid`, grupo detecta con `:has()`  
+**Disabled no funciona**: Aplica `disabled` al input Y `data-disabled` al InputGroup  
+**Spacing inconsistente**: Addon usa padding específico por align, no modifiques sin CVA
+
+## Referencias
+
+- **shadcn/ui Input**: <https://ui.shadcn.com/docs/components/input>
+- **Radix UI Label**: <https://www.radix-ui.com/primitives/docs/components/label>