@neynar/ui 0.3.0 → 0.4.0

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

@@ -0,0 +1,120 @@
+# DropdownMenu
+
+**Type**: component
+
+A versatile dropdown menu component built on Radix UI primitives Dropdown menus display a list of actions or options that a user can choose from. They're typically triggered by a button and appear as a floating panel with full keyboard navigation support, submenus, and various interactive item types. Built on Radix UI's DropdownMenu primitive with enhanced styling and type safety. Follows the WAI-ARIA Menu Button pattern for accessibility compliance.
+
+## JSX Usage
+
+```jsx
+import { DropdownMenu } from '@neynar/ui';
+
+<DropdownMenu
+  defaultOpen={true}
+  open={true}
+  onOpenChange={handleOpenChange}
+  modal={true}
+  dir={value}
+>
+  {/* Your content here */}
+</DropdownMenu>
+```
+
+## Component Props
+
+### defaultOpen
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether the dropdown is initially open (uncontrolled mode)
+
+### open
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether the dropdown is open (controlled mode)
+
+### onOpenChange
+- **Type**: `(open: boolean) => void`
+- **Required**: No
+- **Description**: Callback fired when the open state changes
+
+### modal
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether the dropdown should be modal (blocks interaction with outside elements)
+
+### dir
+- **Type**: `"ltr" | "rtl"`
+- **Required**: No
+- **Description**: The reading direction of the dropdown menu
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic dropdown menu
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="outline">Options</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>Profile</DropdownMenuItem>
+    <DropdownMenuItem>Settings</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Logout</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+### Example 2
+```tsx
+// Controlled dropdown with alignment
+const [open, setOpen] = useState(false);
+<DropdownMenu open={open} onOpenChange={setOpen}>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost" size="icon">
+      <MoreHorizontal />
+    </Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end">
+    <DropdownMenuItem>Edit</DropdownMenuItem>
+    <DropdownMenuItem>Duplicate</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+### Example 3
+```tsx
+// Complex menu with checkboxes, radio groups, and submenus
+const [showPanel, setShowPanel] = useState(true);
+const [position, setPosition] = useState("top");
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button>Advanced Menu</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent className="w-56">
+    <DropdownMenuLabel>View Options</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuCheckboxItem checked={showPanel} onCheckedChange={setShowPanel}>
+      Show Panel
+    </DropdownMenuCheckboxItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuRadioGroup value={position} onValueChange={setPosition}>
+      <DropdownMenuRadioItem value="top">Top</DropdownMenuRadioItem>
+      <DropdownMenuRadioItem value="bottom">Bottom</DropdownMenuRadioItem>
+    </DropdownMenuRadioGroup>
+    <DropdownMenuSeparator />
+    <DropdownMenuSub>
+      <DropdownMenuSubTrigger>Share</DropdownMenuSubTrigger>
+      <DropdownMenuSubContent>
+        <DropdownMenuItem>Email</DropdownMenuItem>
+        <DropdownMenuItem>Copy Link</DropdownMenuItem>
+      </DropdownMenuSubContent>
+    </DropdownMenuSub>
+  </DropdownMenuContent>
+</DropdownMenu>
+```

package/.llm/empty-content.llm.md

@@ -0,0 +1,103 @@
+# EmptyContent
+
+**Type**: component
+
+EmptyContent - Additional content area for buttons, actions, or secondary information A flexible container for additional content within an empty state, typically used for action buttons, links, or secondary information. Provides consistent width constraints, gap spacing, and alignment for optimal layout of calls-to-action and supplementary content. ## Features - Maximum width of 24rem (384px) for visual balance - Minimum width of 0 to prevent overflow issues - Flex column layout with 1rem (16px) gap between children - Center-aligned items for button grouping - Small text size (text-sm) for secondary content - Text balance for improved multi-line typography - Full width within constraints (w-full) ## Common Use Cases - Primary and secondary action buttons - Button groups with multiple actions - Secondary links or navigation - Additional context or instructions - Step indicators or progress information ## Layout Patterns - Single button: automatically centered - Multiple buttons: stack vertically with gap spacing - Button groups: use flex-row with gap within content - Text content: maintains readability with text-balance
+
+## JSX Usage
+
+```jsx
+import { EmptyContent } from '@neynar/ui';
+
+<EmptyContent
+  className="value"
+>
+  {/* Your content here */}
+</EmptyContent>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Single action button
+import { Button } from './button';
+<EmptyContent>
+  <Button onClick={handleCreate}>Create new project</Button>
+</EmptyContent>
+```
+### Example 2
+```tsx
+// Multiple vertically stacked buttons
+import { Button } from './button';
+<EmptyContent>
+  <Button onClick={handleCreate}>Create project</Button>
+  <Button variant="outline" onClick={handleImport}>Import project</Button>
+</EmptyContent>
+```
+### Example 3
+```tsx
+// Horizontal button group
+import { Button } from './button';
+import { Plus, Upload } from 'lucide-react';
+<EmptyContent>
+  <div className="flex gap-2">
+    <Button onClick={handleCreate}>
+      <Plus className="w-4 h-4 mr-2" />
+      Create
+    </Button>
+    <Button variant="outline" onClick={handleUpload}>
+      <Upload className="w-4 h-4 mr-2" />
+      Upload
+    </Button>
+  </div>
+</EmptyContent>
+```
+### Example 4
+```tsx
+// Button with additional text
+import { Button } from './button';
+<EmptyContent>
+  <Button onClick={handleInvite}>Invite team members</Button>
+  <p className="text-xs text-muted-foreground">
+    or <a href="/import" className="underline">import from CSV</a>
+  </p>
+</EmptyContent>
+```
+### Example 5
+```tsx
+// Secondary links only
+<EmptyContent>
+  <a href="/docs" className="text-sm underline underline-offset-4">
+    View documentation
+  </a>
+  <a href="/examples" className="text-sm underline underline-offset-4">
+    Browse examples
+  </a>
+</EmptyContent>
+```
+### Example 6
+```tsx
+// Custom styled content area
+import { Button } from './button';
+<EmptyContent className="max-w-md gap-2">
+  <Button className="w-full" onClick={handleAction}>
+    Full width button
+  </Button>
+  <p className="text-center">
+    Tighter gap and wider max width
+  </p>
+</EmptyContent>
+```

package/.llm/empty-description.llm.md

@@ -0,0 +1,70 @@
+# EmptyDescription
+
+**Type**: component
+
+EmptyDescription - Descriptive text with link styling for empty states Provides supplementary information, guidance, or context below the empty state title. Automatically styles inline links with underlines and hover effects, making it easy to include helpful links or documentation references within the description text. ## Features - Muted foreground color for visual hierarchy below title - Small text size (text-sm) with relaxed line height for readability - Automatic link styling with underlines and offset - Hover state for links changes color to primary - Supports rich content including paragraphs and inline elements - Center-aligned text within empty state layout ## Link Styling - Default: underline with 4px offset, muted-foreground color - Hover: primary color while maintaining underline - Provides clear visual affordance for interactive elements ## Best Practices - Provide helpful context or next steps - Keep descriptions concise (1-2 sentences) - Include actionable guidance when possible - Use links to documentation, help, or related features - Avoid overwhelming users with too much information
+
+## JSX Usage
+
+```jsx
+import { EmptyDescription } from '@neynar/ui';
+
+<EmptyDescription
+  className="value"
+>
+  {/* Your content here */}
+</EmptyDescription>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Simple description text
+<EmptyDescription>
+  Try adjusting your search or filters to find what you're looking for.
+</EmptyDescription>
+```
+### Example 2
+```tsx
+// Description with inline link
+<EmptyDescription>
+  Get started by <a href="/docs/setup">reading our setup guide</a> or
+  watching the tutorial video.
+</EmptyDescription>
+```
+### Example 3
+```tsx
+// Multi-line description
+<EmptyDescription>
+  Your inbox is empty. New messages and notifications will appear here
+  when you receive them.
+</EmptyDescription>
+```
+### Example 4
+```tsx
+// Description with multiple links
+<EmptyDescription>
+  Need help? Check out our <a href="/docs">documentation</a> or
+  <a href="/support">contact support</a>.
+</EmptyDescription>
+```
+### Example 5
+```tsx
+// Custom styled description
+<EmptyDescription className="text-base text-foreground max-w-md">
+  Override default styling for custom appearance and width.
+</EmptyDescription>
+```

package/.llm/empty-header.llm.md

@@ -0,0 +1,64 @@
+# EmptyHeader
+
+**Type**: component
+
+EmptyHeader - Groups media and title elements with constrained width A container component that groups the EmptyMedia and EmptyTitle elements together, applying a maximum width constraint (max-w-sm / 24rem) for optimal visual hierarchy and readability. Typically used to create a cohesive header unit within the empty state. ## Features - Maximum width of 24rem (384px) for visual balance - Flex column layout with 0.5rem (8px) gap between children - Center-aligned items and text - Maintains semantic grouping for screen readers ## Usage Patterns - Group EmptyMedia and EmptyTitle together - Create visual separation from description and content - Constrain width of title for better readability - Optional - components can be used without header grouping
+
+## JSX Usage
+
+```jsx
+import { EmptyHeader } from '@neynar/ui';
+
+<EmptyHeader
+  className="value"
+>
+  {/* Your content here */}
+</EmptyHeader>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Standard header with icon and title
+import { Package } from 'lucide-react';
+<EmptyHeader>
+  <EmptyMedia variant="icon">
+    <Package />
+  </EmptyMedia>
+  <EmptyTitle>No packages found</EmptyTitle>
+</EmptyHeader>
+```
+### Example 2
+```tsx
+// Header with large illustration
+import { Rocket } from 'lucide-react';
+<EmptyHeader>
+  <EmptyMedia>
+    <Rocket className="w-20 h-20 text-primary" />
+  </EmptyMedia>
+  <EmptyTitle>Ready to launch!</EmptyTitle>
+</EmptyHeader>
+```
+### Example 3
+```tsx
+// Custom styled header
+<EmptyHeader className="max-w-md gap-4">
+  <EmptyMedia variant="icon">
+    <Star />
+  </EmptyMedia>
+  <EmptyTitle>Custom spacing and width</EmptyTitle>
+</EmptyHeader>
+```

package/.llm/empty-media.llm.md

@@ -0,0 +1,81 @@
+# EmptyMedia
+
+**Type**: component
+
+EmptyMedia - Icon or illustration display component with styling variants Displays icons, illustrations, or other visual elements in an empty state. Offers two variants: a transparent default for custom-sized graphics and an "icon" variant with consistent sizing and background styling. Automatically handles SVG pointer events and shrinking behavior. ## Variants ### default - Transparent background (bg-transparent) - No size constraints - use for custom-sized illustrations - Full control over icon/illustration dimensions - Best for large decorative graphics (48px+) ### icon - Muted background (bg-muted) with rounded corners (rounded-lg) - Fixed 40px × 40px container (size-10) - Automatically sizes child SVGs to 24px (size-6) unless explicitly sized - Text color set to foreground for proper contrast - Best for standard icon sizes (16-24px) - Provides visual emphasis through background contrast ## Features - SVG pointer events disabled to prevent interaction issues - Shrink prevention for consistent sizing - Bottom margin (mb-2 / 8px) for spacing from subsequent elements - Flex layout with centered content - Compatible with all icon libraries (lucide-react, heroicons, etc.)
+
+## JSX Usage
+
+```jsx
+import { EmptyMedia } from '@neynar/ui';
+
+<EmptyMedia
+  variant={value}
+  className="value"
+>
+  {/* Your content here */}
+</EmptyMedia>
+```
+
+## Component Props
+
+### variant
+- **Type**: `"default" | "icon"`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Standard icon variant with auto-sizing
+import { Inbox } from 'lucide-react';
+<EmptyMedia variant="icon">
+  <Inbox />
+</EmptyMedia>
+```
+### Example 2
+```tsx
+// Default variant with custom-sized illustration
+import { Package } from 'lucide-react';
+<EmptyMedia>
+  <Package className="w-16 h-16 text-primary" />
+</EmptyMedia>
+```
+### Example 3
+```tsx
+// Icon variant with explicitly sized SVG (overrides auto-sizing)
+import { Search } from 'lucide-react';
+<EmptyMedia variant="icon">
+  <Search className="size-5" />
+</EmptyMedia>
+```
+### Example 4
+```tsx
+// Custom styled media container
+import { Sparkles } from 'lucide-react';
+<EmptyMedia className="bg-primary/10 rounded-full p-4">
+  <Sparkles className="w-8 h-8 text-primary" />
+</EmptyMedia>
+```
+### Example 5
+```tsx
+// Multiple icons or complex graphics
+import { Users, Plus } from 'lucide-react';
+<EmptyMedia>
+  <div className="relative">
+    <Users className="w-12 h-12 text-muted-foreground" />
+    <Plus className="w-6 h-6 text-primary absolute -bottom-1 -right-1" />
+  </div>
+</EmptyMedia>
+```

package/.llm/empty-state.llm.md

@@ -0,0 +1,174 @@
+# EmptyState
+
+**Type**: component
+
+EmptyState - Displays empty or no-data states with consistent UX patterns A comprehensive component for handling empty states across applications. Provides a standardized way to communicate when content is unavailable, data is missing, or initial setup is required. Built with accessibility-first principles and follows established empty state design patterns to guide users toward resolution. **Common Use Cases:** - Search results with no matches - Empty lists, tables, or dashboards - Inbox or notification centers with no items - Data visualization with no data - Onboarding states for new users - Error recovery scenarios **Component Structure:** The component follows a top-down visual hierarchy: Icon → Title → Description → Action. All elements except the title are optional, allowing for flexible implementation across different contexts while maintaining visual consistency.
+
+## JSX Usage
+
+```jsx
+import { EmptyState } from '@neynar/ui';
+
+<EmptyState
+  title="value"
+  description="value"
+  icon={value}
+  action={() => {}}
+  className="value"
+>
+  {/* Your content here */}
+</EmptyState>
+```
+
+## Component Props
+
+### title
+- **Type**: `string`
+- **Required**: Yes
+- **Description**: No description available
+
+### description
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### icon
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+### action
+- **Type**: `{
+    /**
+     * Text label for the action button
+     *
+     * Should be specific and action-oriented rather than generic.
+     * @example "Create your first post", "Import data", "Try again"
+     */
+    label: string;
+
+    /**
+     * Click handler function executed when the action button is pressed
+     *
+     * Called when the user activates the button via click or keyboard interaction.
+     * Should handle the primary action to resolve the empty state.
+     */
+    onClick: () => void;
+  }`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Minimal empty state with just title
+<EmptyState title="No notifications" />
+```
+### Example 2
+```tsx
+// Search results empty state
+import { Search } from 'lucide-react';
+<EmptyState
+  icon={<Search className="w-12 h-12" />}
+  title="No results found"
+  description="Try adjusting your search terms or filters"
+  action={{
+    label: "Clear filters",
+    onClick: () => resetFilters()
+  }}
+/>
+```
+### Example 3
+```tsx
+// Inbox empty state with call-to-action
+import { Inbox, Plus } from 'lucide-react';
+<EmptyState
+  icon={<Inbox className="w-16 h-16" />}
+  title="Your inbox is empty"
+  description="New messages and notifications will appear here"
+  action={{
+    label: "Compose message",
+    onClick: () => openComposer()
+  }}
+/>
+```
+### Example 4
+```tsx
+// Data dashboard empty state with custom styling
+import { BarChart3, TrendingUp } from 'lucide-react';
+<EmptyState
+  className="min-h-[400px] bg-gradient-to-br from-muted/20 to-muted/10 rounded-lg border border-dashed border-muted-foreground/20"
+  icon={<BarChart3 className="w-14 h-14 opacity-60" />}
+  title="No analytics data"
+  description="Connect your data source or import historical data to view insights"
+  action={{
+    label: "Connect data source",
+    onClick: () => showDataSourceModal()
+  }}
+/>
+```
+### Example 5
+```tsx
+// File manager empty state
+import { FolderOpen, Upload } from 'lucide-react';
+<EmptyState
+  icon={<FolderOpen className="w-12 h-12" />}
+  title="This folder is empty"
+  description="Drag and drop files here or use the upload button"
+  action={{
+    label: "Upload files",
+    onClick: () => triggerFileUpload()
+  }}
+/>
+```
+### Example 6
+```tsx
+// Error recovery empty state
+import { AlertTriangle, RefreshCw } from 'lucide-react';
+<EmptyState
+  icon={<AlertTriangle className="w-12 h-12 text-destructive" />}
+  title="Failed to load data"
+  description="There was a problem loading your content. Please try again."
+  action={{
+    label: "Retry",
+    onClick: () => refetchData()
+  }}
+/>
+```
+### Example 7
+```tsx
+// Team members empty state with multiple actions
+import { Users, UserPlus, Mail } from 'lucide-react';
+function TeamEmptyState() {
+  return (
+    <div className="space-y-4">
+      <EmptyState
+        icon={<Users className="w-16 h-16" />}
+        title="No team members yet"
+        description="Invite colleagues to collaborate on projects"
+        action={{
+          label: "Invite members",
+          onClick: () => openInviteModal()
+        }}
+      />
+      <div className="flex justify-center gap-2">
+        <Button variant="outline" size="sm" onClick={() => importFromCsv()}>
+          <Mail className="w-4 h-4 mr-2" />
+          Import from CSV
+        </Button>
+      </div>
+    </div>
+  );
+}
+```

package/.llm/empty-title.llm.md

@@ -0,0 +1,54 @@
+# EmptyTitle
+
+**Type**: component
+
+EmptyTitle - Prominent heading text for empty state messages Displays the primary heading or title for an empty state, styled with medium font weight and tight character spacing for visual hierarchy. Typically describes what is missing or the current state in a concise, user-friendly way. ## Features - Large text size (text-lg / 1.125rem / 18px) - Medium font weight (font-medium / 500) for emphasis - Tight character spacing (tracking-tight / -0.025em) for readability - Foreground color for maximum contrast - Center-aligned within empty state layout ## Best Practices - Keep titles short and descriptive (2-6 words) - Focus on the current state rather than what's wrong - Use positive language when possible - Be specific rather than generic ("No projects" vs "Empty") - Avoid technical jargon or error codes
+
+## JSX Usage
+
+```jsx
+import { EmptyTitle } from '@neynar/ui';
+
+<EmptyTitle
+  className="value"
+>
+  {/* Your content here */}
+</EmptyTitle>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Simple descriptive title
+<EmptyTitle>No results found</EmptyTitle>
+```
+### Example 2
+```tsx
+// Positive framing for empty inbox
+<EmptyTitle>You're all caught up!</EmptyTitle>
+```
+### Example 3
+```tsx
+// Specific empty list title
+<EmptyTitle>No team members yet</EmptyTitle>
+```
+### Example 4
+```tsx
+// Custom styled title
+<EmptyTitle className="text-xl font-semibold text-primary">
+  Welcome to your dashboard
+</EmptyTitle>
+```