@neynar/ui 1.0.0 → 1.0.2

package/llm/components/tabs.llm.md

@@ -0,0 +1,245 @@
+# Tabs
+
+Organize content into multiple panels with tab navigation, supporting both horizontal and vertical layouts.
+
+## Import
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "@neynar/ui/tabs"
+```
+
+## Anatomy
+
+```tsx
+<Tabs defaultValue="tab1">
+  <TabsList>
+    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">Content 1</TabsContent>
+  <TabsContent value="tab2">Content 2</TabsContent>
+</Tabs>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Tabs | Root container, manages active tab state and orientation |
+| TabsList | Groups tab triggers, controls visual variant |
+| TabsTrigger | Individual tab button with value identifier |
+| TabsContent | Content panel shown when corresponding tab is active |
+
+## Props
+
+### Tabs
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| defaultValue | string \| number \| null | `0` | Initial active tab (uncontrolled) |
+| value | string \| number \| null | - | Controlled active tab value |
+| onValueChange | (value, eventDetails) => void | - | Called when active tab changes |
+| orientation | "horizontal" \| "vertical" | "horizontal" | Layout direction |
+
+When `value` is `null`, no tab will be active.
+
+### TabsList
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | "default" \| "line" | "default" | Visual style of tab list |
+| activateOnFocus | boolean | - | Auto-activate tab on arrow key focus |
+| loopFocus | boolean | - | Loop keyboard focus at list ends |
+
+**Variants:**
+- `default` - Tabs with muted background and active highlight
+- `line` - Minimal tabs with underline indicator on active tab
+
+### TabsTrigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | string \| number | - | Identifier matching TabsContent value |
+| disabled | boolean | - | Prevents tab activation |
+
+Supports nested icons and badges as children.
+
+### TabsContent
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | string \| number | - | Identifier matching TabsTrigger value |
+| keepMounted | boolean | false | Keep DOM element when hidden |
+
+## Data Attributes
+
+### Tabs, TabsList
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-orientation | "horizontal" or "vertical" |
+| data-activation-direction | "left", "right", "up", "down", or "none" |
+
+### TabsTrigger
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-active | Tab is currently active |
+| data-disabled | Tab is disabled |
+
+### TabsContent
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-hidden | Panel is not active |
+| data-index | Panel index number |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">
+    Manage your account settings.
+  </TabsContent>
+  <TabsContent value="password">
+    Change your password here.
+  </TabsContent>
+</Tabs>
+```
+
+### Controlled State
+
+```tsx
+function ControlledTabs() {
+  const [activeTab, setActiveTab] = useState("webhooks")
+
+  return (
+    <Tabs value={activeTab} onValueChange={setActiveTab}>
+      <TabsList>
+        <TabsTrigger value="webhooks">Webhooks</TabsTrigger>
+        <TabsTrigger value="keys">API Keys</TabsTrigger>
+        <TabsTrigger value="logs">Logs</TabsTrigger>
+      </TabsList>
+      <TabsContent value="webhooks">...</TabsContent>
+      <TabsContent value="keys">...</TabsContent>
+      <TabsContent value="logs">...</TabsContent>
+    </Tabs>
+  )
+}
+```
+
+### With Icons and Badges
+
+```tsx
+<Tabs defaultValue="inbox">
+  <TabsList variant="line">
+    <TabsTrigger value="inbox">
+      <MailIcon />
+      Inbox
+      <Badge variant="default" className="ml-1.5">12</Badge>
+    </TabsTrigger>
+    <TabsTrigger value="drafts">
+      <FileTextIcon />
+      Drafts
+      <Badge variant="secondary" className="ml-1.5">3</Badge>
+    </TabsTrigger>
+    <TabsTrigger value="sent">
+      <SendIcon />
+      Sent
+    </TabsTrigger>
+  </TabsList>
+  <TabsContent value="inbox">12 unread messages</TabsContent>
+  <TabsContent value="drafts">3 draft messages</TabsContent>
+  <TabsContent value="sent">Sent messages</TabsContent>
+</Tabs>
+```
+
+### Line Variant
+
+```tsx
+<Tabs defaultValue="all">
+  <TabsList variant="line">
+    <TabsTrigger value="all">All</TabsTrigger>
+    <TabsTrigger value="active">Active</TabsTrigger>
+    <TabsTrigger value="completed">Completed</TabsTrigger>
+  </TabsList>
+  <TabsContent value="all">All items</TabsContent>
+  <TabsContent value="active">Active items</TabsContent>
+  <TabsContent value="completed">Completed items</TabsContent>
+</Tabs>
+```
+
+### Vertical Orientation
+
+```tsx
+<Tabs defaultValue="profile" orientation="vertical" className="w-[600px]">
+  <TabsList>
+    <TabsTrigger value="profile">
+      <UserIcon />
+      Profile
+    </TabsTrigger>
+    <TabsTrigger value="account">
+      <KeyIcon />
+      Account
+    </TabsTrigger>
+    <TabsTrigger value="notifications">
+      <BellIcon />
+      Notifications
+    </TabsTrigger>
+  </TabsList>
+  <TabsContent value="profile">Profile settings</TabsContent>
+  <TabsContent value="account">Account security</TabsContent>
+  <TabsContent value="notifications">Notification preferences</TabsContent>
+</Tabs>
+```
+
+### Disabled Tabs
+
+```tsx
+<Tabs defaultValue="general">
+  <TabsList>
+    <TabsTrigger value="general">General</TabsTrigger>
+    <TabsTrigger value="privacy">Privacy</TabsTrigger>
+    <TabsTrigger value="billing" disabled>
+      Billing
+    </TabsTrigger>
+    <TabsTrigger value="team" disabled>
+      Team
+      <Badge variant="outline" className="ml-1.5">Pro</Badge>
+    </TabsTrigger>
+  </TabsList>
+  <TabsContent value="general">General settings</TabsContent>
+  <TabsContent value="privacy">Privacy settings</TabsContent>
+</Tabs>
+```
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus to next focusable element |
+| ArrowLeft / ArrowRight | Navigate between tabs (horizontal) |
+| ArrowUp / ArrowDown | Navigate between tabs (vertical) |
+| Enter / Space | Activate focused tab (when activateOnFocus is false) |
+| Home | Focus first tab |
+| End | Focus last tab |
+
+## Accessibility
+
+- Uses `role="tablist"`, `role="tab"`, and `role="tabpanel"` for proper semantic structure
+- Active tab marked with `aria-selected="true"`
+- Tab panels linked via `aria-labelledby` and `aria-controls`
+- Keyboard navigation follows ARIA Authoring Practices Guide
+- Focus management automatically handled when switching tabs
+
+## Related
+
+- [Button](./button.llm.md) - For tab-like actions
+- [Badge](./badge.llm.md) - For counts in tabs
+- [Card](./card.llm.md) - For content panels

package/llm/components/text.llm.md

@@ -0,0 +1,108 @@
+# Text
+
+Paragraph text component with size, weight, color, alignment, and truncation options.
+
+## Import
+
+```tsx
+import { Text, Caption, Overline } from "@neynar/ui/typography"
+```
+
+## Usage
+
+```tsx
+<Text>Default paragraph text</Text>
+<Text size="lg" weight="semibold">Large semibold text</Text>
+<Text color="muted">Secondary text</Text>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| size | "xs" \| "sm" \| "base" \| "lg" \| "xl" \| "2xl" | "base" | Text size |
+| weight | "normal" \| "medium" \| "semibold" \| "bold" | - | Font weight |
+| color | "default" \| "muted" \| "subtle" \| "destructive" \| "success" \| "warning" \| "info" | "default" | Text color |
+| align | "left" \| "center" \| "right" | - | Text alignment |
+| transform | "uppercase" \| "lowercase" \| "capitalize" | - | Text transform |
+| wrap | "pretty" \| "balance" | - | Text wrapping strategy |
+| lineClamp | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | - | Truncate after N lines |
+| as | React.ElementType | "p" | Change rendered element |
+| render | React.ReactElement | - | Advanced polymorphism |
+
+## Convenience Components
+
+### Caption
+
+Small muted text for metadata, timestamps, secondary info.
+
+```tsx
+<Caption>Posted 3 hours ago</Caption>
+// Equivalent to: <Text size="xs" color="muted">
+```
+
+### Overline
+
+Uppercase label text for categories and section headers.
+
+```tsx
+<Overline>Featured Article</Overline>
+// Equivalent to: <Text size="xs" transform="uppercase">
+```
+
+## Examples
+
+### Sizes
+
+```tsx
+<Text size="xs">Extra small</Text>
+<Text size="sm">Small</Text>
+<Text size="base">Base (default)</Text>
+<Text size="lg">Large</Text>
+<Text size="xl">Extra large</Text>
+```
+
+### Colors
+
+```tsx
+<Text color="default">Default text</Text>
+<Text color="muted">Muted helper text</Text>
+<Text color="destructive">Error message</Text>
+<Text color="success">Success message</Text>
+```
+
+### Truncation
+
+```tsx
+<Text lineClamp={2}>
+  This long text will be truncated after two lines with an ellipsis...
+</Text>
+```
+
+### Text Wrapping
+
+```tsx
+<Text wrap="balance">
+  Balanced text distributes words evenly across lines
+</Text>
+<Text wrap="pretty">
+  Pretty text avoids orphaned words on the last line
+</Text>
+```
+
+### Polymorphism
+
+```tsx
+// Simple: change element
+<Text as="span">Inline text</Text>
+<Text as="label">Label text</Text>
+
+// Advanced: render prop
+<Text render={<a href="/link" />}>Link text</Text>
+```
+
+## Related
+
+- [Title](./title.llm.md) - Heading component
+- [Code](./code.llm.md) - Inline code
+- [Blockquote](./blockquote.llm.md) - Quoted content

package/llm/components/textarea.llm.md

@@ -0,0 +1,236 @@
+# Textarea
+
+Multi-line text input with automatic vertical growth and comprehensive validation states.
+
+## Import
+
+```tsx
+import { Textarea } from "@neynar/ui/textarea"
+```
+
+## Anatomy
+
+```tsx
+<Textarea placeholder="Enter text..." />
+```
+
+## Props
+
+Extends all native `<textarea>` HTML props including:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| rows | number | - | Initial number of visible text rows |
+| cols | number | - | Width in average character widths |
+| disabled | boolean | false | Disables the textarea |
+| aria-invalid | boolean | false | Shows error state with red border and ring |
+| placeholder | string | - | Placeholder text |
+| value | string | - | Controlled value |
+| onChange | (e: ChangeEvent) => void | - | Change handler |
+| className | string | - | Additional CSS classes |
+
+All standard textarea attributes are supported (maxLength, autoFocus, readOnly, etc.)
+
+## Auto-Grow Behavior
+
+Textarea uses `field-sizing-content` to automatically grow vertically based on content:
+
+```tsx
+// Auto-grows from min-h-16 as content expands
+<Textarea
+  placeholder="Start typing and watch this grow..."
+  className="min-h-16"
+/>
+```
+
+The component has a default `min-h-16` (64px minimum height).
+
+## Resize Control
+
+Override the default resize behavior via className:
+
+```tsx
+// Disable resize handles
+<Textarea className="resize-none" />
+
+// Vertical resize only (default browser behavior)
+<Textarea className="resize-y" />
+
+// Both directions
+<Textarea className="resize" />
+```
+
+## States
+
+### Error State
+
+Use `aria-invalid` for validation errors:
+
+```tsx
+<Textarea
+  aria-invalid={hasError}
+  placeholder="Required field..."
+/>
+```
+
+Error styling:
+- Red border (`border-destructive`)
+- Red focus ring (`ring-destructive/20`, darker in dark mode)
+- Works with Label component error state
+
+### Disabled State
+
+```tsx
+<Textarea
+  disabled
+  value="Cannot edit this content"
+/>
+```
+
+Disabled styling:
+- 50% opacity
+- No pointer cursor
+- Not focusable
+
+## Data Attributes
+
+| Attribute | Purpose |
+|-----------|---------|
+| data-slot="textarea" | Component identifier for styling and testing |
+
+## Examples
+
+### Basic with Label
+
+```tsx
+import { Label } from "@neynar/ui/label"
+
+<div className="space-y-2">
+  <Label htmlFor="description">Description</Label>
+  <Textarea
+    id="description"
+    placeholder="Enter a description..."
+    rows={3}
+  />
+</div>
+```
+
+### Controlled with Character Count
+
+```tsx
+function CommentForm() {
+  const [value, setValue] = useState("")
+  const maxLength = 280
+  const remaining = maxLength - value.length
+  const isOverLimit = remaining < 0
+
+  return (
+    <div className="space-y-2">
+      <Textarea
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        aria-invalid={isOverLimit}
+        placeholder="What's on your mind?"
+      />
+      <p className={isOverLimit ? "text-destructive" : "text-muted-foreground"}>
+        {remaining} characters remaining
+      </p>
+    </div>
+  )
+}
+```
+
+### Code/JSON Input
+
+```tsx
+<Textarea
+  className="font-mono text-sm"
+  placeholder="Paste JSON here..."
+  rows={8}
+  defaultValue={`{\n  "event": "cast.created",\n  "data": { ... }\n}`}
+/>
+```
+
+### With Validation Error
+
+```tsx
+function FeedbackForm() {
+  const [feedback, setFeedback] = useState("")
+  const [error, setError] = useState("")
+
+  const validate = () => {
+    if (feedback.length < 10) {
+      setError("Feedback must be at least 10 characters")
+    }
+  }
+
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="feedback" className={error ? "text-destructive" : ""}>
+        Feedback
+      </Label>
+      <Textarea
+        id="feedback"
+        value={feedback}
+        onChange={(e) => setFeedback(e.target.value)}
+        onBlur={validate}
+        aria-invalid={!!error}
+      />
+      {error && (
+        <p className="text-destructive text-sm">{error}</p>
+      )}
+    </div>
+  )
+}
+```
+
+### Webhook Payload Editor
+
+```tsx
+<div className="space-y-2">
+  <Label>Request Body (JSON)</Label>
+  <Textarea
+    className="font-mono text-sm"
+    rows={8}
+    defaultValue={webhookPayload}
+  />
+  <Button size="sm">
+    <SendIcon data-icon="inline-start" />
+    Send Test Request
+  </Button>
+</div>
+```
+
+## Keyboard
+
+Standard textarea keyboard behavior:
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus (can be prevented) |
+| Enter | New line |
+| Ctrl/Cmd + A | Select all |
+| Ctrl/Cmd + Z | Undo |
+
+## Accessibility
+
+- Semantic `<textarea>` element
+- Works with Label component via htmlFor/id
+- Error state communicated via `aria-invalid`
+- Placeholder provides input hint (not a replacement for label)
+- Disabled state prevents focus and interaction
+- Full keyboard navigation support
+
+## Styling Notes
+
+The component includes comprehensive focus and error states:
+- **Focus**: Blue ring (`ring-ring/50`) with 3px width
+- **Error**: Red border and ring in both light/dark modes
+- **Dark mode**: Subtle background tint (`bg-input/30`)
+- **Transitions**: Smooth color and shadow changes
+
+## Related
+
+- **[Label](/components/label.llm.md)** - Accessible form labels
+- **[Input](/components/input.llm.md)** - Single-line text input
+- **[Form](/components/form.llm.md)** - Form validation patterns

package/llm/components/title.llm.md

@@ -0,0 +1,88 @@
+# Title
+
+Semantic heading component (h1-h6) with independent visual sizing.
+
+## Import
+
+```tsx
+import { Title } from "@neynar/ui/typography"
+```
+
+## Usage
+
+```tsx
+<Title>Default h2 heading</Title>
+<Title order={1}>Page title (h1)</Title>
+<Title order={3} size="xl">Visually large h3</Title>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| order | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 2 | Semantic heading level (h1-h6) |
+| size | "xs" \| "sm" \| "base" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl" | auto | Visual size (overrides order default) |
+| weight | "normal" \| "medium" \| "semibold" \| "bold" | auto | Font weight (overrides order default) |
+| color | "default" \| "muted" \| "subtle" \| "destructive" \| "success" \| "warning" \| "info" | "default" | Text color |
+| as | React.ElementType | auto | Change rendered element |
+| render | React.ReactElement | - | Advanced polymorphism |
+
+## Order Defaults
+
+Each order has default size and weight:
+
+| Order | Element | Default Size | Default Weight |
+|-------|---------|--------------|----------------|
+| 1 | h1 | 4xl | bold |
+| 2 | h2 | 3xl | bold |
+| 3 | h3 | 2xl | semibold |
+| 4 | h4 | xl | semibold |
+| 5 | h5 | lg | medium |
+| 6 | h6 | base | medium |
+
+## Examples
+
+### Semantic Headings
+
+```tsx
+<Title order={1}>Page Title</Title>
+<Title order={2}>Section Heading</Title>
+<Title order={3}>Subsection</Title>
+```
+
+### Visual Override
+
+```tsx
+// Semantic h3, but visually as large as h1
+<Title order={3} size="4xl">
+  SEO-friendly h3 with hero styling
+</Title>
+```
+
+### Colors
+
+```tsx
+<Title color="muted">Secondary heading</Title>
+<Title color="destructive">Error heading</Title>
+```
+
+### Polymorphism
+
+```tsx
+// Render as different element
+<Title as="div">Non-semantic title styling</Title>
+
+// Advanced: render prop
+<Title render={<a href="/section" />}>Linked heading</Title>
+```
+
+## Accessibility
+
+- Use `order` for semantic structure (screen readers)
+- Use `size` for visual presentation
+- Don't skip heading levels (h1 → h3)
+
+## Related
+
+- [Text](./text.llm.md) - Paragraph text
+- [Code](./code.llm.md) - Inline code