@neynar/ui 0.3.0 → 0.4.0

package/.llm/toggle-group.llm.md

@@ -0,0 +1,101 @@
+# ToggleGroup
+
+**Type**: component
+
+Toggle Group - A group of toggle buttons with single or multiple selection ToggleGroup provides a way to group related toggle buttons together, allowing users to select from a set of mutually exclusive options (single selection) or independent options (multiple selection). Built on Radix UI Toggle Group primitive with enhanced styling through CVA variants and full accessibility support including keyboard navigation. The component supports both controlled and uncontrolled usage patterns, with automatic focus management and roving tabindex behavior. Visual variants are inherited by all child items but can be overridden per item if needed.
+
+## JSX Usage
+
+```jsx
+import { ToggleGroup } from '@neynar/ui';
+
+<ToggleGroup
+  className="value"
+  type={value}
+  variant={value}
+  size={value}
+  defaultValue={[]}
+  value={[]}
+  onValueChange={handleValueChange}
+  disabled={true}
+  rovingFocus={true}
+  orientation={value}
+  dir={value}
+  loop={true}
+  asChild={true}
+>
+  {/* Your content here */}
+</ToggleGroup>
+```
+
+## Component Props
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### type
+- **Type**: `"single" | "multiple"`
+- **Required**: Yes
+- **Description**: No description available
+
+### variant
+- **Type**: `"default" | "outline"`
+- **Required**: No
+- **Description**: No description available
+
+### size
+- **Type**: `"sm" | "default" | "lg"`
+- **Required**: No
+- **Description**: No description available
+
+### defaultValue
+- **Type**: `string | string[]`
+- **Required**: No
+- **Description**: No description available
+
+### value
+- **Type**: `string | string[]`
+- **Required**: No
+- **Description**: No description available
+
+### onValueChange
+- **Type**: `(value: string | string[]) => void`
+- **Required**: No
+- **Description**: No description available
+
+### disabled
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### rovingFocus
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### orientation
+- **Type**: `"horizontal" | "vertical"`
+- **Required**: No
+- **Description**: No description available
+
+### dir
+- **Type**: `"ltr" | "rtl"`
+- **Required**: No
+- **Description**: No description available
+
+### loop
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available

package/.llm/toggle.llm.md

@@ -0,0 +1,40 @@
+# Toggle
+
+**Type**: component
+
+A two-state button that can be either on or off The Toggle component provides an accessible button with on/off state functionality. Built on Radix UI Toggle primitives with customizable variants and sizes. Perfect for text formatting controls, feature toggles, and any binary state controls. Automatically manages ARIA attributes and provides keyboard navigation.
+
+## JSX Usage
+
+```jsx
+import { Toggle } from '@neynar/ui';
+
+<Toggle
+  className={value}
+  variant={value}
+  size={value}
+  ...props={value}
+/>
+```
+
+## Component Props
+
+### className
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### variant
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### size
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available
+
+### ...props
+- **Type**: `unknown`
+- **Required**: Yes
+- **Description**: No description available

package/.llm/tooltip-content.llm.md

@@ -0,0 +1,185 @@
+# TooltipContent
+
+**Type**: component
+
+TooltipContent - The floating tooltip content container Contains the content displayed in the tooltip popup. Automatically positioned relative to the trigger element with intelligent collision detection to ensure the tooltip stays within the viewport. Includes smooth animations and an arrow pointer for visual connection to the trigger. The content component handles complex positioning logic, including collision detection, viewport boundaries, and responsive positioning. It supports rich content including text, images, and interactive elements while maintaining accessibility standards.
+
+## JSX Usage
+
+```jsx
+import { TooltipContent } from '@neynar/ui';
+
+<TooltipContent
+  asChild={true}
+  "aria-label"="value"
+  onEscapeKeyDown={handleEscapeKeyDown}
+  onPointerDownOutside={handlePointerDownOutside}
+  forceMount={true}
+  side={value}
+  sideOffset={0}
+  align={value}
+  alignOffset={0}
+  avoidCollisions={true}
+  collisionBoundary={[]}
+  collisionPadding={value}
+  arrowPadding={0}
+  sticky={value}
+  hideWhenDetached={true}
+  className="value"
+>
+  {/* Your content here */}
+</TooltipContent>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### "aria-label"
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### onEscapeKeyDown
+- **Type**: `(event: KeyboardEvent) => void`
+- **Required**: No
+- **Description**: No description available
+
+### onPointerDownOutside
+- **Type**: `(event: PointerEvent) => void`
+- **Required**: No
+- **Description**: No description available
+
+### forceMount
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### side
+- **Type**: `"top" | "right" | "bottom" | "left"`
+- **Required**: No
+- **Description**: No description available
+
+### sideOffset
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### align
+- **Type**: `"start" | "center" | "end"`
+- **Required**: No
+- **Description**: No description available
+
+### alignOffset
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### avoidCollisions
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### collisionBoundary
+- **Type**: `Element | Element[]`
+- **Required**: No
+- **Description**: No description available
+
+### collisionPadding
+- **Type**: `| number
+    | { top?: number; right?: number; bottom?: number; left?: number }`
+- **Required**: No
+- **Description**: No description available
+
+### arrowPadding
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### sticky
+- **Type**: `"partial" | "always"`
+- **Required**: No
+- **Description**: No description available
+
+### hideWhenDetached
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### className
+- **Type**: `string`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Simple text tooltip
+<TooltipContent>
+  <p>This is helpful information</p>
+</TooltipContent>
+```
+### Example 2
+```tsx
+// Positioned tooltip with custom offset
+<TooltipContent
+  side="left"
+  sideOffset={12}
+  align="start"
+  alignOffset={-4}
+>
+  <p>Precisely positioned tooltip</p>
+</TooltipContent>
+```
+### Example 3
+```tsx
+// Rich content with custom styling
+<TooltipContent className="max-w-[320px] p-4">
+  <div className="space-y-2">
+    <div className="flex items-center gap-2">
+      <InfoIcon className="h-4 w-4 text-blue-500" />
+      <p className="font-semibold">Pro Feature</p>
+    </div>
+    <p className="text-sm text-gray-600">
+      This feature is available in Pro plans. Upgrade to unlock
+      advanced functionality and premium support.
+    </p>
+    <Button size="sm" className="mt-2">Upgrade Now</Button>
+  </div>
+</TooltipContent>
+```
+### Example 4
+```tsx
+// Tooltip with collision boundary
+<TooltipContent
+  collisionPadding={{ top: 10, bottom: 10 }}
+  hideWhenDetached
+  sticky="always"
+>
+  <p>Stays within safe boundaries</p>
+</TooltipContent>
+```
+### Example 5
+```tsx
+// Controlled tooltip with escape handling
+<TooltipContent
+  onEscapeKeyDown={(e) => {
+    console.log('Tooltip dismissed with Escape');
+    // Custom handling if needed
+  }}
+  onPointerDownOutside={(e) => {
+    console.log('Clicked outside tooltip');
+  }}
+>
+  <p>Interactive tooltip with event handlers</p>
+</TooltipContent>
+```

package/.llm/tooltip-provider.llm.md

@@ -0,0 +1,68 @@
+# TooltipProvider
+
+**Type**: component
+
+TooltipProvider - Global context provider for tooltip functionality Wraps your application or component tree to enable tooltip functionality. Controls global tooltip behavior such as delay duration before showing tooltips. Required for tooltip components to function properly across your app. The provider manages global settings that affect all tooltips within its tree, including timing behavior and accessibility features. Individual tooltips can override these settings as needed.
+
+## JSX Usage
+
+```jsx
+import { TooltipProvider } from '@neynar/ui';
+
+<TooltipProvider
+  delayDuration={0}
+  skipDelayDuration={0}
+  disableHoverableContent={true}
+>
+  {/* Your content here */}
+</TooltipProvider>
+```
+
+## Component Props
+
+### delayDuration
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### skipDelayDuration
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### disableHoverableContent
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Wrap your entire app
+<TooltipProvider>
+  <App />
+</TooltipProvider>
+```
+### Example 2
+```tsx
+// With custom delay and skip behavior
+<TooltipProvider
+  delayDuration={500}
+  skipDelayDuration={200}
+>
+  <MyComponent />
+</TooltipProvider>
+```
+### Example 3
+```tsx
+// Disable hoverable content for stricter accessibility
+<TooltipProvider disableHoverableContent>
+  <Form />
+</TooltipProvider>
+```

package/.llm/tooltip-trigger.llm.md

@@ -0,0 +1,70 @@
+# TooltipTrigger
+
+**Type**: component
+
+TooltipTrigger - The element that triggers the tooltip display Wraps the element that will show the tooltip on hover or focus. Use the `asChild` prop to merge props with the child element rather than rendering an additional wrapper element. Essential for maintaining semantic meaning and avoiding unnecessary DOM nesting. The trigger automatically handles all interaction events including mouse hover, touch interactions, keyboard focus, and blur events. It preserves the original element's accessibility properties while adding tooltip functionality.
+
+## JSX Usage
+
+```jsx
+import { TooltipTrigger } from '@neynar/ui';
+
+<TooltipTrigger
+  asChild={true}
+>
+  {/* Your content here */}
+</TooltipTrigger>
+```
+
+## Component Props
+
+### asChild
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic trigger with button
+<TooltipTrigger asChild>
+  <Button>Hover me</Button>
+</TooltipTrigger>
+```
+### Example 2
+```tsx
+// With icon button
+<TooltipTrigger asChild>
+  <Button variant="ghost" size="icon">
+    <Settings className="h-4 w-4" />
+  </Button>
+</TooltipTrigger>
+```
+### Example 3
+```tsx
+// With disabled element (requires wrapper for pointer events)
+<TooltipTrigger asChild>
+  <span className="inline-block cursor-not-allowed">
+    <Button disabled>Disabled Action</Button>
+  </span>
+</TooltipTrigger>
+```
+### Example 4
+```tsx
+// With custom element
+<TooltipTrigger asChild>
+  <div
+    role="button"
+    tabIndex={0}
+    className="cursor-pointer p-2 rounded hover:bg-gray-100"
+  >
+    Custom trigger element
+  </div>
+</TooltipTrigger>
+```

package/.llm/tooltip.llm.md

@@ -0,0 +1,129 @@
+# Tooltip
+
+**Type**: component
+
+Tooltip - Display contextual information on hover or focus A versatile tooltip component built on Radix UI primitives that provides contextual information when users hover over or focus on an element. Perfect for displaying help text, definitions, or additional context without cluttering the interface. Automatically wraps content in a TooltipProvider for convenience. The tooltip supports both controlled and uncontrolled usage patterns, with intelligent positioning, collision detection, and smooth animations. Built with accessibility as a priority, including proper ARIA attributes and keyboard navigation support.
+
+## JSX Usage
+
+```jsx
+import { Tooltip } from '@neynar/ui';
+
+<Tooltip
+  defaultOpen={true}
+  open={true}
+  onOpenChange={handleOpenChange}
+  delayDuration={0}
+  disableHoverableContent={true}
+>
+  {/* Your content here */}
+</Tooltip>
+```
+
+## Component Props
+
+### defaultOpen
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### open
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### onOpenChange
+- **Type**: `(open: boolean) => void`
+- **Required**: No
+- **Description**: No description available
+
+### delayDuration
+- **Type**: `number`
+- **Required**: No
+- **Description**: No description available
+
+### disableHoverableContent
+- **Type**: `boolean`
+- **Required**: No
+- **Description**: No description available
+
+### children
+- **Type**: `React.ReactNode`
+- **Required**: No
+- **Description**: No description available
+
+## Examples
+
+### Example 1
+```tsx
+// Basic tooltip
+<Tooltip>
+  <TooltipTrigger asChild>
+    <Button variant="outline">Hover me</Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>This is a helpful tooltip</p>
+  </TooltipContent>
+</Tooltip>
+```
+### Example 2
+```tsx
+// Icon button with tooltip
+import { Info } from "lucide-react"
+<Tooltip>
+  <TooltipTrigger asChild>
+    <Button variant="ghost" size="icon">
+      <Info className="h-4 w-4" />
+    </Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>Additional information</p>
+  </TooltipContent>
+</Tooltip>
+```
+### Example 3
+```tsx
+// Controlled tooltip with custom delay
+const [open, setOpen] = useState(false)
+<Tooltip
+  open={open}
+  onOpenChange={setOpen}
+  delayDuration={300}
+>
+  <TooltipTrigger asChild>
+    <Button onClick={() => setOpen(!open)}>Toggle</Button>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>Controlled tooltip state</p>
+  </TooltipContent>
+</Tooltip>
+```
+### Example 4
+```tsx
+// Disabled element with tooltip (requires wrapper)
+<Tooltip>
+  <TooltipTrigger asChild>
+    <span className="inline-block">
+      <Button disabled>Disabled Action</Button>
+    </span>
+  </TooltipTrigger>
+  <TooltipContent>
+    <p>You need to complete setup first</p>
+  </TooltipContent>
+</Tooltip>
+```
+### Example 5
+```tsx
+// Positioned tooltip with rich content
+<Tooltip>
+  <TooltipTrigger asChild>
+    <Badge variant="secondary">API Key</Badge>
+  </TooltipTrigger>
+  <TooltipContent side="right" className="max-w-[250px]">
+    <div className="space-y-1">
+      <p className="font-medium">API Authentication</p>
+      <p className="text-xs">Your key is used to authenticate requests</p>
+    </div>
+  </TooltipContent>
+</Tooltip>
+```

package/.llm/use-carousel.llm.md

@@ -0,0 +1,55 @@
+# useCarousel
+
+**Type**: hook
+
+Hook to access carousel context and controls Must be used within a Carousel component. Provides access to the carousel API and navigation methods for building custom carousel interactions.
+
+## API Surface
+
+```typescript
+import { useCarousel } from '@neynar/ui';
+
+export function useCarousel(): ReturnType<typeof useCarousel> { ... }
+```
+
+## Returns
+
+**Return Type**: `ReturnType<typeof useCarousel>`
+
+
+**Description**: Carousel context containing API, navigation controls, and state
+## Usage
+
+```typescript
+import { useCarousel } from '@neynar/ui';
+
+const result = useCarousel();
+```
+
+## Examples
+
+```tsx
+function CarouselDots() {
+  const { api, scrollNext, canScrollNext } = useCarousel();
+  const [current, setCurrent] = useState(0);
+  useEffect(() => {
+    if (!api) return;
+    setCurrent(api.selectedScrollSnap());
+    api.on('select', () => setCurrent(api.selectedScrollSnap()));
+  }, [api]);
+  return (
+    <div className="flex gap-2">
+      {Array.from({ length: 5 }).map((_, i) => (
+        <button
+          key={i}
+          className={current === i ? "active" : ""}
+          onClick={() => api?.scrollTo(i)}
+        />
+      ))}
+    </div>
+  );
+}
+```
+## Throws
+
+- Error when used outside of Carousel component

package/.llm/use-command-state.llm.md

@@ -0,0 +1,32 @@
+# useCmdk
+
+**Type**: hook
+
+Run a selector against the store state.
+
+## API Surface
+
+```typescript
+import { useCmdk } from '@neynar/ui';
+
+export function useCmdk(selector: (state: State) => T): T { ... }
+```
+
+## Parameters
+
+### selector
+- **Type**: `(state: State) => T`
+- **Required**: Yes
+- **Description**: No description available
+## Returns
+
+**Return Type**: `T`
+
+
+## Usage
+
+```typescript
+import { useCmdk } from '@neynar/ui';
+
+const result = useCmdk(() => {});
+```