@neynar/ui 1.0.1 → 1.0.3

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

@@ -0,0 +1,228 @@
+# ToggleGroup
+
+A group of toggle buttons that share state, commonly used for formatting toolbars, view switchers, and filter controls.
+
+## Import
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@neynar/ui/toggle-group"
+```
+
+## Anatomy
+
+```tsx
+<ToggleGroup>
+  <ToggleGroupItem value="option1">Option 1</ToggleGroupItem>
+  <ToggleGroupItem value="option2">Option 2</ToggleGroupItem>
+  <ToggleGroupItem value="option3">Option 3</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| ToggleGroup | Root container that manages shared state and layout |
+| ToggleGroupItem | Individual toggle button within the group |
+
+## Props
+
+### ToggleGroup
+
+Inherits all props from `@base-ui/react/toggle-group` plus variant styling props.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `any[]` | - | Controlled state: array of pressed item values |
+| defaultValue | `any[]` | - | Uncontrolled initial state |
+| onValueChange | `(value: any[]) => void` | - | Called when selection changes |
+| multiple | `boolean` | `true` | Allow multiple items to be pressed |
+| variant | `"default" \| "outline"` | - | Visual style inherited by all items |
+| size | `"default" \| "sm" \| "lg"` | - | Size variant inherited by all items |
+| spacing | `number` | `0` | Gap between items (0 = joined buttons) |
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction |
+| disabled | `boolean` | `false` | Disable all toggles in the group |
+| loopFocus | `boolean` | `true` | Wrap focus when reaching end with arrow keys |
+
+**Note:** By default, `multiple={true}` allows multiple selections. Set `multiple={false}` for single selection mode.
+
+### ToggleGroupItem
+
+Inherits variant and size from parent ToggleGroup context unless explicitly overridden.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | - | **Required.** Unique identifier for this item |
+| variant | `"default" \| "outline"` | Inherits from group | Override group variant |
+| size | `"default" \| "sm" \| "lg"` | Inherits from group | Override group size |
+| aria-label | `string` | - | Required for icon-only buttons |
+
+## Data Attributes
+
+### ToggleGroup
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-orientation | Always: `"horizontal"` or `"vertical"` |
+| data-disabled | Group is disabled |
+| data-multiple | Multiple selection is enabled |
+| data-spacing | Always: spacing value |
+| data-variant | Always: variant name |
+| data-size | Always: size name |
+
+### ToggleGroupItem
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-pressed | Item is in pressed state |
+| data-disabled | Item is disabled |
+
+## Variants
+
+### Visual Variants
+
+| Variant | Appearance |
+|---------|------------|
+| default | Transparent background, fills on press |
+| outline | Border with shadow, subtle background on press |
+
+### Sizes
+
+| Size | Height | Min Width | Padding |
+|------|--------|-----------|---------|
+| sm | 32px | 32px | 6px |
+| default | 36px | 36px | 8px |
+| lg | 40px | 40px | 10px |
+
+## Examples
+
+### Single Selection (Time Range Picker)
+
+```tsx
+function TimeRangePicker() {
+  const [range, setRange] = useState(["7d"])
+
+  return (
+    <ToggleGroup
+      value={range}
+      onValueChange={(value) => {
+        if (value) setRange(value)
+      }}
+      variant="outline"
+      spacing={0}
+    >
+      <ToggleGroupItem value="1d">1D</ToggleGroupItem>
+      <ToggleGroupItem value="7d">7D</ToggleGroupItem>
+      <ToggleGroupItem value="30d">30D</ToggleGroupItem>
+      <ToggleGroupItem value="90d">90D</ToggleGroupItem>
+    </ToggleGroup>
+  )
+}
+```
+
+### Multiple Selection (Text Formatting)
+
+```tsx
+function TextFormatting() {
+  return (
+    <ToggleGroup variant="outline" spacing={0}>
+      <ToggleGroupItem value="bold" aria-label="Bold">
+        <BoldIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="italic" aria-label="Italic">
+        <ItalicIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="underline" aria-label="Underline">
+        <UnderlineIcon />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  )
+}
+```
+
+### View Switcher (Icon-Only)
+
+```tsx
+function ViewSwitcher() {
+  const [view, setView] = useState(["grid"])
+
+  return (
+    <ToggleGroup
+      value={view}
+      onValueChange={(value) => {
+        if (value) setView(value)
+      }}
+      variant="outline"
+      spacing={0}
+    >
+      <ToggleGroupItem value="grid" aria-label="Grid view">
+        <GridIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="list" aria-label="List view">
+        <ListIcon />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  )
+}
+```
+
+### Vertical Layout with Spacing
+
+```tsx
+<ToggleGroup orientation="vertical" spacing={2} variant="outline">
+  <ToggleGroupItem value="option1">Option 1</ToggleGroupItem>
+  <ToggleGroupItem value="option2">Option 2</ToggleGroupItem>
+  <ToggleGroupItem value="option3">Option 3</ToggleGroupItem>
+</ToggleGroup>
+```
+
+### Separated Buttons (Spacing > 0)
+
+```tsx
+<ToggleGroup variant="outline" spacing={4}>
+  <ToggleGroupItem value="filter1">Active</ToggleGroupItem>
+  <ToggleGroupItem value="filter2">Pending</ToggleGroupItem>
+  <ToggleGroupItem value="filter3">Archived</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Tab | Focus the group (first/last item based on direction) |
+| ArrowRight / ArrowDown | Move focus to next item |
+| ArrowLeft / ArrowUp | Move focus to previous item |
+| Space / Enter | Toggle the focused item |
+| Home | Focus first item |
+| End | Focus last item |
+
+Arrow key direction depends on `orientation`: horizontal uses Left/Right, vertical uses Up/Down.
+
+## Accessibility
+
+- Uses `role="group"` for the container
+- Each toggle uses `aria-pressed` to indicate state
+- Icon-only buttons **must** include `aria-label`
+- Keyboard navigation follows ARIA authoring practices
+- Focus management automatically handles arrow key navigation
+
+## Styling Notes
+
+### Joined Buttons (spacing=0)
+
+When `spacing={0}`, items are visually joined:
+- First item keeps left border radius (or top for vertical)
+- Middle items have no border radius
+- Last item keeps right border radius (or bottom for vertical)
+- Outline variant: middle items share borders (no duplicate borders)
+
+### Context Inheritance
+
+Items automatically inherit `variant` and `size` from the parent ToggleGroup via React context. You can override these per-item if needed.
+
+## Related
+
+- [Toggle](./toggle.llm.md) - Single toggle button
+- [Button](./button.llm.md) - Standard button component
+- [RadioGroup](./radio-group.llm.md) - Radio button groups

package/llm/components/toggle.llm.md

@@ -0,0 +1,235 @@
+# Toggle
+
+Two-state button that can be pressed (on) or unpressed (off).
+
+## Import
+
+```tsx
+import { Toggle } from "@neynar/ui/toggle"
+```
+
+## Anatomy
+
+```tsx
+<Toggle>
+  <Icon />
+  Label
+</Toggle>
+```
+
+## Props
+
+### Toggle
+
+Extends `@base-ui/react/toggle` Props with additional variant styling.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| pressed | boolean | - | Controlled pressed state |
+| defaultPressed | boolean | false | Uncontrolled default pressed state |
+| onPressedChange | (pressed: boolean) => void | - | Called when pressed state changes |
+| disabled | boolean | false | Whether toggle is disabled |
+| variant | "default" \| "outline" | "default" | Visual style variant |
+| size | "sm" \| "default" \| "lg" | "default" | Toggle size |
+| children | ReactNode | - | Toggle content (icon, text, or both) |
+| className | string | - | Additional CSS classes |
+| render | ReactElement \| function | - | Custom render prop |
+
+### Variant Details
+
+**variant="default"**: Transparent background, shows pressed state with muted background.
+
+**variant="outline"**: Border with shadow, more prominent visual separation.
+
+## Data Attributes
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-pressed | Toggle is in pressed state |
+| data-disabled | Toggle is disabled |
+| aria-pressed | "true" or "false" based on state |
+
+## Variants
+
+| Variant | Options |
+|---------|---------|
+| variant | default, outline |
+| size | sm, default, lg |
+
+## Examples
+
+### Basic Toggle
+
+```tsx
+function BasicExample() {
+  const [pressed, setPressed] = useState(false)
+
+  return (
+    <Toggle
+      pressed={pressed}
+      onPressedChange={setPressed}
+    >
+      Toggle me
+    </Toggle>
+  )
+}
+```
+
+### Icon-Only Toggle
+
+```tsx
+import { BoldIcon } from "lucide-react"
+
+function IconToggle() {
+  return (
+    <Toggle aria-label="Toggle bold">
+      <BoldIcon />
+    </Toggle>
+  )
+}
+```
+
+### Icon with Text
+
+```tsx
+import { GridIcon, ListIcon } from "lucide-react"
+
+function ViewModeToggle() {
+  const [viewMode, setViewMode] = useState<"grid" | "list">("grid")
+
+  return (
+    <div className="flex gap-2">
+      <Toggle
+        pressed={viewMode === "grid"}
+        onPressedChange={(pressed) =>
+          pressed && setViewMode("grid")
+        }
+        aria-label="Grid view"
+      >
+        <GridIcon />
+        Grid
+      </Toggle>
+      <Toggle
+        pressed={viewMode === "list"}
+        onPressedChange={(pressed) =>
+          pressed && setViewMode("list")
+        }
+        aria-label="List view"
+      >
+        <ListIcon />
+        List
+      </Toggle>
+    </div>
+  )
+}
+```
+
+### Formatting Toolbar
+
+```tsx
+import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react"
+
+function FormattingToolbar() {
+  const [formatting, setFormatting] = useState({
+    bold: false,
+    italic: false,
+    underline: false,
+  })
+
+  return (
+    <div className="flex gap-2">
+      <Toggle
+        size="sm"
+        variant="outline"
+        pressed={formatting.bold}
+        onPressedChange={(pressed) =>
+          setFormatting((prev) => ({ ...prev, bold: pressed }))
+        }
+        aria-label="Toggle bold"
+      >
+        <BoldIcon />
+      </Toggle>
+      <Toggle
+        size="sm"
+        variant="outline"
+        pressed={formatting.italic}
+        onPressedChange={(pressed) =>
+          setFormatting((prev) => ({ ...prev, italic: pressed }))
+        }
+        aria-label="Toggle italic"
+      >
+        <ItalicIcon />
+      </Toggle>
+      <Toggle
+        size="sm"
+        variant="outline"
+        pressed={formatting.underline}
+        onPressedChange={(pressed) =>
+          setFormatting((prev) => ({ ...prev, underline: pressed }))
+        }
+        aria-label="Toggle underline"
+      >
+        <UnderlineIcon />
+      </Toggle>
+    </div>
+  )
+}
+```
+
+### Theme Toggle
+
+```tsx
+import { SunIcon, MoonIcon } from "lucide-react"
+
+function ThemeToggle() {
+  const [theme, setTheme] = useState<"light" | "dark">("light")
+
+  return (
+    <div className="flex gap-2">
+      <Toggle
+        variant="outline"
+        pressed={theme === "light"}
+        onPressedChange={(pressed) =>
+          pressed && setTheme("light")
+        }
+        aria-label="Light theme"
+      >
+        <SunIcon />
+        Light
+      </Toggle>
+      <Toggle
+        variant="outline"
+        pressed={theme === "dark"}
+        onPressedChange={(pressed) =>
+          pressed && setTheme("dark")
+        }
+        aria-label="Dark theme"
+      >
+        <MoonIcon />
+        Dark
+      </Toggle>
+    </div>
+  )
+}
+```
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| Space | Toggle pressed state |
+| Enter | Toggle pressed state |
+
+## Accessibility
+
+- Renders semantic `<button>` element with `aria-pressed` attribute
+- Icons automatically sized to 16px (size-4) unless custom size class provided
+- Always provide `aria-label` when using icon-only toggles
+- Disabled state prevents all interaction and reduces opacity
+- Focus visible ring indicates keyboard focus
+
+## Related
+
+- [Button](./button.llm.md) - For actions instead of state toggles
+- [Checkbox](./checkbox.llm.md) - For form selections
+- [Switch](./switch.llm.md) - For on/off settings

package/llm/components/tooltip.llm.md

@@ -0,0 +1,191 @@
+# Tooltip
+
+Displays contextual information on hover or focus.
+
+## Import
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent } from "@neynar/ui/tooltip"
+```
+
+## Anatomy
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>Hover me</TooltipTrigger>
+  <TooltipContent>Helpful information</TooltipContent>
+</Tooltip>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Tooltip | Root container, manages open state automatically |
+| TooltipTrigger | Element that shows tooltip on hover/focus |
+| TooltipContent | Popup content with automatic portal, positioning, and arrow |
+| TooltipProvider | Optional provider for configuring shared delay (auto-included in Tooltip) |
+
+## Props
+
+### Tooltip
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| defaultOpen | boolean | - | Whether tooltip is initially open (uncontrolled) |
+| open | boolean | - | Controlled open state |
+| onOpenChange | (open: boolean) => void | - | Called when open state changes |
+| trackCursorAxis | 'none' \| 'both' \| 'x' \| 'y' | 'none' | Which axis the tooltip should track the cursor on |
+
+### TooltipTrigger
+
+Standard trigger props with `render` prop support. Use `render` to customize:
+
+```tsx
+<TooltipTrigger render={<Button variant="ghost" size="icon" />}>
+  <SettingsIcon />
+</TooltipTrigger>
+```
+
+### TooltipContent
+
+Automatically renders portal with positioner and arrow.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| side | 'top' \| 'bottom' \| 'left' \| 'right' | 'top' | Which side to position tooltip |
+| sideOffset | number | 4 | Distance from trigger in pixels |
+| align | 'start' \| 'center' \| 'end' | 'center' | How to align tooltip relative to side |
+| alignOffset | number | 0 | Offset along alignment axis in pixels |
+| className | string | - | Additional CSS classes |
+
+### TooltipProvider
+
+Only needed when sharing state across multiple tooltips. Tooltip automatically includes provider.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| delay | number | 0 | Delay in ms before showing tooltips |
+
+## Data Attributes (for styling)
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-open | Tooltip is open |
+| data-closed | Tooltip is closed |
+| data-side | Current side: 'top' \| 'bottom' \| 'left' \| 'right' |
+| data-align | Current alignment: 'start' \| 'center' \| 'end' |
+| data-starting-style | Tooltip is animating in |
+| data-ending-style | Tooltip is animating out |
+| data-instant | Animations should be instant |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <Button variant="outline">Hover me</Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>This is a tooltip</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+### Icon Button with Tooltip
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <Button variant="ghost" size="icon">
+      <SettingsIcon />
+    </Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>Settings</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+### Placement Options
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <Button>Show below</Button>
+  </TooltipTrigger>
+  <TooltipContent side="bottom" align="start">
+    <p>Positioned at bottom-start</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+### With Keyboard Shortcut
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <Button variant="outline">Save</Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <div className="flex items-center gap-2">
+      <span>Save document</span>
+      <kbd className="bg-background text-foreground rounded border px-1.5 py-0.5 font-mono text-xs">
+        ⌘S
+      </kbd>
+    </div>
+  </TooltipContent>
+</Tooltip>
+```
+
+### Help Icon with Detailed Info
+
+```tsx
+<Tooltip>
+  <TooltipTrigger>
+    <button className="text-muted-foreground hover:text-foreground inline-flex items-center transition-colors">
+      <HelpCircleIcon className="size-4" />
+    </button>
+  </TooltipTrigger>
+  <TooltipContent side="top">
+    <p className="max-w-xs">
+      Track your API requests, rate limits, and usage patterns across all your applications.
+    </p>
+  </TooltipContent>
+</Tooltip>
+```
+
+### Always Open (Controlled)
+
+```tsx
+<Tooltip defaultOpen>
+  <TooltipTrigger>
+    <Button variant="outline">Always visible</Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>This tooltip is always visible</p>
+  </TooltipContent>
+</Tooltip>
+```
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus to/from trigger |
+| Escape | Close tooltip |
+
+## Accessibility
+
+- Automatically adds ARIA attributes for screen readers
+- Tooltip appears on hover and focus for keyboard users
+- Content announced to screen readers when opened
+- Works with disabled elements (tooltip still shows)
+- Arrow provides visual relationship between trigger and content
+
+## Related
+
+- [Popover](./popover.llm.md) - For interactive content requiring click to open
+- [HoverCard](./hover-card.llm.md) - For rich preview content on hover