@neynar/ui 1.0.1 → 1.0.3

package/llm/components/switch.llm.md

@@ -0,0 +1,258 @@
+# Switch
+
+Toggle switch for binary on/off settings with keyboard support and form integration.
+
+## Import
+
+```tsx
+import { Switch } from "@neynar/ui/switch"
+```
+
+## Anatomy
+
+```tsx
+<Switch />
+```
+
+The Switch component is a single component that internally uses `Switch.Root` and `Switch.Thumb` from Base UI.
+
+## Props
+
+### Switch
+
+Extends all props from `Switch.Root.Props` from `@base-ui/react/switch`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| size | "sm" \| "default" | "default" | Size variant of the switch |
+| checked | boolean | - | Controlled checked state |
+| defaultChecked | boolean | false | Initial checked state (uncontrolled) |
+| onCheckedChange | (checked: boolean, eventDetails) => void | - | Called when checked state changes |
+| disabled | boolean | false | Disables interaction |
+| readOnly | boolean | false | Prevents state changes but allows focus |
+| required | boolean | false | Marks as required for form validation |
+| name | string | - | Form field name |
+| id | string | - | Element id for label association |
+| aria-invalid | boolean | - | Shows error styling for validation |
+| className | string | - | Additional CSS classes |
+
+## Sizes
+
+| Size | Dimensions | Use Case |
+|------|------------|----------|
+| sm | 14px × 24px | Compact layouts, dense settings panels |
+| default | 18.4px × 32px | Standard size for most use cases |
+
+## Data Attributes
+
+The following data attributes are automatically applied for styling:
+
+| Attribute | When Present |
+|-----------|--------------|
+| data-checked | Switch is on |
+| data-unchecked | Switch is off |
+| data-disabled | Switch is disabled |
+| data-size="sm" \| "default" | Current size variant |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { Switch } from "@neynar/ui/switch"
+import { Label } from "@neynar/ui/label"
+
+function Example() {
+  return (
+    <div className="flex items-center gap-3">
+      <Switch id="notifications" />
+      <Label htmlFor="notifications">Enable notifications</Label>
+    </div>
+  )
+}
+```
+
+### Controlled State
+
+```tsx
+import { useState } from "react"
+import { Switch } from "@neynar/ui/switch"
+import { Label } from "@neynar/ui/label"
+
+function ControlledExample() {
+  const [enabled, setEnabled] = useState(false)
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center gap-3">
+        <Switch
+          id="webhooks"
+          checked={enabled}
+          onCheckedChange={setEnabled}
+        />
+        <Label htmlFor="webhooks">Enable webhooks</Label>
+      </div>
+      <p className="text-sm text-muted-foreground">
+        Status: {enabled ? "Enabled" : "Disabled"}
+      </p>
+    </div>
+  )
+}
+```
+
+### Settings Panel
+
+```tsx
+import { Switch } from "@neynar/ui/switch"
+import { Label } from "@neynar/ui/label"
+
+function SettingsPanel() {
+  return (
+    <div className="border-border divide-border divide-y rounded-lg border">
+      <div className="flex items-center justify-between p-4">
+        <div className="space-y-0.5">
+          <Label htmlFor="email" className="text-sm font-medium">
+            Email Notifications
+          </Label>
+          <p className="text-muted-foreground text-xs">
+            Receive alerts about important updates
+          </p>
+        </div>
+        <Switch id="email" size="sm" defaultChecked />
+      </div>
+      <div className="flex items-center justify-between p-4">
+        <div className="space-y-0.5">
+          <Label htmlFor="marketing" className="text-sm font-medium">
+            Marketing Emails
+          </Label>
+          <p className="text-muted-foreground text-xs">
+            Product updates and announcements
+          </p>
+        </div>
+        <Switch id="marketing" size="sm" />
+      </div>
+    </div>
+  )
+}
+```
+
+### Form Integration
+
+```tsx
+import { Switch } from "@neynar/ui/switch"
+import { Label } from "@neynar/ui/label"
+
+function FormExample() {
+  return (
+    <form>
+      <div className="space-y-4">
+        <div className="flex items-center justify-between">
+          <Label htmlFor="terms" className="text-sm">
+            I agree to the terms and conditions
+          </Label>
+          <Switch id="terms" name="terms" required />
+        </div>
+        <button type="submit">Submit</button>
+      </div>
+    </form>
+  )
+}
+```
+
+### With Disabled State
+
+```tsx
+import { Switch } from "@neynar/ui/switch"
+import { Label } from "@neynar/ui/label"
+
+function DisabledExample() {
+  const [parentEnabled, setParentEnabled] = useState(false)
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between">
+        <Label htmlFor="main">Enable Feature</Label>
+        <Switch
+          id="main"
+          checked={parentEnabled}
+          onCheckedChange={setParentEnabled}
+        />
+      </div>
+      <div className="flex items-center justify-between">
+        <Label htmlFor="sub" className="text-muted-foreground">
+          Sub-option (requires feature)
+        </Label>
+        <Switch
+          id="sub"
+          size="sm"
+          disabled={!parentEnabled}
+          defaultChecked
+        />
+      </div>
+    </div>
+  )
+}
+```
+
+### Invalid State
+
+```tsx
+import { Switch } from "@neynar/ui/switch"
+import { Label } from "@neynar/ui/label"
+
+function ValidationExample() {
+  const [agreed, setAgreed] = useState(false)
+  const [submitted, setSubmitted] = useState(false)
+
+  const isInvalid = submitted && !agreed
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center justify-between">
+        <Label htmlFor="required">Accept terms (required)</Label>
+        <Switch
+          id="required"
+          checked={agreed}
+          onCheckedChange={setAgreed}
+          aria-invalid={isInvalid}
+        />
+      </div>
+      {isInvalid && (
+        <p className="text-destructive text-sm">
+          You must accept the terms to continue
+        </p>
+      )}
+      <button onClick={() => setSubmitted(true)}>Submit</button>
+    </div>
+  )
+}
+```
+
+## Keyboard Interaction
+
+| Key | Action |
+|-----|--------|
+| Space | Toggle checked state |
+| Enter | Toggle checked state |
+| Tab | Move focus to/from switch |
+
+## Accessibility
+
+- Renders a native `<input type="checkbox">` for form integration and screen readers
+- Supports `aria-invalid` for validation error states
+- Automatically manages focus states with visible focus ring
+- Works with `<Label>` via `htmlFor` prop for clickable labels
+- Disabled switches are properly announced and non-interactive
+
+## Styling Notes
+
+- Use `aria-invalid` prop to show error state (red border and ring)
+- The switch has an extended click area (`after:absolute after:-inset-x-3 after:-inset-y-2`) for easier interaction
+- Dark mode automatically adjusts colors for unchecked state background
+- Focus ring uses `ring-ring/50` with 3px width for accessibility
+
+## Related
+
+- [Label](./label.llm.md) - Associate labels with switches
+- [Checkbox](./checkbox.llm.md) - Alternative for yes/no choices
+- [RadioGroup](./radio-group.llm.md) - Multiple exclusive options

package/llm/components/table.llm.md

@@ -0,0 +1,334 @@
+# Table
+
+Compound component for displaying tabular data with semantic HTML table structure and automatic responsive scrolling.
+
+## Import
+
+```tsx
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+} from "@neynar/ui/table"
+```
+
+## Anatomy
+
+```tsx
+<Table>
+  <TableCaption>Optional description</TableCaption>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Column 1</TableHead>
+      <TableHead>Column 2</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>Data 1</TableCell>
+      <TableCell>Data 2</TableCell>
+    </TableRow>
+  </TableBody>
+  <TableFooter>
+    <TableRow>
+      <TableCell colSpan={2}>Summary</TableCell>
+    </TableRow>
+  </TableFooter>
+</Table>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Table | Root container with automatic horizontal scroll |
+| TableHeader | Header section containing column titles |
+| TableBody | Body section containing data rows |
+| TableFooter | Footer section for summary rows (totals, etc.) |
+| TableRow | Individual row within header, body, or footer |
+| TableHead | Header cell for column titles |
+| TableCell | Data cell for row content |
+| TableCaption | Accessible description rendered below table |
+
+## Props
+
+All components extend standard HTML table element props (`React.ComponentProps<"table">`, `React.ComponentProps<"thead">`, etc.).
+
+### Table
+
+Automatically wraps content in a responsive scroll container.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional classes for the table element |
+| ...props | ComponentProps<"table"> | - | Standard table element props |
+
+### TableHeader
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional classes for thead element |
+| ...props | ComponentProps<"thead"> | - | Standard thead element props |
+
+### TableBody
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional classes for tbody element |
+| ...props | ComponentProps<"tbody"> | - | Standard tbody element props |
+
+### TableFooter
+
+Styled with muted background for visual distinction.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional classes for tfoot element |
+| ...props | ComponentProps<"tfoot"> | - | Standard tfoot element props |
+
+### TableRow
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| data-state | "selected" | - | Apply selected styling to row |
+| className | string | - | Additional classes for tr element |
+| ...props | ComponentProps<"tr"> | - | Standard tr element props |
+
+### TableHead
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional classes for th element |
+| ...props | ComponentProps<"th"> | - | Standard th element props (scope, etc.) |
+
+### TableCell
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| colSpan | number | - | Number of columns to span |
+| className | string | - | Additional classes for td element |
+| ...props | ComponentProps<"td"> | - | Standard td element props |
+
+### TableCaption
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | - | Additional classes for caption element |
+| ...props | ComponentProps<"caption"> | - | Standard caption element props |
+
+## Data Attributes
+
+| Attribute | Element | When Present |
+|-----------|---------|--------------|
+| data-state="selected" | TableRow | Row is visually highlighted as selected |
+| data-slot | All | Identifies component part for styling ("table", "table-header", etc.) |
+
+## Examples
+
+### Basic Table
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Invoice</TableHead>
+      <TableHead>Status</TableHead>
+      <TableHead className="text-right">Amount</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell className="font-medium">INV001</TableCell>
+      <TableCell>Paid</TableCell>
+      <TableCell className="text-right">$250.00</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell className="font-medium">INV002</TableCell>
+      <TableCell>Pending</TableCell>
+      <TableCell className="text-right">$150.00</TableCell>
+    </TableRow>
+  </TableBody>
+  <TableFooter>
+    <TableRow>
+      <TableCell colSpan={2}>Total</TableCell>
+      <TableCell className="text-right">$400.00</TableCell>
+    </TableRow>
+  </TableFooter>
+</Table>
+```
+
+### With Status Badges
+
+```tsx
+import { Badge } from "@neynar/ui/badge"
+
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Service</TableHead>
+      <TableHead>Status</TableHead>
+      <TableHead>Uptime</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell className="font-medium">API Gateway</TableCell>
+      <TableCell>
+        <Badge variant="secondary">
+          <CheckCircle2Icon className="size-3" />
+          Operational
+        </Badge>
+      </TableCell>
+      <TableCell>99.99%</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell className="font-medium">Webhooks</TableCell>
+      <TableCell>
+        <Badge variant="destructive">
+          <XCircleIcon className="size-3" />
+          Offline
+        </Badge>
+      </TableCell>
+      <TableCell>85.20%</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### With Action Buttons
+
+```tsx
+import { Button } from "@neynar/ui/button"
+
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>API Key</TableHead>
+      <TableHead>Environment</TableHead>
+      <TableHead className="text-right">Actions</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell className="font-mono text-xs">neynar_sk_***_8f3d</TableCell>
+      <TableCell>
+        <Badge variant="default">Production</Badge>
+      </TableCell>
+      <TableCell className="text-right">
+        <div className="flex justify-end gap-2">
+          <Button variant="ghost" size="icon-sm">
+            <ExternalLinkIcon className="size-4" />
+          </Button>
+          <Button variant="ghost" size="icon-sm">
+            <MoreHorizontalIcon className="size-4" />
+          </Button>
+        </div>
+      </TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Selectable Rows
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Role</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell className="font-medium">Alice Johnson</TableCell>
+      <TableCell>Admin</TableCell>
+    </TableRow>
+    <TableRow data-state="selected">
+      <TableCell className="font-medium">Bob Smith</TableCell>
+      <TableCell>Developer</TableCell>
+    </TableRow>
+    <TableRow>
+      <TableCell className="font-medium">Carol White</TableCell>
+      <TableCell>Designer</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### With Caption
+
+```tsx
+<Table>
+  <TableCaption>A list of your recent transactions</TableCaption>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Transaction</TableHead>
+      <TableHead>Date</TableHead>
+      <TableHead className="text-right">Amount</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell className="font-medium">Purchase</TableCell>
+      <TableCell>2025-12-29</TableCell>
+      <TableCell className="text-right">$99.00</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## Styling
+
+### Responsive Scrolling
+
+The Table component automatically provides horizontal scrolling for tables that exceed viewport width. No additional configuration needed.
+
+### Compact Tables
+
+Reduce spacing for dense data:
+
+```tsx
+<Table className="text-xs">
+  <TableHeader>
+    <TableRow>
+      <TableHead className="h-8 px-2">ID</TableHead>
+      <TableHead className="h-8 px-2">Event</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell className="p-1 px-2 font-mono">001</TableCell>
+      <TableCell className="p-1 px-2">cast.created</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Alignment
+
+Use Tailwind utility classes for text alignment:
+
+```tsx
+<TableHead className="text-right">Amount</TableHead>
+<TableCell className="text-center">Status</TableCell>
+```
+
+## Accessibility
+
+- Semantic HTML table structure (`<table>`, `<thead>`, `<tbody>`, `<tfoot>`)
+- TableCaption provides accessible description for screen readers
+- TableHead uses `<th>` elements with implicit scope
+- Proper heading hierarchy maintained
+- All standard table ARIA attributes supported via props
+
+## Related
+
+- [Badge](/components/badge) - Status indicators within table cells
+- [Button](/components/button) - Action buttons for row operations
+- [Checkbox](/components/checkbox) - Selectable rows