@neynar/ui 1.0.0 → 1.0.2

package/llm/components/dropdown-menu.llm.md

@@ -0,0 +1,404 @@
+# DropdownMenu
+
+A versatile dropdown menu component for displaying contextual actions and selections.
+
+## Import
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuGroup,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+  DropdownMenuShortcut,
+} from "@neynar/ui/dropdown-menu"
+```
+
+## Anatomy
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger>
+    <Button>Open</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuLabel>Section</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuGroup>
+      <DropdownMenuItem>Item</DropdownMenuItem>
+    </DropdownMenuGroup>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| DropdownMenu | Root container, manages open/close state and keyboard navigation |
+| DropdownMenuTrigger | Button that opens the menu |
+| DropdownMenuContent | Content container with automatic portal and positioning |
+| DropdownMenuItem | Individual menu item with optional variants |
+| DropdownMenuCheckboxItem | Menu item with checkbox for independent toggles |
+| DropdownMenuRadioGroup | Container for mutually exclusive radio items |
+| DropdownMenuRadioItem | Radio item for single selection within a group |
+| DropdownMenuLabel | Label for grouping related items |
+| DropdownMenuSeparator | Visual divider between menu sections |
+| DropdownMenuGroup | Logical container for related items |
+| DropdownMenuSub | Root container for nested submenus |
+| DropdownMenuSubTrigger | Trigger for opening a submenu |
+| DropdownMenuSubContent | Content container for submenu items |
+| DropdownMenuShortcut | Visual display of keyboard shortcuts |
+
+## Props
+
+### DropdownMenu
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| open | boolean | - | Controlled open state |
+| onOpenChange | (open: boolean) => void | - | Called when open state changes |
+| defaultOpen | boolean | false | Uncontrolled initial open state |
+
+### DropdownMenuTrigger
+
+Uses `render` prop pattern for custom trigger elements:
+
+```tsx
+<DropdownMenuTrigger render={<Button variant="outline" />}>
+  Open Menu
+</DropdownMenuTrigger>
+```
+
+### DropdownMenuContent
+
+Automatically renders in a portal with positioning system.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| align | "start" \| "center" \| "end" | "start" | Horizontal alignment relative to trigger |
+| alignOffset | number | 0 | Offset in pixels from aligned position |
+| side | "top" \| "right" \| "bottom" \| "left" | "bottom" | Preferred side to position menu |
+| sideOffset | number | 4 | Distance in pixels from trigger |
+
+### DropdownMenuItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | "default" \| "destructive" \| "success" \| "warning" \| "info" | "default" | Visual style variant |
+| inset | boolean | false | Add extra left padding for alignment |
+| disabled | boolean | false | Disable item interaction |
+
+### DropdownMenuCheckboxItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| checked | boolean \| "indeterminate" | - | Checked state |
+| onCheckedChange | (checked: boolean) => void | - | Called when checked state changes |
+
+### DropdownMenuRadioGroup
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | string | - | Currently selected value |
+| onValueChange | (value: string) => void | - | Called when selection changes |
+
+### DropdownMenuRadioItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | string | - | Value for this radio item |
+
+### DropdownMenuLabel
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| inset | boolean | false | Add extra left padding for alignment with icon items |
+
+### DropdownMenuSubTrigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| inset | boolean | false | Add extra left padding for alignment |
+
+Automatically displays chevron icon on the right.
+
+### DropdownMenuSubContent
+
+Same props as DropdownMenuContent, but with different defaults:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| side | "top" \| "right" \| "bottom" \| "left" | "right" | Preferred side to position submenu |
+| alignOffset | number | -3 | Offset for better visual alignment |
+
+## Data Attributes (for styling)
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-open | Menu or submenu is open |
+| data-closed | Menu or submenu is closed |
+| data-highlighted | Item is keyboard-highlighted or hovered |
+| data-disabled | Item is disabled |
+| data-inset | Item or label has inset padding |
+
+## Variants
+
+DropdownMenuItem supports semantic variants:
+
+| Variant | Use Case |
+|---------|----------|
+| default | Standard actions |
+| destructive | Delete, remove, or dangerous actions |
+| success | Confirmations or positive actions |
+| warning | Caution-required actions |
+| info | Informational actions |
+
+## Examples
+
+### Basic Menu
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger>
+    <Button variant="outline">Open Menu</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>
+      <EditIcon />
+      Edit
+    </DropdownMenuItem>
+    <DropdownMenuItem>
+      <CopyIcon />
+      Duplicate
+    </DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem variant="destructive">
+      <TrashIcon />
+      Delete
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+### User Account Menu
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger>
+    <Button variant="ghost" size="icon">
+      <UserIcon />
+    </Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end" className="w-56">
+    <DropdownMenuLabel>My Account</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>
+      <UserIcon />
+      Profile
+      <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
+    </DropdownMenuItem>
+    <DropdownMenuItem>
+      <SettingsIcon />
+      Settings
+      <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
+    </DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem variant="destructive">
+      <LogOutIcon />
+      Log Out
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+### Checkbox Items
+
+```tsx
+function NotificationMenu() {
+  const [notifications, setNotifications] = useState(true)
+  const [marketing, setMarketing] = useState(false)
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger>
+        <Button variant="outline">Preferences</Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent>
+        <DropdownMenuLabel>Notifications</DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuCheckboxItem
+          checked={notifications}
+          onCheckedChange={setNotifications}
+        >
+          <BellIcon />
+          Push Notifications
+        </DropdownMenuCheckboxItem>
+        <DropdownMenuCheckboxItem
+          checked={marketing}
+          onCheckedChange={setMarketing}
+        >
+          <MailIcon />
+          Marketing Emails
+        </DropdownMenuCheckboxItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+### Radio Group
+
+```tsx
+function ThemeSelector() {
+  const [theme, setTheme] = useState("system")
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger>
+        <Button variant="outline">Theme: {theme}</Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent>
+        <DropdownMenuLabel>Theme</DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuRadioGroup value={theme} onValueChange={setTheme}>
+          <DropdownMenuRadioItem value="light">
+            <SunIcon />
+            Light
+          </DropdownMenuRadioItem>
+          <DropdownMenuRadioItem value="dark">
+            <MoonIcon />
+            Dark
+          </DropdownMenuRadioItem>
+          <DropdownMenuRadioItem value="system">
+            <MonitorIcon />
+            System
+          </DropdownMenuRadioItem>
+        </DropdownMenuRadioGroup>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+### Nested Submenus
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger>
+    <Button variant="outline">Actions</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>
+      <EditIcon />
+      Edit
+    </DropdownMenuItem>
+    <DropdownMenuItem>
+      <CopyIcon />
+      Duplicate
+    </DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuSub>
+      <DropdownMenuSubTrigger>
+        <ShareIcon />
+        Share
+      </DropdownMenuSubTrigger>
+      <DropdownMenuSubContent>
+        <DropdownMenuItem>
+          <MailIcon />
+          Email
+        </DropdownMenuItem>
+        <DropdownMenuItem>
+          <CopyIcon />
+          Copy Link
+        </DropdownMenuItem>
+        <DropdownMenuItem>
+          <DownloadIcon />
+          Export
+        </DropdownMenuItem>
+      </DropdownMenuSubContent>
+    </DropdownMenuSub>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem variant="destructive">
+      <TrashIcon />
+      Delete
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+### Organized with Groups
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger>
+    <Button variant="outline">Menu</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent className="w-56">
+    <DropdownMenuGroup>
+      <DropdownMenuLabel>My Account</DropdownMenuLabel>
+    </DropdownMenuGroup>
+    <DropdownMenuSeparator />
+    <DropdownMenuGroup>
+      <DropdownMenuItem>
+        <UserIcon />
+        Profile
+      </DropdownMenuItem>
+      <DropdownMenuItem>
+        <SettingsIcon />
+        Settings
+      </DropdownMenuItem>
+    </DropdownMenuGroup>
+    <DropdownMenuSeparator />
+    <DropdownMenuGroup>
+      <DropdownMenuLabel>Team</DropdownMenuLabel>
+    </DropdownMenuGroup>
+    <DropdownMenuGroup>
+      <DropdownMenuItem>
+        <PlusIcon />
+        Invite Members
+      </DropdownMenuItem>
+      <DropdownMenuItem>
+        <MailIcon />
+        Team Settings
+      </DropdownMenuItem>
+    </DropdownMenuGroup>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| Space / Enter | Open menu (on trigger) / Activate item (in menu) |
+| ArrowDown / ArrowUp | Navigate between items |
+| ArrowRight | Open submenu |
+| ArrowLeft | Close submenu |
+| Escape | Close menu |
+| Tab | Move focus out and close menu |
+
+## Accessibility
+
+- Built on Base UI Menu primitives with ARIA menu pattern
+- Automatic focus management and keyboard navigation
+- Screen reader announcements for menu state changes
+- All items are properly labeled and keyboard accessible
+- Checkbox and radio items announce their checked state
+- Disabled items are properly marked with `aria-disabled`
+
+## Related
+
+- [ContextMenu](/components/context-menu) - Right-click menu with similar structure
+- [Select](/components/select) - For form-based single selection
+- [Combobox](/components/combobox) - For searchable selection
+- [Button](/components/button) - Common trigger element

package/llm/components/empty.llm.md

@@ -0,0 +1,282 @@
+# Empty
+
+Compound component for displaying empty states with media, messaging, and call-to-action elements.
+
+## Import
+
+```tsx
+import {
+  Empty,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+  EmptyDescription,
+  EmptyContent,
+} from "@neynar/ui/empty"
+```
+
+## Anatomy
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <Icon />
+    </EmptyMedia>
+    <EmptyTitle>Title</EmptyTitle>
+    <EmptyDescription>Description text</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>Action</Button>
+  </EmptyContent>
+</Empty>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Empty | Root container with centered flex layout and dashed border |
+| EmptyHeader | Vertical stack for media, title, and description |
+| EmptyMedia | Icon/media container with optional background styling |
+| EmptyTitle | Large heading text |
+| EmptyDescription | Supporting text with link styling |
+| EmptyContent | Action area for buttons or links |
+
+## Props
+
+### Empty
+
+Standard div props with centered layout and dashed border.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+| children | ReactNode | - | Empty state content |
+
+### EmptyHeader
+
+Standard div props. Groups media, title, and description.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+| children | ReactNode | - | Header content (media, title, description) |
+
+### EmptyMedia
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | "default" \| "icon" | "default" | Styling variant |
+| className | string | - | Additional CSS classes |
+| children | ReactNode | - | Icon or media element |
+
+**Variant Behavior:**
+- `default`: Transparent background, use with custom-sized icons
+- `icon`: Muted background with padding, auto-sizes icons to size-6
+
+### EmptyTitle
+
+Standard div props for the title heading.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+| children | ReactNode | - | Title text |
+
+### EmptyDescription
+
+Standard div props with link styling support.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+| children | ReactNode | - | Description text (supports inline links) |
+
+Inline links (`<a>`) are automatically styled with underlines and hover effects.
+
+### EmptyContent
+
+Standard div props for action elements.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional CSS classes |
+| children | ReactNode | - | Action buttons or links |
+
+## Data Attributes
+
+All components have unique `data-slot` attributes for styling hooks:
+
+| Attribute | Component |
+|-----------|-----------|
+| data-slot="empty" | Empty |
+| data-slot="empty-header" | EmptyHeader |
+| data-slot="empty-icon" | EmptyMedia |
+| data-slot="empty-title" | EmptyTitle |
+| data-slot="empty-description" | EmptyDescription |
+| data-slot="empty-content" | EmptyContent |
+
+EmptyMedia also includes:
+- `data-variant`: Current variant value
+
+## Variants
+
+### Media Variants
+
+| Variant | Use Case |
+|---------|----------|
+| default | Large custom-sized icons (size-12), transparent background |
+| icon | Standard icons with muted background, auto-sized to size-6 |
+
+## Examples
+
+### Basic Empty State
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <SearchIcon />
+    </EmptyMedia>
+    <EmptyTitle>No results found</EmptyTitle>
+    <EmptyDescription>
+      Try adjusting your search terms or filters.
+    </EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+### With Action Button
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <WebhookIcon />
+    </EmptyMedia>
+    <EmptyTitle>No webhooks configured</EmptyTitle>
+    <EmptyDescription>
+      Get started by creating your first webhook to receive real-time notifications.
+    </EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>
+      <WebhookIcon data-icon="inline-start" />
+      Create Webhook
+    </Button>
+  </EmptyContent>
+</Empty>
+```
+
+### With Multiple Actions
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <DatabaseIcon />
+    </EmptyMedia>
+    <EmptyTitle>No data sources</EmptyTitle>
+    <EmptyDescription>
+      Connect your first data source to start analyzing data.
+    </EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <div className="flex flex-col gap-2 sm:flex-row">
+      <Button>Connect Data Source</Button>
+      <Button variant="outline">View Documentation</Button>
+    </div>
+  </EmptyContent>
+</Empty>
+```
+
+### With Link in Description
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia>
+      <DatabaseIcon className="size-12 text-muted-foreground" />
+    </EmptyMedia>
+    <EmptyTitle>No data available</EmptyTitle>
+    <EmptyDescription>
+      Start collecting data by setting up your first integration.{" "}
+      <a href="#">Learn more</a>
+    </EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+### Large Icon (Default Variant)
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="default">
+      <FileTextIcon className="size-12 text-muted-foreground" />
+    </EmptyMedia>
+    <EmptyTitle>No documents</EmptyTitle>
+    <EmptyDescription>
+      Use the default variant with manually sized icons for larger displays.
+    </EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+### Minimal (No Media)
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyTitle>No items to display</EmptyTitle>
+    <EmptyDescription>
+      Empty states can work without media icons for simpler contexts.
+    </EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+### Success/Completed State
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <InboxIcon />
+    </EmptyMedia>
+    <EmptyTitle>All caught up!</EmptyTitle>
+    <EmptyDescription>
+      You have no new notifications. We'll notify you when something happens.
+    </EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+## Composition Patterns
+
+### Minimal Pattern
+Header with media and title only (no description, no actions).
+
+### Standard Pattern
+Header with media, title, and description (no actions).
+
+### Action Pattern
+Complete header + content section with one or more buttons.
+
+### Text-Only Pattern
+Header with title and description, no media or actions.
+
+## Accessibility
+
+- Use semantic HTML elements for text content
+- Ensure sufficient color contrast for text and icons
+- Keep empty state messages clear and actionable
+- Provide keyboard-accessible actions when present
+- Consider loading states vs empty states for better UX
+
+## Related
+
+- Button - For empty state actions
+- Alert - For error or warning states
+- Card - Often contains empty states