@neynar/ui 1.0.1 → 1.0.3

package/llm/components/badge.llm.md

@@ -0,0 +1,185 @@
+# Badge
+
+Small label for displaying metadata, status indicators, counts, and categorical information.
+
+## Import
+
+```tsx
+import { Badge } from "@neynar/ui/badge"
+```
+
+## Anatomy
+
+```tsx
+<Badge variant="default">Label</Badge>
+```
+
+## Props
+
+### Badge
+
+Extends all HTML span attributes plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | "default" \| "secondary" \| "destructive" \| "success" \| "warning" \| "info" \| "outline" \| "ghost" \| "link" | "default" | Visual style variant |
+| render | React.ReactElement \| ((state) => React.ReactElement) | - | Custom element to render as (e.g., `<a />`) |
+| className | string | - | Additional CSS classes |
+
+All standard HTML span attributes are supported (onClick, aria-*, data-*, etc.).
+
+### Special Props
+
+**render prop** - Render Badge as a different element:
+
+```tsx
+<Badge render={<a href="/docs" />}>Documentation</Badge>
+```
+
+## Variants
+
+### Visual Variants
+
+| Variant | Use Case | Appearance |
+|---------|----------|------------|
+| default | Primary emphasis, featured items | Solid primary color background |
+| secondary | Neutral status, less emphasis | Subtle secondary background |
+| outline | Low emphasis, borders | Border with transparent background |
+| ghost | Minimal, hover reveals | Transparent, hover shows background |
+| link | Clickable, link-style | Underlined text style |
+
+### Semantic Variants
+
+| Variant | Use Case | Appearance |
+|---------|----------|------------|
+| destructive | Errors, critical warnings | Red/destructive color with subtle background |
+| success | Success states, confirmations | Green/success color with subtle background |
+| warning | Warnings, alerts | Yellow/warning color with subtle background |
+| info | Informational messages | Blue/info color with subtle background |
+
+## Examples
+
+### Basic Variants
+
+```tsx
+<Badge>Default</Badge>
+<Badge variant="secondary">Secondary</Badge>
+<Badge variant="outline">Outline</Badge>
+<Badge variant="destructive">Error</Badge>
+```
+
+### With Icons
+
+Add `data-icon="inline-start"` or `data-icon="inline-end"` to icon elements for proper spacing:
+
+```tsx
+import { StarIcon, FlameIcon } from "lucide-react"
+
+<Badge>
+  <StarIcon data-icon="inline-start" />
+  Featured
+</Badge>
+
+<Badge variant="destructive">
+  <FlameIcon data-icon="inline-start" />
+  Hot
+</Badge>
+```
+
+### Counter Badges
+
+```tsx
+<Badge>3</Badge>
+<Badge>12</Badge>
+<Badge>99+</Badge>
+<Badge variant="destructive">5</Badge>
+```
+
+### Status Indicators
+
+Use colored dots for operational status:
+
+```tsx
+<Badge variant="secondary">
+  <span className="bg-green-500 mr-1 size-2 rounded-full" />
+  Online
+</Badge>
+
+<Badge variant="secondary">
+  <span className="bg-yellow-500 mr-1 size-2 rounded-full" />
+  Degraded
+</Badge>
+
+<Badge variant="secondary">
+  <span className="bg-red-500 mr-1 size-2 rounded-full" />
+  Offline
+</Badge>
+```
+
+### As Link
+
+```tsx
+<Badge render={<a href="/pricing" />} variant="outline">
+  Upgrade to Pro
+</Badge>
+```
+
+### Plan Tiers
+
+```tsx
+import { CrownIcon, SparklesIcon } from "lucide-react"
+
+<Badge variant="secondary">Free</Badge>
+<Badge>
+  <SparklesIcon data-icon="inline-start" />
+  Popular
+</Badge>
+<Badge variant="outline">
+  <CrownIcon data-icon="inline-start" />
+  Enterprise
+</Badge>
+```
+
+## Data Attributes
+
+The Badge component sets these data attributes for styling:
+
+| Attribute | Value |
+|-----------|-------|
+| data-slot | "badge" |
+| data-icon | "inline-start" or "inline-end" (on icon elements) |
+
+## Styling
+
+### Icon Sizing
+
+Icons inside Badge automatically get `size-3` (12px). Use `data-icon="inline-start"` or `data-icon="inline-end"` for proper padding:
+
+```tsx
+// Automatic icon sizing and spacing
+<Badge>
+  <StarIcon data-icon="inline-start" />
+  Text
+</Badge>
+```
+
+### Custom Styling
+
+```tsx
+<Badge className="text-lg px-4">
+  Large Badge
+</Badge>
+```
+
+## Accessibility
+
+- Badge uses semantic HTML `<span>` by default
+- Can be rendered as `<a>` via render prop for clickable badges
+- Supports all ARIA attributes for enhanced semantics
+- No built-in focus management (use render prop with `<button>` or `<a>` for interactive badges)
+
+## Related
+
+- **Button** - For clickable actions instead of labels
+- **Avatar** - Can be combined with Badge for status indicators
+- **Card** - Badges commonly used in card headers for categorization

package/llm/components/blockquote.llm.md

@@ -0,0 +1,86 @@
+# Blockquote
+
+Quoted content with left border accent and italic styling.
+
+## Import
+
+```tsx
+import { Blockquote } from "@neynar/ui/typography"
+```
+
+## Usage
+
+```tsx
+<Blockquote>
+  The best way to predict the future is to invent it.
+</Blockquote>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| color | "default" \| "muted" \| "subtle" | "default" | Text color (limited to neutral colors) |
+| className | string | - | Additional CSS classes |
+
+## Examples
+
+### Basic Quote
+
+```tsx
+<Blockquote>
+  Design is not just what it looks like and feels like.
+  Design is how it works.
+</Blockquote>
+```
+
+### With Attribution
+
+```tsx
+<figure>
+  <Blockquote>
+    The only way to do great work is to love what you do.
+  </Blockquote>
+  <figcaption>
+    <Caption>— Steve Jobs</Caption>
+  </figcaption>
+</figure>
+```
+
+### Muted Style
+
+```tsx
+<Blockquote color="muted">
+  A subtle quote that doesn't demand attention.
+</Blockquote>
+```
+
+### In Article Context
+
+```tsx
+<article>
+  <Title order={2}>Key Insights</Title>
+  <Text>The author makes several important points:</Text>
+  <Blockquote>
+    Simplicity is the ultimate sophistication.
+  </Blockquote>
+  <Text>This philosophy guides the entire design system.</Text>
+</article>
+```
+
+## Styling
+
+Default styling:
+- Left border accent (`border-l-4 border-border`)
+- Left padding (`pl-4`)
+- Italic text
+
+## Color Restriction
+
+Colors are limited to `default`, `muted`, and `subtle` for semantic appropriateness. Blockquotes represent quoted content, not status messages.
+
+## Related
+
+- [Text](./text.llm.md) - Paragraph text
+- [Title](./title.llm.md) - Headings
+- [Card](./card.llm.md) - For featured quotes

package/llm/components/breadcrumb.llm.md

@@ -0,0 +1,245 @@
+# Breadcrumb
+
+Semantic navigation component displaying hierarchical page location with accessible breadcrumb trail.
+
+## Import
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+} from "@neynar/ui/breadcrumb"
+```
+
+## Anatomy
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Settings</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| Breadcrumb | Root `<nav>` container with `aria-label="breadcrumb"` |
+| BreadcrumbList | Ordered list (`<ol>`) with responsive flex layout |
+| BreadcrumbItem | List item (`<li>`) wrapper for links/pages |
+| BreadcrumbLink | Interactive link (`<a>`) for navigable pages, supports custom `render` prop |
+| BreadcrumbPage | Current page indicator (`<span>`) with `aria-current="page"` |
+| BreadcrumbSeparator | Visual separator (`<li>`) between items, defaults to chevron icon |
+| BreadcrumbEllipsis | Collapsed section indicator (`<span>`) for long paths |
+
+## Props
+
+### Breadcrumb
+
+Standard `<nav>` HTML attributes. Automatically includes `aria-label="breadcrumb"`.
+
+### BreadcrumbList
+
+Standard `<ol>` HTML attributes. Automatically styled with responsive spacing (1.5 gap on mobile, 2.5 on desktop).
+
+### BreadcrumbItem
+
+Standard `<li>` HTML attributes. Styled as inline-flex container.
+
+### BreadcrumbLink
+
+Extends standard `<a>` HTML attributes with Base UI's `render` prop support.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| render | ReactElement | - | Custom element to render as (e.g., Next.js Link) |
+| href | string | - | Link destination |
+
+**Using render prop:**
+```tsx
+import { Link } from "next/link"
+
+<BreadcrumbLink render={<Link href="/dashboard" />}>
+  Dashboard
+</BreadcrumbLink>
+```
+
+### BreadcrumbPage
+
+Standard `<span>` HTML attributes. Automatically includes `aria-current="page"` and `aria-disabled="true"`.
+
+### BreadcrumbSeparator
+
+Standard `<li>` HTML attributes with custom separator support.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | ReactNode | ChevronRightIcon | Custom separator content (icon or text) |
+
+### BreadcrumbEllipsis
+
+Standard `<span>` HTML attributes. Renders MoreHorizontalIcon with screen reader text "More".
+
+## Data Attributes
+
+All components include `data-slot` attributes for styling:
+
+| Component | Attribute |
+|-----------|-----------|
+| Breadcrumb | `data-slot="breadcrumb"` |
+| BreadcrumbList | `data-slot="breadcrumb-list"` |
+| BreadcrumbItem | `data-slot="breadcrumb-item"` |
+| BreadcrumbLink | `data-slot="breadcrumb-link"` |
+| BreadcrumbPage | `data-slot="breadcrumb-page"` |
+| BreadcrumbSeparator | `data-slot="breadcrumb-separator"` |
+| BreadcrumbEllipsis | `data-slot="breadcrumb-ellipsis"` |
+
+## Examples
+
+### Basic Navigation
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Settings</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### With Icons
+
+```tsx
+import { HomeIcon, SettingsIcon } from "lucide-react"
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/" aria-label="Home">
+        <HomeIcon className="size-4" />
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>
+        <SettingsIcon className="mr-2 size-4" />
+        Settings
+      </BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### Custom Separator
+
+```tsx
+import { SlashIcon } from "lucide-react"
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator>
+      <SlashIcon />
+    </BreadcrumbSeparator>
+    <BreadcrumbItem>
+      <BreadcrumbPage>Dashboard</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### Truncated Long Paths
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbEllipsis />
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/settings">Settings</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>API Keys</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### With Next.js Link
+
+```tsx
+import { Link } from "next/link"
+
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink render={<Link href="/" />}>
+        Home
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink render={<Link href="/dashboard" />}>
+        Dashboard
+      </BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Settings</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+## Accessibility
+
+- Root component uses semantic `<nav>` with `aria-label="breadcrumb"`
+- Uses ordered list (`<ol>`) for proper navigation structure
+- Current page has `aria-current="page"` and `aria-disabled="true"`
+- Separators marked with `role="presentation"` and `aria-hidden="true"`
+- Ellipsis includes screen reader text "More"
+- Links have hover state with color transition for visual feedback
+- Automatically wraps on small screens for responsive behavior
+
+## Related
+
+- [Link](/docs/components/link) - For custom link rendering
+- [Navigation Menu](/docs/components/navigation-menu) - For primary navigation