@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/skeleton.tsx

@@ -1,66 +1,148 @@
 import { cn } from "@/lib/utils";
 
 /**
- * A skeleton component for displaying loading placeholders that improve perceived performance
+ * Props for Skeleton component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace HTML div inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SkeletonDocsProps = {
+  /** Additional CSS classes for customizing size, shape, and appearance */
+  className?: string;
+  /** Custom children content (rarely used as skeletons are typically empty) */
+  children?: React.ReactNode;
+  /** ARIA label for accessibility when the skeleton represents specific content */
+  "aria-label"?: string;
+  /** ARIA description for accessibility when additional context is needed */
+  "aria-describedby"?: string;
+  /** Role attribute for semantic meaning (defaults to generic presentation) @default "presentation" */
+  role?: string;
+  /** Test ID for component testing */
+  "data-testid"?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Skeleton - Animated loading placeholder that improves 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.
+ * A lightweight component that creates animated placeholders mimicking the structure
+ * and layout of content being loaded. Features a subtle pulse animation to indicate
+ * loading state while maintaining 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.
+ * Built on standard HTML div element with Tailwind CSS animations. Designed to be
+ * highly composable and can be shaped to match any content structure using className.
+ * The component uses semantic presentation role by default for optimal accessibility.
  *
  * @example
  * ```tsx
- * // Basic usage - simple text placeholder
+ * // Basic text content placeholder
  * <Skeleton className="h-4 w-[250px]" />
  * ```
  *
  * @example
  * ```tsx
- * // Avatar skeleton - circular placeholder
- * <Skeleton className="h-12 w-12 rounded-full" />
+ * // Avatar placeholder - circular skeleton
+ * <Skeleton className="h-12 w-12 rounded-full" aria-label="Loading user avatar" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Button placeholder with proper dimensions
+ * <Skeleton className="h-10 w-24 rounded-md" aria-label="Loading action button" />
  * ```
  *
  * @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" />
+ * // Image placeholder with aspect ratio
+ * <Skeleton className="h-48 w-full rounded-lg" aria-label="Loading featured image" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Card content structure - multiple related skeletons
+ * <div className="space-y-3" aria-busy="true" aria-label="Loading article content">
+ *   <Skeleton className="h-6 w-3/4" /> // Title
+ *   <Skeleton className="h-4 w-full" /> // First line
+ *   <Skeleton className="h-4 w-5/6" /> // Second line
+ *   <Skeleton className="h-4 w-4/5" /> // Third line
  * </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>
+ * // Complex user profile layout
+ * <Card className="p-6">
+ *   <div className="flex items-center gap-4 mb-4">
+ *     <Skeleton className="h-16 w-16 rounded-full" aria-label="Loading profile picture" />
+ *     <div className="space-y-2">
+ *       <Skeleton className="h-5 w-32" /> // Name
+ *       <Skeleton className="h-4 w-24" /> // Title
+ *       <Skeleton className="h-3 w-20" /> // Status
  *     </div>
- *   </CardHeader>
- *   <CardContent>
+ *   </div>
+ *   <div className="space-y-3">
  *     <Skeleton className="h-4 w-full" />
  *     <Skeleton className="h-4 w-4/5" />
- *   </CardContent>
+ *     <Skeleton className="h-32 w-full rounded-md" /> // Content area
+ *   </div>
  * </Card>
  * ```
  *
- * @param className - Additional CSS classes for customizing size, shape, and appearance
- * @param props - Standard HTML div element props
+ * @example
+ * ```tsx
+ * // Data table loading state
+ * <div className="space-y-2" aria-busy="true" aria-label="Loading table data">
+ *   {Array.from({ length: 5 }).map((_, index) => (
+ *     <div key={index} className="flex items-center gap-4 p-2">
+ *       <Skeleton className="h-8 w-8 rounded-full" />
+ *       <Skeleton className="h-4 w-32" />
+ *       <Skeleton className="h-4 w-24" />
+ *       <Skeleton className="h-4 w-16" />
+ *       <div className="ml-auto">
+ *         <Skeleton className="h-8 w-20 rounded-md" />
+ *       </div>
+ *     </div>
+ *   ))}
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Navigation menu loading
+ * <nav className="space-y-2" aria-label="Loading navigation">
+ *   {Array.from({ length: 4 }).map((_, index) => (
+ *     <div key={index} className="flex items-center gap-3 p-2">
+ *       <Skeleton className="h-5 w-5 rounded" /> // Icon
+ *       <Skeleton className="h-4 w-20" /> // Label
+ *     </div>
+ *   ))}
+ * </nav>
+ * ```
  *
  * @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.
+ * - Uses pulse animation to indicate loading state without being distracting
+ * - Maintains layout dimensions to prevent content jumping when real content loads
+ * - Supports ARIA labels for screen reader context when representing specific content
+ * - Consider wrapping multiple related skeletons in containers with aria-busy="true"
+ * - Respects prefers-reduced-motion user preference through Tailwind's animate-pulse
+ * - Use meaningful aria-label values to describe what content is being loaded
+ * - Group related skeletons with appropriate ARIA landmarks for better navigation
+ *
+ * @performance
+ * - Lightweight implementation with minimal DOM overhead
+ * - CSS-based pulse animation is GPU-accelerated and performant
+ * - No JavaScript animations or intervals for optimal battery life
+ * - Optimized for SSR and hydration without layout shifts
+ *
+ * @styling
+ * - Base classes: bg-accent animate-pulse rounded-md
+ * - Highly customizable via className prop with Tailwind utilities
+ * - Common patterns: h-4 w-[200px] (text), h-12 w-12 rounded-full (avatar)
+ * - Responsive sizing: w-full md:w-1/2 lg:w-1/3 for adaptive layouts
+ * - Shape variants: rounded-none (rectangular), rounded-full (circular), rounded-lg (images)
  *
- * @see {@link https://ui.shadcn.com/docs/components/skeleton} shadcn/ui Skeleton documentation
+ * @see {@link https://ui.shadcn.com/docs/components/skeleton} shadcn/ui Skeleton Documentation
+ * @see {@link Card} Often used within card layouts for structured content loading
+ * @see {@link Avatar} Use with Avatar components for profile loading states
+ * @see {@link Button} Match button dimensions for interactive element placeholders
  * @since 1.0.0
  */
 function Skeleton({ className, ...props }: React.ComponentProps<"div">) {

package/src/components/ui/slider.tsx

@@ -4,24 +4,66 @@ import * as SliderPrimitive from "@radix-ui/react-slider";
 import { cn } from "@/lib/utils";
 
 /**
- * Slider component for selecting numeric values within a range
+ * Props for Slider (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 SliderDocsProps = {
+  /** Additional CSS classes for styling customization */
+  className?: string;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior @default false */
+  asChild?: boolean;
+  /** The default value(s) of the slider when initially rendered. Use when you do not need to control the state of the slider. Provide an array with single value for a single thumb, or multiple values for multiple thumbs. */
+  defaultValue?: number[];
+  /** The controlled value(s) of the slider. Must be used in conjunction with onValueChange. Provide an array with single value for a single thumb, or multiple values for multiple thumbs. */
+  value?: number[];
+  /** Event handler called when the slider value changes during interaction. Receives an array of current values. */
+  onValueChange?: (value: number[]) => void;
+  /** Event handler called when the value changes at the end of an interaction (mouse up, touch end, key release). Useful when you only need to capture a final value e.g. to update a backend service. */
+  onValueCommit?: (value: number[]) => void;
+  /** The name of the slider. Submitted with its owning form as part of a name/value pair. When multiple thumbs are used, multiple inputs will be rendered. */
+  name?: string;
+  /** When true, prevents the user from interacting with the slider. Disabled sliders cannot be focused and do not receive keyboard events. @default false */
+  disabled?: boolean;
+  /** The orientation of the slider. Affects layout and keyboard navigation behavior. @default "horizontal" */
+  orientation?: "horizontal" | "vertical";
+  /** The reading direction of the slider. If omitted, inherits globally from DirectionProvider or assumes LTR reading mode. Affects the direction of value changes with arrow keys. */
+  dir?: "ltr" | "rtl";
+  /** Whether the slider is visually inverted. When true, the range appears on the opposite side and keyboard navigation is reversed. @default false */
+  inverted?: boolean;
+  /** The minimum value for the range. Must be less than max. @default 0 */
+  min?: number;
+  /** The maximum value for the range. Must be greater than min. @default 100 */
+  max?: number;
+  /** The stepping interval. Values will be rounded to multiples of this number. Use 0 for infinite precision. @default 1 */
+  step?: number;
+  /** The minimum permitted steps between multiple thumbs. Prevents thumbs from overlapping or getting too close to each other. @default 0 */
+  minStepsBetweenThumbs?: number;
+  /** The ID of the form that the slider belongs to. If omitted, the slider will be associated with a parent form if one exists. Used for form submission and validation. */
+  form?: string;
+} & React.ComponentProps<typeof SliderPrimitive.Root>;
+
+/**
+ * Slider - Range input control for selecting numeric values
  *
  * 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.
+ * horizontal and vertical orientations, custom ranges, step intervals, and comprehensive
+ * accessibility features for keyboard and touch interaction.
  *
- * Based on the shadcn/ui Slider component with enhanced styling and behavior.
+ * The component automatically renders the appropriate number of thumbs based on the
+ * number of values provided, supporting both single-value and multi-value range selection.
+ * Built with enhanced styling and smooth animations for an optimal user experience.
  *
  * @example
  * ```tsx
  * // Basic single-value slider
- * <Slider defaultValue={[33]} max={100} step={1} />
+ * <Slider defaultValue={[50]} max={100} step={1} />
  * ```
  *
  * @example
  * ```tsx
- * // Controlled slider with state
+ * // Controlled slider with state management
  * const [value, setValue] = useState([25])
  *
  * <Slider
@@ -34,7 +76,7 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // Range slider with two thumbs
+ * // Range slider with two thumbs for selecting a range
  * <Slider
  *   defaultValue={[25, 75]}
  *   max={100}
@@ -45,7 +87,7 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // Vertical orientation
+ * // Vertical orientation for space-constrained layouts
  * <Slider
  *   defaultValue={[50]}
  *   max={100}
@@ -56,7 +98,7 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // Custom range and step
+ * // Custom range and step intervals for precise control
  * <Slider
  *   defaultValue={[500]}
  *   min={0}
@@ -65,34 +107,38 @@ import { cn } from "@/lib/utils";
  * />
  * ```
  *
+ * @example
+ * ```tsx
+ * // Form integration with name and onValueCommit
+ * <form>
+ *   <Slider
+ *     name="volume"
+ *     defaultValue={[75]}
+ *     max={100}
+ *     onValueCommit={(value) => console.log('Final value:', value)}
+ *   />
+ * </form>
+ * ```
+ *
  * @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
+ * - Full keyboard navigation support:
+ *   - Arrow keys adjust value by step amount (Left/Down decrease, Right/Up increase)
+ *   - Page Up/Page Down adjust by larger increments (typically 10 × step)
+ *   - Shift + Arrow keys for larger adjustments
+ *   - Home/End keys jump to minimum/maximum values
+ * - Focus management with visible focus indicators and ring styling
+ * - Touch and mouse interaction fully supported with proper pointer events
+ * - Screen reader announcements for value changes and state updates
  * - Disabled state properly communicated to assistive technologies
+ * - Automatic form integration with proper name/value pairs
+ * - RTL (right-to-left) text direction support
  *
- * @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
- *
+ * @see {@link https://ui.shadcn.com/docs/components/slider} shadcn/ui Slider Documentation
+ * @see {@link https://www.radix-ui.com/docs/primitives/components/slider} Radix UI Slider API Reference
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/slider/} WAI-ARIA Slider Pattern
  * @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,