@neynar/ui 1.0.1 → 1.0.3

package/llm/components/slider.llm.md

@@ -0,0 +1,213 @@
+# Slider
+
+Slider for selecting single values or ranges with one or more draggable thumbs.
+
+## Import
+
+```tsx
+import { Slider } from "@neynar/ui/slider"
+```
+
+## Anatomy
+
+```tsx
+<Slider defaultValue={[50]} min={0} max={100} />
+```
+
+## Props
+
+All props from Base UI Slider.Root are supported.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| defaultValue | number \| number[] | - | Uncontrolled initial value. Use array for ranges. |
+| value | number \| number[] | - | Controlled value. Use array for ranges. |
+| onValueChange | (value: number \| number[], eventDetails) => void | - | Called when value changes during interaction. |
+| onValueCommitted | (value: number \| number[], eventDetails) => void | - | Called when interaction completes (pointerup). |
+| min | number | 0 | Minimum value. |
+| max | number | 100 | Maximum value. |
+| step | number | 1 | Step increment for value changes. |
+| largeStep | number | 10 | Step for Page Up/Down or Shift + Arrow keys. |
+| minStepsBetweenValues | number | - | Minimum steps between thumbs in range slider. |
+| disabled | boolean | false | Disables all interactions. |
+| orientation | "horizontal" \| "vertical" | "horizontal" | Slider direction. |
+| thumbAlignment | "center" \| "edge" \| "edge-client-only" | "edge" | How thumbs align at min/max positions. |
+| thumbCollisionBehavior | "none" \| "push" \| "swap" | "push" | How thumbs interact when they collide. |
+| name | string | - | Form field name for submission. |
+| className | string | - | Additional classes for the control element. |
+
+### Value Format
+
+- **Single value**: `defaultValue={[50]}` or `value={[50]}`
+- **Range (two thumbs)**: `defaultValue={[25, 75]}`
+- **Multiple thumbs**: `defaultValue={[20, 40, 60, 80]}`
+
+Values are always arrays. Component automatically creates the correct number of thumbs based on array length.
+
+### Thumb Alignment
+
+Set to `"edge"` by default (thumbs align to edges at min/max):
+- `"center"` - Thumb centers align at min/max
+- `"edge"` - Thumb edges align at min/max (default)
+- `"edge-client-only"` - Like edge but only on client
+
+## Data Attributes
+
+Applied to control element for styling:
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-disabled | Slider is disabled |
+| data-horizontal | Orientation is horizontal |
+| data-vertical | Orientation is vertical |
+
+Applied to individual elements via `data-slot`:
+- `data-slot="slider"` - Root element
+- `data-slot="slider-track"` - Track element
+- `data-slot="slider-range"` - Filled indicator
+- `data-slot="slider-thumb"` - Draggable thumb(s)
+
+## Examples
+
+### Basic Single Value
+
+```tsx
+function VolumeControl() {
+  return (
+    <div className="space-y-2">
+      <label>Volume</label>
+      <Slider defaultValue={[50]} min={0} max={100} />
+    </div>
+  )
+}
+```
+
+### Controlled with Display
+
+```tsx
+function RateLimitControl() {
+  const [value, setValue] = useState([60])
+
+  return (
+    <div className="space-y-2">
+      <div className="flex justify-between">
+        <label>Requests per minute</label>
+        <span className="font-mono">{value[0]}</span>
+      </div>
+      <Slider
+        value={value}
+        onValueChange={(v) => setValue(Array.isArray(v) ? [...v] : [v])}
+        min={10}
+        max={200}
+        step={10}
+      />
+    </div>
+  )
+}
+```
+
+### Range Selection
+
+```tsx
+function PriceRangeFilter() {
+  const [range, setRange] = useState([25, 75])
+
+  return (
+    <div className="space-y-2">
+      <label>Price Range: ${range[0]} - ${range[1]}</label>
+      <Slider
+        value={range}
+        onValueChange={(v) => setRange(Array.isArray(v) ? [...v] : [v])}
+        min={0}
+        max={100}
+        step={5}
+      />
+    </div>
+  )
+}
+```
+
+### With Step Increments
+
+```tsx
+<Slider
+  defaultValue={[50]}
+  min={0}
+  max={100}
+  step={25}
+/>
+```
+
+### Vertical Orientation
+
+```tsx
+<div className="h-48">
+  <Slider
+    defaultValue={[50]}
+    min={0}
+    max={100}
+    orientation="vertical"
+  />
+</div>
+```
+
+### Multiple Thresholds
+
+```tsx
+function AlertThresholds() {
+  const [thresholds, setThresholds] = useState([25, 50, 75])
+
+  return (
+    <div className="space-y-2">
+      <label>Alert Levels: {thresholds.join(', ')}</label>
+      <Slider
+        value={thresholds}
+        onValueChange={(v) => setThresholds(Array.isArray(v) ? [...v] : [v])}
+        min={0}
+        max={100}
+        step={5}
+      />
+    </div>
+  )
+}
+```
+
+### Disabled State
+
+```tsx
+<Slider
+  defaultValue={[50]}
+  min={0}
+  max={100}
+  disabled
+/>
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Arrow Left/Down | Decrease value by `step` |
+| Arrow Right/Up | Increase value by `step` |
+| Page Down | Decrease by `largeStep` (default 10) |
+| Page Up | Increase by `largeStep` (default 10) |
+| Shift + Arrow | Increase/decrease by `largeStep` |
+| Home | Set to minimum value |
+| End | Set to maximum value |
+| Tab | Focus next thumb |
+| Shift + Tab | Focus previous thumb |
+
+## Accessibility
+
+- Uses ARIA `slider` role with proper attributes
+- Announces current value, min, max, and orientation to screen readers
+- Full keyboard navigation support
+- Focus indicators on thumbs with hover/focus ring
+- Disabled state prevents interaction and reduces opacity
+- Touch-friendly with adequate thumb size (16px)
+
+## Related
+
+- [Input](./input.llm.md) - For precise numeric entry
+- [Select](./select.llm.md) - For discrete value selection
+- [RadioGroup](./radio-group.llm.md) - For choosing one option

package/llm/components/sonner.llm.md

@@ -0,0 +1,299 @@
+# Sonner (Toast Notifications)
+
+Toast notification system built on Sonner with themed icons and automatic color system integration.
+
+## Import
+
+```tsx
+import { Toaster, toast } from "@neynar/ui/sonner"
+```
+
+## Anatomy
+
+```tsx
+// Add once to your app root
+<Toaster position="bottom-right" />
+
+// Trigger toasts anywhere in your app
+toast.success("Saved successfully")
+toast.error("Failed to save")
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Toaster | Container component rendered once at app root. Manages all toast notifications. |
+| toast | Function API for triggering notifications. Includes type variants and promise handling. |
+
+## Props
+
+### Toaster
+
+Pre-configured toast container with custom icons and theme integration. Renders at the specified position and manages all active toasts.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| position | "top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right" | "bottom-right" | Screen position for toasts |
+| theme | "light" \| "dark" \| "system" | "system" | Color theme for toasts |
+| richColors | boolean | true | Enhanced colors for toast variants |
+| expand | boolean | false | Expand toasts on hover |
+| visibleToasts | number | 3 | Maximum visible toasts at once |
+| closeButton | boolean | false | Show close button on all toasts |
+| duration | number | 4000 | Default duration in milliseconds |
+| toastOptions | object | - | Global toast styling options |
+
+### toast Function API
+
+Function for triggering toast notifications. Available variants:
+
+```tsx
+// Basic toast
+toast("Message")
+
+// Type variants
+toast.success("Success message")
+toast.error("Error message")
+toast.warning("Warning message")
+toast.info("Info message")
+toast.loading("Loading...")
+
+// Promise handling
+toast.promise(promise, {
+  loading: "Loading...",
+  success: "Success!",
+  error: "Failed"
+})
+```
+
+### Toast Options
+
+All toast functions accept an optional second parameter with these options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| description | string | Secondary text below the title |
+| duration | number | Override default duration (milliseconds) |
+| icon | ReactNode | Custom icon (replaces default) |
+| action | { label: string, onClick: () => void } | Primary action button |
+| cancel | { label: string, onClick: () => void } | Secondary cancel button |
+| id | string | Custom toast ID for updates |
+| position | string | Override global position |
+| dismissible | boolean | Allow manual dismissal (default: true) |
+| onDismiss | () => void | Callback when dismissed |
+| onAutoClose | () => void | Callback when auto-closed |
+
+## Customizations
+
+### Custom Icons
+
+Default icons are automatically provided:
+- Success: `CircleCheckIcon`
+- Error: `OctagonXIcon`
+- Warning: `TriangleAlertIcon`
+- Info: `InfoIcon`
+- Loading: `Loader2Icon` (animated)
+
+Override with the `icon` option:
+
+```tsx
+toast.success("Copied!", {
+  icon: <CopyIcon className="size-4" />
+})
+```
+
+### Theme Integration
+
+Toasts automatically integrate with your theme's CSS variables:
+- Uses `--popover` colors for normal toasts
+- Uses `--success`, `--destructive`, `--warning`, `--info` for variants
+- Applies `--radius` for border radius
+- Includes backdrop blur effect
+
+### Styling
+
+Customize appearance via `toastOptions`:
+
+```tsx
+<Toaster
+  toastOptions={{
+    classNames: {
+      toast: "custom-toast-class",
+      title: "custom-title-class",
+      description: "custom-description-class"
+    },
+    style: {
+      background: "var(--custom-bg)",
+      border: "1px solid var(--custom-border)"
+    }
+  }}
+/>
+```
+
+## Examples
+
+### Basic Usage
+
+```tsx
+function SaveButton() {
+  const handleSave = async () => {
+    try {
+      await saveData()
+      toast.success("Data saved successfully")
+    } catch (error) {
+      toast.error("Failed to save data")
+    }
+  }
+
+  return <Button onClick={handleSave}>Save</Button>
+}
+```
+
+### With Description
+
+```tsx
+toast.error("Failed to save", {
+  description: "Please check your internet connection and try again"
+})
+```
+
+### With Action Button
+
+```tsx
+toast.success("File uploaded", {
+  description: "Your file has been uploaded successfully",
+  action: {
+    label: "View",
+    onClick: () => router.push("/files")
+  }
+})
+```
+
+### With Both Actions
+
+```tsx
+toast.success("Changes saved", {
+  description: "Do you want to publish these changes now?",
+  action: {
+    label: "Publish",
+    onClick: () => publishChanges()
+  },
+  cancel: {
+    label: "Later",
+    onClick: () => console.log("Cancelled")
+  }
+})
+```
+
+### Promise Handling
+
+```tsx
+function CreateButton() {
+  const handleCreate = () => {
+    const promise = createAPIKey()
+
+    toast.promise(promise, {
+      loading: "Creating API key...",
+      success: "API key created successfully",
+      error: "Failed to create API key"
+    })
+  }
+
+  return <Button onClick={handleCreate}>Create Key</Button>
+}
+```
+
+### Promise with Dynamic Messages
+
+```tsx
+toast.promise(fetchUser(), {
+  loading: "Loading user...",
+  success: (data) => ({
+    message: `Welcome ${data.name}!`,
+    description: data.email,
+    duration: 5000
+  }),
+  error: (error) => ({
+    message: "Failed to load user",
+    description: error.message
+  })
+})
+```
+
+### Loading State Management
+
+```tsx
+function RegenerateButton() {
+  const handleRegenerate = async () => {
+    const toastId = toast.loading("Regenerating API key...", {
+      description: "This may take a few seconds"
+    })
+
+    try {
+      const newKey = await regenerateKey()
+      toast.success("API key regenerated", {
+        id: toastId, // Updates existing toast
+        description: "Your old key has been invalidated"
+      })
+    } catch (error) {
+      toast.error("Failed to regenerate", {
+        id: toastId
+      })
+    }
+  }
+
+  return <Button onClick={handleRegenerate}>Regenerate</Button>
+}
+```
+
+### Custom Duration
+
+```tsx
+// Short notification (2 seconds)
+toast.success("Copied!", { duration: 2000 })
+
+// Long notification (10 seconds)
+toast.warning("Important update", { duration: 10000 })
+
+// Persistent until dismissed
+toast.info("Review required", { duration: Infinity })
+```
+
+### Multiple Positions
+
+```tsx
+// Override global position per toast
+toast.success("Top notification", { position: "top-center" })
+toast.error("Bottom notification", { position: "bottom-left" })
+```
+
+### Stack Multiple Toasts
+
+```tsx
+function showBatch() {
+  toast.success("First notification")
+  setTimeout(() => toast.info("Second notification"), 200)
+  setTimeout(() => toast.warning("Third notification"), 400)
+}
+```
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| Escape | Dismiss all toasts |
+| Swipe | Dismiss individual toast (touch devices) |
+
+## Accessibility
+
+- ARIA live regions announce toast messages to screen readers
+- Toasts are automatically announced with appropriate politeness level based on type
+- Keyboard accessible dismissal with Escape key
+- Focus management preserves user context
+- Action buttons are keyboard navigable
+
+## Related
+
+- [Alert](./alert.llm.md) - Static inline notifications
+- [Alert Dialog](./alert-dialog.llm.md) - Modal confirmations
+- [Dialog](./dialog.llm.md) - Modal dialogs

package/llm/components/spinner.llm.md

@@ -0,0 +1,187 @@
+# Spinner
+
+Animated loading spinner for indicating processing states and asynchronous operations.
+
+## Import
+
+```tsx
+import { Spinner } from "@neynar/ui/spinner"
+```
+
+## Anatomy
+
+```tsx
+<Spinner />
+```
+
+## Props
+
+Extends all standard SVG element props (`React.ComponentProps<"svg">`), including `className`, `aria-*`, and SVG attributes.
+
+### Common Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Custom CSS classes. Default size is `size-4` (16px) |
+| color | string | - | Icon color (inherits from text color by default) |
+| size | number \| string | - | Icon size in pixels or as string |
+| strokeWidth | number \| string | - | Stroke width for the icon |
+
+### Built-in Attributes
+
+- `role="status"` - Announces loading state to screen readers
+- `aria-label="Loading"` - Provides accessible label
+- `animate-spin` - Continuous rotation animation
+
+## Sizing
+
+Use Tailwind size utilities via `className`:
+
+```tsx
+// Extra small (12px)
+<Spinner className="size-3" />
+
+// Small/Default (16px)
+<Spinner className="size-4" />
+
+// Medium (24px)
+<Spinner className="size-6" />
+
+// Large (32px)
+<Spinner className="size-8" />
+
+// Extra large (48px)
+<Spinner className="size-12" />
+```
+
+## Examples
+
+### Basic Loading Indicator
+
+```tsx
+<div className="flex items-center justify-center">
+  <Spinner className="size-8" />
+</div>
+```
+
+### With Loading Text
+
+```tsx
+<div className="flex flex-col items-center gap-3">
+  <Spinner className="size-8" />
+  <p className="text-sm text-muted-foreground">Loading content...</p>
+</div>
+```
+
+### In Button (Loading State)
+
+```tsx
+<Button disabled>
+  <Spinner data-icon="inline-start" />
+  Loading...
+</Button>
+```
+
+The `data-icon="inline-start"` attribute uses Button's internal spacing for icons at the start position.
+
+### Small Button
+
+```tsx
+<Button size="sm" disabled>
+  <Spinner data-icon="inline-start" className="size-3.5" />
+  Saving...
+</Button>
+```
+
+### Inline with Text
+
+```tsx
+<div className="flex items-center gap-2">
+  <Spinner className="size-4" />
+  <span className="text-sm">Syncing with Farcaster network...</span>
+</div>
+```
+
+### Custom Colors
+
+```tsx
+// Primary color
+<Spinner className="size-6 text-primary" />
+
+// Custom color
+<Spinner className="size-6 text-blue-600" />
+
+// Destructive
+<Spinner className="size-6 text-destructive" />
+
+// Muted
+<Spinner className="size-6 text-muted-foreground" />
+```
+
+### Full-Page Loading
+
+```tsx
+<div className="flex min-h-[400px] items-center justify-center">
+  <Spinner className="size-12" />
+</div>
+```
+
+### Card Loading State
+
+```tsx
+<Card>
+  <CardContent className="flex min-h-[200px] flex-col items-center justify-center gap-3">
+    <Spinner className="size-8" />
+    <p className="text-sm text-muted-foreground">Loading activity feed...</p>
+  </CardContent>
+</Card>
+```
+
+### Conditional Loading with Success State
+
+```tsx
+function DataLoader() {
+  const [status, setStatus] = useState<"loading" | "success">("loading")
+
+  return (
+    <Button onClick={handleLoad} disabled={status === "loading"}>
+      {status === "loading" ? (
+        <Spinner data-icon="inline-start" />
+      ) : (
+        <CheckCircle2Icon data-icon="inline-start" className="text-green-600" />
+      )}
+      {status === "loading" ? "Loading..." : "Fetch Data"}
+    </Button>
+  )
+}
+```
+
+## Size Reference
+
+| Class | Pixels | Use Case |
+|-------|--------|----------|
+| `size-3` | 12px | Extra small buttons, tight spaces |
+| `size-4` | 16px | Default, inline text, small buttons |
+| `size-6` | 24px | Medium buttons, prominent indicators |
+| `size-8` | 32px | Large buttons, card loading states |
+| `size-12` | 48px | Full page loading, empty states |
+
+## Accessibility
+
+- Built-in `role="status"` for ARIA live region announcement
+- `aria-label="Loading"` provides screen reader context
+- Animation respects `prefers-reduced-motion` when configured
+- Color contrast should meet WCAG AA standards (use appropriate text colors)
+
+## Implementation Notes
+
+- Uses Lucide's `Loader2Icon` component
+- Animated via Tailwind's `animate-spin` utility
+- Inherits text color by default for easy theming
+- SVG renders inline for optimal performance
+- No additional JavaScript runtime overhead
+
+## Related
+
+- [Button](./button.llm.md) - Often used with Spinner for loading states
+- [Skeleton](./skeleton.llm.md) - Alternative loading indicator for content placeholders