@neynar/ui 0.2.0 → 0.3.0

package/docs/llm/components/display.md

@@ -131,4 +131,129 @@ import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext
   <CarouselPrevious />
   <CarouselNext />
 </Carousel>
+```
+
+## Kbd and KbdGroup
+
+Display keyboard shortcuts and key combinations with semantic HTML.
+
+```tsx
+import { Kbd, KbdGroup } from "@neynar/ui"
+
+// Single key
+<Kbd>Enter</Kbd>
+<Kbd>Esc</Kbd>
+<Kbd>⌘</Kbd>
+
+// Key combinations
+<KbdGroup>
+  <Kbd>⌘</Kbd>
+  <Kbd>K</Kbd>
+</KbdGroup>
+
+<KbdGroup>
+  <Kbd>⌘</Kbd>
+  <Kbd>⇧</Kbd>
+  <Kbd>P</Kbd>
+</KbdGroup>
+
+// In documentation
+<p>
+  Press <KbdGroup><Kbd>⌘</Kbd><Kbd>K</Kbd></KbdGroup> to open the
+  command palette.
+</p>
+
+// In search interfaces
+<div className="relative">
+  <Input placeholder="Search..." />
+  <div className="absolute right-3 top-1/2 -translate-y-1/2">
+    <KbdGroup>
+      <Kbd>⌘</Kbd>
+      <Kbd>K</Kbd>
+    </KbdGroup>
+  </div>
+</div>
+
+// In tooltips
+<Tooltip>
+  <TooltipTrigger asChild>
+    <Button variant="ghost" size="icon">
+      <Settings className="h-4 w-4" />
+    </Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    Open Settings <KbdGroup><Kbd>⌘</Kbd><Kbd>,</Kbd></KbdGroup>
+  </TooltipContent>
+</Tooltip>
+```
+
+## Empty
+
+Empty state placeholder for no data scenarios with optional icon, title, description, and actions.
+
+```tsx
+import { Empty } from "@neynar/ui"
+import { Search, Inbox } from "lucide-react"
+
+// Basic empty state
+<Empty
+  icon={<Search className="h-8 w-8" />}
+  title="No results found"
+  description="Try adjusting your search criteria"
+/>
+
+// With action
+<Empty
+  icon={<Inbox className="h-8 w-8" />}
+  title="No messages"
+  description="You don't have any messages yet"
+  action={<Button>Compose Message</Button>}
+/>
+
+// Multiple actions
+<Empty
+  title="No data available"
+  description="Get started by uploading your first file"
+  actions={
+    <div className="flex gap-2">
+      <Button>Upload File</Button>
+      <Button variant="outline">Learn More</Button>
+    </div>
+  }
+/>
+```
+
+## Spinner
+
+Loading indicator for async operations with GPU-accelerated animation.
+
+```tsx
+import { Spinner } from "@neynar/ui"
+
+// Basic spinner
+<Spinner />
+
+// Different sizes
+<Spinner className="size-3" />  // Small
+<Spinner className="size-4" />  // Default
+<Spinner className="size-6" />  // Large
+<Spinner className="size-8" />  // Extra large
+
+// With color
+<Spinner className="text-primary" />
+<Spinner className="text-destructive" />
+
+// In button
+<Button disabled>
+  <Spinner className="mr-2 size-4" />
+  Loading...
+</Button>
+
+// Centered loading state
+<div className="flex items-center justify-center p-8">
+  <Spinner className="size-6" />
+</div>
+
+// With custom aria-label
+<Spinner aria-label="Loading user profile" />
 ```

package/docs/llm/components/feedback.md

@@ -64,20 +64,6 @@ import { Skeleton } from "@neynar/ui"
 </div>
 ```
 
-## EmptyState
-
-Handle empty data scenarios with helpful messaging.
-
-```tsx
-import { EmptyState } from "@neynar/ui"
-
-<EmptyState 
-  title="No casts found"
-  description="Try adjusting your search criteria"
-  action={<Button>Refresh</Button>}
-/>
-```
-
 ## Sonner (Toast)
 
 Non-blocking notifications for actions and events.

package/docs/llm/components/forms.md

@@ -20,6 +20,100 @@ import { Input, Label, Textarea, TextField } from "@neynar/ui"
 <TextField label="Username" placeholder="Enter username" required />
 ```
 
+## Field
+
+Flexible form field composition with label, description, error, and hint support.
+
+```tsx
+import { Field, Input } from "@neynar/ui"
+
+// Basic field with label
+<Field label="Email Address">
+  <Input type="email" placeholder="you@example.com" />
+</Field>
+
+// Field with description
+<Field
+  label="Password"
+  description="Must be at least 8 characters"
+>
+  <Input type="password" />
+</Field>
+
+// Field with error
+<Field
+  label="Username"
+  error="Username is already taken"
+>
+  <Input defaultValue="john" />
+</Field>
+
+// Field with hint
+<Field
+  label="API Key"
+  hint="Keep this secret"
+>
+  <Input type="password" />
+</Field>
+
+// Complete field with all features
+<Field
+  label="Full Name"
+  description="Enter your legal name"
+  error={errors.name}
+  hint="This will appear on your profile"
+  required
+>
+  <Input placeholder="John Doe" />
+</Field>
+```
+
+## InputGroup
+
+Input with left/right addons for icons, text, or buttons.
+
+```tsx
+import { InputGroup, Input } from "@neynar/ui"
+import { Search, DollarSign, Send } from "lucide-react"
+
+// Icon addon
+<InputGroup>
+  <InputGroup.LeftAddon>
+    <Search className="h-4 w-4" />
+  </InputGroup.LeftAddon>
+  <Input placeholder="Search..." />
+</InputGroup>
+
+// Text addon
+<InputGroup>
+  <InputGroup.LeftAddon>
+    https://
+  </InputGroup.LeftAddon>
+  <Input placeholder="example.com" />
+</InputGroup>
+
+// Currency input
+<InputGroup>
+  <InputGroup.LeftAddon>
+    <DollarSign className="h-4 w-4" />
+  </InputGroup.LeftAddon>
+  <Input type="number" placeholder="0.00" />
+  <InputGroup.RightAddon>
+    USD
+  </InputGroup.RightAddon>
+</InputGroup>
+
+// With button
+<InputGroup>
+  <Input placeholder="Enter email..." />
+  <InputGroup.RightAddon>
+    <Button size="sm">
+      <Send className="h-4 w-4" />
+    </Button>
+  </InputGroup.RightAddon>
+</InputGroup>
+```
+
 ## Selection Components
 
 ```tsx

package/docs/llm/components/layout.md

@@ -56,4 +56,173 @@ import { AspectRatio } from "@neynar/ui";
 <AspectRatio ratio={1} className="bg-muted">
   <div className="flex items-center justify-center">1:1 Square</div>
 </AspectRatio>
+```
+
+## ButtonGroup
+
+Visual grouping for related buttons with flexible composition.
+
+```tsx
+import { ButtonGroup } from "@neynar/ui"
+
+// Basic button group
+<ButtonGroup>
+  <Button variant="outline">Left</Button>
+  <Button variant="outline">Middle</Button>
+  <Button variant="outline">Right</Button>
+</ButtonGroup>
+
+// Different orientations
+<ButtonGroup orientation="vertical">
+  <Button>Top</Button>
+  <Button>Middle</Button>
+  <Button>Bottom</Button>
+</ButtonGroup>
+
+// Mixed button types
+<ButtonGroup>
+  <Button variant="default">Primary</Button>
+  <Button variant="secondary">Secondary</Button>
+  <Button variant="outline" size="icon">
+    <MoreVertical className="h-4 w-4" />
+  </Button>
+</ButtonGroup>
+
+// Toolbar pattern
+<ButtonGroup>
+  <Button variant="ghost" size="icon"><Bold className="h-4 w-4" /></Button>
+  <Button variant="ghost" size="icon"><Italic className="h-4 w-4" /></Button>
+  <Button variant="ghost" size="icon"><Underline className="h-4 w-4" /></Button>
+</ButtonGroup>
+```
+
+## Item
+
+Flexible list item composition with media, content, and actions following the compound component pattern.
+
+```tsx
+import {
+  Item,
+  ItemGroup,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemHeader,
+  ItemFooter,
+  ItemActions,
+  ItemSeparator
+} from "@neynar/ui"
+
+// Basic list item
+<ItemGroup>
+  <Item>
+    <ItemMedia variant="icon">
+      <FileText className="h-4 w-4" />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Document.pdf</ItemTitle>
+      <ItemDescription>Last modified today</ItemDescription>
+    </ItemContent>
+  </Item>
+</ItemGroup>
+
+// File list with actions
+<ItemGroup>
+  <Item asChild>
+    <a href="/documents/report.pdf">
+      <ItemMedia variant="icon">
+        <FileText className="h-4 w-4" />
+      </ItemMedia>
+      <ItemContent>
+        <ItemHeader>
+          <ItemTitle>Q4 Report.pdf</ItemTitle>
+          <Badge variant="secondary">PDF</Badge>
+        </ItemHeader>
+        <ItemDescription>Last modified today at 2:45 PM</ItemDescription>
+        <ItemFooter>
+          <span className="text-xs text-muted-foreground">2.4 MB</span>
+        </ItemFooter>
+      </ItemContent>
+      <ItemActions>
+        <Button variant="ghost" size="icon">
+          <MoreVertical className="h-4 w-4" />
+        </Button>
+      </ItemActions>
+    </a>
+  </Item>
+</ItemGroup>
+
+// User list with avatars
+<ItemGroup>
+  <Item>
+    <ItemMedia variant="image">
+      <img src="/avatars/alice.jpg" alt="Alice" />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Alice Johnson</ItemTitle>
+      <ItemDescription>Product Manager</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Button variant="outline" size="sm">Message</Button>
+    </ItemActions>
+  </Item>
+  <ItemSeparator />
+  <Item>
+    <ItemMedia variant="image">
+      <img src="/avatars/bob.jpg" alt="Bob" />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Bob Smith</ItemTitle>
+      <ItemDescription>Engineer</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Button variant="outline" size="sm">Message</Button>
+    </ItemActions>
+  </Item>
+</ItemGroup>
+
+// Notification list with variants
+<ItemGroup>
+  <Item variant="muted">
+    <ItemMedia variant="icon">
+      <User className="h-4 w-4" />
+    </ItemMedia>
+    <ItemContent>
+      <ItemHeader>
+        <ItemTitle>New follower</ItemTitle>
+        <Badge>New</Badge>
+      </ItemHeader>
+      <ItemDescription>John started following you</ItemDescription>
+      <ItemFooter>
+        <span className="text-xs text-muted-foreground">5 min ago</span>
+      </ItemFooter>
+    </ItemContent>
+  </Item>
+</ItemGroup>
+
+// Compact settings menu
+<ItemGroup>
+  <Item asChild size="sm">
+    <a href="/settings/profile">
+      <ItemContent>
+        <ItemTitle>Profile</ItemTitle>
+      </ItemContent>
+      <ItemActions>
+        <ChevronRight className="h-4 w-4 text-muted-foreground" />
+      </ItemActions>
+    </a>
+  </Item>
+  <ItemSeparator />
+  <Item asChild size="sm">
+    <a href="/settings/notifications">
+      <ItemContent>
+        <ItemTitle>Notifications</ItemTitle>
+      </ItemContent>
+      <ItemActions>
+        <ChevronRight className="h-4 w-4 text-muted-foreground" />
+      </ItemActions>
+    </a>
+  </Item>
+</ItemGroup>
 ```

package/llms.txt

@@ -1,6 +1,6 @@
 # @neynar/ui Component Library
 
-A production-ready React component library with 265+ components, hooks, and utilities. Built on Radix UI primitives with Tailwind CSS v4, ensuring WCAG-compliant accessibility and zero runtime overhead.
+A production-ready React component library with 272+ components, hooks, and utilities. Built on Radix UI primitives with Tailwind CSS v4, ensuring WCAG-compliant accessibility and zero runtime overhead.
 
 ## Quick Reference
 
@@ -11,21 +11,21 @@ import "@neynar/ui/styles"
 
 ## 🔍 How to Search Components
 
-**IMPORTANT:** DO NOT load the entire `llm-docs/sdk-items-registry.json` file - it contains 265+ items and will exceed context limits.
+**IMPORTANT:** DO NOT load the entire `.llm/sdk-items-registry.json` file - it contains 265+ items and will exceed context limits.
 
 Instead, search efficiently using these methods:
 
 ### Method 1: Search by Component Name (Recommended)
 ```bash
 # Search for specific component documentation
-cat llm-docs/{component-name}.llm.md
-# Example: cat llm-docs/button.llm.md
+cat .llm/{component-name}.llm.md
+# Example: cat .llm/button.llm.md
 ```
 
-### Method 2: Search Registry by Keywords  
+### Method 2: Search Registry by Keywords
 ```bash
 # Use jq to search registry by keywords without loading entire file
-jq 'to_entries[] | select(.value.keywords[]? | contains("button")) | {key: .key, description: .value.description}' llm-docs/sdk-items-registry.json
+jq 'to_entries[] | select(.value.keywords[]? | contains("button")) | {key: .key, description: .value.description}' .llm/sdk-items-registry.json
 ```
 
 ### Method 3: List Components by Category
@@ -81,7 +81,7 @@ import { H1, H2, P, Span, Code, Stack, Badge } from "@neynar/ui"
 
 ## Registry Structure
 
-The `llm-docs/sdk-items-registry.json` contains metadata for all components:
+The `.llm/sdk-items-registry.json` contains metadata for all components:
 
 ```json
 {
@@ -99,9 +99,9 @@ The `llm-docs/sdk-items-registry.json` contains metadata for all components:
 For component discovery, use this approach:
 
 1. **Know what you need?** → Use Method 1 (direct file access)
-2. **Searching by functionality?** → Use Method 2 (keyword search)  
+2. **Searching by functionality?** → Use Method 2 (keyword search)
 3. **Browsing categories?** → Use Method 3 (category patterns)
-4. **Need complete list?** → Use `jq 'keys' llm-docs/sdk-items-registry.json`
+4. **Need complete list?** → Use `jq 'keys' .llm/sdk-items-registry.json`
 
 **Performance Tip:** Each .llm.md file contains complete documentation including props, examples, and TypeScript definitions. Only load what you need.
 
@@ -109,7 +109,9 @@ For component discovery, use this approach:
 
 ### Layout Components → [docs/llm/components/layout.md](docs/llm/components/layout.md)
 - **Container** - Responsive container with max-width constraints
-- **Stack** - Flexible vertical and horizontal layout primitive  
+- **Stack** - Flexible vertical and horizontal layout primitive
+- **ButtonGroup** - Groups related buttons with consistent spacing
+- **Item** + 9 sub-components - Flexible list item with media, content, and actions
 - **Separator** - Visual content dividers
 - **AspectRatio** - Responsive aspect ratio containers
 - **ResizablePanelGroup**, **ResizablePanel**, **ResizableHandle** - Interactive resizable layouts
@@ -129,6 +131,8 @@ For component discovery, use this approach:
 - **Input** - Text input fields with validation states
 - **Textarea** - Multi-line text input with auto-resize
 - **TextField** - Complete form field with label and validation
+- **Field** - Flexible form field composition with label, description, error, and hint
+- **InputGroup** - Input with left/right addons for icons, text, or buttons
 - **Label** - Accessible form labels
 - **Checkbox** - Boolean input with indeterminate state
 - **RadioGroup**, **RadioGroupItem** - Single-choice selection
@@ -151,7 +155,9 @@ For component discovery, use this approach:
 - **Progress** - Loading and completion indicators
 - **Skeleton** - Loading state placeholders
 - **Chart** + 5 sub-components - Data visualization
-- **EmptyState** - No data placeholder with actions
+- **Kbd**, **KbdGroup** - Keyboard shortcuts and key combinations display
+- **Empty** - Empty state placeholder for no data scenarios
+- **Spinner** - Loading indicator for async operations
 
 ### Table Components → [docs/llm/components/tables.md](docs/llm/components/tables.md)
 - **Table** + 7 sub-components - Data tables
@@ -201,7 +207,7 @@ The typography system provides semantic HTML components with consistent styling:
 #### Available Components
 - **H1, H2, H3, H4, H5, H6** - Semantic headings with proper hierarchy
 - **P** - Paragraph text with body variant styling
-- **Span** - Inline text with default styling  
+- **Span** - Inline text with default styling
 - **A** - Links with proper hover/focus states
 - **Code** - Inline code with monospace styling
 - **Small** - Small text for captions/metadata

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neynar/ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "author": "Neynar Inc.",
   "description": "React UI component library built on shadcn/ui and Tailwind CSS",
@@ -50,22 +50,22 @@
     "@radix-ui/react-dialog": "1.1.14",
     "@radix-ui/react-dropdown-menu": "2.1.15",
     "@radix-ui/react-hover-card": "1.1.14",
-    "@radix-ui/react-label": "2.1.7",
+    "@radix-ui/react-label": "^2.1.7",
     "@radix-ui/react-menubar": "1.1.15",
     "@radix-ui/react-navigation-menu": "1.2.13",
     "@radix-ui/react-popover": "1.1.14",
     "@radix-ui/react-progress": "1.1.7",
     "@radix-ui/react-radio-group": "1.3.7",
     "@radix-ui/react-select": "2.2.5",
-    "@radix-ui/react-separator": "1.1.7",
+    "@radix-ui/react-separator": "^1.1.7",
     "@radix-ui/react-slider": "1.3.5",
-    "@radix-ui/react-slot": "1.2.3",
+    "@radix-ui/react-slot": "^1.2.3",
     "@radix-ui/react-switch": "1.2.5",
     "@radix-ui/react-tabs": "1.1.12",
     "@radix-ui/react-toggle": "1.1.9",
     "@radix-ui/react-toggle-group": "1.1.10",
     "@radix-ui/react-tooltip": "1.2.7",
-    "class-variance-authority": "0.7.1",
+    "class-variance-authority": "^0.7.1",
     "clsx": "2.1.1",
     "cmdk": "1.1.1",
     "date-fns": "4.1.0",
@@ -94,6 +94,7 @@
     "prettier": "3.6.2",
     "react": "19.1.1",
     "react-dom": "19.1.1",
+    "shadcn": "^3.4.0",
     "storybook": "9.1.2",
     "tailwindcss": "4.1.11",
     "ts-morph": "^26.0.0",

package/src/components/ui/badge.tsx

@@ -23,6 +23,9 @@ import { cn } from "@/lib/utils";
  * @variant default - Primary brand color badge for important status indicators and primary actions
  * @variant secondary - Muted background badge for supplementary information and low-priority labels
  * @variant destructive - Error/warning badge for critical states, failures, and urgent attention
+ * @variant success - Success badge for positive states, successes, and positive attention
+ * @variant warning - Warning badge for warning states, warnings, and negative attention
+ * @variant info - Info badge for informational states, information, and neutral attention
  * @variant outline - Subtle border-only badge for minimal emphasis and subtle labeling
  *
  * @param props - Variant configuration object
@@ -43,7 +46,7 @@ import { cn } from "@/lib/utils";
  * ```
  */
 const badgeVariants = cva(
-  "inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden",
+  "inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-bold w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden",
   {
     variants: {
       variant: {
@@ -52,7 +55,12 @@ const badgeVariants = cva(
         secondary:
           "border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",
         destructive:
-          "border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+          "border-transparent bg-destructive text-destructive-foreground [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+        success:
+          "border-transparent bg-success text-success-foreground [a&]:hover:bg-success/90",
+        warning:
+          "border-transparent bg-warning text-warning-foreground [a&]:hover:bg-warning/90",
+        info: "border-transparent bg-info text-info-foreground [a&]:hover:bg-info/90",
         outline:
           "text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
       },
@@ -70,7 +78,14 @@ const badgeVariants = cva(
 // eslint-disable-next-line unused-imports/no-unused-vars
 type BadgeDocsProps = {
   /** The visual variant of the badge that determines its color scheme and emphasis level */
-  variant?: "default" | "secondary" | "destructive" | "outline";
+  variant?:
+    | "default"
+    | "secondary"
+    | "destructive"
+    | "success"
+    | "warning"
+    | "info"
+    | "outline";
   /** Additional CSS classes to apply to the badge for custom styling */
   className?: string;
   /** Content to display inside the badge (text, icons, or React components) */
@@ -100,6 +115,9 @@ type BadgeDocsProps = {
  * <Badge>New</Badge>
  * <Badge variant="secondary">Draft</Badge>
  * <Badge variant="destructive">Error</Badge>
+ * <Badge variant="success">Success</Badge>
+ * <Badge variant="warning">Warning</Badge>
+ * <Badge variant="info">Info</Badge>
  * <Badge variant="outline">Pending</Badge>
  * ```
  *