@neynar/ui 0.2.1 → 0.3.1

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-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>
+```

package/.llm/empty.llm.md

@@ -0,0 +1,158 @@
+# Empty
+
+**Type**: component
+
+Empty - Flexible container for displaying empty states with consistent layout A foundational empty state component that provides a centered, vertically-aligned container optimized for displaying empty or no-data states. Uses a composable architecture similar to Alert and Card components, allowing fine-grained control over layout and content through sub-components. ## Key Features - Composable sub-components for flexible layouts (header, media, title, description, content) - Responsive padding that adapts from mobile to desktop (p-6 to md:p-12) - Built-in flex layout with automatic centering and gap spacing - Border-dashed styling hint for visual differentiation - Maximum content width constraints for optimal readability - Text balance for improved typography on multi-line content - Fully accessible with semantic HTML structure ## When to Use - Search results with no matches - Empty data tables, lists, or dashboards - Onboarding states for new users - File uploads or content creation areas - Inbox or notification centers with no items - Error recovery or loading failure scenarios ## Component Architecture - **Empty**: Root container with flex layout, padding, and centering - **EmptyHeader**: Groups media and title with constrained width (max-w-sm) - **EmptyMedia**: Icon or illustration display with two variants - **EmptyTitle**: Prominent heading text with medium font weight - **EmptyDescription**: Muted description text with link styling - **EmptyContent**: Additional content area for buttons or secondary info
+
+## JSX Usage
+
+```jsx
+import { Empty } from '@neynar/ui';
+
+<Empty
+  className="value"
+>
+  {/* Your content here */}
+</Empty>
+```
+
+## 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
+// Basic empty state with icon, title, and description
+import { Inbox } from 'lucide-react';
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <Inbox />
+    </EmptyMedia>
+    <EmptyTitle>No messages yet</EmptyTitle>
+  </EmptyHeader>
+  <EmptyDescription>
+    New messages will appear here when you receive them.
+  </EmptyDescription>
+</Empty>
+```
+### Example 2
+```tsx
+// Search results empty state with action button
+import { Search } from 'lucide-react';
+import { Button } from './button';
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <Search />
+    </EmptyMedia>
+    <EmptyTitle>No results found</EmptyTitle>
+  </EmptyHeader>
+  <EmptyDescription>
+    Try adjusting your search or filters to find what you're looking for.
+  </EmptyDescription>
+  <EmptyContent>
+    <Button variant="outline" onClick={clearFilters}>
+      Clear filters
+    </Button>
+  </EmptyContent>
+</Empty>
+```
+### Example 3
+```tsx
+// File upload empty state with custom illustration
+import { Upload } from 'lucide-react';
+import { Button } from './button';
+<Empty className="min-h-[400px] border-2 border-dashed">
+  <EmptyHeader>
+    <EmptyMedia>
+      <Upload className="w-16 h-16 text-muted-foreground" />
+    </EmptyMedia>
+    <EmptyTitle>Drop files here</EmptyTitle>
+  </EmptyHeader>
+  <EmptyDescription>
+    Drag and drop files to upload, or click the button below.
+  </EmptyDescription>
+  <EmptyContent>
+    <Button onClick={openFilePicker}>
+      Choose files
+    </Button>
+  </EmptyContent>
+</Empty>
+```
+### Example 4
+```tsx
+// Complex empty state with multiple actions
+import { Users, UserPlus, Upload } from 'lucide-react';
+import { Button } from './button';
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <Users />
+    </EmptyMedia>
+    <EmptyTitle>No team members</EmptyTitle>
+  </EmptyHeader>
+  <EmptyDescription>
+    Get started by <a href="/invite">inviting your first team member</a> or
+    importing from a CSV file.
+  </EmptyDescription>
+  <EmptyContent>
+    <div className="flex gap-2">
+      <Button onClick={openInviteModal}>
+        <UserPlus className="w-4 h-4 mr-2" />
+        Invite member
+      </Button>
+      <Button variant="outline" onClick={importFromCsv}>
+        <Upload className="w-4 h-4 mr-2" />
+        Import CSV
+      </Button>
+    </div>
+  </EmptyContent>
+</Empty>
+```
+### Example 5
+```tsx
+// Minimal empty state without header grouping
+import { Sparkles } from 'lucide-react';
+<Empty>
+  <EmptyMedia>
+    <Sparkles className="w-12 h-12 text-primary" />
+  </EmptyMedia>
+  <EmptyTitle>All caught up!</EmptyTitle>
+  <EmptyDescription>
+    You've reviewed all pending items.
+  </EmptyDescription>
+</Empty>
+```
+### Example 6
+```tsx
+// Error state with custom styling
+import { AlertCircle } from 'lucide-react';
+import { Button } from './button';
+<Empty className="border-destructive/50 bg-destructive/5">
+  <EmptyHeader>
+    <EmptyMedia>
+      <AlertCircle className="w-12 h-12 text-destructive" />
+    </EmptyMedia>
+    <EmptyTitle>Failed to load data</EmptyTitle>
+  </EmptyHeader>
+  <EmptyDescription className="text-destructive/90">
+    There was an error loading your content. Please try again.
+  </EmptyDescription>
+  <EmptyContent>
+    <Button variant="destructive" onClick={retry}>
+      Retry
+    </Button>
+  </EmptyContent>
+</Empty>
+```

package/.llm/field-content.llm.md

@@ -0,0 +1,28 @@
+# FieldContent
+
+**Type**: component
+
+FieldContent component
+
+## JSX Usage
+
+```jsx
+import { FieldContent } from '@neynar/ui';
+
+<FieldContent
+  className={value}
+  ...props={value}
+/>
+```
+
+## Component Props
+
+### className
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### ...props
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available

package/.llm/field-description.llm.md

@@ -0,0 +1,28 @@
+# FieldDescription
+
+**Type**: component
+
+FieldDescription component
+
+## JSX Usage
+
+```jsx
+import { FieldDescription } from '@neynar/ui';
+
+<FieldDescription
+  className={value}
+  ...props={value}
+/>
+```
+
+## Component Props
+
+### className
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### ...props
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available

package/.llm/field-error.llm.md

@@ -0,0 +1,41 @@
+# FieldError
+
+**Type**: component
+
+FieldError component
+
+## JSX Usage
+
+```jsx
+import { FieldError } from '@neynar/ui';
+
+<FieldError
+  className={value}
+  errors={value}
+  ...props={value}
+>
+  {/* Your content here */}
+</FieldError>
+```
+
+## Component Props
+
+### className
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### children
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### errors
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### ...props
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available

package/.llm/field-group.llm.md

@@ -0,0 +1,84 @@
+# FieldGroup
+
+**Type**: component
+
+FieldGroup - Container for organizing multiple form fields A layout wrapper that vertically stacks Field components with optimized spacing. It provides container query support for responsive field orientations and automatically adjusts spacing for different control types (standard fields vs. checkbox/radio groups). The component uses CSS container queries (@container) which allows child Field components with `orientation="responsive"` to adapt their layout based on the FieldGroup's width rather than the viewport width.
+
+## JSX Usage
+
+```jsx
+import { FieldGroup } from '@neynar/ui';
+
+<FieldGroup
+  className="value"
+>
+  {/* Your content here */}
+</FieldGroup>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+Basic field grouping
+```tsx
+<FieldSet>
+  <FieldLegend>Contact Information</FieldLegend>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="email">Email</FieldLabel>
+      <Input id="email" type="email" />
+    </Field>
+    <Field>
+      <FieldLabel htmlFor="phone">Phone</FieldLabel>
+      <Input id="phone" type="tel" />
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+### Example 2
+Responsive field orientations with container queries
+```tsx
+<FieldGroup>
+  <Field orientation="responsive">
+    <FieldLabel htmlFor="name">Full Name</FieldLabel>
+    <Input id="name" />
+    <FieldDescription>As it appears on your ID</FieldDescription>
+  </Field>
+  <Field orientation="responsive">
+    <FieldLabel htmlFor="company">Company</FieldLabel>
+    <Input id="company" />
+  </Field>
+</FieldGroup>
+```
+### Example 3
+Nested field groups for complex layouts
+```tsx
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="street">Street Address</FieldLabel>
+    <Input id="street" />
+  </Field>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="city">City</FieldLabel>
+      <Input id="city" />
+    </Field>
+    <Field>
+      <FieldLabel htmlFor="zip">Zip Code</FieldLabel>
+      <Input id="zip" />
+    </Field>
+  </FieldGroup>
+</FieldGroup>
+```

package/.llm/field-label.llm.md

@@ -0,0 +1,28 @@
+# FieldLabel
+
+**Type**: component
+
+FieldLabel component
+
+## JSX Usage
+
+```jsx
+import { FieldLabel } from '@neynar/ui';
+
+<FieldLabel
+  className={value}
+  ...props={value}
+/>
+```
+
+## Component Props
+
+### className
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### ...props
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available

package/.llm/field-legend.llm.md

@@ -0,0 +1,77 @@
+# FieldLegend
+
+**Type**: component
+
+FieldLegend - Fieldset caption with size variants A caption element that provides a title or description for a group of related form fields within a FieldSet. Renders as a native HTML `<legend>` element with size variants to match different design contexts. The "legend" variant (default) uses standard text sizing for top-level fieldsets, while the "label" variant provides smaller text suitable for nested fieldsets or when you need the legend to visually match form labels.
+
+## JSX Usage
+
+```jsx
+import { FieldLegend } from '@neynar/ui';
+
+<FieldLegend
+  className="value"
+  variant={value}
+>
+  {/* Your content here */}
+</FieldLegend>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### variant
+- **Type**: `"legend" | "label"`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+Standard legend for top-level fieldset
+```tsx
+<FieldSet>
+  <FieldLegend>Personal Information</FieldLegend>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="name">Full Name</FieldLabel>
+      <Input id="name" />
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+### Example 2
+Label-sized legend for nested fieldset
+```tsx
+<FieldSet>
+  <FieldLegend variant="label">Notification Preferences</FieldLegend>
+  <FieldGroup>
+    <Field orientation="horizontal">
+      <Switch id="email" />
+      <FieldLabel htmlFor="email">Email notifications</FieldLabel>
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+### Example 3
+Legend with description
+```tsx
+<FieldSet>
+  <FieldLegend>Billing Address</FieldLegend>
+  <FieldDescription>
+    This address will appear on your invoices and receipts.
+  </FieldDescription>
+  <FieldGroup>
+    // fields go here
+  </FieldGroup>
+</FieldSet>
+```

package/.llm/field-separator.llm.md

@@ -0,0 +1,35 @@
+# FieldSeparator
+
+**Type**: component
+
+FieldSeparator component
+
+## JSX Usage
+
+```jsx
+import { FieldSeparator } from '@neynar/ui';
+
+<FieldSeparator
+  className={value}
+  ...props={value}
+>
+  {/* Your content here */}
+</FieldSeparator>
+```
+
+## Component Props
+
+### children
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### className
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### ...props
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available

package/.llm/field-set.llm.md

@@ -0,0 +1,80 @@
+# FieldSet
+
+**Type**: component
+
+FieldSet - Semantic form control grouping container A container that renders a native HTML `<fieldset>` element with optimized spacing and layout presets. It provides semantic grouping for related form controls, which improves accessibility by allowing assistive technologies to understand the relationship between form fields. The component automatically adjusts gap spacing when containing checkbox or radio groups, providing tighter spacing for these control types.
+
+## JSX Usage
+
+```jsx
+import { FieldSet } from '@neynar/ui';
+
+<FieldSet
+  className="value"
+>
+  {/* Your content here */}
+</FieldSet>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+Basic fieldset with legend and fields
+```tsx
+<FieldSet>
+  <FieldLegend>Delivery Information</FieldLegend>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="address">Address</FieldLabel>
+      <Input id="address" />
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+### Example 2
+Fieldset with radio group
+```tsx
+<FieldSet>
+  <FieldLegend>Shipping Method</FieldLegend>
+  <FieldGroup data-slot="radio-group">
+    <Field orientation="horizontal">
+      <Radio id="standard" />
+      <FieldLabel htmlFor="standard">Standard</FieldLabel>
+    </Field>
+    <Field orientation="horizontal">
+      <Radio id="express" />
+      <FieldLabel htmlFor="express">Express</FieldLabel>
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+### Example 3
+Nested fieldsets for complex forms
+```tsx
+<FieldSet>
+  <FieldLegend>Account Settings</FieldLegend>
+  <FieldGroup>
+    <FieldSet>
+      <FieldLegend variant="label">Profile</FieldLegend>
+      <FieldGroup>
+        <Field>
+          <FieldLabel htmlFor="username">Username</FieldLabel>
+          <Input id="username" />
+        </Field>
+      </FieldGroup>
+    </FieldSet>
+  </FieldGroup>
+</FieldSet>
+```