@neynar/ui 0.2.1 → 0.3.0

package/src/components/ui/input-group.tsx

@@ -0,0 +1,801 @@
+"use client"
+
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Textarea } from "@/components/ui/textarea"
+
+/**
+ * Props for InputGroup component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+type InputGroupDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Child components (InputGroupInput, InputGroupTextarea, InputGroupAddon) */
+  children?: React.ReactNode;
+  /** Mark the entire input group as disabled with data-disabled="true" */
+  "data-disabled"?: "true" | "false";
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "children">;
+
+/**
+ * InputGroup - Container for inputs with integrated addons, buttons, and text
+ *
+ * A flexible container component that combines text inputs or textareas with decorative
+ * or functional elements like icons, buttons, labels, and keyboard shortcuts. Supports
+ * both inline (left/right) and block (top/bottom) addon positioning for diverse layout
+ * needs. Provides unified focus states, error handling, and disabled states across all
+ * child elements.
+ *
+ * @example
+ * ```tsx
+ * // Search input with icon and keyboard shortcut
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <Search className="size-4" />
+ *   </InputGroupAddon>
+ *   <InputGroupInput placeholder="Search..." />
+ *   <InputGroupAddon align="inline-end">
+ *     <Kbd>⌘K</Kbd>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Email subscription form with submit button
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <Mail className="size-4" />
+ *   </InputGroupAddon>
+ *   <InputGroupInput type="email" placeholder="Enter your email" />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupButton size="sm">Subscribe</InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Price input with currency indicators
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <DollarSign className="size-4" />
+ *   </InputGroupAddon>
+ *   <InputGroupInput type="number" placeholder="0.00" />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupText>USD</InputGroupText>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Comment textarea with block addons
+ * <InputGroup>
+ *   <InputGroupAddon align="block-start">
+ *     <InputGroupText>Your Comment</InputGroupText>
+ *   </InputGroupAddon>
+ *   <InputGroupTextarea placeholder="Write your comment..." rows={4} />
+ *   <InputGroupAddon align="block-end">
+ *     <InputGroupButton size="sm">
+ *       <Send className="size-4" />
+ *       Post
+ *     </InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Error state with aria-invalid
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <Mail className="size-4" />
+ *   </InputGroupAddon>
+ *   <InputGroupInput
+ *     type="email"
+ *     placeholder="Email"
+ *     aria-invalid="true"
+ *     defaultValue="invalid-email"
+ *   />
+ * </InputGroup>
+ * ```
+ *
+ * @accessibility
+ * - Container uses role="group" to associate related form elements
+ * - Focus states are unified across the input and all addons with visible ring
+ * - Error states automatically style container with destructive colors when aria-invalid="true"
+ * - Disabled state propagates to all children via data-disabled attribute
+ * - Click on addons automatically focuses the input for better UX
+ * - Keyboard navigation works naturally with native input focus behavior
+ *
+ * @see {@link InputGroupInput} Text input element within the group
+ * @see {@link InputGroupTextarea} Textarea element within the group
+ * @see {@link InputGroupAddon} Container for icons, text, buttons, or labels
+ * @see {@link InputGroupButton} Action button within an addon
+ * @see {@link InputGroupText} Static text or labels within an addon
+ * @since 1.0.0
+ */
+function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="input-group"
+      role="group"
+      className={cn(
+        "group/input-group border-input dark:bg-input/30 relative flex w-full items-center rounded-md border shadow-xs transition-[color,box-shadow] outline-none",
+        "h-9 min-w-0 has-[>textarea]:h-auto",
+
+        // Variants based on alignment.
+        "has-[>[data-align=inline-start]]:[&>input]:pl-2",
+        "has-[>[data-align=inline-end]]:[&>input]:pr-2",
+        "has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>[data-align=block-start]]:[&>input]:pb-3",
+        "has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-end]]:[&>input]:pt-3",
+
+        // Focus state.
+        "has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot=input-group-control]:focus-visible]:ring-[3px]",
+
+        // Error state.
+        "has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[[data-slot][aria-invalid=true]]:border-destructive dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40",
+
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+/**
+ * InputGroupAddon variant configuration for positioning addons around inputs
+ * @variant inline-start - Position addon to the left of the input (default)
+ * @variant inline-end - Position addon to the right of the input
+ * @variant block-start - Position addon above the input (full width)
+ * @variant block-end - Position addon below the input (full width)
+ */
+const inputGroupAddonVariants = cva(
+  "text-muted-foreground flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium select-none [&>svg:not([class*='size-'])]:size-4 [&>kbd]:rounded-[calc(var(--radius)-5px)] group-data-[disabled=true]/input-group:opacity-50",
+  {
+    variants: {
+      align: {
+        "inline-start":
+          "order-first pl-3 has-[>button]:ml-[-0.45rem] has-[>kbd]:ml-[-0.35rem]",
+        "inline-end":
+          "order-last pr-3 has-[>button]:mr-[-0.45rem] has-[>kbd]:mr-[-0.35rem]",
+        "block-start":
+          "order-first w-full justify-start px-3 pt-3 [.border-b]:pb-3 group-has-[>input]/input-group:pt-2.5",
+        "block-end":
+          "order-last w-full justify-start px-3 pb-3 [.border-t]:pt-3 group-has-[>input]/input-group:pb-2.5",
+      },
+    },
+    defaultVariants: {
+      align: "inline-start",
+    },
+  }
+)
+
+/**
+ * Props for InputGroupAddon component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CVA inferred types
+ */
+type InputGroupAddonDocsProps = {
+  /** Position of the addon relative to the input element @default "inline-start" */
+  align?: "inline-start" | "inline-end" | "block-start" | "block-end";
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Child content (InputGroupText, InputGroupButton, icons, Kbd, etc.) */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "children">;
+
+/**
+ * InputGroupAddon - Container for icons, buttons, text, or labels within an InputGroup
+ *
+ * A flexible addon container that can be positioned at any edge of the input (left, right,
+ * top, or bottom). Automatically adjusts layout and spacing based on alignment. Clicking
+ * the addon area focuses the associated input for improved usability. Supports icons,
+ * static text, buttons, keyboard shortcuts (Kbd), and custom content.
+ *
+ * @example
+ * ```tsx
+ * // Icon addon on the left (inline-start)
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <Search className="size-4" />
+ *   </InputGroupAddon>
+ *   <InputGroupInput placeholder="Search..." />
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Text suffix on the right (inline-end)
+ * <InputGroup>
+ *   <InputGroupInput placeholder="Enter amount" />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupText>USD</InputGroupText>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Button addon for action
+ * <InputGroup>
+ *   <InputGroupInput placeholder="Enter coupon code" />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupButton size="sm">Apply</InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Keyboard shortcut indicator
+ * <InputGroup>
+ *   <InputGroupInput placeholder="Quick search" />
+ *   <InputGroupAddon align="inline-end">
+ *     <Kbd>⌘K</Kbd>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Block addon with multiple elements (top position)
+ * <InputGroup>
+ *   <InputGroupAddon align="block-start">
+ *     <InputGroupText>Message</InputGroupText>
+ *     <InputGroupButton size="icon-xs">
+ *       <X className="size-4" />
+ *     </InputGroupButton>
+ *   </InputGroupAddon>
+ *   <InputGroupTextarea placeholder="Type your message..." />
+ * </InputGroup>
+ * ```
+ *
+ * @accessibility
+ * - Uses role="group" to semantically group addon content
+ * - Clicking addon focuses the input (unless clicking a button)
+ * - Icons automatically sized with [&>svg:not([class*='size-'])]:size-4
+ * - Respects disabled state from parent InputGroup
+ * - Keyboard shortcuts (Kbd) properly styled and positioned
+ *
+ * @see {@link InputGroupText} For static text within the addon
+ * @see {@link InputGroupButton} For action buttons within the addon
+ * @since 1.0.0
+ */
+function InputGroupAddon({
+  className,
+  align = "inline-start",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="input-group-addon"
+      data-align={align}
+      className={cn(inputGroupAddonVariants({ align }), className)}
+      onClick={(e) => {
+        if ((e.target as HTMLElement).closest("button")) {
+          return
+        }
+        e.currentTarget.parentElement?.querySelector("input")?.focus()
+      }}
+      {...props}
+    />
+  )
+}
+
+/**
+ * InputGroupButton variant configuration for sizing buttons within addons
+ * @variant xs - Extra small button height (24px) for compact inline addons (default)
+ * @variant sm - Small button height (32px) for standard inline or block addons
+ * @variant icon-xs - Extra small icon-only button (24x24px) for compact addons
+ * @variant icon-sm - Small icon-only button (32x32px) for standard addons
+ */
+const inputGroupButtonVariants = cva(
+  "text-sm shadow-none flex gap-2 items-center",
+  {
+    variants: {
+      size: {
+        xs: "h-6 gap-1 px-2 rounded-[calc(var(--radius)-5px)] [&>svg:not([class*='size-'])]:size-3.5 has-[>svg]:px-2",
+        sm: "h-8 px-2.5 gap-1.5 rounded-md has-[>svg]:px-2.5",
+        "icon-xs":
+          "size-6 rounded-[calc(var(--radius)-5px)] p-0 has-[>svg]:p-0",
+        "icon-sm": "size-8 p-0 has-[>svg]:p-0",
+      },
+    },
+    defaultVariants: {
+      size: "xs",
+    },
+  }
+)
+
+/**
+ * Props for InputGroupButton component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CVA inferred types
+ */
+type InputGroupButtonDocsProps = {
+  /** Button size variant optimized for input group layout @default "xs" */
+  size?: "xs" | "sm" | "icon-xs" | "icon-sm";
+  /** Button variant from Button component @default "ghost" */
+  variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link";
+  /** Button type attribute @default "button" */
+  type?: "button" | "submit" | "reset";
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Button content (text, icons, or both) */
+  children?: React.ReactNode;
+  /** Click handler for the button action */
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
+  /** Whether the button is disabled */
+  disabled?: boolean;
+} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "size">;
+
+/**
+ * InputGroupButton - Action button within an InputGroupAddon
+ *
+ * A specialized button component optimized for use within input group addons. Styled with
+ * reduced shadows and compact sizing to integrate seamlessly with the input group container.
+ * Supports text buttons, icon buttons, and combination buttons with various size options.
+ * Uses ghost variant by default for subtle integration with the input group.
+ *
+ * @example
+ * ```tsx
+ * // Text button for action
+ * <InputGroup>
+ *   <InputGroupInput placeholder="Enter coupon code" />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupButton size="sm">Apply</InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Icon-only button for compact actions
+ * <InputGroup>
+ *   <InputGroupInput readOnly value="API Key: sk_live_123..." />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupButton size="icon-xs">
+ *       <Copy className="size-4" />
+ *     </InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Button with icon and text
+ * <InputGroup>
+ *   <InputGroupInput type="email" placeholder="Enter email" />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupButton size="sm">
+ *       <Send className="size-4" />
+ *       Subscribe
+ *     </InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Submit button in block addon
+ * <InputGroup>
+ *   <InputGroupTextarea placeholder="Write your message..." />
+ *   <InputGroupAddon align="block-end">
+ *     <InputGroupButton size="sm" variant="default" type="submit">
+ *       Post Comment
+ *     </InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple buttons with different variants
+ * <InputGroup>
+ *   <InputGroupTextarea placeholder="Compose..." />
+ *   <InputGroupAddon align="block-end">
+ *     <InputGroupButton size="sm" variant="outline">Cancel</InputGroupButton>
+ *     <InputGroupButton size="sm" variant="default">Send</InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @accessibility
+ * - Inherits all Button accessibility features
+ * - Default type="button" prevents accidental form submission
+ * - Keyboard accessible with Enter and Space activation
+ * - Focus visible with proper focus ring styling
+ * - Disabled state properly communicated to assistive technologies
+ *
+ * @see {@link Button} Base button component with full variant options
+ * @see {@link InputGroupAddon} Container for this button
+ * @since 1.0.0
+ */
+function InputGroupButton({
+  className,
+  type = "button",
+  variant = "ghost",
+  size = "xs",
+  ...props
+}: Omit<React.ComponentProps<typeof Button>, "size"> &
+  VariantProps<typeof inputGroupButtonVariants>) {
+  return (
+    <Button
+      type={type}
+      data-size={size}
+      variant={variant}
+      className={cn(inputGroupButtonVariants({ size }), className)}
+      {...props}
+    />
+  )
+}
+
+/**
+ * Props for InputGroupText component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+type InputGroupTextDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Text content, icons, or other inline elements */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLSpanElement>;
+
+/**
+ * InputGroupText - Static text or label content within an InputGroupAddon
+ *
+ * A span element for displaying non-interactive text, labels, prefixes, suffixes, or icons
+ * within an input group addon. Styled with muted foreground colors and optimized spacing.
+ * Commonly used for currency symbols, units of measurement, URL protocols, or descriptive labels.
+ *
+ * @example
+ * ```tsx
+ * // Currency symbol prefix
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <DollarSign className="size-4" />
+ *   </InputGroupAddon>
+ *   <InputGroupInput type="number" placeholder="0.00" />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupText>USD</InputGroupText>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // URL protocol prefix
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <InputGroupText>https://</InputGroupText>
+ *   </InputGroupAddon>
+ *   <InputGroupInput placeholder="example.com" />
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Label for textarea
+ * <InputGroup>
+ *   <InputGroupAddon align="block-start">
+ *     <InputGroupText>Message</InputGroupText>
+ *   </InputGroupAddon>
+ *   <InputGroupTextarea placeholder="Type your message..." />
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Character counter
+ * <InputGroup>
+ *   <InputGroupTextarea placeholder="Comment..." />
+ *   <InputGroupAddon align="block-end">
+ *     <InputGroupText className="text-xs">250 characters</InputGroupText>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @accessibility
+ * - Non-interactive element that provides context to the input
+ * - Icons within are marked as pointer-events-none
+ * - Muted color indicates non-interactive nature
+ * - Can be used with aria-label on parent input for better screen reader support
+ *
+ * @see {@link InputGroupAddon} Container for this text element
+ * @since 1.0.0
+ */
+function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      className={cn(
+        "text-muted-foreground flex items-center gap-2 text-sm [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+/**
+ * Props for InputGroupInput component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+type InputGroupInputDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Input placeholder text */
+  placeholder?: string;
+  /** Input type (text, email, number, password, etc.) @default "text" */
+  type?: React.HTMLInputTypeAttribute;
+  /** Input value (controlled component) */
+  value?: string | number;
+  /** Default value (uncontrolled component) */
+  defaultValue?: string | number;
+  /** Change handler for controlled inputs */
+  onChange?: React.ChangeEventHandler<HTMLInputElement>;
+  /** Whether the input is disabled */
+  disabled?: boolean;
+  /** Whether the input is read-only */
+  readOnly?: boolean;
+  /** Marks the input as invalid for error state styling */
+  "aria-invalid"?: boolean | "true" | "false";
+  /** Name attribute for form submission */
+  name?: string;
+  /** ID for label association */
+  id?: string;
+  /** Whether the field is required */
+  required?: boolean;
+} & Omit<React.InputHTMLAttributes<HTMLInputElement>, "type">;
+
+/**
+ * InputGroupInput - Text input element within an InputGroup
+ *
+ * A styled input component designed to work seamlessly within an InputGroup container.
+ * Inherits all standard HTML input props and removes default borders, shadows, and focus
+ * rings since the parent InputGroup handles visual states. Automatically flexes to fill
+ * available space between addons.
+ *
+ * @example
+ * ```tsx
+ * // Basic text input with icon
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <Search className="size-4" />
+ *   </InputGroupAddon>
+ *   <InputGroupInput placeholder="Search..." />
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Email input with validation
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <Mail className="size-4" />
+ *   </InputGroupAddon>
+ *   <InputGroupInput
+ *     type="email"
+ *     placeholder="you@example.com"
+ *     required
+ *     aria-invalid={!isValid}
+ *   />
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled number input
+ * const [amount, setAmount] = useState("");
+ * <InputGroup>
+ *   <InputGroupAddon align="inline-start">
+ *     <DollarSign className="size-4" />
+ *   </InputGroupAddon>
+ *   <InputGroupInput
+ *     type="number"
+ *     placeholder="0.00"
+ *     value={amount}
+ *     onChange={(e) => setAmount(e.target.value)}
+ *   />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupText>USD</InputGroupText>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Read-only input for displaying values
+ * <InputGroup>
+ *   <InputGroupInput
+ *     readOnly
+ *     value="API Key: sk_live_123456789"
+ *   />
+ *   <InputGroupAddon align="inline-end">
+ *     <InputGroupButton size="icon-xs">
+ *       <Copy className="size-4" />
+ *     </InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @accessibility
+ * - Inherits all native HTML input accessibility features
+ * - Focus management handled by parent InputGroup with visible focus ring
+ * - Error states indicated via aria-invalid attribute
+ * - Properly associates with labels using id and htmlFor
+ * - Keyboard accessible with standard input navigation
+ * - Supports all ARIA attributes for enhanced accessibility
+ *
+ * @see {@link Input} Base input component
+ * @see {@link InputGroup} Parent container component
+ * @since 1.0.0
+ */
+function InputGroupInput({
+  className,
+  ...props
+}: React.ComponentProps<"input">) {
+  return (
+    <Input
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 rounded-none border-0 bg-transparent shadow-none focus-visible:ring-0 dark:bg-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+/**
+ * Props for InputGroupTextarea component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+type InputGroupTextareaDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Textarea placeholder text */
+  placeholder?: string;
+  /** Number of visible text rows @default 3 */
+  rows?: number;
+  /** Textarea value (controlled component) */
+  value?: string;
+  /** Default value (uncontrolled component) */
+  defaultValue?: string;
+  /** Change handler for controlled textareas */
+  onChange?: React.ChangeEventHandler<HTMLTextAreaElement>;
+  /** Whether the textarea is disabled */
+  disabled?: boolean;
+  /** Whether the textarea is read-only */
+  readOnly?: boolean;
+  /** Marks the textarea as invalid for error state styling */
+  "aria-invalid"?: boolean | "true" | "false";
+  /** Name attribute for form submission */
+  name?: string;
+  /** ID for label association */
+  id?: string;
+  /** Whether the field is required */
+  required?: boolean;
+  /** Maximum character length */
+  maxLength?: number;
+} & React.TextareaHTMLAttributes<HTMLTextAreaElement>;
+
+/**
+ * InputGroupTextarea - Multi-line textarea element within an InputGroup
+ *
+ * A styled textarea component designed to work with InputGroup, especially with block-aligned
+ * addons (top/bottom positioning). Removes default borders and shadows as the parent InputGroup
+ * handles visual states. Resizing is disabled by default to maintain consistent layout with
+ * the container. Automatically flexes to fill available space.
+ *
+ * @example
+ * ```tsx
+ * // Basic textarea with label addon
+ * <InputGroup>
+ *   <InputGroupAddon align="block-start">
+ *     <InputGroupText>Message</InputGroupText>
+ *   </InputGroupAddon>
+ *   <InputGroupTextarea placeholder="Type your message here..." />
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Textarea with submit button below
+ * <InputGroup>
+ *   <InputGroupTextarea placeholder="Write your comment..." rows={4} />
+ *   <InputGroupAddon align="block-end">
+ *     <InputGroupButton size="sm">
+ *       <Send className="size-4" />
+ *       Post
+ *     </InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complete comment form with top and bottom addons
+ * <InputGroup>
+ *   <InputGroupAddon align="block-start">
+ *     <InputGroupText>Your Comment</InputGroupText>
+ *     <InputGroupButton size="icon-xs">
+ *       <X className="size-4" />
+ *     </InputGroupButton>
+ *   </InputGroupAddon>
+ *   <InputGroupTextarea placeholder="Add a comment..." rows={3} />
+ *   <InputGroupAddon align="block-end">
+ *     <InputGroupButton size="sm" variant="default">
+ *       Post Comment
+ *     </InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Textarea with character counter
+ * const [message, setMessage] = useState("");
+ * <InputGroup>
+ *   <InputGroupTextarea
+ *     placeholder="Compose your message..."
+ *     value={message}
+ *     onChange={(e) => setMessage(e.target.value)}
+ *     rows={5}
+ *   />
+ *   <InputGroupAddon align="block-end">
+ *     <InputGroupText className="text-xs">
+ *       {message.length} characters
+ *     </InputGroupText>
+ *     <InputGroupButton size="sm">Send</InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @accessibility
+ * - Inherits all native HTML textarea accessibility features
+ * - Focus management handled by parent InputGroup with visible focus ring
+ * - Error states indicated via aria-invalid attribute
+ * - Properly associates with labels using id and htmlFor
+ * - Keyboard accessible with standard textarea navigation
+ * - Supports all ARIA attributes including aria-describedby for character limits
+ *
+ * @see {@link Textarea} Base textarea component
+ * @see {@link InputGroup} Parent container component
+ * @see {@link InputGroupAddon} Use with align="block-start" or "block-end" for best layout
+ * @since 1.0.0
+ */
+function InputGroupTextarea({
+  className,
+  ...props
+}: React.ComponentProps<"textarea">) {
+  return (
+    <Textarea
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 resize-none rounded-none border-0 bg-transparent py-3 shadow-none focus-visible:ring-0 dark:bg-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupText,
+  InputGroupInput,
+  InputGroupTextarea,
+  type InputGroupDocsProps,
+  type InputGroupAddonDocsProps,
+  type InputGroupButtonDocsProps,
+  type InputGroupTextDocsProps,
+  type InputGroupInputDocsProps,
+  type InputGroupTextareaDocsProps,
+}