@neynar/ui 0.1.1

package/src/components/ui/skeleton.tsx

@@ -0,0 +1,76 @@
+import { cn } from "@/lib/utils";
+
+/**
+ * A skeleton component for displaying loading placeholders that improve perceived performance
+ *
+ * The Skeleton component creates animated placeholders that mimic the structure and layout
+ * of content that is being loaded. It uses a subtle pulse animation to indicate loading
+ * state and maintains layout stability during data fetching operations.
+ *
+ * Based on shadcn/ui skeleton patterns, this component is designed to be highly composable
+ * and can be shaped to match any content structure using Tailwind CSS classes.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - simple text placeholder
+ * <Skeleton className="h-4 w-[250px]" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Avatar skeleton - circular placeholder
+ * <Skeleton className="h-12 w-12 rounded-full" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Card skeleton - structured content placeholder
+ * <div className="space-y-2">
+ *   <Skeleton className="h-6 w-3/4" />
+ *   <Skeleton className="h-4 w-full" />
+ *   <Skeleton className="h-4 w-5/6" />
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex layout with multiple skeletons
+ * <Card>
+ *   <CardHeader>
+ *     <div className="flex items-center gap-3">
+ *       <Skeleton className="h-10 w-10 rounded-full" />
+ *       <div className="space-y-2">
+ *         <Skeleton className="h-4 w-24" />
+ *         <Skeleton className="h-3 w-16" />
+ *       </div>
+ *     </div>
+ *   </CardHeader>
+ *   <CardContent>
+ *     <Skeleton className="h-4 w-full" />
+ *     <Skeleton className="h-4 w-4/5" />
+ *   </CardContent>
+ * </Card>
+ * ```
+ *
+ * @param className - Additional CSS classes for customizing size, shape, and appearance
+ * @param props - Standard HTML div element props
+ *
+ * @accessibility
+ * The component includes a pulse animation to indicate loading state and maintains
+ * layout stability. Consider adding aria-busy="true" or aria-label="Loading content"
+ * to parent containers for better screen reader support.
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/skeleton} shadcn/ui Skeleton documentation
+ * @since 1.0.0
+ */
+function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="skeleton"
+      className={cn("bg-accent animate-pulse rounded-md", className)}
+      {...props}
+    />
+  );
+}
+
+export { Skeleton };

package/src/components/ui/slider.tsx

@@ -0,0 +1,147 @@
+import * as React from "react";
+import * as SliderPrimitive from "@radix-ui/react-slider";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Slider component for selecting numeric values within a range
+ *
+ * A versatile range input control built on Radix UI Slider primitives that allows users
+ * to select single or multiple values by dragging thumbs along a track. Supports both
+ * horizontal and vertical orientations, custom ranges, step intervals, and accessibility
+ * features for keyboard and touch interaction.
+ *
+ * Based on the shadcn/ui Slider component with enhanced styling and behavior.
+ *
+ * @example
+ * ```tsx
+ * // Basic single-value slider
+ * <Slider defaultValue={[33]} max={100} step={1} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled slider with state
+ * const [value, setValue] = useState([25])
+ *
+ * <Slider
+ *   value={value}
+ *   onValueChange={setValue}
+ *   max={100}
+ *   step={5}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Range slider with two thumbs
+ * <Slider
+ *   defaultValue={[25, 75]}
+ *   max={100}
+ *   step={1}
+ *   minStepsBetweenThumbs={10}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical orientation
+ * <Slider
+ *   defaultValue={[50]}
+ *   max={100}
+ *   orientation="vertical"
+ *   className="h-60"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom range and step
+ * <Slider
+ *   defaultValue={[500]}
+ *   min={0}
+ *   max={1000}
+ *   step={50}
+ * />
+ * ```
+ *
+ * @accessibility
+ * - Implements WAI-ARIA slider pattern with proper roles and properties
+ * - Arrow keys adjust value by step amount (Left/Down decrease, Right/Up increase)
+ * - Page Up/Page Down adjust by larger increments (10 × step)
+ * - Home/End keys jump to minimum/maximum values
+ * - Supports keyboard navigation with focus visible indicators
+ * - Touch and mouse interaction supported
+ * - Screen reader announcements for value changes
+ * - Disabled state properly communicated to assistive technologies
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/slider} for design patterns
+ * @see {@link https://www.radix-ui.com/docs/primitives/components/slider} for API reference
+ *
+ * @since 1.0.0
+ */
+/**
+ * @param className - Additional CSS classes for styling customization
+ * @param defaultValue - The default value(s) of the slider (uncontrolled)
+ * @param value - The controlled value(s) of the slider
+ * @param min - The minimum value of the slider (default: 0)
+ * @param max - The maximum value of the slider (default: 100)
+ * @param step - The step interval for value changes (default: 1)
+ * @param orientation - The orientation of the slider ("horizontal" | "vertical")
+ * @param disabled - Whether the slider is disabled
+ * @param onValueChange - Callback fired when the value changes
+ * @param minStepsBetweenThumbs - Minimum steps between thumbs in range mode
+ * @param ...props - Additional props passed to the underlying Radix Slider Root
+ */
+function Slider({
+  className,
+  defaultValue,
+  value,
+  min = 0,
+  max = 100,
+  ...props
+}: React.ComponentProps<typeof SliderPrimitive.Root>) {
+  const _values = Array.isArray(value)
+    ? value
+    : Array.isArray(defaultValue)
+      ? defaultValue
+      : [min, max];
+
+  return (
+    <SliderPrimitive.Root
+      data-slot="slider"
+      defaultValue={defaultValue}
+      value={value}
+      min={min}
+      max={max}
+      className={cn(
+        "relative flex w-full touch-none items-center select-none data-[disabled]:opacity-50 data-[orientation=vertical]:h-full data-[orientation=vertical]:min-h-44 data-[orientation=vertical]:w-auto data-[orientation=vertical]:flex-col",
+        className,
+      )}
+      {...props}
+    >
+      <SliderPrimitive.Track
+        data-slot="slider-track"
+        className={cn(
+          "bg-muted relative grow overflow-hidden rounded-full data-[orientation=horizontal]:h-1.5 data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-1.5",
+        )}
+      >
+        <SliderPrimitive.Range
+          data-slot="slider-range"
+          className={cn(
+            "bg-primary absolute data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full",
+          )}
+        />
+      </SliderPrimitive.Track>
+      {Array.from({ length: _values.length }, (_, index) => (
+        <SliderPrimitive.Thumb
+          data-slot="slider-thumb"
+          key={index}
+          className="border-primary bg-background ring-ring/50 block size-4 shrink-0 rounded-full border shadow-sm transition-[color,box-shadow] hover:ring-4 focus-visible:ring-4 focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50"
+        />
+      ))}
+    </SliderPrimitive.Root>
+  );
+}
+
+export { Slider };

package/src/components/ui/sonner.tsx

@@ -0,0 +1,120 @@
+import { useTheme } from "@/hooks/use-theme";
+import { Toaster as Sonner, type ToasterProps, toast } from "sonner";
+
+/**
+ * Toast notification container component built on Sonner
+ *
+ * An opinionated toast component that provides beautiful, accessible notifications
+ * with minimal setup. Automatically integrates with the theme system and provides
+ * consistent styling across the application. This is the recommended toast solution
+ * for @neynar/ui projects, replacing previous toast implementations.
+ *
+ * @example
+ * ```tsx
+ * // Add to your app root layout
+ * import { Toaster } from '@neynar/ui/components/ui/sonner';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="en">
+ *       <body>
+ *         <main>{children}</main>
+ *         <Toaster />
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Basic toast usage from anywhere in your app
+ * import { toast } from 'sonner';
+ *
+ * // Simple notification
+ * toast('Cast published successfully');
+ *
+ * // Success variant
+ * toast.success('Profile updated');
+ *
+ * // With description and action
+ * toast('Event created', {
+ *   description: 'Sunday, December 03, 2023 at 9:00 AM',
+ *   action: {
+ *     label: 'Undo',
+ *     onClick: () => console.log('Undo')
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Promise-based toasts for async operations
+ * toast.promise(saveData(), {
+ *   loading: 'Saving changes...',
+ *   success: 'Data saved successfully!',
+ *   error: 'Failed to save changes'
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom configuration
+ * <Toaster
+ *   position="top-center"
+ *   expand={true}
+ *   richColors
+ *   duration={5000}
+ *   closeButton
+ * />
+ * ```
+ *
+ * @param props - Configuration options for the toast container
+ * @param props.position - Position of toasts on screen. Options: "top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right". Default: "bottom-right"
+ * @param props.hotkey - Keyboard shortcut to focus toasts. Default: ["altKey", "KeyT"]
+ * @param props.richColors - Enable enhanced colors for different toast types. Default: false
+ * @param props.expand - Expand toasts by default to show full content. Default: false
+ * @param props.duration - Default duration in milliseconds before auto-dismiss. Default: 4000
+ * @param props.gap - Spacing between toasts in pixels. Default: 14
+ * @param props.visibleToasts - Maximum number of toasts visible at once. Default: 3
+ * @param props.closeButton - Show close button on each toast. Default: false
+ * @param props.toastOptions - Default options applied to all toasts
+ * @param props.className - Additional CSS classes for the toast container
+ * @param props.style - Additional inline styles for the toast container
+ * @param props.offset - Offset from viewport edges in pixels or string
+ * @param props.dir - Text direction for toast content. Options: "ltr", "rtl", "auto". Default: "ltr"
+ * @param props.loadingIcon - Custom loading icon component
+ * @param props.icons - Custom icons for different toast types
+ *
+ * @accessibility
+ * - Toasts are announced to screen readers with appropriate ARIA attributes
+ * - Keyboard navigation support with customizable hotkey
+ * - Auto-dismiss functionality with configurable duration
+ * - Focus management for interactive elements within toasts
+ * - Respects user's prefers-reduced-motion settings
+ * - High contrast support for better visibility
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/sonner} - shadcn/ui Sonner documentation
+ * @see {@link https://sonner.emilkowal.ski/} - Official Sonner documentation
+ * @since 1.0.0
+ */
+function Toaster({ ...props }: ToasterProps) {
+  const { mode } = useTheme();
+
+  return (
+    <Sonner
+      theme={mode as ToasterProps["theme"]}
+      className="toaster group"
+      style={
+        {
+          "--normal-bg": "var(--popover)",
+          "--normal-text": "var(--popover-foreground)",
+          "--normal-border": "var(--border)",
+        } as React.CSSProperties
+      }
+      {...props}
+    />
+  );
+}
+
+export { Toaster, toast };

package/src/components/ui/stack.tsx

@@ -0,0 +1,180 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * Props for the Stack component
+ *
+ * @public
+ */
+export type StackProps = React.HTMLAttributes<HTMLDivElement> & {
+  /**
+   * The spacing between stack items using Tailwind CSS spacing scale
+   *
+   * Controls the gap between child elements using Tailwind's space utilities.
+   * Each value corresponds to a Tailwind spacing unit (1 = 0.25rem, 4 = 1rem, etc.)
+   *
+   * @defaultValue 4
+   * @example
+   * ```tsx
+   * // Tight spacing for compact layouts
+   * <Stack spacing={2}>
+   *   <Button>Save</Button>
+   *   <Button>Cancel</Button>
+   * </Stack>
+   *
+   * // Generous spacing for section separation
+   * <Stack spacing={8}>
+   *   <section>First section</section>
+   *   <section>Second section</section>
+   * </Stack>
+   * ```
+   */
+  spacing?: 1 | 2 | 3 | 4 | 6 | 8 | 12;
+
+  /**
+   * The layout direction of the stack
+   *
+   * - `"vertical"` - Arranges children in a column with vertical spacing
+   * - `"horizontal"` - Arranges children in a row with horizontal spacing
+   *
+   * @defaultValue "vertical"
+   * @example
+   * ```tsx
+   * // Vertical stack (default)
+   * <Stack>
+   *   <Card>Item 1</Card>
+   *   <Card>Item 2</Card>
+   * </Stack>
+   *
+   * // Horizontal stack for action buttons
+   * <Stack direction="horizontal">
+   *   <Button>Primary</Button>
+   *   <Button variant="outline">Secondary</Button>
+   * </Stack>
+   * ```
+   */
+  direction?: "vertical" | "horizontal";
+};
+
+/**
+ * Stack - A flexible layout component for consistent spacing between elements
+ *
+ * Stack is a fundamental layout primitive that arranges child elements in either
+ * vertical or horizontal direction with consistent spacing. Built on flexbox principles,
+ * it provides a clean API for common layout patterns without requiring custom CSS.
+ *
+ * This component is particularly useful for:
+ * - Form layouts with consistent field spacing
+ * - Button groups and action bars
+ * - Content sections with uniform gaps
+ * - Navigation lists and menus
+ * - Card layouts and content grids
+ *
+ * @example Basic vertical layout (default)
+ * ```tsx
+ * <Stack>
+ *   <Card>Profile Information</Card>
+ *   <Card>Account Settings</Card>
+ *   <Card>Privacy Controls</Card>
+ * </Stack>
+ * ```
+ *
+ * @example Horizontal action bar
+ * ```tsx
+ * <Stack direction="horizontal" spacing={3}>
+ *   <Button>Save Changes</Button>
+ *   <Button variant="outline">Cancel</Button>
+ *   <Button variant="ghost">Reset</Button>
+ * </Stack>
+ * ```
+ *
+ * @example Form sections with custom spacing
+ * ```tsx
+ * <Stack spacing={6}>
+ *   <fieldset>
+ *     <legend>Personal Information</legend>
+ *     <Stack spacing={3}>
+ *       <Input placeholder="Full Name" />
+ *       <Input placeholder="Email Address" />
+ *     </Stack>
+ *   </fieldset>
+ *   <fieldset>
+ *     <legend>Preferences</legend>
+ *     <Stack spacing={2}>
+ *       <Checkbox>Email notifications</Checkbox>
+ *       <Checkbox>Marketing updates</Checkbox>
+ *     </Stack>
+ *   </fieldset>
+ * </Stack>
+ * ```
+ *
+ * @example Responsive layout with additional styling
+ * ```tsx
+ * <Stack
+ *   spacing={4}
+ *   className="w-full max-w-md mx-auto p-6"
+ * >
+ *   <h2>User Dashboard</h2>
+ *   <Stack direction="horizontal" spacing={2} className="justify-between">
+ *     <Badge>Online</Badge>
+ *     <Button size="sm">Edit Profile</Button>
+ *   </Stack>
+ * </Stack>
+ * ```
+ *
+ * @remarks
+ * **Design Philosophy:**
+ * - Follows the principle of consistent spacing throughout the UI
+ * - Uses Tailwind's spacing scale for predictable sizing
+ * - Composable with other layout components
+ * - Maintains semantic HTML structure
+ *
+ * **Performance:**
+ * - Lightweight wrapper around flexbox CSS
+ * - No JavaScript overhead for layout calculations
+ * - Leverages Tailwind's JIT compilation for minimal CSS
+ *
+ * **Accessibility:**
+ * - Preserves natural document flow and reading order
+ * - Compatible with screen readers and keyboard navigation
+ * - Supports semantic HTML elements as children
+ * - Does not interfere with focus management
+ *
+ * @public
+ * @since 1.0.0
+ * @see {@link https://tailwindcss.com/docs/space} Tailwind CSS spacing utilities
+ */
+const Stack = React.forwardRef<HTMLDivElement, StackProps>(
+  ({ className, spacing = 4, direction = "vertical", ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          direction === "vertical" ? "flex flex-col" : "flex flex-row",
+          {
+            "space-y-1": direction === "vertical" && spacing === 1,
+            "space-y-2": direction === "vertical" && spacing === 2,
+            "space-y-3": direction === "vertical" && spacing === 3,
+            "space-y-4": direction === "vertical" && spacing === 4,
+            "space-y-6": direction === "vertical" && spacing === 6,
+            "space-y-8": direction === "vertical" && spacing === 8,
+            "space-y-12": direction === "vertical" && spacing === 12,
+            "space-x-1": direction === "horizontal" && spacing === 1,
+            "space-x-2": direction === "horizontal" && spacing === 2,
+            "space-x-3": direction === "horizontal" && spacing === 3,
+            "space-x-4": direction === "horizontal" && spacing === 4,
+            "space-x-6": direction === "horizontal" && spacing === 6,
+            "space-x-8": direction === "horizontal" && spacing === 8,
+            "space-x-12": direction === "horizontal" && spacing === 12,
+          },
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+Stack.displayName = "Stack";
+
+export { Stack };