@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/components/core/ScrollArea/ScrollArea.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import React__default, { useRef, useMemo, useImperativeHandle } from 'react';
+import React__default, { useRef, useMemo, useImperativeHandle, useState, useEffect } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { scrollAreaTheme } from './ScrollArea.theme.js';
 import { useSmoothScroll } from './smooth/useSmoothScroll.js';
@@ -25,7 +26,7 @@ import { useSmoothScroll } from './smooth/useSmoothScroll.js';
  * </ScrollArea>
  * ```
  */
-const ScrollArea = React__default.forwardRef(({ children, type = 'hover', orientation = 'vertical', snap, snapAlign = 'start', smooth = false, smoothConfig, onScrollProgress, onPerformanceUpdate, className, theme, ...props }, ref) => {
+const ScrollArea = React__default.forwardRef(({ children, type = 'hover', size = 'default', orientation = 'vertical', dragToScroll = false, snap, snapAlign = 'start', smooth = true, smoothConfig, onScrollProgress, onPerformanceUpdate, className, theme, ...props }, ref) => {
     // Internal ref for the scrollable element
     const internalRef = useRef(null);
     // Determine scroll orientation for smooth scroll
@@ -50,21 +51,272 @@ const ScrollArea = React__default.forwardRef(({ children, type = 'hover', orient
     const smoothAPI = useSmoothScroll(smooth ? internalRef : null, smoothScrollConfig, smoothOrientation);
     // Expose extended API via ref
     useImperativeHandle(ref, () => {
-        if (!internalRef.current)
-            return null;
+        // internalRef.current is always set by the time the imperative handle is
+        // accessed (refs are resolved after mount). The non-null assertion avoids
+        // the unsafe `null as unknown as ScrollAreaRef` double-cast.
         const element = internalRef.current;
         // Create extended ref object
         const extendedRef = element;
         // Add smooth scroll methods if smooth is enabled
         if (smooth && smoothAPI) {
-            extendedRef.smoothScrollTo = smoothAPI.scrollTo;
+            extendedRef.smoothScrollTo = (position, options) => {
+                if (inertiaFrameIdRef.current !== null) {
+                    cancelAnimationFrame(inertiaFrameIdRef.current);
+                    inertiaFrameIdRef.current = null;
+                }
+                smoothAPI.scrollTo(position, options);
+            };
             extendedRef.getScrollVelocity = smoothAPI.getVelocity;
             extendedRef.pauseSmoothScroll = smoothAPI.stop;
             extendedRef.resumeSmoothScroll = smoothAPI.start;
             extendedRef.refreshSnapPoints = smoothAPI.refreshSnapPoints;
         }
+        extendedRef.setPosition = (position) => {
+            if (inertiaFrameIdRef.current !== null) {
+                cancelAnimationFrame(inertiaFrameIdRef.current);
+                inertiaFrameIdRef.current = null;
+            }
+            if (smooth && smoothAPI) {
+                smoothAPI.setPosition(position);
+            }
+            else {
+                const max = orientation === 'horizontal'
+                    ? element.scrollWidth - element.clientWidth
+                    : element.scrollHeight - element.clientHeight;
+                const clamped = Math.max(0, Math.min(max, position));
+                if (orientation === 'horizontal') {
+                    element.scrollLeft = clamped;
+                }
+                else {
+                    element.scrollTop = clamped;
+                }
+            }
+        };
         return extendedRef;
-    }, [smooth, smoothAPI]);
+    }, [smooth, smoothAPI, orientation]);
+    // Drag-to-scroll (mouse panning) with inertia.
+    const dragRef = useRef(null);
+    const suppressClickRef = useRef(false);
+    const [isDragging, setIsDragging] = useState(false);
+    const inertiaFrameIdRef = useRef(null);
+    // Cancel inertia animation on unmount
+    useEffect(() => {
+        return () => {
+            if (inertiaFrameIdRef.current !== null) {
+                cancelAnimationFrame(inertiaFrameIdRef.current);
+            }
+        };
+    }, []);
+    const startDragInertia = (vx, vy) => {
+        if (inertiaFrameIdRef.current !== null) {
+            cancelAnimationFrame(inertiaFrameIdRef.current);
+        }
+        let lastTime = performance.now();
+        const el = internalRef.current;
+        if (!el)
+            return;
+        const tick = (now) => {
+            const dt = now - lastTime;
+            lastTime = now;
+            // Prevent frame skip issues when tab is backgrounded
+            if (dt > 100) {
+                inertiaFrameIdRef.current = requestAnimationFrame(tick);
+                return;
+            }
+            // Apply friction decay (0.95 per 16.67ms frame)
+            const friction = 0.95;
+            const timeFactor = dt / 16.67;
+            const currentFriction = Math.pow(friction, timeFactor);
+            let activeVx = vx;
+            let activeVy = vy;
+            if (orientation === 'vertical') {
+                activeVx = 0;
+            }
+            else if (orientation === 'horizontal') {
+                activeVy = 0;
+            }
+            const deltaX = activeVx * dt;
+            const deltaY = activeVy * dt;
+            const nextLeft = el.scrollLeft + deltaX;
+            const nextTop = el.scrollTop + deltaY;
+            // Apply positions
+            if (smooth && smoothAPI) {
+                if (smoothOrientation === 'horizontal') {
+                    smoothAPI.setPosition(nextLeft);
+                    if (orientation === 'both') {
+                        el.scrollTop = nextTop;
+                    }
+                }
+                else {
+                    smoothAPI.setPosition(nextTop);
+                    if (orientation === 'both') {
+                        el.scrollLeft = nextLeft;
+                    }
+                }
+            }
+            else {
+                if (orientation !== 'vertical')
+                    el.scrollLeft = nextLeft;
+                if (orientation !== 'horizontal')
+                    el.scrollTop = nextTop;
+            }
+            // Decay velocity
+            vx *= currentFriction;
+            vy *= currentFriction;
+            // If we hit scroll boundaries, stop inertia on that axis
+            const maxScrollLeft = el.scrollWidth - el.clientWidth;
+            const maxScrollTop = el.scrollHeight - el.clientHeight;
+            if (el.scrollLeft <= 0 || el.scrollLeft >= maxScrollLeft)
+                vx = 0;
+            if (el.scrollTop <= 0 || el.scrollTop >= maxScrollTop)
+                vy = 0;
+            const currentSpeed = Math.sqrt(vx * vx + vy * vy);
+            if (currentSpeed > 0.05) {
+                inertiaFrameIdRef.current = requestAnimationFrame(tick);
+            }
+            else {
+                inertiaFrameIdRef.current = null;
+            }
+        };
+        inertiaFrameIdRef.current = requestAnimationFrame(tick);
+    };
+    const onDragPointerDown = (e) => {
+        if (e.pointerType !== 'mouse' || e.button !== 0)
+            return;
+        // Stop any running inertia animation on fresh interaction
+        if (inertiaFrameIdRef.current !== null) {
+            cancelAnimationFrame(inertiaFrameIdRef.current);
+            inertiaFrameIdRef.current = null;
+        }
+        suppressClickRef.current = false;
+        if (e.target.closest('input, textarea, select, [contenteditable="true"]'))
+            return;
+        const el = internalRef.current;
+        if (!el)
+            return;
+        dragRef.current = {
+            startX: e.clientX,
+            startY: e.clientY,
+            scrollLeft: el.scrollLeft,
+            scrollTop: el.scrollTop,
+            dragging: false,
+            pointerId: e.pointerId,
+            history: [{ time: performance.now(), x: e.clientX, y: e.clientY }]
+        };
+    };
+    const onDragPointerMove = (e) => {
+        const drag = dragRef.current;
+        const el = internalRef.current;
+        if (!drag || !el)
+            return;
+        const now = performance.now();
+        drag.history.push({ time: now, x: e.clientX, y: e.clientY });
+        // Keep only the last 100ms of history for velocity calculation
+        while (drag.history.length > 0 && now - drag.history[0].time > 100) {
+            drag.history.shift();
+        }
+        const dx = e.clientX - drag.startX;
+        const dy = e.clientY - drag.startY;
+        if (!drag.dragging) {
+            if (Math.abs(dx) < 4 && Math.abs(dy) < 4)
+                return;
+            drag.dragging = true;
+            setIsDragging(true);
+            el.setPointerCapture(drag.pointerId);
+        }
+        const targetLeft = drag.scrollLeft - dx;
+        const targetTop = drag.scrollTop - dy;
+        if (smooth && smoothAPI) {
+            if (smoothOrientation === 'horizontal') {
+                smoothAPI.setPosition(targetLeft);
+                if (orientation === 'both') {
+                    el.scrollTop = targetTop;
+                }
+            }
+            else {
+                smoothAPI.setPosition(targetTop);
+                if (orientation === 'both') {
+                    el.scrollLeft = targetLeft;
+                }
+            }
+        }
+        else {
+            if (orientation !== 'vertical')
+                el.scrollLeft = targetLeft;
+            if (orientation !== 'horizontal')
+                el.scrollTop = targetTop;
+        }
+    };
+    const onDragPointerEnd = (e) => {
+        var _a;
+        const drag = dragRef.current;
+        if (!drag)
+            return;
+        if (drag.dragging) {
+            suppressClickRef.current = e.type === 'pointerup';
+            setIsDragging(false);
+            const el = internalRef.current;
+            if (el) {
+                (_a = el.releasePointerCapture) === null || _a === void 0 ? void 0 : _a.call(el, drag.pointerId);
+                // Calculate release velocity
+                const now = performance.now();
+                const recentHistory = drag.history.filter(h => now - h.time < 100);
+                if (recentHistory.length >= 2) {
+                    const first = recentHistory[0];
+                    const last = recentHistory[recentHistory.length - 1];
+                    const dt = last.time - first.time;
+                    if (dt > 10) {
+                        const vx = (last.x - first.x) / dt;
+                        const vy = (last.y - first.y) / dt;
+                        const speed = Math.sqrt(vx * vx + vy * vy);
+                        // Only trigger inertia if speed is high enough AND smooth scrolling is enabled
+                        if (speed > 0.15 && smooth) {
+                            startDragInertia(-vx, -vy);
+                        }
+                    }
+                }
+            }
+        }
+        dragRef.current = null;
+    };
+    const onDragClickCapture = (e) => {
+        if (!suppressClickRef.current)
+            return;
+        suppressClickRef.current = false;
+        e.preventDefault();
+        e.stopPropagation();
+    };
+    const dragHandlers = dragToScroll
+        ? {
+            onPointerDown: onDragPointerDown,
+            onPointerMove: onDragPointerMove,
+            onPointerUp: onDragPointerEnd,
+            onPointerCancel: onDragPointerEnd,
+            onClickCapture: onDragClickCapture,
+            // Native HTML5 drag (images, links) hijacks the gesture mid-pan
+            onDragStart: (e) => e.preventDefault(),
+        }
+        : undefined;
+    // Scroll-detection state for type='scroll' (overlay scrollbar)
+    const [isScrolling, setIsScrolling] = useState(false);
+    const scrollTimerRef = useRef(undefined);
+    useEffect(() => {
+        if (type !== 'scroll')
+            return;
+        const el = internalRef.current;
+        if (!el)
+            return;
+        const onScroll = () => {
+            setIsScrolling(true);
+            clearTimeout(scrollTimerRef.current);
+            scrollTimerRef.current = setTimeout(() => setIsScrolling(false), 1000);
+        };
+        el.addEventListener('scroll', onScroll, { passive: true });
+        return () => {
+            el.removeEventListener('scroll', onScroll);
+            clearTimeout(scrollTimerRef.current);
+        };
+    }, [type]);
     // Resolve theme with overrides
     const resolvedTheme = useMemo(() => {
         var _a, _b, _c;
@@ -75,7 +327,19 @@ const ScrollArea = React__default.forwardRef(({ children, type = 'hover', orient
         });
     }, [theme]);
     // Determine overflow classes based on orientation
+    // For type='scroll', use overflow:overlay so scrollbar overlays content
     const overflowClasses = useMemo(() => {
+        if (type === 'scroll') {
+            switch (orientation) {
+                case 'horizontal':
+                    return 'overflow-x-[overlay] overflow-y-hidden';
+                case 'both':
+                    return 'overflow-x-[overlay] overflow-y-[overlay]';
+                case 'vertical':
+                default:
+                    return 'overflow-y-[overlay] overflow-x-hidden';
+            }
+        }
         switch (orientation) {
             case 'horizontal':
                 return 'overflow-x-auto overflow-y-hidden';
@@ -85,7 +349,7 @@ const ScrollArea = React__default.forwardRef(({ children, type = 'hover', orient
             default:
                 return 'overflow-y-auto overflow-x-hidden';
         }
-    }, [orientation]);
+    }, [orientation, type]);
     // Scroll snap classes
     // When snap is enabled for horizontal/both, the viewport becomes a flex container
     // so that items are direct children of the scrollable element (required for snap-align).
@@ -107,9 +371,11 @@ const ScrollArea = React__default.forwardRef(({ children, type = 'hover', orient
         return `${axisClass} ${strictnessClass} ${alignClass} ${layoutClass}`;
     }, [snap, orientation, snapAlign]);
     // Base scrollbar styling classes (shared across all types)
+    const scrollbarDimension = size === 'thin'
+        ? '[&::-webkit-scrollbar]:w-1 [&::-webkit-scrollbar]:h-1'
+        : '[&::-webkit-scrollbar]:w-2 [&::-webkit-scrollbar]:h-2';
     const scrollbarBase = [
-        '[&::-webkit-scrollbar]:w-2',
-        '[&::-webkit-scrollbar]:h-2',
+        scrollbarDimension,
         '[&::-webkit-scrollbar-track]:bg-transparent',
         '[&::-webkit-scrollbar-thumb]:rounded-full',
         '[&::-webkit-scrollbar-corner]:bg-transparent',
@@ -120,17 +386,25 @@ const ScrollArea = React__default.forwardRef(({ children, type = 'hover', orient
             case 'always':
                 return [
                     '[&::-webkit-scrollbar-thumb]:bg-[var(--color-border)]',
-                    '[&::-webkit-scrollbar-track]:bg-[var(--color-background-secondary)]',
+                    '[&::-webkit-scrollbar-track]:bg-[var(--color-surface-sunken)]',
                 ].join(' ');
             case 'scroll':
                 return [
-                    '[&::-webkit-scrollbar-thumb]:bg-[var(--color-border)]',
+                    '[&::-webkit-scrollbar-thumb]:bg-transparent',
+                    '[&[data-scrolling]::-webkit-scrollbar-thumb]:bg-[var(--color-border)]',
+                    '[&::-webkit-scrollbar-thumb]:transition-colors',
+                    '[&::-webkit-scrollbar-thumb]:duration-300',
                 ].join(' ');
             case 'hover':
                 return [
                     '[&::-webkit-scrollbar-thumb]:bg-transparent',
                     '[&:hover::-webkit-scrollbar-thumb]:bg-[var(--color-border)]',
                 ].join(' ');
+            case 'none':
+                return [
+                    '[&::-webkit-scrollbar]:!hidden',
+                    '[scrollbar-width:none]',
+                ].join(' ');
             case 'auto':
             default:
                 return [
@@ -138,7 +412,15 @@ const ScrollArea = React__default.forwardRef(({ children, type = 'hover', orient
                 ].join(' ');
         }
     }, [type]);
-    return (jsx("div", { ref: internalRef, className: cn(resolvedTheme.baseStyle, overflowClasses, snapClasses, scrollbarBase, scrollbarVisibility, className), "data-orientation": orientation, "data-type": type, "data-smooth": smooth, ...props, children: children }));
+    const onWheel = (e) => {
+        var _a;
+        if (inertiaFrameIdRef.current !== null) {
+            cancelAnimationFrame(inertiaFrameIdRef.current);
+            inertiaFrameIdRef.current = null;
+        }
+        (_a = props.onWheel) === null || _a === void 0 ? void 0 : _a.call(props, e);
+    };
+    return (jsx("div", { ref: internalRef, className: cn(resolvedTheme.baseStyle, overflowClasses, snapClasses, scrollbarBase, scrollbarVisibility, dragToScroll && 'cursor-grab', isDragging && 'cursor-grabbing select-none', className), "data-orientation": orientation, "data-type": type, "data-smooth": smooth, "data-scrolling": isScrolling || undefined, "data-dragging": isDragging || undefined, ...props, ...dragHandlers, onWheel: onWheel, children: children }));
 });
 ScrollArea.displayName = 'ScrollArea';
 

package/dist/components/core/ScrollArea/ScrollArea.theme.js

@@ -5,7 +5,7 @@
 const scrollAreaTheme = {
     baseStyle: 'relative h-full w-full',
     scrollbarStyle: 'flex touch-none select-none transition-colors duration-150',
-    thumbStyle: 'relative flex-1 rounded-full bg-[var(--color-border)]',
+    thumbStyle: 'relative flex-1 rounded-full bg-[var(--color-border)]/60',
 };
 
 export { scrollAreaTheme };

package/dist/components/core/ScrollArea/ScrollArea.types.d.ts

@@ -4,10 +4,17 @@ import { SmoothScrollConfig, ScrollProgress, PerformanceMetrics } from './smooth
  * Scrollbar visibility behavior
  * - 'auto': Standard browser behavior (show when content overflows)
  * - 'always': Always show scrollbar
- * - 'scroll': Always show scrollbar track
+ * - 'scroll': Show scrollbar only while actively scrolling (overlay, no track)
  * - 'hover': Show scrollbar only on hover
+ * - 'none': Hide scrollbar completely while keeping scroll functionality
  */
-export type ScrollAreaType = 'auto' | 'always' | 'scroll' | 'hover';
+export type ScrollAreaType = 'auto' | 'always' | 'scroll' | 'hover' | 'none';
+/**
+ * Scrollbar size
+ * - 'default': 8px scrollbar (w-2/h-2)
+ * - 'thin': 4px scrollbar (w-1/h-1)
+ */
+export type ScrollAreaSize = 'default' | 'thin';
 /**
  * Theme structure for the ScrollArea component
  */
@@ -29,13 +36,15 @@ export interface ScrollAreaThemeOverrides {
  */
 export interface ScrollAreaRef extends HTMLDivElement {
     /** Programmatically scroll to position with smooth animation */
-    smoothScrollTo?: (position: number, options?: any) => void;
+    smoothScrollTo?: (position: number, options?: import("./smooth/SmoothScrollEngine.types").ScrollToOptions) => void;
     /** Get current scroll velocity */
     getScrollVelocity?: () => number;
     /** Pause smooth scrolling */
     pauseSmoothScroll?: () => void;
     /** Resume smooth scrolling */
     resumeSmoothScroll?: () => void;
+    /** Set scroll position immediately without animation */
+    setPosition?: (position: number) => void;
     /** Refresh snap points */
     refreshSnapPoints?: () => void;
 }
@@ -65,6 +74,8 @@ export interface ScrollAreaProps extends HTMLAttributes<HTMLDivElement> {
     children: ReactNode;
     /** Scrollbar visibility behavior @default 'hover' */
     type?: ScrollAreaType;
+    /** Scrollbar size @default 'default' */
+    size?: ScrollAreaSize;
     /** Scroll direction @default 'vertical' */
     orientation?: 'vertical' | 'horizontal' | 'both';
     /**
@@ -80,9 +91,18 @@ export interface ScrollAreaProps extends HTMLAttributes<HTMLDivElement> {
      */
     snapAlign?: 'start' | 'center' | 'end';
     /**
-     * Enable smooth momentum-based scrolling
+     * Enable mouse drag-to-scroll panning (grab the content and drag, like touch).
+     * Mouse-only — touch input already pans natively. A real drag needs ~4px of
+     * movement first, so plain clicks on content (cards, buttons) still work; the
+     * click that would follow a completed drag is suppressed. Drags never start
+     * from text fields, so selection inside inputs/textareas is unaffected.
      * @default false
      */
+    dragToScroll?: boolean;
+    /**
+     * Enable smooth momentum-based scrolling
+     * @default true
+     */
     smooth?: boolean;
     /**
      * Configuration for smooth scrolling

package/dist/components/core/ScrollArea/index.d.ts

@@ -1,5 +1,5 @@
 export { ScrollArea } from './ScrollArea';
-export type { ScrollAreaProps, ScrollAreaRef, ScrollAreaTheme, ScrollAreaThemeOverrides, ScrollAreaType, } from './ScrollArea.types';
+export type { ScrollAreaProps, ScrollAreaRef, ScrollAreaTheme, ScrollAreaThemeOverrides, ScrollAreaType, ScrollAreaSize, } from './ScrollArea.types';
 export { scrollAreaTheme } from './ScrollArea.theme';
 export { useSmoothScroll } from './smooth/useSmoothScroll';
 export type { SmoothScrollAPI, SmoothScrollConfig, ScrollProgress, ScrollToOptions, SnapPoint, EasingFunction, PerformanceMetrics, } from './smooth';

package/dist/components/core/ScrollArea/smooth/SmoothScrollEngine.d.ts

@@ -16,6 +16,7 @@ export declare class SmoothScrollEngine {
     private previousPosition;
     private idleFrames;
     private static readonly IDLE_THRESHOLD;
+    private isAnimating;
     private animationStartTime;
     private animationDuration;
     private animationStartPosition;
@@ -98,6 +99,10 @@ export declare class SmoothScrollEngine {
      * Scroll to element
      */
     scrollToElement(element: HTMLElement, options?: ScrollToOptions): void;
+    /**
+     * Set scroll position immediately without animation, updating internal state
+     */
+    setPosition(position: number): void;
     /**
      * Get current velocity
      */

package/dist/components/core/ScrollArea/smooth/SmoothScrollEngine.js

@@ -1,3 +1,4 @@
+"use client";
 import { SnapPointDetector } from './SnapPointDetector.js';
 import { PerformanceMonitor } from '../../../../utils/performanceMonitor.js';
 import { normalizeWheelDelta, getMaxScroll, lerp, clampScroll, calculateVelocity, calculateScrollProgress, detectScrollDirection } from '../../../../utils/smoothScrollUtils.js';
@@ -36,6 +37,10 @@ class SmoothScrollEngine {
         this.previousPosition = 0;
         this.idleFrames = 0;
         // Programmatic scroll animation
+        // NOTE: this flag — NOT animationOnComplete — gates whether a programmatic
+        // animation is active. onComplete is optional, so keying off it meant
+        // scrollTo(pos) with no callback never animated (the Scroll-to-Top/Bottom bug).
+        this.isAnimating = false;
         this.animationStartTime = 0;
         this.animationDuration = 0;
         this.animationStartPosition = 0;
@@ -66,6 +71,7 @@ class SmoothScrollEngine {
                 this.state.targetSnapPoint = null;
             }
             // Cancel programmatic animation
+            this.isAnimating = false;
             this.animationOnComplete = null;
             this.wake();
         };
@@ -102,11 +108,13 @@ class SmoothScrollEngine {
             this.state.target += adjustedDelta;
             this.touchStartY = touchY;
             this.touchStartX = touchX;
-            // Cancel snap animation
+            // Cancel snap + programmatic animation on user input
             if (this.state.isSnapping) {
                 this.state.isSnapping = false;
                 this.state.targetSnapPoint = null;
             }
+            this.isAnimating = false;
+            this.animationOnComplete = null;
             this.wake();
         };
         /**
@@ -120,7 +128,7 @@ class SmoothScrollEngine {
             // Record frame for performance monitoring
             this.performanceMonitor.recordFrame(time);
             // Handle programmatic animation
-            if (this.animationOnComplete) {
+            if (this.isAnimating) {
                 this.animateProgrammaticScroll(time);
             }
             // Handle snap animation
@@ -140,7 +148,7 @@ class SmoothScrollEngine {
             const isSettled = Math.abs(this.state.current - this.state.target) < 0.5 &&
                 Math.abs(this.state.velocity.current) < 0.1 &&
                 !this.state.isSnapping &&
-                !this.animationOnComplete;
+                !this.isAnimating;
             if (isSettled) {
                 this.idleFrames++;
                 if (this.idleFrames >= SmoothScrollEngine.IDLE_THRESHOLD) {
@@ -267,6 +275,7 @@ class SmoothScrollEngine {
         this.state.target = this.state.current;
         if (progress >= 1) {
             // Animation complete
+            this.isAnimating = false;
             const callback = this.animationOnComplete;
             this.animationOnComplete = null;
             if (callback)
@@ -416,6 +425,7 @@ class SmoothScrollEngine {
         this.state.isSnapping = false;
         this.state.targetSnapPoint = null;
         // Setup animation
+        this.isAnimating = true;
         this.animationStartTime = performance.now();
         this.animationDuration = duration;
         this.animationStartPosition = this.state.current;
@@ -447,6 +457,30 @@ class SmoothScrollEngine {
         }
         this.scrollTo(position, options);
     }
+    /**
+     * Set scroll position immediately without animation, updating internal state
+     */
+    setPosition(position) {
+        const max = getMaxScroll(this.element, this.orientation);
+        const clamped = clampScroll(position, 0, max);
+        this.state.current = clamped;
+        this.state.target = clamped;
+        this.previousPosition = clamped;
+        this.state.velocity.current = 0;
+        this.state.velocity.previous = 0;
+        // Sync to DOM
+        if (this.orientation === 'horizontal') {
+            this.element.scrollLeft = clamped;
+        }
+        else {
+            this.element.scrollTop = clamped;
+        }
+        // Stop any ongoing programmatic scroll or snapping
+        this.state.isSnapping = false;
+        this.state.targetSnapPoint = null;
+        this.isAnimating = false;
+        this.animationOnComplete = null;
+    }
     /**
      * Get current velocity
      */

package/dist/components/core/ScrollArea/smooth/SnapPointDetector.js

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Detects and manages CSS scroll snap points
  * Reads snap-align values from DOM and calculates scroll positions

package/dist/components/core/ScrollArea/smooth/useSmoothScroll.js

@@ -1,3 +1,4 @@
+"use client";
 import { useRef, useEffect, useMemo } from 'react';
 import { SmoothScrollEngine } from './SmoothScrollEngine.js';
 import { isReducedMotion } from '../../../../utils/smoothScrollUtils.js';
@@ -106,6 +107,10 @@ function useSmoothScroll(elementRef, config = {}, orientation = 'vertical') {
                 var _a;
                 (_a = engineRef.current) === null || _a === void 0 ? void 0 : _a.updateConfig(newConfig);
             },
+            setPosition: (position) => {
+                var _a;
+                (_a = engineRef.current) === null || _a === void 0 ? void 0 : _a.setPosition(position);
+            },
             refreshSnapPoints: () => {
                 var _a;
                 (_a = engineRef.current) === null || _a === void 0 ? void 0 : _a.refreshSnapPoints();

package/dist/components/core/ScrollArea/smooth/useSmoothScroll.types.d.ts

@@ -39,6 +39,11 @@ export interface SmoothScrollAPI {
      * @param config - Partial configuration to update
      */
     update: (config: SmoothScrollConfigUpdate) => void;
+    /**
+     * Set scroll position immediately without animation, updating internal state
+     * @param position - Target scroll position in pixels
+     */
+    setPosition: (position: number) => void;
     /**
      * Refresh snap points (call when DOM changes)
      */