@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/scroll-area.tsx

@@ -4,12 +4,92 @@ import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
 import { cn } from "@/lib/utils";
 
 /**
- * ScrollArea component provides cross-browser custom scrollbar styling
+ * Props for ScrollArea (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 ScrollAreaDocsProps = {
+  /** Additional CSS classes for styling */
+  className?: string;
+  /** Child elements to be rendered inside the scrollable area */
+  children?: React.ReactNode;
+  /** Describes the nature of scrollbar visibility @default "hover" */
+  type?: "auto" | "always" | "scroll" | "hover";
+  /** Time in milliseconds before scrollbars hide when type is "hover" @default 600 */
+  scrollHideDelay?: number;
+  /** Text direction for internationalization */
+  dir?: "ltr" | "rtl";
+  /** Nonce attribute for Content Security Policy */
+  nonce?: string;
+  /** Whether to render as its child element instead @default false */
+  asChild?: boolean;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for ScrollBar (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 ScrollBarDocsProps = {
+  /** Scrollbar orientation, controls which axis the scrollbar appears on @default "vertical" */
+  orientation?: "vertical" | "horizontal";
+  /** Forces the scrollbar to remain mounted even when not needed */
+  forceMount?: true;
+  /** Whether to render as its child element instead @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for ScrollAreaViewport (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 ScrollAreaViewportDocsProps = {
+  /** Whether to render as its child element instead @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling */
+  className?: string;
+  /** Child elements to be rendered inside the viewport */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for ScrollAreaThumb (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 ScrollAreaThumbDocsProps = {
+  /** Whether to render as its child element instead @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for ScrollAreaCorner (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 ScrollAreaCornerDocsProps = {
+  /** Whether to render as its child element instead @default false */
+  asChild?: boolean;
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * ScrollArea - Custom scrollable area with cross-browser styling
  *
  * Augments native scroll functionality for custom, cross-browser styling with enhanced
  * scrolling experience. Built on Radix UI's ScrollArea primitive for accessibility
  * and keyboard navigation support. Provides consistent scrollbar appearance across
- * different browsers while maintaining native scroll behavior.
+ * different browsers while maintaining native scroll behavior and performance.
+ *
+ * The component automatically handles vertical scrolling and can be extended with
+ * horizontal scrolling using the ScrollBar component. Supports programmatic control
+ * via refs and maintains all native scrolling behaviors including touch gestures.
  *
  * @example
  * ```tsx
@@ -42,91 +122,322 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // Both scrollbars for large content
- * <ScrollArea className="h-96 w-80 rounded-md border">
+ * // Both scrollbars for large content with always-visible scrollbars
+ * <ScrollArea className="h-96 w-80 rounded-md border" type="always">
  *   <div className="w-[600px] p-4">
- *     // Wide content with vertical overflow
+ *     <div className="space-y-4">
+ *       {largeDataSet.map((item) => (
+ *         <div key={item.id} className="min-w-max">
+ *           {item.wideContent}
+ *         </div>
+ *       ))}
+ *     </div>
  *   </div>
  *   <ScrollBar orientation="horizontal" />
  * </ScrollArea>
  * ```
  *
- * @param className - Additional CSS classes for styling
- * @param children - Content to be rendered inside the scrollable area
+ * @example
+ * ```tsx
+ * // Programmatic scrolling with ref
+ * function ProgrammaticScroll() {
+ *   const viewportRef = useRef<HTMLDivElement>(null);
+ *
+ *   const scrollToTop = () => {
+ *     viewportRef.current?.scrollTo({ top: 0, behavior: 'smooth' });
+ *   };
+ *
+ *   return (
+ *     <ScrollArea className="h-72 w-96">
+ *       <ScrollAreaViewport ref={viewportRef}>
+ *         <div className="p-4">
+ *           // Long content here
+ *           <button onClick={scrollToTop}>Scroll to top</button>
+ *         </div>
+ *       </ScrollAreaViewport>
+ *     </ScrollArea>
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - Maintains native keyboard scrolling (Arrow keys, Page Up/Down, Home/End)
+ * - Preserves focus management and tab order within scrollable content
+ * - Screen readers can navigate content naturally using standard commands
+ * - Supports touch gestures and momentum scrolling on mobile devices
+ * - Scrollbars automatically receive appropriate ARIA attributes
+ * - Respects user preferences for reduced motion
  *
- * @see {@link https://ui.shadcn.com/docs/components/scroll-area} - shadcn/ui ScrollArea documentation
+ * @see {@link ScrollBar} Companion scrollbar component for explicit horizontal scrolling
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/scroll-area} Radix UI ScrollArea Primitive
+ * @see {@link https://ui.shadcn.com/docs/components/scroll-area} shadcn/ui ScrollArea Documentation
  * @since 1.0.0
- * @see {@link ScrollBar} - Companion scrollbar component for horizontal scrolling
  */
-function ScrollArea({
-  className,
-  children,
-  ...props
-}: React.ComponentProps<typeof ScrollAreaPrimitive.Root>) {
-  return (
-    <ScrollAreaPrimitive.Root
-      data-slot="scroll-area"
-      className={cn("relative", className)}
-      {...props}
-    >
-      <ScrollAreaPrimitive.Viewport
-        data-slot="scroll-area-viewport"
-        className="focus-visible:ring-ring/50 size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:outline-1"
+const ScrollArea = React.forwardRef<
+  React.ElementRef<typeof ScrollAreaPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>
+>(
+  (
+    {
+      className,
+      children,
+      type = "hover",
+      scrollHideDelay = 600,
+      dir,
+      nonce,
+      asChild = false,
+      ...props
+    },
+    ref,
+  ) => {
+    return (
+      <ScrollAreaPrimitive.Root
+        ref={ref}
+        data-slot="scroll-area"
+        className={cn("relative", className)}
+        type={type}
+        scrollHideDelay={scrollHideDelay}
+        dir={dir}
+        nonce={nonce}
+        asChild={asChild}
+        {...props}
       >
-        {children}
-      </ScrollAreaPrimitive.Viewport>
-      <ScrollBar />
-      <ScrollAreaPrimitive.Corner />
-    </ScrollAreaPrimitive.Root>
-  );
-}
+        <ScrollAreaViewport>{children}</ScrollAreaViewport>
+        <ScrollBar />
+        <ScrollAreaCorner />
+      </ScrollAreaPrimitive.Root>
+    );
+  },
+);
+ScrollArea.displayName = "ScrollArea";
 
 /**
- * ScrollBar component for custom scrollbar styling
+ * ScrollBar - Custom styled scrollbar for ScrollArea
  *
  * Companion component to ScrollArea that renders styled scrollbars with
- * support for both vertical and horizontal orientations. Usually used
- * when explicit horizontal scrolling is needed.
+ * support for both vertical and horizontal orientations. The vertical
+ * scrollbar is automatically included in ScrollArea, but horizontal
+ * scrollbars must be explicitly added when needed.
  *
- * @param className - Additional CSS classes for scrollbar styling
- * @param orientation - Scrollbar orientation, defaults to "vertical"
+ * The scrollbar automatically shows/hides based on content overflow and
+ * user interaction. Supports touch interactions and provides visual
+ * feedback during scroll operations.
  *
  * @example
  * ```tsx
- * // Horizontal scrollbar (vertical is automatic)
- * <ScrollArea className="w-full">
- *   <div className="flex gap-4 p-4">
- *     // Wide content
+ * // Explicit horizontal scrollbar for wide content
+ * <ScrollArea className="w-full max-w-md">
+ *   <div className="flex gap-4 p-4 min-w-max">
+ *     {items.map((item) => (
+ *       <div key={item.id} className="w-48 flex-none">
+ *         {item.content}
+ *       </div>
+ *     ))}
  *   </div>
  *   <ScrollBar orientation="horizontal" />
  * </ScrollArea>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Both scrollbars with custom styling
+ * <ScrollArea className="h-64 w-64 border">
+ *   <div className="w-96 h-96 p-4">
+ *     Large content that overflows both axes
+ *   </div>
+ *   <ScrollBar orientation="vertical" className="bg-slate-100" />
+ *   <ScrollBar orientation="horizontal" className="bg-slate-100" />
+ * </ScrollArea>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Force-mounted scrollbar that always shows
+ * <ScrollArea className="h-48 w-full">
+ *   <div className="p-4">
+ *     Content that may or may not overflow
+ *   </div>
+ *   <ScrollBar orientation="horizontal" forceMount />
+ * </ScrollArea>
+ * ```
+ *
+ * @accessibility
+ * - Scrollbar thumb responds to keyboard interactions when focused
+ * - Supports drag operations for precise scrolling control
+ * - Automatically receives appropriate ARIA attributes for orientation
+ * - Visual feedback during hover and active states
+ * - Respects user preferences for scrollbar width and behavior
+ *
+ * @see {@link ScrollArea} Main scrollable container component
+ * @since 1.0.0
+ */
+const ScrollBar = React.forwardRef<
+  React.ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>
+>(
+  (
+    {
+      className,
+      orientation = "vertical",
+      forceMount,
+      asChild = false,
+      ...props
+    },
+    ref,
+  ) => {
+    return (
+      <ScrollAreaPrimitive.ScrollAreaScrollbar
+        ref={ref}
+        data-slot="scroll-area-scrollbar"
+        orientation={orientation}
+        forceMount={forceMount}
+        asChild={asChild}
+        className={cn(
+          "flex touch-none p-px transition-colors select-none",
+          orientation === "vertical" &&
+            "h-full w-2.5 border-l border-l-transparent",
+          orientation === "horizontal" &&
+            "h-2.5 flex-col border-t border-t-transparent",
+          className,
+        )}
+        {...props}
+      >
+        <ScrollAreaThumb />
+      </ScrollAreaPrimitive.ScrollAreaScrollbar>
+    );
+  },
+);
+ScrollBar.displayName = "ScrollBar";
+
+/**
+ * ScrollAreaViewport - The viewport area of the scroll area
+ *
+ * Contains the scrollable content and handles the actual scrolling behavior.
+ * This is the element that receives focus and handles keyboard navigation.
+ * Use refs on this component for programmatic scrolling control.
+ *
+ * @example
+ * ```tsx
+ * // Accessing viewport for programmatic scrolling
+ * const ScrollWithButton = () => {
+ *   const viewportRef = useRef<HTMLDivElement>(null);
+ *
+ *   const scrollToBottom = () => {
+ *     const viewport = viewportRef.current;
+ *     if (viewport) {
+ *       viewport.scrollTop = viewport.scrollHeight;
+ *     }
+ *   };
+ *
+ *   return (
+ *     <ScrollArea className="h-64 w-96">
+ *       <ScrollAreaViewport ref={viewportRef}>
+ *         <div className="p-4">
+ *           // Content here
+ *           <button onClick={scrollToBottom}>Scroll to bottom</button>
+ *         </div>
+ *       </ScrollAreaViewport>
+ *     </ScrollArea>
+ *   );
+ * };
+ * ```
+ *
+ * @see {@link ScrollArea} Main scrollable container component
+ * @since 1.0.0
+ */
+const ScrollAreaViewport = React.forwardRef<
+  React.ElementRef<typeof ScrollAreaPrimitive.Viewport>,
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Viewport>
+>(({ className, children, asChild = false, ...props }, ref) => (
+  <ScrollAreaPrimitive.Viewport
+    ref={ref}
+    data-slot="scroll-area-viewport"
+    className={cn(
+      "focus-visible:ring-ring/50 size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:outline-1",
+      className,
+    )}
+    asChild={asChild}
+    {...props}
+  >
+    {children}
+  </ScrollAreaPrimitive.Viewport>
+));
+ScrollAreaViewport.displayName = "ScrollAreaViewport";
+
+/**
+ * ScrollAreaThumb - The draggable thumb element within the scrollbar
+ *
+ * Represents the current scroll position and can be dragged to scroll content.
+ * Usually styled automatically as part of the ScrollBar component, but can
+ * be customized for specific design requirements.
+ *
+ * @example
+ * ```tsx
+ * // Custom scrollbar with styled thumb
+ * const CustomScrollbar = ({ orientation = "vertical" }) => (
+ *   <ScrollAreaPrimitive.ScrollAreaScrollbar orientation={orientation}>
+ *     <ScrollAreaThumb className="bg-blue-500 hover:bg-blue-600 active:bg-blue-700" />
+ *   </ScrollAreaPrimitive.ScrollAreaScrollbar>
+ * );
+ * ```
+ *
+ * @see {@link ScrollBar} Parent scrollbar component
+ * @since 1.0.0
+ */
+const ScrollAreaThumb = React.forwardRef<
+  React.ElementRef<typeof ScrollAreaPrimitive.ScrollAreaThumb>,
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaThumb>
+>(({ className, asChild = false, ...props }, ref) => (
+  <ScrollAreaPrimitive.ScrollAreaThumb
+    ref={ref}
+    data-slot="scroll-area-thumb"
+    className={cn("bg-border relative flex-1 rounded-full", className)}
+    asChild={asChild}
+    {...props}
+  />
+));
+ScrollAreaThumb.displayName = "ScrollAreaThumb";
+
+/**
+ * ScrollAreaCorner - The corner element where horizontal and vertical scrollbars meet
+ *
+ * Appears when both horizontal and vertical scrollbars are present. Usually
+ * handled automatically by the ScrollArea component but can be customized
+ * for specific layout requirements.
+ *
+ * @example
+ * ```tsx
+ * // Custom corner styling
+ * <ScrollArea className="h-64 w-64">
+ *   <div className="w-96 h-96 p-4">
+ *     Content that overflows both axes
+ *   </div>
+ *   <ScrollBar orientation="horizontal" />
+ *   <ScrollAreaCorner className="bg-gray-100" />
+ * </ScrollArea>
+ * ```
+ *
+ * @see {@link ScrollArea} Main scrollable container component
+ * @since 1.0.0
  */
-function ScrollBar({
-  className,
-  orientation = "vertical",
-  ...props
-}: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>) {
-  return (
-    <ScrollAreaPrimitive.ScrollAreaScrollbar
-      data-slot="scroll-area-scrollbar"
-      orientation={orientation}
-      className={cn(
-        "flex touch-none p-px transition-colors select-none",
-        orientation === "vertical" &&
-          "h-full w-2.5 border-l border-l-transparent",
-        orientation === "horizontal" &&
-          "h-2.5 flex-col border-t border-t-transparent",
-        className,
-      )}
-      {...props}
-    >
-      <ScrollAreaPrimitive.ScrollAreaThumb
-        data-slot="scroll-area-thumb"
-        className="bg-border relative flex-1 rounded-full"
-      />
-    </ScrollAreaPrimitive.ScrollAreaScrollbar>
-  );
-}
+const ScrollAreaCorner = React.forwardRef<
+  React.ElementRef<typeof ScrollAreaPrimitive.Corner>,
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Corner>
+>(({ className, asChild = false, ...props }, ref) => (
+  <ScrollAreaPrimitive.Corner
+    ref={ref}
+    data-slot="scroll-area-corner"
+    className={className}
+    asChild={asChild}
+    {...props}
+  />
+));
+ScrollAreaCorner.displayName = "ScrollAreaCorner";
 
-export { ScrollArea, ScrollBar };
+export {
+  ScrollArea,
+  ScrollBar,
+  ScrollAreaViewport,
+  ScrollAreaThumb,
+  ScrollAreaCorner,
+};