@neynar/ui 0.3.0 → 0.4.0

package/.llm/textarea.llm.md

@@ -0,0 +1,311 @@
+# Textarea
+
+**Type**: component
+
+Textarea - Multi-line text input control for extended content entry A styled textarea component built on the native HTML textarea element for entering longer pieces of text that span multiple lines, such as comments, descriptions, messages, or any content that requires multiple lines of input. Features automatic content-based resizing using CSS field-sizing when supported by the browser. Built following shadcn/ui design patterns with consistent styling and behavior across form elements. Inherits all native HTML textarea functionality while providing enhanced visual design and better accessibility patterns.
+
+## JSX Usage
+
+```jsx
+import { Textarea } from '@neynar/ui';
+
+<Textarea
+  className="value"
+  placeholder="value"
+  disabled={true}
+  readOnly={true}
+  rows={0}
+  cols={0}
+  maxLength={0}
+  minLength={0}
+  required={true}
+  form="value"
+  name="value"
+  id="value"
+  value="value"
+  defaultValue="value"
+  wrap={value}
+  autoFocus={true}
+  autoComplete="value"
+  autoCapitalize={value}
+  spellCheck={true}
+  onChange={handleChange}
+  onFocus={handleFocus}
+  onBlur={handleBlur}
+  onKeyDown={handleKeyDown}
+  onKeyUp={handleKeyUp}
+  onKeyPress={handleKeyPress}
+  "aria-invalid"={value}
+  "aria-describedby"="value"
+  "aria-labelledby"="value"
+  "aria-label"="value"
+  tabIndex={0}
+  style={value}
+/>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### placeholder
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### readOnly
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### rows
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### cols
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### maxLength
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### minLength
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### required
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### form
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### name
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### id
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### value
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### defaultValue
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### wrap
+- **Type**: `"soft" | "hard" | "off"`
+- **Required**: No
+- **Description**: No description available
+
+### autoFocus
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### autoComplete
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### autoCapitalize
+- **Type**: `"none" | "sentences" | "words" | "characters"`
+- **Required**: No
+- **Description**: No description available
+
+### spellCheck
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### onChange
+- **Type**: `(event: React.ChangeEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onFocus
+- **Type**: `(event: React.FocusEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onBlur
+- **Type**: `(event: React.FocusEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onKeyDown
+- **Type**: `(event: React.KeyboardEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onKeyUp
+- **Type**: `(event: React.KeyboardEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onKeyPress
+- **Type**: `(event: React.KeyboardEvent<HTMLTextAreaElement>) => void`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-invalid"
+- **Type**: `boolean | "false" | "true" | "grammar" | "spelling"`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-describedby"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-labelledby"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-label"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### tabIndex
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### style
+- **Type**: `React.CSSProperties & {
+    resize?: "none" | "both" | "horizontal" | "vertical";
+  }`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic usage
+<Textarea placeholder="Type your message here..." />
+```
+### Example 2
+```tsx
+// With label and validation
+<div className="space-y-2">
+  <Label htmlFor="description">Description</Label>
+  <Textarea
+    id="description"
+    placeholder="Enter a description..."
+    rows={4}
+    required
+  />
+</div>
+```
+### Example 3
+```tsx
+// Controlled with character limit and validation
+const [bio, setBio] = useState("");
+const [error, setError] = useState("");
+const maxLength = 160;
+<div className="space-y-2">
+  <Label htmlFor="bio">Bio</Label>
+  <Textarea
+    id="bio"
+    value={bio}
+    onChange={(e) => {
+      setBio(e.target.value);
+      if (e.target.value.length > maxLength) {
+        setError("Bio is too long");
+      } else {
+        setError("");
+      }
+    }}
+    placeholder="Tell us about yourself..."
+    maxLength={maxLength}
+    aria-invalid={!!error}
+    aria-describedby={error ? "bio-error" : "bio-count"}
+  />
+  <div className="flex justify-between items-center">
+    <p id="bio-count" className="text-sm text-muted-foreground">
+      {bio.length}/{maxLength} characters
+    </p>
+    {error && (
+      <p id="bio-error" className="text-sm text-destructive">
+        {error}
+      </p>
+    )}
+  </div>
+</div>
+```
+### Example 4
+```tsx
+// Auto-resizing with minimum height
+<Textarea
+  placeholder="This textarea grows with content"
+  className="min-h-[100px] max-h-[300px]"
+  style={{ resize: "vertical" }}
+/>
+```
+### Example 5
+```tsx
+// Form integration with validation
+<form onSubmit={handleSubmit}>
+  <div className="space-y-2">
+    <Label htmlFor="feedback">Feedback</Label>
+    <Textarea
+      id="feedback"
+      name="feedback"
+      placeholder="Share your thoughts..."
+      required
+      minLength={10}
+      maxLength={500}
+      rows={3}
+    />
+  </div>
+  <Button type="submit">Submit Feedback</Button>
+</form>
+```
+### Example 6
+```tsx
+// Different wrap behaviors for code/text
+<div className="space-y-4">
+  <div>
+    <Label>Code (no wrapping)</Label>
+    <Textarea
+      wrap="off"
+      placeholder="Enter code here..."
+      className="font-mono text-sm"
+      style={{ resize: "both" }}
+    />
+  </div>
+  <div>
+    <Label>Text (soft wrapping)</Label>
+    <Textarea
+      wrap="soft"
+      placeholder="Enter text content..."
+    />
+  </div>
+</div>
+```

package/.llm/theme-preference.llm.md

@@ -0,0 +1,25 @@
+# ThemePreference
+
+**Type**: type
+
+Theme preference options for the theme system Controls how the application determines the active theme: - `"system"` - Automatically follows the user's OS preference - `"light"` - Forces light theme regardless of system preference - `"dark"` - Forces dark theme regardless of system preference
+
+## Type Definition
+
+```typescript
+import { ThemePreference } from '@neynar/ui';
+
+type ThemePreference = "system" | "light" | "dark"
+```
+
+## Examples
+
+```tsx
+const { preference, setPreference } = useTheme();
+
+// Switch to dark mode
+setPreference("dark");
+
+// Follow system preference
+setPreference("system");
+```

package/.llm/theme-toggle.llm.md

@@ -0,0 +1,57 @@
+# ThemeToggle
+
+**Type**: component
+
+ThemeToggle - A zero-configuration theme switcher with system, light, and dark modes A completely self-contained theme toggle component that provides an intuitive dropdown interface for switching between system preference, light mode, and dark mode. Works immediately without any provider setup, context configuration, or additional dependencies. Built on top of shadcn/ui components (Button + DropdownMenu) with the Neynar useTheme hook for state management. Handles theme persistence via cookies, system preference detection, real-time system changes, and synchronization across multiple instances. **Zero Configuration Design:** Just import and use - no providers, no setup, no configuration required. The component handles all theme management internally and provides a complete solution out of the box. **Perfect for:** - Application headers and navigation bars - Settings panels and preference screens - Toolbars and floating action areas - Any location where users need quick theme access
+
+## JSX Usage
+
+```jsx
+import { ThemeToggle } from '@neynar/ui';
+
+<ThemeToggle
+  variant={value}
+  size={value}
+  className="value"
+  showLabel={true}
+  align={value}
+  asChild={true}
+/>
+```
+
+## Component Props
+
+### variant
+- **Type**: `| "default"
+    | "destructive"
+    | "outline"
+    | "secondary"
+    | "ghost"
+    | "link"`
+- **Required**: No
+- **Description**: Visual style variant inherited from Button component (default: "outline")
+
+### size
+- **Type**: `"default" | "sm" | "lg" | "icon"`
+- **Required**: No
+- **Description**: Size variant inherited from Button component (default: "icon")
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: Additional CSS classes for custom styling
+
+### showLabel
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: Whether to show theme name text (auto-enabled for non-icon sizes)
+
+### align
+- **Type**: `"start" | "center" | "end"`
+- **Required**: No
+- **Description**: Dropdown menu alignment relative to trigger button (default: "end")
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available

package/.llm/theme.llm.md

@@ -0,0 +1,14 @@
+# Theme
+
+**Type**: component
+
+Theme - Prevents flash of unstyled content (FOUC) during theme initialization A critical component that prevents the flash of incorrect theme styling by applying the user's preferred theme before the page renders. This component should be placed once at the root of your application, ideally in the document head or at the very beginning of the body. The component works by injecting a small inline script that: 1. Reads the stored theme preference from cookies 2. Detects system theme preference if set to "system" 3. Applies the appropriate theme class and color scheme immediately 4. Executes synchronously before first paint to prevent FOUC Built as a zero-configuration component that requires no props or setup. Simply drop it into your application's root layout and it will handle theme initialization automatically.
+
+## JSX Usage
+
+```jsx
+import { Theme } from '@neynar/ui';
+
+<Theme
+/>
+```

package/.llm/toaster.llm.md

@@ -0,0 +1,193 @@
+# Toaster
+
+**Type**: component
+
+Toast notification container component built on Sonner A feature-rich toast component that provides beautiful, accessible notifications with seamless theme integration and extensive customization options. Built on the popular Sonner library with enhanced theming that automatically synchronizes with the application's theme system using the useTheme hook. This component serves as the central toast container and should be placed once in your application root. It manages the display, positioning, and lifecycle of all toast notifications throughout your application. **Key Features:** - **Automatic theme synchronization** - Integrates with useTheme for consistent styling - **Flexible positioning** - Six different positions with smart stacking - **Rich accessibility** - Full keyboard navigation and screen reader support - **Promise integration** - Built-in loading/success/error states for async operations - **Gesture support** - Touch-friendly swipe-to-dismiss with configurable directions - **Performance optimized** - Efficient rendering with configurable limits - **Customizable styling** - Comprehensive theming and custom icon support
+
+## JSX Usage
+
+```jsx
+import { Toaster } from '@neynar/ui';
+
+<Toaster
+  invert={true}
+  theme={value}
+  position={value}
+  hotkey={[]}
+  richColors={true}
+  expand={true}
+  duration={0}
+  gap={0}
+  visibleToasts={0}
+  closeButton={true}
+  toastOptions={value}
+  className="value"
+  style={value}
+  offset={value}
+  mobileOffset={value}
+  dir={value}
+  swipeDirections={[]}
+  icons={value}
+  containerAriaLabel="value"
+/>
+```
+
+## Component Props
+
+### invert
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### theme
+- **Type**: `"light" | "dark" | "system"`
+- **Required**: No
+- **Description**: No description available
+
+### position
+- **Type**: `| "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right"
+    | "top-center"
+    | "bottom-center"`
+- **Required**: No
+- **Description**: No description available
+
+### hotkey
+- **Type**: `string[]`
+- **Required**: No
+- **Description**: No description available
+
+### richColors
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### expand
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### duration
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### gap
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### visibleToasts
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### closeButton
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### toastOptions
+- **Type**: `{
+    /** Additional CSS classes for toast elements */
+    className?: string;
+    /** Show close button for individual toasts @default false */
+    closeButton?: boolean;
+    /** CSS classes for description text */
+    descriptionClassName?: string;
+    /** Inline styles for toast container */
+    style?: React.CSSProperties;
+    /** Styles for cancel button */
+    cancelButtonStyle?: React.CSSProperties;
+    /** Styles for action button */
+    actionButtonStyle?: React.CSSProperties;
+    /** Duration before auto-dismiss in milliseconds */
+    duration?: number;
+    /** Remove default styling to allow full custom styling @default false */
+    unstyled?: boolean;
+    /** CSS class overrides for specific toast elements */
+    classNames?: {
+      toast?: string;
+      title?: string;
+      description?: string;
+      loader?: string;
+      closeButton?: string;
+      cancelButton?: string;
+      actionButton?: string;
+      success?: string;
+      error?: string;
+      info?: string;
+      warning?: string;
+      loading?: string;
+      default?: string;
+      content?: string;
+      icon?: string;
+    };
+    /** Accessible label for close button */
+    closeButtonAriaLabel?: string;
+  }`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### style
+- **Type**: `React.CSSProperties`
+- **Required**: No
+- **Description**: No description available
+
+### offset
+- **Type**: `| string
+    | number
+    | {
+        top?: string | number;
+        right?: string | number;
+        bottom?: string | number;
+        left?: string | number;
+      }`
+- **Required**: No
+- **Description**: No description available
+
+### mobileOffset
+- **Type**: `| string
+    | number
+    | {
+        top?: string | number;
+        right?: string | number;
+        bottom?: string | number;
+        left?: string | number;
+      }`
+- **Required**: No
+- **Description**: No description available
+
+### dir
+- **Type**: `"rtl" | "ltr" | "auto"`
+- **Required**: No
+- **Description**: No description available
+
+### swipeDirections
+- **Type**: `("top" | "right" | "bottom" | "left")[]`
+- **Required**: No
+- **Description**: No description available
+
+### icons
+- **Type**: `{
+    success?: React.ReactNode;
+    info?: React.ReactNode;
+    warning?: React.ReactNode;
+    error?: React.ReactNode;
+    loading?: React.ReactNode;
+    close?: React.ReactNode;
+  }`
+- **Required**: No
+- **Description**: No description available
+
+### containerAriaLabel
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available

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

@@ -0,0 +1,59 @@
+# ToggleGroupItem
+
+**Type**: component
+
+Toggle Group Item - Individual selectable item within a ToggleGroup Represents a single toggleable option within a ToggleGroup component. Each item automatically inherits variant and size styling from the parent ToggleGroup context through React Context, but these can be overridden for specific styling needs. Supports flexible content including icons, text, or mixed combinations. The component participates in the parent ToggleGroup's keyboard navigation and selection behavior, with proper ARIA attributes for accessibility. Focus management and selection state are handled automatically by the Radix UI primitive.
+
+## JSX Usage
+
+```jsx
+import { ToggleGroupItem } from '@neynar/ui';
+
+<ToggleGroupItem
+  className="value"
+  value="value"
+  disabled={true}
+  variant={value}
+  size={value}
+  asChild={true}
+>
+  {/* Your content here */}
+</ToggleGroupItem>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### value
+- **Type**: `string`
+- **Required**: Yes
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### variant
+- **Type**: `"default" | "outline"`
+- **Required**: No
+- **Description**: No description available
+
+### size
+- **Type**: `"sm" | "default" | "lg"`
+- **Required**: No
+- **Description**: No description available
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available