refactor: ScrollArea

Author: tugcekucukoglu

apps/showcase/assets/apidoc/index.json

@@ -151,10 +151,10 @@ export const headlessMenu = [
                 name: 'usePanel',
                 href: '/docs/headless/panel'
             },
-            // {
-            //     name: 'useScrollArea',
-            //     href: '/docs/headless/scrollarea'
-            // },
+            {
+                name: 'useScrollArea',
+                href: '/docs/headless/scrollarea'
+            },
             {
                 name: 'useSplitter',
                 href: '/docs/headless/splitter'

apps/showcase/assets/menu/submenu/menu-headless.data.ts

@@ -151,10 +151,10 @@ export const primitivesMenu = [
                 name: 'Panel',
                 href: '/docs/primitives/panel'
             },
-            // {
-            //     name: 'ScrollArea',
-            //     href: '/docs/primitives/scrollarea'
-            // },
+            {
+                name: 'ScrollArea',
+                href: '/docs/primitives/scrollarea'
+            },
             {
                 name: 'Splitter',
                 href: '/docs/primitives/splitter'

apps/showcase/assets/menu/submenu/menu-primitives.data.ts

@@ -57,18 +57,13 @@ const tags = [
 ];
 
 export default function BasicDemo() {
-    const { rootProps, viewportProps, getScrollbarProps, getThumbProps, rootRef, viewportRef, scrollbarYRef, thumbYRef, hiddenState } =
-        useScrollArea();
+    const { rootProps, viewportProps, contentProps, getScrollbarProps, getThumbProps, hiddenState } = useScrollArea();
 
     return (
         <div className="max-w-56 w-full mx-auto">
-            <div
-                {...rootProps}
-                ref={rootRef}
-                className="relative h-72 border border-surface-200 dark:border-surface-700 rounded has-[:focus-visible]:border-primary overflow-hidden"
-            >
-                <div {...viewportProps} ref={viewportRef} className="h-full w-full overflow-scroll outline-none" style={{ scrollbarWidth: 'none' }}>
-                    <div className="flex flex-col p-1">
+            <div {...rootProps} className="relative h-72 border border-surface-200 dark:border-surface-700 rounded has-[:focus-visible]:border-primary overflow-hidden">
+                <div {...viewportProps} className="h-full w-full overflow-scroll outline-none" style={{ scrollbarWidth: 'none' }}>
+                    <div {...contentProps} className="flex flex-col p-1">
                         {tags.map((tag) => (
                             <div key={tag} className="py-2 px-3 text-sm text-surface-700 dark:text-surface-0 rounded-md">
                                 {tag}
@@ -79,14 +74,12 @@ export default function BasicDemo() {
                 {!hiddenState.y && (
                     <div
                         {...getScrollbarProps('vertical')}
-                        ref={scrollbarYRef}
                         className="absolute top-0 right-0 w-2.5 h-full flex touch-none select-none"
                         style={{ padding: '2px' }}
                     >
                         <div
                             {...getThumbProps('vertical')}
-                            ref={thumbYRef}
-                            className="relative rounded-full bg-surface-300 dark:bg-surface-600 hover:bg-surface-400 dark:hover:bg-surface-500 transition-colors flex-1"
+                            className="relative rounded-full bg-primary hover:bg-primary-emphasis transition-colors flex-1"
                             style={{
                                 height: 'var(--thumb-height, 40px)',
                                 transform: 'translate3d(0, var(--thumb-offset, 0), 0)'

apps/showcase/demo/headless/scrollarea/basic-demo.tsx

@@ -53,12 +53,12 @@
     position: relative;
     flex: 1;
     border-radius: 9999px;
-    background-color: light-dark(var(--p-surface-300), var(--p-surface-600));
+    background-color: var(--p-primary-color);
     height: var(--thumb-height, 40px);
     transform: translate3d(0, var(--thumb-offset, 0), 0);
     transition: background-color 150ms ease;
 }
 
 .thumb:hover {
-    background-color: light-dark(var(--p-surface-400), var(--p-surface-500));
+    background-color: var(--p-primary-hover-color);
 }

apps/showcase/demo/primitives/scrollarea/basic-demo.module.css

@@ -8,17 +8,18 @@ component: scrollarea
 
 ## Usage
 
-```tsx showLineNumbers {1,3,5-6,9-11}
+```tsx showLineNumbers {1,3,5-7,9-11}
 import { useScrollArea } from '@primereact/headless/scrollarea';
 
-const { rootProps, viewportProps, getScrollbarProps, getThumbProps, cornerProps, state, rootRef, viewportRef, scrollbarYRef, thumbYRef, hiddenState } = useScrollArea();
+const { rootProps, viewportProps, contentProps, getScrollbarProps, getThumbProps, hiddenState } = useScrollArea();
 
-<div {...rootProps} ref={rootRef}>
-    <div {...viewportProps} ref={viewportRef} style={{ overflow: 'scroll', scrollbarWidth: 'none' }}>
+<div {...rootProps}>
+    <div {...viewportProps} style={{ overflow: 'scroll', scrollbarWidth: 'none' }}>
+        <div {...contentProps}></div>
     </div>
     {!hiddenState.y && (
-        <div {...getScrollbarProps('vertical')} ref={scrollbarYRef}>
-            <div {...getThumbProps('vertical')} ref={thumbYRef} />
+        <div {...getScrollbarProps('vertical')}>
+            <div {...getThumbProps('vertical')} />
         </div>
     )}
 </div>;
@@ -28,7 +29,7 @@ const { rootProps, viewportProps, getScrollbarProps, getThumbProps, cornerProps,
 
 ## Features
 
-- Returns spread-ready prop objects and ref assignments for all scroll area elements
+- Returns spread-ready prop objects with built-in ref callbacks for all scroll area elements
 - Automatic thumb size calculation based on viewport-to-content ratio
 - Pointer-based drag handling for both scrollbar track and thumb
 - ResizeObserver-based recalculation on content changes
@@ -47,42 +48,69 @@ const scrollArea = useScrollArea({ variant: 'hover' });
 
 Available values: `'auto'` (default), `'hover'`, `'scroll'`, `'always'`, `'hidden'`.
 
+### Hidden State
+
+`hiddenState` provides boolean flags that indicate whether each scrollbar and the corner should be rendered.
+
+```tsx
+const { hiddenState } = useScrollArea();
+
+// hiddenState.x      → true when horizontal scrollbar is unnecessary
+// hiddenState.y      → true when vertical scrollbar is unnecessary
+// hiddenState.corner → true when the corner element is unnecessary (at least one axis has no overflow)
+```
+
+Use these flags for conditional rendering of scrollbar and corner elements.
+
+### Corner Size
+
+`cornerSize` exposes the measured dimensions of the corner area where both scrollbars intersect. The hook sets `--corner-width` and `--corner-height` CSS variables on the root automatically, but `cornerSize` provides direct access for layout calculations.
+
+```tsx
+const { cornerSize } = useScrollArea();
+
+// cornerSize.width  → pixel width of the vertical scrollbar (0 when no corner)
+// cornerSize.height → pixel height of the horizontal scrollbar (0 when no corner)
+```
+
 ### Overflow Detection
 
-The hook tracks whether content overflows the viewport in each direction via `hiddenState` and `state`.
+`state` provides fine-grained scroll position flags for building fade masks, shadow indicators, or loading triggers at content edges.
 
 ```tsx
-const { hiddenState, state } = useScrollArea();
+const { state } = useScrollArea();
 
-// hiddenState.y       → true when vertical scrollbar is unnecessary
 // state.hasOverflowX  → true when content overflows horizontally
+// state.hasOverflowY  → true when content overflows vertically
 // state.scrollYBefore → true when scrolled past the top edge
 // state.scrollYAfter  → true when content remains below the viewport
+// state.scrollXBefore → true when scrolled past the left edge
+// state.scrollXAfter  → true when content remains to the right
 ```
 
 ### Both Scrollbars
 
 For content that overflows in both directions, use `getScrollbarProps` and `getThumbProps` with both orientations. The corner element fills the intersection.
 
 ```tsx
-const { getScrollbarProps, getThumbProps, cornerProps, scrollbarYRef, scrollbarXRef, thumbYRef, thumbXRef, cornerRef, hiddenState } = useScrollArea();
+const { getScrollbarProps, getThumbProps, cornerProps, hiddenState } = useScrollArea();
 
 {
     !hiddenState.y && (
-        <div {...getScrollbarProps('vertical')} ref={scrollbarYRef}>
-            <div {...getThumbProps('vertical')} ref={thumbYRef} />
+        <div {...getScrollbarProps('vertical')}>
+            <div {...getThumbProps('vertical')} />
         </div>
     );
 }
 {
     !hiddenState.x && (
-        <div {...getScrollbarProps('horizontal')} ref={scrollbarXRef}>
-            <div {...getThumbProps('horizontal')} ref={thumbXRef} />
+        <div {...getScrollbarProps('horizontal')}>
+            <div {...getThumbProps('horizontal')} />
         </div>
     );
 }
 {
-    !hiddenState.corner && <div {...cornerProps} ref={cornerRef} />;
+    !hiddenState.corner && <div {...cornerProps} />;
 }
 ```
 

apps/showcase/docs/headless/scrollarea/features.mdx

@@ -30,7 +30,7 @@ import { ScrollArea } from 'primereact/scrollarea';
     <ScrollArea.Viewport>
         <ScrollArea.Content></ScrollArea.Content>
     </ScrollArea.Viewport>
-    <ScrollArea.Scrollbar orientation="vertical">
+    <ScrollArea.Scrollbar>
         <ScrollArea.Thumb />
     </ScrollArea.Scrollbar>
 </ScrollArea.Root>
@@ -45,12 +45,18 @@ Use `as` on any sub-component to change the rendered HTML element.
 ```tsx
 <ScrollArea.Root as="section">
     <ScrollArea.Viewport as="main">
-        <ScrollArea.Content as="article">...</ScrollArea.Content>
+        <ScrollArea.Content as="article"></ScrollArea.Content>
     </ScrollArea.Viewport>
 </ScrollArea.Root>
 ```
 
-Default elements: `Root`=`div`, `Viewport`=`div`, `Content`=`div`, `Scrollbar`=`div`, `Thumb`=`div`, `Corner`=`div`.
+### Render Function Children
+
+Sub-components accept a render function as children, providing access to the component instance.
+
+```tsx
+<ScrollArea.Root>{(instance) => <div>{instance.state.scrolling ? 'Scrolling...' : 'Idle'}</div>}</ScrollArea.Root>
+```
 
 ## API
 

apps/showcase/docs/primitives/scrollarea/features.mdx

@@ -43,6 +43,34 @@ export const useScrollArea = withHeadless({
         const scrollYTimeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
         const rafRef = React.useRef<number | null>(null);
 
+        const setRootRef = React.useCallback((node: HTMLDivElement | null) => {
+            rootRef.current = node;
+        }, []);
+
+        const setViewportRef = React.useCallback((node: HTMLDivElement | null) => {
+            viewportRef.current = node;
+        }, []);
+
+        const setScrollbarYRef = React.useCallback((node: HTMLDivElement | null) => {
+            scrollbarYRef.current = node;
+        }, []);
+
+        const setScrollbarXRef = React.useCallback((node: HTMLDivElement | null) => {
+            scrollbarXRef.current = node;
+        }, []);
+
+        const setThumbYRef = React.useCallback((node: HTMLDivElement | null) => {
+            thumbYRef.current = node;
+        }, []);
+
+        const setThumbXRef = React.useCallback((node: HTMLDivElement | null) => {
+            thumbXRef.current = node;
+        }, []);
+
+        const setCornerRef = React.useCallback((node: HTMLDivElement | null) => {
+            cornerRef.current = node;
+        }, []);
+
         const computeThumb = React.useCallback(function computeThumb() {
             const vp = viewportRef.current;
 
@@ -347,74 +375,73 @@ export const useScrollArea = withHeadless({
             () => ({
                 'data-scope': 'scrollarea' as const,
                 'data-part': 'root' as const,
+                ref: setRootRef,
                 role: 'presentation' as const,
                 'data-variant': props.variant,
                 onPointerEnter: onRootPointerEnter,
                 onPointerLeave: onRootPointerLeave,
-                onPointerDown: onRootPointerDown
+                onPointerDown: onRootPointerDown,
+                style: {
+                    position: 'relative' as const,
+                    '--corner-height': `${cornerSize.height}px`,
+                    '--corner-width': `${cornerSize.width}px`
+                }
             }),
-            [props.variant, onRootPointerEnter, onRootPointerLeave, onRootPointerDown]
+            [props.variant, onRootPointerEnter, onRootPointerLeave, onRootPointerDown, cornerSize]
         );
 
         const viewportProps = React.useMemo(
             () => ({
                 'data-scope': 'scrollarea' as const,
                 'data-part': 'viewport' as const,
+                ref: setViewportRef,
                 tabIndex: undefined as number | undefined,
                 onScroll: handleScroll
             }),
-            [handleScroll]
+            [handleScroll, setViewportRef]
         );
 
         const getScrollbarProps = React.useCallback(
             (orientation: 'vertical' | 'horizontal') => ({
                 'data-scope': 'scrollarea' as const,
                 'data-part': (orientation === 'vertical' ? 'scrollbar-y' : 'scrollbar-x') as 'scrollbar-y' | 'scrollbar-x',
                 'data-orientation': orientation,
+                ref: orientation === 'vertical' ? setScrollbarYRef : setScrollbarXRef,
                 onPointerDown: (event: React.PointerEvent<HTMLDivElement>) => handleScrollbarPointerDown(event, orientation),
                 onPointerMove: handleScrollbarPointerMove,
                 onPointerUp: handleScrollbarPointerUp,
                 onWheel: (event: React.WheelEvent<HTMLDivElement>) => handleScrollbarWheel(event, orientation)
             }),
-            [handleScrollbarPointerDown, handleScrollbarPointerMove, handleScrollbarPointerUp, handleScrollbarWheel]
+            [handleScrollbarPointerDown, handleScrollbarPointerMove, handleScrollbarPointerUp, handleScrollbarWheel, setScrollbarYRef, setScrollbarXRef]
         );
 
         const getThumbProps = React.useCallback(
             (orientation: 'vertical' | 'horizontal') => ({
                 'data-scope': 'scrollarea' as const,
                 'data-part': (orientation === 'vertical' ? 'thumb-y' : 'thumb-x') as 'thumb-y' | 'thumb-x',
                 'data-orientation': orientation,
+                ref: orientation === 'vertical' ? setThumbYRef : setThumbXRef,
                 onPointerDown: (event: React.PointerEvent<HTMLDivElement>) => handleThumbPointerDown(event, orientation)
             }),
-            [handleThumbPointerDown]
+            [handleThumbPointerDown, setThumbYRef, setThumbXRef]
         );
 
-        const contentProps = React.useMemo(
-            () => ({
-                'data-scope': 'scrollarea' as const,
-                'data-part': 'content' as const
-            }),
-            []
-        );
+        const contentProps = {
+            'data-scope': 'scrollarea' as const,
+            'data-part': 'content' as const
+        };
 
         const cornerProps = React.useMemo(
             () => ({
                 'data-scope': 'scrollarea' as const,
-                'data-part': 'corner' as const
+                'data-part': 'corner' as const,
+                ref: setCornerRef
             }),
-            []
+            [setCornerRef]
         );
 
         return {
             state,
-            // element refs
-            rootRef,
-            viewportRef,
-            scrollbarYRef,
-            scrollbarXRef,
-            thumbYRef,
-            thumbXRef,
-            cornerRef,
             cornerSize,
             hiddenState,
             // prop getters