@neynar/ui 1.0.0 → 1.0.2

package/llm/components/checkbox.llm.md

@@ -0,0 +1,234 @@
+# Checkbox
+
+Binary selection component for forms, settings, and multi-select interfaces.
+
+## Import
+
+```tsx
+import { Checkbox } from "@neynar/ui/checkbox"
+```
+
+## Anatomy
+
+```tsx
+<Checkbox />
+```
+
+The component includes a built-in indicator with check icon - no need for separate child components.
+
+## Props
+
+All Base UI Checkbox.Root props are supported. Common props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| checked | boolean | - | Controlled checked state |
+| defaultChecked | boolean | false | Initial checked state (uncontrolled) |
+| onCheckedChange | (checked: boolean) => void | - | Called when state changes |
+| disabled | boolean | false | Prevents user interaction |
+| required | boolean | false | Must be checked before form submission |
+| name | string | - | Form field name |
+| value | string | - | Form value when checked |
+| indeterminate | boolean | false | Show indeterminate/mixed state |
+| readOnly | boolean | false | Prevents state changes but shows value |
+
+### Styling Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| className | string | Additional CSS classes |
+
+## Data Attributes
+
+Use these for custom styling:
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-checked | Checkbox is checked |
+| data-unchecked | Checkbox is unchecked |
+| data-disabled | Component is disabled |
+| data-readonly | Component is readonly |
+| data-required | Field is required |
+| data-invalid | Validation failed (with Field) |
+| data-focused | Checkbox has focus |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<label className="flex items-center gap-2">
+  <Checkbox />
+  <span>Accept terms and conditions</span>
+</label>
+```
+
+### Controlled State
+
+```tsx
+function NewsletterSubscription() {
+  const [subscribed, setSubscribed] = useState(false)
+
+  return (
+    <label className="flex items-center gap-2">
+      <Checkbox
+        checked={subscribed}
+        onCheckedChange={(checked) => setSubscribed(checked as boolean)}
+      />
+      <span>Subscribe to newsletter</span>
+    </label>
+  )
+}
+```
+
+### With Label Component
+
+```tsx
+import { Label } from "@neynar/ui/label"
+
+<label className="flex items-center gap-2">
+  <Checkbox defaultChecked />
+  <Label>Enable notifications</Label>
+</label>
+```
+
+### With Description
+
+```tsx
+<label className="flex items-start gap-3">
+  <Checkbox defaultChecked />
+  <div className="flex-1">
+    <Label>Email notifications</Label>
+    <p className="text-muted-foreground text-xs">
+      Receive email updates about your account activity
+    </p>
+  </div>
+</label>
+```
+
+### Form Integration
+
+```tsx
+<form>
+  <fieldset className="space-y-3">
+    <legend className="text-sm font-medium">Preferences</legend>
+
+    <label className="flex items-center gap-2">
+      <Checkbox name="weekly-summary" defaultChecked />
+      <Label>Send weekly summaries</Label>
+    </label>
+
+    <label className="flex items-center gap-2">
+      <Checkbox name="dark-mode" />
+      <Label>Enable dark mode</Label>
+    </label>
+
+    <label className="flex items-center gap-2">
+      <Checkbox name="public-profile" required />
+      <Label>I accept the terms of service *</Label>
+    </label>
+  </fieldset>
+</form>
+```
+
+### Disabled State
+
+```tsx
+<label className="flex items-center gap-2">
+  <Checkbox disabled defaultChecked />
+  <Label>Admin access (requires Pro plan)</Label>
+</label>
+```
+
+### Permission Settings Example
+
+```tsx
+function APIPermissions() {
+  const [permissions, setPermissions] = useState({
+    readAccess: true,
+    writeAccess: false,
+    adminAccess: false,
+  })
+
+  const togglePermission = (key: keyof typeof permissions) => {
+    setPermissions(prev => ({ ...prev, [key]: !prev[key] }))
+  }
+
+  return (
+    <div className="space-y-3">
+      <label className="flex items-start gap-3">
+        <Checkbox
+          checked={permissions.readAccess}
+          onCheckedChange={() => togglePermission('readAccess')}
+        />
+        <div className="flex-1">
+          <Label>Read Access</Label>
+          <p className="text-muted-foreground text-xs">
+            Fetch casts, users, and channel data
+          </p>
+        </div>
+      </label>
+
+      <label className="flex items-start gap-3">
+        <Checkbox
+          checked={permissions.writeAccess}
+          onCheckedChange={() => togglePermission('writeAccess')}
+        />
+        <div className="flex-1">
+          <Label>Write Access</Label>
+          <p className="text-muted-foreground text-xs">
+            Publish casts and update profiles
+          </p>
+        </div>
+      </label>
+
+      <label className="flex items-start gap-3">
+        <Checkbox
+          checked={permissions.adminAccess}
+          onCheckedChange={() => togglePermission('adminAccess')}
+          disabled
+        />
+        <div className="flex-1">
+          <Label>Admin Access</Label>
+          <p className="text-muted-foreground text-xs">
+            Full administrative permissions (Enterprise only)
+          </p>
+        </div>
+      </label>
+    </div>
+  )
+}
+```
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| Space | Toggle checked state |
+| Enter | Toggle checked state (in forms) |
+| Tab | Move focus to next element |
+| Shift + Tab | Move focus to previous element |
+
+## Accessibility
+
+- Renders semantic HTML with hidden native checkbox input
+- Full keyboard navigation support
+- Proper ARIA attributes automatically applied
+- Works with form labels via native label element
+- Supports required field validation
+- Focus visible states for keyboard users
+
+## Styling Notes
+
+- Size: 16px × 16px (size-4)
+- Border radius: 4px
+- Checked state shows primary color background
+- Includes focus ring on keyboard focus
+- Disabled state reduces opacity to 50%
+- Peer class allows styling adjacent elements based on state
+
+## Related
+
+- [Label](./label.llm.md) - Accessible labels for form fields
+- [Switch](./switch.llm.md) - Alternative for on/off toggles
+- [Radio Group](./radio-group.llm.md) - Single selection from multiple options

package/llm/components/code.llm.md

@@ -0,0 +1,75 @@
+# Code
+
+Inline code component with monospace font and subtle background.
+
+## Import
+
+```tsx
+import { Code } from "@neynar/ui/typography"
+```
+
+## Usage
+
+```tsx
+<Text>
+  Use the <Code>useState</Code> hook for local state.
+</Text>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| color | "default" \| "muted" \| "subtle" \| "destructive" \| "success" \| "warning" \| "info" | "default" | Text color |
+| className | string | - | Additional CSS classes |
+
+## Examples
+
+### Basic
+
+```tsx
+<Code>npm install @neynar/ui</Code>
+```
+
+### Inline with Text
+
+```tsx
+<Text>
+  The <Code>Button</Code> component accepts a <Code>variant</Code> prop.
+</Text>
+```
+
+### With Colors
+
+```tsx
+<Code color="destructive">error.message</Code>
+<Code color="success">response.data</Code>
+```
+
+### In Lists
+
+```tsx
+<ul>
+  <li><Code>variant</Code> - Visual style</li>
+  <li><Code>size</Code> - Component size</li>
+  <li><Code>disabled</Code> - Disable interaction</li>
+</ul>
+```
+
+## Styling
+
+Default styling:
+- Monospace font (`font-mono`)
+- Small text size (`text-sm`)
+- Muted background (`bg-muted`)
+- Rounded corners
+- Horizontal padding
+
+## Note
+
+For multi-line code blocks with syntax highlighting, use a dedicated solution like `prism-react-renderer` or `shiki`.
+
+## Related
+
+- [Text](./text.llm.md) - Paragraph text
+- [Kbd](./kbd.llm.md) - Keyboard shortcuts

package/llm/components/collapsible.llm.md

@@ -0,0 +1,271 @@
+# Collapsible
+
+Expandable sections that show and hide content with smooth animations.
+
+## Import
+
+```tsx
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from "@neynar/ui/collapsible"
+```
+
+## Anatomy
+
+```tsx
+<Collapsible>
+  <CollapsibleTrigger />
+  <CollapsibleContent />
+</Collapsible>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Collapsible | Root container, manages open/closed state |
+| CollapsibleTrigger | Button that toggles the content visibility |
+| CollapsibleContent | Panel that shows/hides with animation |
+
+## Props
+
+### Collapsible
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| open | boolean | - | Controlled open state |
+| defaultOpen | boolean | - | Initial open state (uncontrolled) |
+| onOpenChange | (open: boolean, details: object) => void | - | Called when open state changes |
+| disabled | boolean | - | Disables all interactions |
+| className | string \| function | - | CSS class or function returning class based on state |
+| style | CSSProperties \| function | - | Style object or function returning styles based on state |
+| render | ReactElement \| function | - | Custom render element or function |
+
+### CollapsibleTrigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| nativeButton | boolean | true | Whether to render a native `<button>` element |
+| className | string \| function | - | CSS class or function returning class based on state |
+| style | CSSProperties \| function | - | Style object or function returning styles based on state |
+| render | ReactElement \| function | - | Custom render element or function |
+
+**Note**: Set `nativeButton={false}` if using `render` to replace with a non-button element (e.g., `<div>`).
+
+### CollapsibleContent
+
+Automatically animates height when opening/closing using CSS variables.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| keepMounted | boolean | false | Keep element in DOM when closed |
+| hiddenUntilFound | boolean | false | Enable browser's page search to find and expand content |
+| className | string \| function | - | CSS class or function returning class based on state |
+| style | CSSProperties \| function | - | Style object or function returning styles based on state |
+| render | ReactElement \| function | - | Custom render element or function |
+
+**Note**: `hiddenUntilFound` overrides `keepMounted` and uses `hidden="until-found"` attribute.
+
+### Render Prop
+
+All components support the `render` prop to customize the rendered element:
+
+```tsx
+<CollapsibleTrigger render={<Button variant="outline" />}>
+  Toggle Settings
+</CollapsibleTrigger>
+```
+
+## Data Attributes
+
+Use these for styling based on component state:
+
+| Attribute | When Present | Where |
+|-----------|--------------|-------|
+| data-panel-open | Collapsible is open | Trigger |
+| data-starting-style | Panel is animating in | Content |
+| data-ending-style | Panel is animating out | Content |
+
+## CSS Variables
+
+Available for custom animations:
+
+| Variable | Description | Where |
+|----------|-------------|-------|
+| --collapsible-panel-height | Current panel height | Content |
+| --collapsible-panel-width | Current panel width | Content |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<Collapsible defaultOpen>
+  <CollapsibleTrigger className="flex items-center justify-between border rounded-lg p-4">
+    <span>Click to toggle</span>
+    <ChevronDownIcon />
+  </CollapsibleTrigger>
+  <CollapsibleContent>
+    <div className="border-x border-b p-4">
+      Hidden content that slides open
+    </div>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Controlled State
+
+```tsx
+function Settings() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <div>
+      <Button onClick={() => setOpen(!open)}>Toggle</Button>
+
+      <Collapsible open={open} onOpenChange={setOpen}>
+        <CollapsibleTrigger>
+          Settings {open ? <ChevronUpIcon /> : <ChevronDownIcon />}
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <div>Advanced settings panel</div>
+        </CollapsibleContent>
+      </Collapsible>
+    </div>
+  )
+}
+```
+
+### Settings Panel with Icons
+
+```tsx
+<Collapsible>
+  <CollapsibleTrigger className="flex items-center justify-between border rounded-lg p-4">
+    <div className="flex items-center gap-3">
+      <div className="bg-primary/10 text-primary rounded-md p-2">
+        <SettingsIcon className="size-5" />
+      </div>
+      <div>
+        <p className="font-medium">API Settings</p>
+        <p className="text-sm text-muted-foreground">Configure rate limits</p>
+      </div>
+    </div>
+    <ChevronDownIcon className="size-5" />
+  </CollapsibleTrigger>
+  <CollapsibleContent>
+    <div className="border-x border-b p-4">
+      <Label htmlFor="rate-limit">Rate Limit</Label>
+      <Input id="rate-limit" type="number" defaultValue="10000" />
+    </div>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Multiple Independent Sections
+
+```tsx
+function AdvancedSettings() {
+  return (
+    <div className="space-y-3">
+      <Collapsible>
+        <CollapsibleTrigger className="w-full border rounded-lg p-4">
+          API Settings
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <div className="border-x border-b p-4">API configuration</div>
+        </CollapsibleContent>
+      </Collapsible>
+
+      <Collapsible>
+        <CollapsibleTrigger className="w-full border rounded-lg p-4">
+          Security
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <div className="border-x border-b p-4">Security settings</div>
+        </CollapsibleContent>
+      </Collapsible>
+    </div>
+  )
+}
+```
+
+### Nested Collapsibles
+
+```tsx
+<Collapsible defaultOpen>
+  <CollapsibleTrigger className="border rounded-lg p-4">
+    Integrations
+  </CollapsibleTrigger>
+  <CollapsibleContent>
+    <div className="border-x border-b p-4 space-y-2">
+      <Collapsible>
+        <CollapsibleTrigger className="border rounded p-3 text-sm">
+          Email Integration
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <div className="mt-1 border rounded p-3">
+            Configure email settings
+          </div>
+        </CollapsibleContent>
+      </Collapsible>
+
+      <Collapsible>
+        <CollapsibleTrigger className="border rounded p-3 text-sm">
+          Webhooks
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <div className="mt-1 border rounded p-3">
+            Configure webhooks
+          </div>
+        </CollapsibleContent>
+      </Collapsible>
+    </div>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Animated Chevron with Data Attributes
+
+```tsx
+<Collapsible>
+  <CollapsibleTrigger className="group border rounded-lg p-4">
+    <ChevronDownIcon className="transition-transform group-data-[panel-open]:rotate-180" />
+    Expand Section
+  </CollapsibleTrigger>
+  <CollapsibleContent>
+    <div className="border-x border-b p-4">Content</div>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Disabled State
+
+```tsx
+<Collapsible disabled>
+  <CollapsibleTrigger className="border rounded-lg p-4 opacity-50 cursor-not-allowed">
+    Disabled Section
+  </CollapsibleTrigger>
+  <CollapsibleContent>
+    <div className="border-x border-b p-4">Cannot be opened</div>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+## Keyboard
+
+| Key | Action |
+|-----|--------|
+| Space | Toggle when trigger is focused |
+| Enter | Toggle when trigger is focused |
+
+## Accessibility
+
+- Trigger automatically receives `role="button"` and proper ARIA attributes
+- Content visibility controlled with proper ARIA states
+- Focus management handled automatically
+- Keyboard navigation fully supported with Space/Enter keys
+- Use `hiddenUntilFound` prop to enable browser's Ctrl+F/Cmd+F page search to find and expand collapsed content
+
+## Related
+
+- [Accordion](/components/accordion.llm.md) - For mutually exclusive collapsible sections
+- [Dialog](/components/dialog.llm.md) - For modal content overlays
+- [Tabs](/components/tabs.llm.md) - For switching between different views