@neynar/ui 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Neynar Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# @neynar/ui
+
+A comprehensive, production-ready React component library built on **Radix UI** primitives and **Tailwind CSS v4**. Features 52 accessible components plus advanced hooks for building modern web applications with confidence.
+
+## 🎯 Key Highlights
+
+- **Over 50 Components, Hooks and Utilities** - Complete UI ecosystem for any application type
+- **Accessibility-First** - WCAG 2.1 AA compliant with comprehensive keyboard navigation
+- **TypeScript Native** - Full type safety with intelligent IntelliSense support
+- **Advanced Theming** - OKLCH color space with system-aware custom themes
+- **Framework Agnostic** - Seamless integration with Next.js, Vite, Remix, and more
+- **Zero-Config Dark Mode** - Intelligent theme system with SSR-safe persistence
+- **shadcn/ui Enhanced** - Extends shadcn/ui patterns with advanced features
+- **Tree Shakeable** - Optimized bundle sizes with granular imports
+
+## 🚀 Quick Installation
+
+```bash
+npm install @neynar/ui
+# or
+yarn add @neynar/ui
+# or
+pnpm add @neynar/ui
+```
+
+## ⚡ Get Started in 30 Seconds
+
+```tsx
+import { Button, Card, CardHeader, CardTitle, CardContent } from "@neynar/ui";
+import "@neynar/ui/styles";
+
+function App() {
+  return (
+    <Card className="max-w-md">
+      <CardHeader>
+        <CardTitle>@neynar/ui is Ready</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <Button>Primary Action</Button>
+        <Button variant="outline">Secondary Action</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## 🎨 Component Categories
+
+| Category | Components | Description |
+|----------|------------|-------------|
+| 📝 **Forms & Input** | Button, Input, Textarea, TextField, Select, Combobox, Checkbox, Switch, RadioGroup, DatePicker, Calendar, Label, Slider | Essential form building blocks with validation support |
+| 📱 **Layout & Structure** | Container, Stack, Card, Separator, AspectRatio, Accordion, Collapsible, Resizable, ScrollArea | Flexible components for responsive layouts |
+| 🧭 **Navigation & Menus** | NavigationMenu, Tabs, Breadcrumb, Pagination, Sidebar, DropdownMenu, ContextMenu, Menubar, Command | Comprehensive navigation solutions |
+| 💬 **Overlays & Dialogs** | Dialog, AlertDialog, Popover, Tooltip, Sheet, HoverCard, Drawer | Modal interactions with advanced positioning |
+| ✍️ **Typography** | Typography (with H1-H6, P, A, Code, Label variants) | Consistent text styling with semantic HTML |
+| 📊 **Data Display** | Table, Badge, Avatar, Alert, Progress, Skeleton, EmptyState, Chart, Carousel, Sonner | Rich components for presenting information |
+| 🔧 **Interactive Controls** | Toggle, ToggleGroup, ThemeToggle | Advanced interaction components |
+| 🪝 **Hooks** | useTheme, useIsMobile | React hooks for common functionality |
+| 🛠️ **Utilities** | cn, Theme | Helper utilities and setup components |
+
+## 🌙 Theming
+
+Zero-config light/dark mode with FOUC prevention:
+
+```tsx
+// 1. Add Theme component early in your app (required for FOUC prevention)
+import { Theme } from "@neynar/ui";
+
+// Next.js App Router
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <Theme /> {/* Prevents flash of wrong theme */}
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+
+// Vite/React
+function App() {
+  return (
+    <>
+      <Theme /> {/* Place at the top */}
+      <div className="app">
+        {/* Your app content */}
+      </div>
+    </>
+  );
+}
+
+// 2. Add ThemeToggle anywhere for user control (optional)
+import { ThemeToggle } from "@neynar/ui";
+
+function Header() {
+  return (
+    <header>
+      <h1>My App</h1>
+      <ThemeToggle />
+    </header>
+  );
+}
+```
+
+**How it works:**
+
+- **Theme component** - Injects a tiny script that runs before first paint
+- **No FOUC** - Theme applied instantly on page load
+- **Auto-detects** system preference (light/dark)
+- **Persists** selection in cookies (SSR-safe)
+- **Synchronized** - Multiple ThemeToggle instances stay in sync via events
+- **Framework agnostic** - Works with Next.js, Vite, Remix, etc.
+
+**[→ Complete Theming Guide](./docs/theming.md)** - Learn how to customize colors, create brand themes, and advanced theming patterns.
+
+## 🔧 Framework Integration
+
+@neynar/ui works seamlessly with all modern React frameworks:
+
+- **[Next.js Integration →](./docs/integrations/nextjs.md)** - App Router, Pages Router, SSR, SSG, and custom Link components
+- **[Vite + React Integration →](./docs/integrations/vite.md)** - SPA, React Router, and development setup
+
+## 📈 Performance & Bundle Optimization
+
+### Tree Shaking
+
+Import only what you need for optimal bundle sizes:
+
+```tsx
+// ✅ Good - Import specific components
+import { Button, Card, CardHeader, CardTitle, CardContent } from "@neynar/ui";
+
+// ❌ Avoid - Imports entire library
+import * as UI from "@neynar/ui";
+```
+
+## 📚 Documentation
+
+### 📖 Available Documentation
+
+- **[Component Reference](./docs/components.md)** - Complete component catalog with usage examples
+- **[Troubleshooting Guide](./docs/troubleshooting.md)** - Common issues and solutions
+
+### 🤖 AI & Development Resources
+
+- **[LLM Documentation](./docs/llm/)** - LLM-optimized component usage and templates
+
+## 🛡️ Quality Assurance
+
+### Accessibility Standards
+
+- **WCAG 2.1 AA Compliance** - All components meet accessibility standards
+- **Keyboard Navigation** - Full keyboard support across all interactive elements
+- **Screen Reader Support** - Comprehensive ARIA implementation
+- **Focus Management** - Intelligent focus trapping and restoration
+- **Color Contrast** - Meets contrast requirements in all themes
+
+## 🤝 Contributing & Support
+
+### Community Resources
+
+- **[Storybook Documentation](https://neynar-ui.vercel.app)** - Interactive component explorer
+
+### Contributing Guidelines
+
+- **[Contributing Guide](./CONTRIBUTING.md)** - Complete guide for adding new components
+- **[LLM Prompts](./docs/llm-prompts/)** - Copy-paste prompts for creating shadcn-based and custom components
+
+This library extends shadcn/ui patterns with Neynar-specific enhancements. When contributing:
+
+- Follow our component categorization system (Buttons, Forms, Display, etc.)
+- Include comprehensive TypeScript definitions and TSDoc documentation
+- Create Storybook stories with proper category organization
+- Update all documentation files (AI docs, component docs, exports)
+- Ensure accessibility-first implementations with full keyboard support
+- Pass all automated tests including accessibility compliance checks
+
+## 📄 License
+
+MIT License - see the [LICENSE](./LICENSE) file for complete details.
+
+### Acknowledgments
+
+This library is built on top of excellent open-source projects:
+
+- **[shadcn/ui](https://ui.shadcn.com)** - Component patterns and design system foundation (MIT)
+- **[Radix UI](https://www.radix-ui.com)** - Accessible component primitives (MIT)
+- **[Tailwind CSS](https://tailwindcss.com)** - Utility-first CSS framework (MIT)
+- **[Lucide Icons](https://lucide.dev)** - Beautiful open-source icons (ISC)
+- **[class-variance-authority](https://cva.style)** - Component variant management (Apache-2.0)
+
+---
+
+**Built with ❤️ by the Neynar team**

package/dist/components/ui/accordion.d.ts

@@ -0,0 +1,229 @@
+import * as React from "react";
+import * as AccordionPrimitive from "@radix-ui/react-accordion";
+/**
+ * Accordion - Collapsible content panels for organizing information
+ *
+ * A vertically stacked set of interactive headings that each reveal a section of content.
+ * Built on Radix UI Accordion primitives with optimized animations and accessibility.
+ * Supports both single and multiple expanded items simultaneously based on the type prop.
+ *
+ * @example
+ * ```tsx
+ * // Basic single accordion (only one item can be open)
+ * <Accordion type="single" collapsible>
+ *   <AccordionItem value="item-1">
+ *     <AccordionTrigger>Is it accessible?</AccordionTrigger>
+ *     <AccordionContent>
+ *       Yes. It adheres to the WAI-ARIA design pattern.
+ *     </AccordionContent>
+ *   </AccordionItem>
+ * </Accordion>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple accordion (multiple items can be open)
+ * <Accordion type="multiple">
+ *   <AccordionItem value="item-1">
+ *     <AccordionTrigger>Section 1</AccordionTrigger>
+ *     <AccordionContent>Content for section 1</AccordionContent>
+ *   </AccordionItem>
+ *   <AccordionItem value="item-2">
+ *     <AccordionTrigger>Section 2</AccordionTrigger>
+ *     <AccordionContent>Content for section 2</AccordionContent>
+ *   </AccordionItem>
+ * </Accordion>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // FAQ-style accordion with default open state
+ * <Accordion type="single" collapsible defaultValue="faq-1">
+ *   <AccordionItem value="faq-1">
+ *     <AccordionTrigger>How do I get started?</AccordionTrigger>
+ *     <AccordionContent>
+ *       Follow our quick start guide to set up your first project.
+ *     </AccordionContent>
+ *   </AccordionItem>
+ * </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
+ * - Screen reader announcements for state changes
+ * - Focus management with visible focus indicators
+ * - Properly labeled regions with aria-labelledby
+ * - Meets WCAG 2.1 AA standards for interactive elements
+ *
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/accordion/} WAI-ARIA Accordion Pattern
+ * @see {@link https://ui.shadcn.com/docs/components/accordion} shadcn/ui Accordion Documentation
+ * @see {@link AccordionItem} Individual accordion panel container
+ * @see {@link AccordionTrigger} Clickable header to expand/collapse content
+ * @see {@link AccordionContent} Collapsible content area with smooth animations
+ * @since 1.0.0
+ */
+declare function Accordion({ ...props }: React.ComponentProps<typeof AccordionPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+/**
+ * AccordionItem - Individual collapsible panel within an accordion
+ *
+ * A container component that wraps a single accordion section consisting of a trigger
+ * and collapsible content. Each item requires a unique value prop for identification
+ * and state management. Provides consistent spacing and border styling.
+ *
+ * @example
+ * ```tsx
+ * <AccordionItem value="settings">
+ *   <AccordionTrigger>Account Settings</AccordionTrigger>
+ *   <AccordionContent>
+ *     <p>Manage your account preferences and security settings.</p>
+ *   </AccordionContent>
+ * </AccordionItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom styling
+ * <AccordionItem value="custom" className="border-l-4 border-blue-500">
+ *   <AccordionTrigger>Custom Styled Item</AccordionTrigger>
+ *   <AccordionContent>Content with custom left border</AccordionContent>
+ * </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
+ * - Provides proper focus management between items
+ * - Supports keyboard navigation within the accordion group
+ *
+ * @see {@link AccordionTrigger} The clickable header for this item
+ * @see {@link AccordionContent} The collapsible content for this item
+ */
+declare function AccordionItem({ className, ...props }: React.ComponentProps<typeof AccordionPrimitive.Item>): import("react/jsx-runtime").JSX.Element;
+/**
+ * AccordionTrigger - Clickable header that toggles accordion content visibility
+ *
+ * An interactive button element that users click or activate via keyboard to expand
+ * or collapse the associated accordion content. Features a rotating chevron icon
+ * for visual state indication and supports both text and custom content.
+ *
+ * @example
+ * ```tsx
+ * // Simple text trigger
+ * <AccordionTrigger>
+ *   Click to expand this section
+ * </AccordionTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With icon and custom styling
+ * <AccordionTrigger className="text-lg font-semibold">
+ *   <User className="mr-2 h-4 w-4" />
+ *   User Profile Settings
+ * </AccordionTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With complex content
+ * <AccordionTrigger>
+ *   <div className="flex items-center justify-between w-full">
+ *     <span>Section Title</span>
+ *     <Badge variant="secondary">5 items</Badge>
+ *   </div>
+ * </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
+ * - Focus visible ring for keyboard navigation with proper contrast
+ * - Chevron icon rotation provides visual state feedback
+ * - Screen reader support with proper labeling and state announcements
+ * - Meets WCAG 2.1 AA interactive element requirements
+ *
+ * @see {@link AccordionContent} The content area controlled by this trigger
+ */
+declare function AccordionTrigger({ className, children, ...props }: React.ComponentProps<typeof AccordionPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
+/**
+ * AccordionContent - Collapsible content area of an accordion item
+ *
+ * The expandable content section that is revealed or hidden when the associated
+ * AccordionTrigger is activated. Features smooth height-based animations using
+ * Tailwind CSS keyframes and supports any React content including complex layouts.
+ *
+ * @example
+ * ```tsx
+ * // Simple text content
+ * <AccordionContent>
+ *   <p>This content is revealed when the accordion is expanded.</p>
+ *   <p>It can contain any React components or HTML elements.</p>
+ * </AccordionContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Rich content with components
+ * <AccordionContent>
+ *   <div className="space-y-4">
+ *     <Alert>
+ *       <InfoIcon className="h-4 w-4" />
+ *       <AlertTitle>Important Note</AlertTitle>
+ *       <AlertDescription>This is highlighted information.</AlertDescription>
+ *     </Alert>
+ *     <Button variant="outline">Take Action</Button>
+ *   </div>
+ * </AccordionContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Content with custom padding
+ * <AccordionContent className="pt-6 pb-6">
+ *   Content with extra vertical padding for better spacing.
+ * </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
+ * - Properly associated with trigger via ARIA attributes (aria-controls, aria-labelledby)
+ * - Content respects prefers-reduced-motion user preference
+ * - Focus moves naturally to content when expanded via keyboard
+ *
+ * @animation
+ * - Uses data-[state=open]:animate-accordion-down for expand animation
+ * - Uses data-[state=closed]:animate-accordion-up for collapse animation
+ * - Animations respect user's motion preferences
+ * - Smooth height transitions using Radix UI's --radix-accordion-content-height variable
+ *
+ * @see {@link AccordionTrigger} The trigger that controls this content's visibility
+ */
+declare function AccordionContent({ className, children, ...props }: React.ComponentProps<typeof AccordionPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent };
+//# sourceMappingURL=accordion.d.ts.map

package/dist/components/ui/accordion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accordion.d.ts","sourceRoot":"","sources":["../../../src/components/ui/accordion.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,kBAAkB,MAAM,2BAA2B,CAAC;AAKhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,iBAAS,SAAS,CAAC,EACjB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,kBAAkB,CAAC,IAAI,CAAC,2CAEtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,iBAAS,aAAa,CAAC,EACrB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,kBAAkB,CAAC,IAAI,CAAC,2CAQtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,iBAAS,gBAAgB,CAAC,EACxB,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,kBAAkB,CAAC,OAAO,CAAC,2CAgBzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,iBAAS,gBAAgB,CAAC,EACxB,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,kBAAkB,CAAC,OAAO,CAAC,2CAUzD;AAED,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC"}