@neynar/ui 1.0.1 → 1.0.3

package/llm/components/field.llm.md

@@ -0,0 +1,303 @@
+# Field
+
+Comprehensive form field system with labels, descriptions, error handling, and flexible layouts for building accessible forms.
+
+## Import
+
+```tsx
+import {
+  Field,
+  FieldLabel,
+  FieldContent,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldSet,
+  FieldLegend,
+  FieldSeparator,
+  FieldTitle,
+} from "@neynar/ui/field"
+```
+
+## Anatomy
+
+```tsx
+<Field orientation="vertical" data-invalid={hasError}>
+  <FieldLabel htmlFor="input-id">Label Text</FieldLabel>
+  <FieldContent>
+    <Input id="input-id" />
+    <FieldDescription>Helper text</FieldDescription>
+    <FieldError errors={errors} />
+  </FieldContent>
+</Field>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Field | Base field wrapper with orientation support |
+| FieldLabel | Label for the field input |
+| FieldContent | Container for input + description + error |
+| FieldDescription | Helper text providing context |
+| FieldError | Error message display with auto-deduplication |
+| FieldGroup | Container for multiple related fields |
+| FieldSet | Semantic fieldset container for field groups |
+| FieldLegend | Legend for FieldSet with variant styles |
+| FieldSeparator | Visual separator between field sections |
+| FieldTitle | Title text for checkbox/switch fields |
+
+## Props
+
+### Field
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| orientation | "vertical" \| "horizontal" \| "responsive" | "vertical" | Layout orientation |
+| data-invalid | boolean | - | Apply error styling when true |
+| data-disabled | boolean | - | Apply disabled styling when true |
+
+### FieldLabel
+
+Extends Label component. Use `htmlFor` to associate with input.
+
+### FieldContent
+
+Container with consistent spacing for input + description + error.
+
+### FieldDescription
+
+Helper text automatically styled for placement. Supports links with underline styling.
+
+### FieldError
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| errors | Array<{ message?: string }> | - | Error objects to display |
+| children | ReactNode | - | Custom error content |
+
+Automatically deduplicates errors by message. Shows single error as text, multiple errors as bulleted list.
+
+### FieldGroup
+
+Container for multiple fields with consistent spacing. Provides `@container/field-group` for responsive layouts.
+
+### FieldSet
+
+Semantic `<fieldset>` element for grouping related fields. Use with FieldLegend.
+
+### FieldLegend
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | "legend" \| "label" | "legend" | Visual style variant |
+
+### FieldSeparator
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | ReactNode | - | Optional label text on separator |
+
+### FieldTitle
+
+Title text for fields with embedded controls (checkboxes, switches). Use inside FieldLabel.
+
+## Orientation Variants
+
+| Variant | Behavior |
+|---------|----------|
+| vertical | Label and input stacked vertically (default) |
+| horizontal | Label and input side by side |
+| responsive | Vertical on mobile, horizontal on larger screens (requires FieldGroup) |
+
+## Data Attributes
+
+| Attribute | When Present | Used For |
+|-----------|--------------|----------|
+| data-invalid | Field has errors | Error styling |
+| data-disabled | Field is disabled | Disabled styling |
+| data-orientation | Always | Current orientation value |
+| data-slot | Always | Component identification |
+
+## Examples
+
+### Basic Field
+
+```tsx
+<Field>
+  <FieldLabel htmlFor="username">Username</FieldLabel>
+  <Input id="username" placeholder="Enter username" />
+</Field>
+```
+
+### Field with Description
+
+```tsx
+<Field>
+  <FieldLabel htmlFor="email">Email Address</FieldLabel>
+  <FieldContent>
+    <Input id="email" type="email" placeholder="your@email.com" />
+    <FieldDescription>We'll never share your email</FieldDescription>
+  </FieldContent>
+</Field>
+```
+
+### Field with Error State
+
+```tsx
+const [errors, setErrors] = useState({ email: { message: "Invalid email" } })
+
+<Field data-invalid={!!errors.email}>
+  <FieldLabel htmlFor="email">Email *</FieldLabel>
+  <FieldContent>
+    <Input
+      id="email"
+      type="email"
+      aria-invalid={!!errors.email}
+    />
+    <FieldError errors={[errors.email]} />
+  </FieldContent>
+</Field>
+```
+
+### Horizontal Layout with Switch
+
+```tsx
+<Field orientation="horizontal">
+  <FieldLabel htmlFor="notifications">
+    <Switch id="notifications" />
+    <div>
+      <FieldTitle>Enable Notifications</FieldTitle>
+      <FieldDescription>Receive email updates</FieldDescription>
+    </div>
+  </FieldLabel>
+</Field>
+```
+
+### Grouped Fields with Separator
+
+```tsx
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="name">Name</FieldLabel>
+    <Input id="name" />
+  </Field>
+
+  <FieldSeparator>Security Settings</FieldSeparator>
+
+  <Field>
+    <FieldLabel htmlFor="password">Password</FieldLabel>
+    <Input id="password" type="password" />
+  </Field>
+</FieldGroup>
+```
+
+### Field Set with Radio Group
+
+```tsx
+<FieldSet>
+  <FieldLegend variant="label">Event Type</FieldLegend>
+  <FieldGroup>
+    <RadioGroup value={value} onValueChange={setValue}>
+      <Field orientation="horizontal">
+        <FieldLabel htmlFor="option-1">
+          <RadioGroupItem value="option1" id="option-1" />
+          <div>
+            <FieldTitle>Option One</FieldTitle>
+            <FieldDescription>First choice description</FieldDescription>
+          </div>
+        </FieldLabel>
+      </Field>
+
+      <Field orientation="horizontal">
+        <FieldLabel htmlFor="option-2">
+          <RadioGroupItem value="option2" id="option-2" />
+          <div>
+            <FieldTitle>Option Two</FieldTitle>
+            <FieldDescription>Second choice description</FieldDescription>
+          </div>
+        </FieldLabel>
+      </Field>
+    </RadioGroup>
+  </FieldGroup>
+</FieldSet>
+```
+
+### Multiple Errors
+
+```tsx
+<Field data-invalid={true}>
+  <FieldLabel htmlFor="password">Password</FieldLabel>
+  <FieldContent>
+    <Input id="password" type="password" aria-invalid={true} />
+    <FieldError
+      errors={[
+        { message: "Must be at least 8 characters" },
+        { message: "Must contain a number" },
+        { message: "Must contain a special character" },
+      ]}
+    />
+  </FieldContent>
+</Field>
+```
+
+### Responsive Layout
+
+```tsx
+<FieldGroup>
+  <Field orientation="responsive">
+    <FieldLabel htmlFor="phone">Phone Number</FieldLabel>
+    <FieldContent>
+      <Input id="phone" placeholder="+1 (555) 123-4567" />
+      <FieldDescription>
+        Vertical on mobile, horizontal on larger screens
+      </FieldDescription>
+    </FieldContent>
+  </Field>
+</FieldGroup>
+```
+
+### Disabled Field
+
+```tsx
+<Field data-disabled={true}>
+  <FieldLabel htmlFor="readonly">Read Only Field</FieldLabel>
+  <FieldContent>
+    <Input
+      id="readonly"
+      disabled
+      defaultValue="Cannot edit"
+    />
+    <FieldDescription>This field cannot be modified</FieldDescription>
+  </FieldContent>
+</Field>
+```
+
+## Accessibility
+
+- Uses semantic HTML elements (`fieldset`, `legend`, `label`)
+- FieldError uses `role="alert"` for screen reader announcements
+- Supports `aria-invalid` on inputs for error states
+- FieldLabel properly associates with inputs via `htmlFor`
+- FieldDescription provides additional context without cluttering labels
+- Disabled state reduces opacity for visual indication
+
+## Best Practices
+
+- Always use `htmlFor` on FieldLabel to associate with input `id`
+- Set `data-invalid` on Field and `aria-invalid` on input for error states
+- Use FieldContent when you have description or error messages
+- For checkbox/switch fields, use horizontal orientation with FieldTitle
+- Use FieldSet/FieldLegend for semantically related field groups
+- Use FieldGroup for visual grouping without semantic fieldset
+- Set `data-disabled` on Field when input is disabled
+- Use FieldSeparator to organize long forms into sections
+
+## Related
+
+- [Input](./input.llm.md) - Text input component
+- [Textarea](./textarea.llm.md) - Multi-line text input
+- [Checkbox](./checkbox.llm.md) - Checkbox input
+- [Switch](./switch.llm.md) - Toggle switch
+- [Radio Group](./radio-group.llm.md) - Radio button group
+- [Label](./label.llm.md) - Base label component

package/llm/components/first-light.llm.md

@@ -0,0 +1,129 @@
+# First Light
+
+SVG filter component that enables hand-drawn wobble effects for the First Light theme.
+
+## Import
+
+```tsx
+import { FirstLightFilters } from "@neynar/ui/first-light"
+```
+
+## Usage
+
+Render once in your root layout when using the First Light theme:
+
+```tsx
+// app/layout.tsx
+import "@neynar/ui/themes/first-light";
+import { FirstLightFilters } from "@neynar/ui/first-light";
+import { ColorModeInitializer } from "@neynar/ui/color-mode";
+
+export default function Layout({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <ColorModeInitializer />
+      </head>
+      <body>
+        <FirstLightFilters />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+## Props
+
+No props. Zero configuration.
+
+## How It Works
+
+Renders an invisible SVG containing `<filter>` definitions that create displacement effects using fractal noise. The First Light theme CSS references these filters via `filter: url(#first-light-filter)`.
+
+Without this component, the theme works but edges are straight instead of wobbly.
+
+## Filter Definitions
+
+| Filter ID | Effect | Use Case |
+|-----------|--------|----------|
+| `#first-light-filter` | Standard wobble | Default, applied to most components |
+| `#first-light-filter-light` | Subtle wobble | Barely noticeable, for delicate elements |
+| `#first-light-filter-heavy` | Pronounced wobble | More dramatic hand-drawn effect |
+
+### Filter Parameters
+
+| Filter | Base Frequency | Octaves | Scale |
+|--------|----------------|---------|-------|
+| Standard | 0.015 | 2 | 1.5 |
+| Light | 0.006 | 1 | 0.4 |
+| Heavy | 0.012 | 3 | 1.5 |
+
+## CSS Classes
+
+The First Light theme provides utility classes to apply filters:
+
+```tsx
+// Apply heavier wobble
+<Card className="first-light-heavy">...</Card>
+
+// Apply lighter wobble
+<Button className="first-light-light">Subtle</Button>
+```
+
+| Class | Effect |
+|-------|--------|
+| `.first-light-light` | Applies `#first-light-filter-light` |
+| `.first-light-heavy` | Applies `#first-light-filter-heavy` |
+
+## Technical Details
+
+```tsx
+// The component renders this (simplified):
+<svg aria-hidden="true" style={{ position: "absolute", width: 0, height: 0 }}>
+  <defs>
+    <filter id="first-light-filter">
+      <feTurbulence type="fractalNoise" baseFrequency="0.015" numOctaves="2" />
+      <feDisplacementMap scale="1.5" xChannelSelector="R" yChannelSelector="G" />
+    </filter>
+    {/* + light and heavy variants */}
+  </defs>
+</svg>
+```
+
+- Uses `feTurbulence` for organic noise generation
+- Uses `feDisplacementMap` to distort element edges
+- Each filter uses different seed for variety
+- Filter extends beyond element bounds (x="-3%" etc.) to avoid clipping
+
+## Theme Integration
+
+The First Light theme automatically applies filters to components via CSS:
+
+```css
+/* In first-light.css */
+.theme-first-light [data-slot="card"],
+.theme-first-light [data-slot="button"],
+/* ... etc ... */ {
+  filter: url(#first-light-filter);
+}
+```
+
+## Performance
+
+- SVG is hidden and takes no layout space
+- Filters are GPU-accelerated in modern browsers
+- Minimal memory footprint (single SVG with 3 filters)
+- No runtime JavaScript after initial render
+
+## Accessibility
+
+- SVG has `aria-hidden="true"`
+- Purely decorative - no impact on screen readers
+- Does not affect content readability
+- Motion-safe (no animation)
+
+## Related
+
+- [Theming](../theming.llm.md) - Full theming documentation
+- First Light theme: `@neynar/ui/themes/first-light`

package/llm/components/hover-card.llm.md

@@ -0,0 +1,278 @@
+# HoverCard
+
+Displays rich preview content when hovering over a trigger element.
+
+## Import
+
+```tsx
+import { HoverCard, HoverCardTrigger, HoverCardContent } from "@neynar/ui/hover-card"
+```
+
+## Anatomy
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger>
+    <a href="#">Hover over me</a>
+  </HoverCardTrigger>
+  <HoverCardContent>
+    Preview content appears here
+  </HoverCardContent>
+</HoverCard>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| HoverCard | Root container, manages hover state and timing |
+| HoverCardTrigger | Element that triggers the hover card (link, button, text, avatar) |
+| HoverCardContent | Content container with automatic portal, positioning, and animations |
+
+## Props
+
+### HoverCard
+
+Inherits all props from `@base-ui/react/preview-card` Root component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| open | boolean | - | Controlled open state |
+| defaultOpen | boolean | false | Uncontrolled initial open state |
+| onOpenChange | (open: boolean) => void | - | Called when open state changes |
+
+### HoverCardTrigger
+
+Inherits all props from `@base-ui/react/preview-card` Trigger component.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| render | ReactElement \| function | - | Custom element or render function for the trigger |
+
+The `render` prop accepts a ReactElement or function for customization:
+
+```tsx
+// As a ReactElement
+<HoverCardTrigger render={<Button variant="outline">Hover</Button>}>
+  Content
+</HoverCardTrigger>
+
+// As a function
+<HoverCardTrigger render={(props) => <a {...props} href="#">Link</a>}>
+  Content
+</HoverCardTrigger>
+```
+
+### HoverCardContent
+
+Automatically renders portal and positioner. Combines props from Popup and Positioner components.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| side | "top" \| "right" \| "bottom" \| "left" | "bottom" | Which side of trigger to position the card |
+| sideOffset | number | 4 | Distance from trigger in pixels |
+| align | "start" \| "center" \| "end" | "center" | How to align relative to the trigger |
+| alignOffset | number | 4 | Additional alignment axis offset in pixels |
+| className | string | - | Custom CSS classes (merged with defaults) |
+| initialFocus | boolean \| RefObject \| function | - | Element to focus when opened |
+| finalFocus | boolean \| RefObject \| function | - | Element to focus when closed |
+
+## Data Attributes
+
+Use these for custom styling and animations:
+
+| Attribute | When Present | Description |
+|-----------|--------------|-------------|
+| data-open | Card is open | Apply open state styles |
+| data-closed | Card is closed | Apply closed state styles |
+| data-side | Always | Value: "top" \| "right" \| "bottom" \| "left" |
+| data-align | Always | Value: "start" \| "center" \| "end" |
+| data-starting-style | Opening animation | Initial animation state |
+| data-ending-style | Closing animation | Final animation state |
+
+## Examples
+
+### User Profile Preview
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger>
+    <button className="inline-flex items-center gap-2">
+      <Avatar size="sm">
+        <AvatarImage src="/user.jpg" />
+        <AvatarFallback>DR</AvatarFallback>
+      </Avatar>
+      <span className="font-medium">@dwr</span>
+    </button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-80">
+    <div className="space-y-3">
+      <div className="flex items-start justify-between">
+        <div className="flex items-center gap-3">
+          <Avatar size="lg">
+            <AvatarImage src="/user.jpg" />
+            <AvatarFallback>DR</AvatarFallback>
+          </Avatar>
+          <div>
+            <p className="font-semibold">Dan Romero</p>
+            <p className="text-muted-foreground text-sm">@dwr</p>
+          </div>
+        </div>
+        <Button size="sm">Follow</Button>
+      </div>
+      <p className="text-sm">
+        Building Farcaster and Warpcast. Previously VP Eng at Coinbase.
+      </p>
+      <div className="flex items-center gap-4 text-sm">
+        <div>
+          <span className="font-semibold">124.5K</span>{" "}
+          <span className="text-muted-foreground">followers</span>
+        </div>
+        <div>
+          <span className="font-semibold">428</span>{" "}
+          <span className="text-muted-foreground">following</span>
+        </div>
+      </div>
+    </div>
+  </HoverCardContent>
+</HoverCard>
+```
+
+### Simple Text Preview
+
+```tsx
+<p>
+  Learn more about{" "}
+  <HoverCard>
+    <HoverCardTrigger>
+      <a href="#" className="text-primary hover:underline">
+        typography
+      </a>
+    </HoverCardTrigger>
+    <HoverCardContent>
+      <p className="text-sm">
+        Typography is the art and science of arranging type to make written
+        language clear, visually appealing, and effective.
+      </p>
+    </HoverCardContent>
+  </HoverCard>
+  {" "}in design.
+</p>
+```
+
+### Positioned Above with Custom Width
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger>
+    <Badge variant="secondary" className="cursor-pointer">
+      React 19
+    </Badge>
+  </HoverCardTrigger>
+  <HoverCardContent side="top" className="w-96">
+    <div className="space-y-2">
+      <h4 className="text-sm font-semibold">React 19</h4>
+      <p className="text-muted-foreground text-xs leading-relaxed">
+        Latest version of React with improved concurrent rendering,
+        automatic batching, and new hooks for better performance.
+      </p>
+    </div>
+  </HoverCardContent>
+</HoverCard>
+```
+
+### Rich Content with Avatar and Actions
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger>
+    <Button variant="outline">Farcaster Protocol</Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-72">
+    <div className="space-y-3">
+      <div className="flex items-start gap-3">
+        <Avatar size="sm">
+          <AvatarFallback>FC</AvatarFallback>
+        </Avatar>
+        <div className="flex-1 space-y-1">
+          <h4 className="text-sm font-semibold">Farcaster Protocol</h4>
+          <p className="text-muted-foreground text-xs">
+            A sufficiently decentralized social network.
+          </p>
+        </div>
+      </div>
+      <div className="flex gap-2">
+        <Button size="xs" variant="secondary">Learn More</Button>
+        <Button size="xs" variant="outline">Documentation</Button>
+      </div>
+    </div>
+  </HoverCardContent>
+</HoverCard>
+```
+
+### Multiple Triggers in Feed
+
+```tsx
+<div className="space-y-4">
+  {posts.map((post) => (
+    <div key={post.id} className="border rounded-lg p-4">
+      <div className="mb-2 flex items-center gap-2">
+        <HoverCard>
+          <HoverCardTrigger>
+            <button className="inline-flex items-center gap-2">
+              <Avatar size="sm">
+                <AvatarImage src={post.author.avatar} />
+                <AvatarFallback>{post.author.initials}</AvatarFallback>
+              </Avatar>
+              <span className="font-medium hover:underline">
+                @{post.author.username}
+              </span>
+            </button>
+          </HoverCardTrigger>
+          <HoverCardContent className="w-80">
+            <UserProfilePreview user={post.author} />
+          </HoverCardContent>
+        </HoverCard>
+        <span className="text-muted-foreground text-sm">{post.time}</span>
+      </div>
+      <p className="text-sm">{post.content}</p>
+    </div>
+  ))}
+</div>
+```
+
+## Keyboard
+
+HoverCard is primarily mouse/touch interaction, but keyboard navigation is supported:
+
+| Key | Action |
+|-----|--------|
+| Hover | Open hover card after delay |
+| Mouse leave | Close hover card after delay |
+| Tab | Navigate through interactive elements inside content |
+| Escape | Close hover card immediately |
+
+## Accessibility
+
+- Automatically manages focus when opening/closing
+- Content is rendered in a portal to avoid z-index issues
+- Uses ARIA attributes for screen reader support
+- Supports keyboard navigation for interactive content
+- Trigger remains accessible and keyboard-navigable
+- Respects user's motion preferences for animations
+
+## Styling Notes
+
+- Default width is `w-64` (256px), customize with `className`
+- Uses frosted glass effect with `bg-popover` at 75% opacity and backdrop blur
+- Includes entry/exit animations via data attributes
+- Side-specific slide animations (slides from opposite direction)
+- Respects `--transform-origin` CSS variable for proper animation origins
+- Compatible with all themes (classic, frosted, sketch)
+
+## Related
+
+- [Tooltip](/components/tooltip.llm.md) - For simple text hints (non-interactive)
+- [Popover](/components/popover.llm.md) - For click-triggered interactive content
+- [Dialog](/components/dialog.llm.md) - For modal overlays
+- [Avatar](/components/avatar.llm.md) - Commonly used in hover card triggers