@neynar/ui 1.0.0 → 1.0.2

package/llm/components/input-group.llm.md

@@ -0,0 +1,334 @@
+# InputGroup
+
+Compound component for adding icons, text, buttons, or keyboard shortcuts to inputs and textareas.
+
+## Import
+
+```tsx
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+  InputGroupText,
+  InputGroupTextarea,
+} from "@neynar/ui/input-group"
+```
+
+## Anatomy
+
+```tsx
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <SearchIcon />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Search..." />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="icon-xs">
+      <XIcon />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| InputGroup | Root container that manages unified border, focus ring, and validation states |
+| InputGroupInput | Input element without its own border/ring (integrated with group) |
+| InputGroupTextarea | Textarea element without its own border/ring (integrated with group) |
+| InputGroupAddon | Container for addon content (icons, text, buttons) at start/end |
+| InputGroupButton | Button sized for use within addons |
+| InputGroupText | Text label/prefix/suffix for addons (e.g., "https://", "USD") |
+
+## Props
+
+### InputGroup
+
+Root container. Extends standard `<div>` props.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+| data-disabled | boolean | - | Disables addon opacity when set to "true" |
+
+### InputGroupAddon
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| align | "inline-start" \| "inline-end" \| "block-start" \| "block-end" | "inline-start" | Position of addon relative to input |
+| className | string | - | Additional CSS classes |
+
+Clicking the addon automatically focuses the input (unless clicking a button inside).
+
+### InputGroupButton
+
+Extends Button component props with custom sizes.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| size | "xs" \| "sm" \| "icon-xs" \| "icon-sm" | "xs" | Button size optimized for input groups |
+| variant | ButtonVariant | "ghost" | Button visual style |
+| type | "button" \| "submit" \| "reset" | "button" | HTML button type |
+| className | string | - | Additional CSS classes |
+
+### InputGroupText
+
+Extends standard `<span>` props. Use for text prefixes/suffixes like "https://", "@", "/", "USD", "MB".
+
+### InputGroupInput
+
+Extends standard `<input>` props. Inherits all Input component functionality but without its own border/focus ring.
+
+### InputGroupTextarea
+
+Extends standard `<textarea>` props. Inherits all Textarea component functionality but without its own border/focus ring.
+
+## Alignment Options
+
+| Align | Position | Use Case |
+|-------|----------|----------|
+| inline-start | Left side (horizontal) | Icons, text prefixes, leading buttons |
+| inline-end | Right side (horizontal) | Icons, text suffixes, action buttons |
+| block-start | Top (vertical) | Labels above input |
+| block-end | Bottom (vertical) | Help text or actions below input |
+
+## Button Sizes
+
+| Size | Dimensions | Use Case |
+|------|------------|----------|
+| xs | h-6 (24px) | Text buttons with labels |
+| sm | Standard height | Larger text buttons |
+| icon-xs | 24x24px | Small icon-only buttons |
+| icon-sm | 32x32px | Medium icon-only buttons |
+
+## Data Attributes
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-slot="input-group" | On root container |
+| data-slot="input-group-addon" | On addon containers |
+| data-slot="input-group-control" | On input/textarea |
+| data-align | Shows alignment value on addons |
+| data-disabled="true" | When group is disabled (reduces addon opacity) |
+| aria-invalid="true" | When input is invalid (shows destructive ring) |
+
+## Examples
+
+### Icon Addons
+
+```tsx
+// Icon at start
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <SearchIcon />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Search..." />
+</InputGroup>
+
+// Icon at end
+<InputGroup>
+  <InputGroupInput placeholder="Select date..." />
+  <InputGroupAddon align="inline-end">
+    <CalendarIcon />
+  </InputGroupAddon>
+</InputGroup>
+
+// Both sides
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <SearchIcon />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Search..." />
+  <InputGroupAddon align="inline-end">
+    <XIcon />
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Text Addons
+
+```tsx
+// URL prefix
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <InputGroupText>https://</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="example.com" />
+</InputGroup>
+
+// Currency suffix
+<InputGroup>
+  <InputGroupInput type="number" placeholder="0.00" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>USD</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+
+// Username format
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <InputGroupText>@</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="username" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>.eth</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Button Addons
+
+```tsx
+// Clear button
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <SearchIcon />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Search..." value={query} />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="icon-xs" aria-label="Clear" onClick={handleClear}>
+      <XIcon />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+
+// Copy button
+<InputGroup>
+  <InputGroupInput value="neynar_sk_prod_abc123" readOnly className="font-mono text-sm" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="icon-xs" aria-label="Copy" onClick={handleCopy}>
+      {copied ? <CheckIcon /> : <CopyIcon />}
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+
+// Action button with text
+<InputGroup>
+  <InputGroupInput placeholder="Enter email..." />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="xs">Send</InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Multiple Buttons
+
+```tsx
+// Password with visibility toggle and copy
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <LockIcon />
+  </InputGroupAddon>
+  <InputGroupInput type={showPassword ? "text" : "password"} placeholder="••••••••" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="icon-xs" aria-label="Toggle visibility" onClick={toggleVisibility}>
+      {showPassword ? <EyeOffIcon /> : <EyeIcon />}
+    </InputGroupButton>
+    <InputGroupButton size="icon-xs" aria-label="Copy" onClick={handleCopy}>
+      <CopyIcon />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Complex Combinations
+
+```tsx
+// API endpoint builder with multiple addons
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <InputGroupText>https://api.neynar.com/</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="v2/cast/conversation" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="xs" variant="outline">
+      Test
+    </InputGroupButton>
+    <InputGroupButton size="icon-xs" aria-label="Copy">
+      <CopyIcon />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### States
+
+```tsx
+// Disabled
+<InputGroup data-disabled="true">
+  <InputGroupAddon align="inline-start">
+    <SearchIcon />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Disabled..." disabled />
+</InputGroup>
+
+// Invalid/Error
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <SearchIcon />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Invalid input" aria-invalid="true" />
+</InputGroup>
+
+// Loading
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <Loader2Icon className="animate-spin" />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Loading..." />
+</InputGroup>
+
+// Read-only
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <LockIcon />
+  </InputGroupAddon>
+  <InputGroupInput value="neynar_sk_readonly" readOnly className="font-mono text-sm" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="icon-xs" aria-label="Copy">
+      <CopyIcon />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus to/from input |
+| Click addon | Focus input (unless clicking button) |
+
+Input and button keyboard interactions follow standard HTML behavior.
+
+## Accessibility
+
+- InputGroup uses `role="group"` for semantic grouping
+- Clicking addon automatically focuses input for better UX
+- Icon-only buttons require `aria-label` for screen readers
+- Invalid state shows destructive border/ring when `aria-invalid="true"` is set
+- Disabled state reduces addon opacity and disables interactive elements
+- Focus ring appears on the entire group container, not individual inputs
+
+## Styling Notes
+
+### Icon Auto-Sizing
+
+Icons within addons are automatically sized to 16px (`size-4`) unless a custom size class is applied.
+
+### Focus Management
+
+The InputGroup container manages the focus ring. Individual inputs/textareas have their borders and rings removed to integrate seamlessly.
+
+### Validation States
+
+Set `aria-invalid="true"` on InputGroupInput to show destructive border and ring on the entire group.
+
+## Related
+
+- **Input** - Standalone input without addons
+- **Textarea** - Standalone textarea
+- **Field** - Wrap InputGroup with label and description
+- **Button** - Used within InputGroupButton

package/llm/components/input-otp.llm.md

@@ -0,0 +1,270 @@
+# InputOTP
+
+One-time password input with individual character slots for verification codes, 2FA, and authentication flows.
+
+## Import
+
+```tsx
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSlot,
+  InputOTPSeparator,
+} from "@neynar/ui/input-otp"
+```
+
+## Anatomy
+
+```tsx
+<InputOTP maxLength={6} value={code} onChange={setCode}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    <InputOTPSlot index={3} />
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+  </InputOTPGroup>
+</InputOTP>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| InputOTP | Root container managing OTP input state and behavior |
+| InputOTPGroup | Groups multiple slots together, supports error styling |
+| InputOTPSlot | Individual character slot displaying current value |
+| InputOTPSeparator | Visual separator between groups (minus icon) |
+
+## Props
+
+### InputOTP
+
+Built on the `input-otp` library. Accepts all standard input props plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| maxLength | number | - | Number of character slots (required) |
+| value | string | - | Controlled value state |
+| onChange | (value: string) => void | - | Called when value changes |
+| pattern | string | - | Regex pattern to validate input (e.g., `^[0-9]+$`) |
+| disabled | boolean | false | Disabled state |
+| autoFocus | boolean | false | Auto-focus on mount |
+| containerClassName | string | - | Additional classes for container |
+| onComplete | () => void | - | Called when all slots are filled |
+| inputMode | string | 'numeric' | Virtual keyboard type on mobile |
+| pasteTransformer | (text: string) => string | - | Transform pasted text before applying |
+
+### InputOTPGroup
+
+Container for grouping slots. Set `aria-invalid={true}` to show error state.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| aria-invalid | boolean | - | Shows error styling when true |
+| className | string | - | Additional classes |
+
+### InputOTPSlot
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| index | number | - | Zero-based slot position (required) |
+| className | string | - | Additional classes |
+
+Automatically displays character from context, active state, and animated caret.
+
+### InputOTPSeparator
+
+Visual separator with minus icon. Standard div props accepted.
+
+## Data Attributes
+
+### InputOTP
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-slot | Always "input-otp" |
+
+### InputOTPSlot
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-slot | Always "input-otp-slot" |
+| data-active | Slot is currently focused |
+
+## Examples
+
+### Basic 6-Digit Code
+
+```tsx
+import { useState } from "react"
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSlot,
+  InputOTPSeparator,
+} from "@neynar/ui/input-otp"
+
+function TwoFactorAuth() {
+  const [code, setCode] = useState("")
+
+  return (
+    <InputOTP maxLength={6} value={code} onChange={setCode}>
+      <InputOTPGroup>
+        <InputOTPSlot index={0} />
+        <InputOTPSlot index={1} />
+        <InputOTPSlot index={2} />
+      </InputOTPGroup>
+      <InputOTPSeparator />
+      <InputOTPGroup>
+        <InputOTPSlot index={3} />
+        <InputOTPSlot index={4} />
+        <InputOTPSlot index={5} />
+      </InputOTPGroup>
+    </InputOTP>
+  )
+}
+```
+
+### Email Verification with Error State
+
+```tsx
+import { useState } from "react"
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSlot,
+  InputOTPSeparator,
+} from "@neynar/ui/input-otp"
+import { Label } from "@neynar/ui/label"
+import { Button } from "@neynar/ui/button"
+
+function EmailVerification() {
+  const [code, setCode] = useState("")
+  const [error, setError] = useState(false)
+
+  const handleVerify = () => {
+    if (code !== "123456") {
+      setError(true)
+    }
+  }
+
+  return (
+    <div className="space-y-3">
+      <Label htmlFor="email-code">
+        Enter the code sent to your email
+      </Label>
+      <InputOTP
+        id="email-code"
+        maxLength={6}
+        value={code}
+        onChange={setCode}
+        pattern="^[0-9]+$"
+      >
+        <InputOTPGroup aria-invalid={error}>
+          <InputOTPSlot index={0} />
+          <InputOTPSlot index={1} />
+          <InputOTPSlot index={2} />
+        </InputOTPGroup>
+        <InputOTPSeparator />
+        <InputOTPGroup aria-invalid={error}>
+          <InputOTPSlot index={3} />
+          <InputOTPSlot index={4} />
+          <InputOTPSlot index={5} />
+        </InputOTPGroup>
+      </InputOTP>
+      {error && (
+        <p className="text-destructive text-sm">
+          Invalid code. Please try again.
+        </p>
+      )}
+      <Button onClick={handleVerify} disabled={code.length !== 6}>
+        Verify
+      </Button>
+    </div>
+  )
+}
+```
+
+### 4-Digit PIN
+
+```tsx
+<InputOTP maxLength={4}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+    <InputOTPSlot index={3} />
+  </InputOTPGroup>
+</InputOTP>
+```
+
+### 8-Digit Backup Code
+
+```tsx
+<InputOTP maxLength={8}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+    <InputOTPSlot index={3} />
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+    <InputOTPSlot index={6} />
+    <InputOTPSlot index={7} />
+  </InputOTPGroup>
+</InputOTP>
+```
+
+### With Paste Transformer
+
+```tsx
+<InputOTP
+  maxLength={6}
+  pattern="^[0-9]+$"
+  pasteTransformer={(text) => text.replaceAll("-", "")}
+>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+    <InputOTPSlot index={3} />
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+  </InputOTPGroup>
+</InputOTP>
+```
+
+Now users can paste "123-456" and it becomes "123456".
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| 0-9, A-Z | Enter character (if allowed by pattern) |
+| Backspace | Delete previous character |
+| Delete | Clear current slot |
+| ArrowLeft | Move to previous slot |
+| ArrowRight | Move to next slot |
+| Cmd/Ctrl+V | Paste full code (transformed if pasteTransformer provided) |
+
+## Accessibility
+
+- Uses native input element for proper screen reader support
+- Announces current slot and total slots to assistive technology
+- Focus management handles keyboard navigation between slots
+- Supports autocomplete="one-time-code" for iOS/Android SMS autofill
+- Error state communicated via aria-invalid on groups
+
+## Related
+
+- [Label](./label.llm.md) - Form labels
+- [Button](./button.llm.md) - Verification actions
+- [Form](./form.llm.md) - Form integration