@neynar/ui 0.1.1 → 0.1.2

package/llms.txt

@@ -1,6 +1,6 @@
 # @neynar/ui Component Library
 
-A production-ready React component library with 52 components, 2 hooks, and 1 utility. All components use modern TypeScript patterns with function declarations and named exports.
+A production-ready React component library with 265+ components, hooks, and utilities. Built on Radix UI primitives with Tailwind CSS v4, ensuring WCAG-compliant accessibility and zero runtime overhead.
 
 ## Quick Reference
 
@@ -9,7 +9,103 @@ import { Button, Card, useIsMobile, cn } from "@neynar/ui"
 import "@neynar/ui/styles"
 ```
 
-## Components (52)
+## 🔍 How to Search Components
+
+**IMPORTANT:** DO NOT load the entire `llm-docs/sdk-items-registry.json` file - it contains 265+ items and will exceed context limits.
+
+Instead, search efficiently using these methods:
+
+### Method 1: Search by Component Name (Recommended)
+```bash
+# Search for specific component documentation
+cat llm-docs/{component-name}.llm.md
+# Example: cat llm-docs/button.llm.md
+```
+
+### Method 2: Search Registry by Keywords  
+```bash
+# Use jq to search registry by keywords without loading entire file
+jq 'to_entries[] | select(.value.keywords[]? | contains("button")) | {key: .key, description: .value.description}' llm-docs/sdk-items-registry.json
+```
+
+### Method 3: List Components by Category
+Use these patterns to find components:
+- **button** → Button, Toggle, ToggleGroup
+- **form** → Input, Textarea, Checkbox, Select, Switch
+- **navigation** → NavigationMenu, Breadcrumb, Tabs, Sidebar
+- **overlay** → Dialog, Sheet, Popover, Tooltip
+- **layout** → Container, Stack, Card, Accordion
+
+## Common Mistakes and Corrections
+
+**CRITICAL Typography Errors:**
+- ❌ `<h1>`, `<p>`, `<span>` - NEVER use plain HTML elements
+- ❌ `Text` component does NOT exist 
+- ❌ `<div>Some text</div>` - wrap text in typography components
+
+**CRITICAL Component Name Errors:**
+- ❌ `Stack direction="col"` - use `direction="vertical"`  
+- ❌ `Stack gap="4"` - use `spacing="md"`
+- ❌ `Badge variant="success"` - use `variant="secondary"`
+
+**Correct Usage:**
+```typescript
+import { H1, H2, P, Span, Code, Stack, Badge } from "@neynar/ui"
+
+// ✅ Always use typography components for text
+<H1>Main Title</H1>
+<H2>Section Title</H2>
+<P>Body text content with <Strong>emphasis</Strong></P>
+<Small color="muted">Updated <Code>2024-01-15</Code></Small>
+
+// ✅ Typography in containers
+<Card>
+  <CardHeader>
+    <H3>Card Title</H3>
+    <P color="muted">Description text</P>
+  </CardHeader>
+</Card>
+
+// ✅ Stack with correct props
+<Stack direction="vertical" spacing="md">
+  <P>First paragraph</P>
+  <P>Second paragraph</P>
+</Stack>
+
+// ✅ Badge with valid variants only
+<Badge variant="default">Active</Badge>
+<Badge variant="secondary">Draft</Badge>
+<Badge variant="destructive">Error</Badge>
+<Badge variant="outline">Pending</Badge>
+```
+
+## Registry Structure
+
+The `llm-docs/sdk-items-registry.json` contains metadata for all components:
+
+```json
+{
+  "ComponentName": {
+    "description": "Brief component description with usage context",
+    "file": "component-name.llm.md",
+    "type": "component|hook|function|type",  
+    "keywords": ["relevant", "search", "terms"]
+  }
+}
+```
+
+## Efficient Search Strategy
+
+For component discovery, use this approach:
+
+1. **Know what you need?** → Use Method 1 (direct file access)
+2. **Searching by functionality?** → Use Method 2 (keyword search)  
+3. **Browsing categories?** → Use Method 3 (category patterns)
+4. **Need complete list?** → Use `jq 'keys' llm-docs/sdk-items-registry.json`
+
+**Performance Tip:** Each .llm.md file contains complete documentation including props, examples, and TypeScript definitions. Only load what you need.
+
+## Component Categories
 
 ### Layout Components → [docs/llm/components/layout.md](docs/llm/components/layout.md)
 - **Container** - Responsive container with max-width constraints
@@ -82,7 +178,81 @@ import "@neynar/ui/styles"
 - **ThemeToggle** - Dark/light mode switcher
 
 ### Typography Components → [docs/llm/components/typography.md](docs/llm/components/typography.md)
-- Text styling and typography components
+
+**CRITICAL: Always use typography components instead of plain HTML elements**
+
+The typography system provides semantic HTML components with consistent styling:
+
+#### Semantic HTML Components (Use These Instead of Plain HTML)
+```typescript
+// ❌ DON'T use plain HTML elements
+<h1>Title</h1>
+<p>Content</p>
+<span>Text</span>
+<a href="#">Link</a>
+
+// ✅ DO use typography components  
+<H1>Title</H1>
+<P>Content</P>
+<Span>Text</Span>
+<A href="#">Link</A>
+```
+
+#### Available Components
+- **H1, H2, H3, H4, H5, H6** - Semantic headings with proper hierarchy
+- **P** - Paragraph text with body variant styling
+- **Span** - Inline text with default styling  
+- **A** - Links with proper hover/focus states
+- **Code** - Inline code with monospace styling
+- **Small** - Small text for captions/metadata
+- **Strong** - Bold text for emphasis
+- **Lead** - Large introductory text
+- **Blockquote** - Quoted content with border styling
+
+#### Typography Pattern: Use for ALL Text Content
+```typescript
+// Content containers - wrap ALL text with typography components
+<Card>
+  <CardHeader>
+    <H2>Card Title</H2>
+    <P color="muted">Card description</P>
+  </CardHeader>
+  <CardContent>
+    <P>Main content paragraph</P>
+    <Small color="muted">Last updated: <Code>2024-01-15</Code></Small>
+  </CardContent>
+</Card>
+
+// Form labels and descriptions
+<Label>
+  <Strong>Field Label</Strong>
+</Label>
+<Small color="muted">Field description text</Small>
+
+// Navigation and UI text
+<Button>
+  <Span>Button Text</Span>
+</Button>
+```
+
+#### Color Variants
+- `color="default"` - Standard text color
+- `color="muted"` - Subdued text for secondary info
+- `color="accent"` - Emphasis and highlights
+- `color="destructive"` - Error messages
+- `color="success"` - Success messages
+
+#### When to Use Each Component
+- **H1-H6**: Page/section headings (semantic hierarchy)
+- **P**: Body paragraphs and main content
+- **Span**: Inline text within other components
+- **Code**: Inline code, values, technical terms
+- **Small**: Timestamps, captions, fine print
+- **Strong**: Bold emphasis within text
+- **Lead**: Large introductory paragraphs
+- **A**: All clickable text links
+- **Blockquote**: Quoted content
+- **Typography**: ⚠️ Last resort only - when there's no semantic component for the type of content you want to display (semantic components already handle all styling variants)
 
 ## Utilities & Hooks → [docs/llm/components/utilities.md](docs/llm/components/utilities.md)
 - **cn()** - Class name merging with Tailwind conflict resolution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neynar/ui",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "author": "Neynar Inc.",
   "description": "React UI component library built on shadcn/ui and Tailwind CSS",
@@ -35,6 +35,7 @@
     "lint": "eslint src/",
     "type-check": "tsc --noEmit",
     "clean": "rm -rf dist",
+    "docs:generate": "tsx scripts/llm-tsdoc-generator/index.ts llm-tsdoc-generator.config.json",
     "storybook": "storybook dev --no-open -p 6006",
     "build-storybook": "storybook build"
   },
@@ -94,7 +95,9 @@
     "react-dom": "19.1.1",
     "storybook": "9.1.2",
     "tailwindcss": "4.1.11",
-    "typescript": "5.9.2",
+    "ts-morph": "^26.0.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
     "vite": "7.1.2"
   },
   "peerDependencies": {

package/src/components/ui/accordion.tsx

@@ -4,6 +4,115 @@ import { ChevronDownIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Props for single-item accordion behavior (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+type AccordionSingleDocsProps = {
+  /** Accordion type that allows only one item to be open at a time */
+  type: "single";
+  /** Currently open item value (controlled) */
+  value?: string;
+  /** Initial open item value (uncontrolled) */
+  defaultValue?: string;
+  /** Callback fired when the open item changes */
+  onValueChange?: (value: string) => void;
+  /** Whether the open item can be collapsed by clicking it again */
+  collapsible?: boolean;
+};
+
+/**
+ * Props for multiple-item accordion behavior (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+type AccordionMultipleDocsProps = {
+  /** Accordion type that allows multiple items to be open simultaneously */
+  type: "multiple";
+  /** Currently open item values (controlled) */
+  value?: string[];
+  /** Initial open item values (uncontrolled) */
+  defaultValue?: string[];
+  /** Callback fired when the open items change */
+  onValueChange?: (value: string[]) => void;
+};
+
+/**
+ * Base props shared by all accordion types (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+type AccordionBaseDocsProps = {
+  /** Whether the entire accordion is disabled */
+  disabled?: boolean;
+  /** Layout orientation for the accordion */
+  orientation?: "horizontal" | "vertical";
+  /** Text direction for internationalization */
+  dir?: "ltr" | "rtl";
+  /** Additional CSS classes for styling */
+  className?: string;
+  /** Child AccordionItem components */
+  children?: React.ReactNode;
+};
+
+/**
+ * Complete props for the Accordion component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AccordionDocsProps = (
+  | AccordionSingleDocsProps
+  | AccordionMultipleDocsProps
+) &
+  AccordionBaseDocsProps;
+
+/**
+ * Props for AccordionItem component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AccordionItemDocsProps = {
+  /** Unique identifier for this accordion item (required) */
+  value: string;
+  /** Whether this specific accordion item is disabled */
+  disabled?: boolean;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Child components (AccordionTrigger and AccordionContent) */
+  children?: React.ReactNode;
+} & Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  "value" | "disabled" | "children"
+>;
+
+/**
+ * Props for AccordionTrigger component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AccordionTriggerDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Content to display in the trigger (text, icons, or components) */
+  children?: React.ReactNode;
+  /** Whether the trigger interaction is disabled */
+  disabled?: boolean;
+  /** Render the trigger as its child element when true */
+  asChild?: boolean;
+} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children">;
+
+/**
+ * Props for AccordionContent component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type AccordionContentDocsProps = {
+  /** Additional CSS classes for custom styling (applied to inner div) */
+  className?: string;
+  /** Any React content to display when expanded */
+  children?: React.ReactNode;
+  /** Forces content to remain mounted when collapsed (useful for animations) */
+  forceMount?: true;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "children">;
+
 /**
  * Accordion - Collapsible content panels for organizing information
  *
@@ -52,16 +161,6 @@ import { cn } from "@/lib/utils";
  * </Accordion>
  * ```
  *
- * @param type - "single" allows one item open, "multiple" allows multiple items open
- * @param collapsible - When type="single", allows closing the open item (optional)
- * @param defaultValue - Initial value(s) for open items
- * @param value - Controlled value(s) for open items
- * @param onValueChange - Callback when accordion state changes
- * @param className - Additional CSS classes for styling
- * @param orientation - "horizontal" or "vertical" (default: "vertical")
- * @param dir - Text direction "ltr" or "rtl" for internationalization
- * @param disabled - Disables all accordion interactions
- *
  * @accessibility
  * - Full keyboard navigation support (Arrow keys, Space, Enter, Home, End)
  * - ARIA expanded/collapsed states automatically managed
@@ -77,9 +176,9 @@ import { cn } from "@/lib/utils";
  * @see {@link AccordionContent} Collapsible content area with smooth animations
  * @since 1.0.0
  */
-function Accordion({
-  ...props
-}: React.ComponentProps<typeof AccordionPrimitive.Root>) {
+function Accordion(
+  props: React.ComponentProps<typeof AccordionPrimitive.Root>,
+) {
   return <AccordionPrimitive.Root data-slot="accordion" {...props} />;
 }
 
@@ -109,11 +208,6 @@ function Accordion({
  * </AccordionItem>
  * ```
  *
- * @param value - Unique identifier for this accordion item (required)
- * @param className - Additional CSS classes for custom styling
- * @param disabled - Disables this specific accordion item
- * @param children - Should contain AccordionTrigger and AccordionContent
- *
  * @accessibility
  * - Manages expanded/collapsed state via ARIA attributes
  * - Associates trigger with content using aria-controls and aria-labelledby
@@ -171,11 +265,6 @@ function AccordionItem({
  * </AccordionTrigger>
  * ```
  *
- * @param className - Additional CSS classes for custom styling
- * @param children - Content to display in the trigger (text, icons, or components)
- * @param disabled - Disables the trigger interaction
- * @param asChild - Renders the trigger as its child element when true
- *
  * @accessibility
  * - Keyboard activated with Space, Enter, or Arrow keys
  * - aria-expanded automatically indicates current expanded/collapsed state
@@ -247,10 +336,6 @@ function AccordionTrigger({
  * </AccordionContent>
  * ```
  *
- * @param className - Additional CSS classes for custom styling (applied to inner div)
- * @param children - Any React content to display when expanded
- * @param forceMount - Forces content to remain mounted when collapsed (for animations)
- *
  * @accessibility
  * - Hidden content is not focusable or accessible when collapsed
  * - Smooth height animations enhance user experience without motion issues