@neynar/ui 1.0.0 → 1.0.2

package/llm/contributing.llm.md

@@ -0,0 +1,273 @@
+# Contributing to @neynar/ui (LLM Guide)
+
+Technical reference for AI assistants modifying this package.
+
+## Critical Rules
+
+1. **Never export defaults** - Named exports only
+2. **Always add `data-slot`** - Root element of every component
+3. **Use `type` not `interface`** - For prop definitions
+4. **`"use client"` only when needed** - Only for components using React hooks
+5. **Run type-check** - `yarn type-check` must pass before committing
+
+## File Locations
+
+```
+src/
+├── components/
+│   ├── ui/                    # Base UI components
+│   │   ├── button.tsx
+│   │   └── stories/           # Storybook stories
+│   │       └── button.stories.tsx
+│   └── neynar/                # Neynar-specific components
+│       ├── typography/
+│       ├── color-mode/
+│       └── first-light/
+├── hooks/                     # Custom hooks
+├── lib/                       # Utilities (cn, variants)
+└── styles/                    # CSS and themes
+    └── themes/
+
+llm/                          # LLM documentation
+├── components/                # Per-component docs
+├── index.llm.md              # Package overview
+├── hooks.llm.md
+├── utilities.llm.md
+└── theming.llm.md
+
+package.json                   # Exports map (auto-generated)
+```
+
+## Component Template
+
+```tsx
+// Add "use client" ONLY if component uses hooks
+import { Primitive } from "@base-ui/react/primitive"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+
+const componentVariants = cva("base-classes", {
+  variants: {
+    variant: {
+      default: "...",
+      secondary: "...",
+    },
+  },
+  defaultVariants: {
+    variant: "default",
+  },
+})
+
+type ComponentProps = Primitive.Props & VariantProps<typeof componentVariants>
+
+/**
+ * Brief description.
+ *
+ * @example
+ * ```tsx
+ * <Component>Content</Component>
+ * ```
+ */
+function Component({ className, variant, ...props }: ComponentProps) {
+  return (
+    <Primitive
+      data-slot="component"
+      className={cn(componentVariants({ variant, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Component, componentVariants, type ComponentProps }
+```
+
+## Story Template
+
+```tsx
+import type { Meta, StoryObj } from "@storybook/react"
+import { Component } from "../component"
+
+const meta: Meta<typeof Component> = {
+  title: "UI/Component",
+  component: Component,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof Component>
+
+export const Default: Story = {
+  args: { children: "Example" },
+}
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Component variant="default">Default</Component>
+      <Component variant="secondary">Secondary</Component>
+    </div>
+  ),
+}
+```
+
+## LLM Documentation Template
+
+```markdown
+# ComponentName
+
+One sentence description.
+
+## Import
+
+\`\`\`tsx
+import { Component } from "@neynar/ui/component"
+\`\`\`
+
+## Usage
+
+\`\`\`tsx
+<Component>Content</Component>
+\`\`\`
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | "default" \| "secondary" | "default" | Visual style |
+
+## Examples
+
+### With variant
+\`\`\`tsx
+<Component variant="secondary">Secondary</Component>
+\`\`\`
+```
+
+## data-slot Convention
+
+Every component root element MUST have `data-slot`:
+
+```tsx
+// Single component
+<Button data-slot="button" />
+
+// Compound component
+<Dialog data-slot="dialog">
+  <DialogTrigger data-slot="dialog-trigger" />
+  <DialogContent data-slot="dialog-content">
+    <DialogHeader data-slot="dialog-header" />
+    <DialogTitle data-slot="dialog-title" />
+    <DialogDescription data-slot="dialog-description" />
+    <DialogFooter data-slot="dialog-footer" />
+  </DialogContent>
+</Dialog>
+```
+
+## "use client" Rules
+
+**ADD** when component:
+- Uses `useState`, `useEffect`, `useRef`, `useContext`
+- Uses custom hooks (`useColorMode`, `useMobile`)
+- Has event handlers that need client hydration
+
+**OMIT** when component:
+- Is a pure wrapper around Base UI primitive
+- Only passes props through
+- Has no React hooks
+
+Current components with `"use client"`:
+- avatar, calendar, carousel, chart, collapsible
+- combobox, command, dialog, drawer, field
+- hover-card, input-otp, label, progress, resizable
+- select, sidebar, slider, switch, tabs
+- toggle-group, tooltip
+- color-mode/*, first-light/*
+
+## Semantic Color Tokens
+
+```css
+/* Backgrounds */
+bg-background, bg-card, bg-popover, bg-muted, bg-accent
+
+/* Foregrounds */
+text-foreground, text-muted-foreground, text-card-foreground
+
+/* Status */
+bg-primary, text-primary-foreground
+bg-secondary, text-secondary-foreground
+bg-destructive, text-destructive
+bg-success, text-success
+bg-warning, text-warning
+bg-info, text-info
+
+/* Borders */
+border-border, border-input, border-ring
+```
+
+## Package.json Exports
+
+Exports are auto-generated by `scripts/generate-exports.ts` during build.
+
+Each component gets an entry:
+```json
+{
+  "./button": {
+    "types": "./dist/components/ui/button.d.ts",
+    "import": "./dist/components/ui/button.js"
+  }
+}
+```
+
+## Validation Commands
+
+```bash
+# Must pass before commit
+yarn type-check    # TypeScript
+yarn lint          # ESLint
+yarn build         # Build check
+
+# Development
+yarn storybook     # Visual testing
+```
+
+## Common Patterns
+
+### Polymorphism with `render` prop
+```tsx
+<Button render={<a href="/link" />}>Link Button</Button>
+```
+
+### Compound Components
+```tsx
+<Dialog>
+  <DialogTrigger>Open</DialogTrigger>
+  <DialogContent>
+    <DialogTitle>Title</DialogTitle>
+    <DialogDescription>Description</DialogDescription>
+  </DialogContent>
+</Dialog>
+```
+
+### Forwarding refs (handled by Base UI)
+```tsx
+// Base UI handles ref forwarding automatically
+// No need for forwardRef wrapper
+function Component(props: ComponentProps) {
+  return <Primitive {...props} />
+}
+```
+
+### Icon sizing
+```tsx
+// Icons auto-size via [&_svg:not([class*='size-'])]:size-4
+<Button>
+  <PlusIcon /> {/* Inherits size-4 */}
+  Add Item
+</Button>
+```
+
+## Debugging Tips
+
+- Check `data-slot` attributes in DevTools for component boundaries
+- Use `?path=/story/ui-button--default` in Storybook URL
+- Run `yarn type-check 2>&1 | head -20` for focused error output

package/llm/hooks.llm.md

@@ -0,0 +1,91 @@
+# Hooks
+
+React hooks provided by @neynar/ui.
+
+## useIsMobile
+
+Detects mobile viewport using `matchMedia`. Returns reactive boolean.
+
+### Import
+
+```tsx
+import { useIsMobile } from "@neynar/ui/use-mobile"
+```
+
+### Returns
+
+| Type | Description |
+|------|-------------|
+| `boolean` | `true` when viewport < 768px, `false` otherwise |
+
+### Behavior
+
+- Returns `false` during SSR (hydration-safe)
+- Updates reactively on viewport resize
+- Uses `matchMedia` for performance (no resize listener spam)
+- Breakpoint: 768px (CSS `md:` equivalent)
+
+### Example: Responsive Navigation
+
+```tsx
+import { useIsMobile } from "@neynar/ui/use-mobile"
+
+function ResponsiveNav() {
+  const isMobile = useIsMobile()
+  return isMobile ? <MobileNav /> : <DesktopNav />
+}
+```
+
+### Example: Responsive Modal
+
+Use Sheet for mobile, Dialog for desktop:
+
+```tsx
+import { useIsMobile } from "@neynar/ui/use-mobile"
+import { Sheet, SheetContent } from "@neynar/ui/sheet"
+import { Dialog, DialogContent } from "@neynar/ui/dialog"
+
+function ResponsiveModal({ open, onOpenChange, children }) {
+  const isMobile = useIsMobile()
+
+  if (isMobile) {
+    return (
+      <Sheet open={open} onOpenChange={onOpenChange}>
+        <SheetContent side="bottom">{children}</SheetContent>
+      </Sheet>
+    )
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>{children}</DialogContent>
+    </Dialog>
+  )
+}
+```
+
+### Example: Conditional Rendering
+
+```tsx
+import { useIsMobile } from "@neynar/ui/use-mobile"
+
+function Dashboard() {
+  const isMobile = useIsMobile()
+
+  return (
+    <div className="flex">
+      {!isMobile && <Sidebar />}
+      <main className="flex-1">
+        <Content />
+      </main>
+      {isMobile && <MobileBottomNav />}
+    </div>
+  )
+}
+```
+
+### Related
+
+- [Sheet](./components/sheet.llm.md) - Often used with mobile detection for bottom sheets
+- [Drawer](./components/drawer.llm.md) - Mobile-first bottom sheet component
+- [Sidebar](./components/sidebar.llm.md) - Responsive sidebar that can use mobile detection

package/llm/index.llm.md

@@ -0,0 +1,178 @@
+# @neynar/ui
+
+> React component library built on Base UI primitives + Tailwind CSS v4. 53 production-ready components with per-component imports, SSR-safe dark mode, and two visual themes.
+
+## For AI Agents
+
+**How to use this documentation:**
+
+1. **Start here** for quick reference and component discovery
+2. **Load specific component docs** from `./components/{name}.llm.md` when working with that component
+3. **Load theming.llm.md** when dealing with themes, colors, or dark mode
+4. **Each doc is self-contained** with imports, props, examples, and accessibility info
+
+**Key patterns to remember:**
+- Import path: `import { X } from "@neynar/ui/x"` (lowercase, kebab-case)
+- All components have `data-slot` attributes for CSS targeting
+- Compound components export multiple parts from same path
+- `render` prop (not `asChild`) for polymorphism
+
+## Quick Start
+
+```tsx
+import { Button } from "@neynar/ui/button";
+import { Card, CardHeader, CardContent } from "@neynar/ui/card";
+import "@neynar/ui/themes/purple-dawn";
+
+export function App() {
+  return (
+    <Card>
+      <CardHeader>Welcome</CardHeader>
+      <CardContent>
+        <Button>Get Started</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Import Pattern
+
+Each component has its own entry point:
+
+```tsx
+import { Button } from "@neynar/ui/button";
+import { Dialog, DialogTrigger, DialogContent } from "@neynar/ui/dialog";
+import { Input } from "@neynar/ui/input";
+import { cn } from "@neynar/ui/utils";
+```
+
+## Themes
+
+```tsx
+// Purple Dawn - elegant translucent surfaces (default)
+import "@neynar/ui/themes/purple-dawn";
+
+// First Light - hand-drawn wireframe aesthetic
+import "@neynar/ui/themes/first-light";
+```
+
+## Color Mode
+
+SSR-safe dark mode with automatic system detection:
+
+```tsx
+import { ColorModeInitializer, ColorModeToggle } from "@neynar/ui/color-mode";
+
+// In layout.tsx <head>
+<ColorModeInitializer />
+
+// Anywhere for user control
+<ColorModeToggle />
+```
+
+## Component Index
+
+### Core Inputs
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Button | `@neynar/ui/button` | 9 variants, 8 sizes |
+| Checkbox | `@neynar/ui/checkbox` | Boolean toggle |
+| Input | `@neynar/ui/input` | Text input |
+| RadioGroup | `@neynar/ui/radio-group` | Single selection |
+| Select | `@neynar/ui/select` | Dropdown selection |
+| Slider | `@neynar/ui/slider` | Range input |
+| Switch | `@neynar/ui/switch` | Toggle switch |
+| Textarea | `@neynar/ui/textarea` | Multi-line text |
+| Toggle | `@neynar/ui/toggle` | Pressable toggle |
+| ToggleGroup | `@neynar/ui/toggle-group` | Multiple toggles |
+| Combobox | `@neynar/ui/combobox` | Searchable select |
+
+### Form & Field
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| ButtonGroup | `@neynar/ui/button-group` | Connected buttons |
+| Calendar | `@neynar/ui/calendar` | Date picker |
+| Field | `@neynar/ui/field` | Form field wrapper |
+| InputGroup | `@neynar/ui/input-group` | Input with addons |
+| InputOTP | `@neynar/ui/input-otp` | One-time password |
+| Label | `@neynar/ui/label` | Form labels |
+
+### Layout & Structure
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Accordion | `@neynar/ui/accordion` | Expandable sections |
+| AspectRatio | `@neynar/ui/aspect-ratio` | Maintain ratio |
+| Card | `@neynar/ui/card` | Content container |
+| Collapsible | `@neynar/ui/collapsible` | Show/hide content |
+| Resizable | `@neynar/ui/resizable` | Resizable panels |
+| ScrollArea | `@neynar/ui/scroll-area` | Custom scrollbars |
+| Separator | `@neynar/ui/separator` | Visual divider |
+| Table | `@neynar/ui/table` | Data tables |
+
+### Navigation & Menus
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Breadcrumb | `@neynar/ui/breadcrumb` | Path indicator |
+| ContextMenu | `@neynar/ui/context-menu` | Right-click menu |
+| DropdownMenu | `@neynar/ui/dropdown-menu` | Trigger dropdown |
+| Menubar | `@neynar/ui/menubar` | Horizontal menu |
+| NavigationMenu | `@neynar/ui/navigation-menu` | Site navigation |
+| Pagination | `@neynar/ui/pagination` | Page navigation |
+| Sidebar | `@neynar/ui/sidebar` | Collapsible nav |
+| Tabs | `@neynar/ui/tabs` | Tabbed content |
+
+### Overlays & Dialogs
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| AlertDialog | `@neynar/ui/alert-dialog` | Confirmation |
+| Dialog | `@neynar/ui/dialog` | Modal dialog |
+| Drawer | `@neynar/ui/drawer` | Bottom drawer |
+| HoverCard | `@neynar/ui/hover-card` | Rich hover preview |
+| Popover | `@neynar/ui/popover` | Floating content |
+| Sheet | `@neynar/ui/sheet` | Side panel |
+| Tooltip | `@neynar/ui/tooltip` | Hover info |
+
+### Feedback & Status
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Alert | `@neynar/ui/alert` | Contextual messages |
+| Badge | `@neynar/ui/badge` | Status indicators |
+| Empty | `@neynar/ui/empty` | Empty state |
+| Progress | `@neynar/ui/progress` | Progress bars |
+| Skeleton | `@neynar/ui/skeleton` | Loading placeholders |
+| Sonner | `@neynar/ui/sonner` | Toast notifications |
+| Spinner | `@neynar/ui/spinner` | Loading spinner |
+
+### Advanced
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Avatar | `@neynar/ui/avatar` | User avatars |
+| Carousel | `@neynar/ui/carousel` | Content slider |
+| Chart | `@neynar/ui/chart` | Recharts wrapper |
+| Command | `@neynar/ui/command` | Command palette |
+| Kbd | `@neynar/ui/kbd` | Keyboard shortcuts |
+| Item | `@neynar/ui/item` | List items |
+
+### Typography
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| Title | `@neynar/ui/typography` | Headings (h1-h6) |
+| Text | `@neynar/ui/typography` | Paragraph text |
+| Code | `@neynar/ui/typography` | Inline code |
+| Blockquote | `@neynar/ui/typography` | Quote blocks |
+
+### Theme Utilities
+| Component | Import Path | Description |
+|-----------|-------------|-------------|
+| ColorModeInitializer | `@neynar/ui/color-mode` | FOUC prevention script |
+| ColorModeToggle | `@neynar/ui/color-mode` | Mode switcher dropdown |
+| useColorMode | `@neynar/ui/color-mode` | Programmatic control hook |
+| FirstLightFilters | `@neynar/ui/first-light` | SVG wobble filters |
+
+## Additional Documentation
+
+- [Theming](./theming.llm.md) - Themes, color mode, CSS variables, customization
+- [Hooks](./hooks.llm.md) - useIsMobile responsive hook
+- [Utilities](./utilities.llm.md) - cn() class merging utility
+- [Contributing](./contributing.llm.md) - Component patterns, data-slot, templates