@flikk/ui 1.0.0-beta.1

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

@@ -0,0 +1,145 @@
+import { jsx } from 'react/jsx-runtime';
+import React__default, { useRef, useMemo, useImperativeHandle } from 'react';
+import { cn } from '../../../utils/cn.js';
+import { scrollAreaTheme } from './ScrollArea.theme.js';
+import { useSmoothScroll } from './smooth/useSmoothScroll.js';
+
+/**
+ * ScrollArea provides a custom scrollable container with styled scrollbars.
+ * Supports vertical, horizontal, or both scroll directions with configurable
+ * scrollbar visibility behavior.
+ *
+ * Enhanced with optional smooth momentum-based scrolling via the `smooth` prop.
+ *
+ * @example
+ * ```tsx
+ * <ScrollArea className="h-72">
+ *   <div className="p-4">
+ *     {items.map(item => <div key={item.id}>{item.name}</div>)}
+ *   </div>
+ * </ScrollArea>
+ *
+ * // With smooth scrolling
+ * <ScrollArea smooth smoothConfig={{ lerp: 0.1, elasticEdges: true }}>
+ *   {content}
+ * </ScrollArea>
+ * ```
+ */
+const ScrollArea = React__default.forwardRef(({ children, type = 'hover', orientation = 'vertical', snap, snapAlign = 'start', smooth = false, smoothConfig, onScrollProgress, onPerformanceUpdate, className, theme, ...props }, ref) => {
+    // Internal ref for the scrollable element
+    const internalRef = useRef(null);
+    // Determine scroll orientation for smooth scroll
+    // Note: 'both' defaults to 'vertical' for smooth scroll engine
+    const smoothOrientation = orientation === 'horizontal' ? 'horizontal' : 'vertical';
+    // Initialize smooth scroll hook if enabled
+    const smoothScrollConfig = useMemo(() => {
+        var _a;
+        if (!smooth)
+            return undefined;
+        return {
+            ...smoothConfig,
+            // Automatically respect snap points if snap is enabled
+            respectSnapPoints: snap ? true : (_a = smoothConfig === null || smoothConfig === void 0 ? void 0 : smoothConfig.respectSnapPoints) !== null && _a !== void 0 ? _a : true,
+            onScroll: onScrollProgress,
+            ...(onPerformanceUpdate && {
+            // Performance callback needs to be added to config if provided
+            // This will be handled by the engine's performance monitor
+            }),
+        };
+    }, [smooth, smoothConfig, snap, onScrollProgress, onPerformanceUpdate]);
+    const smoothAPI = useSmoothScroll(smooth ? internalRef : null, smoothScrollConfig, smoothOrientation);
+    // Expose extended API via ref
+    useImperativeHandle(ref, () => {
+        if (!internalRef.current)
+            return null;
+        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.getScrollVelocity = smoothAPI.getVelocity;
+            extendedRef.pauseSmoothScroll = smoothAPI.stop;
+            extendedRef.resumeSmoothScroll = smoothAPI.start;
+            extendedRef.refreshSnapPoints = smoothAPI.refreshSnapPoints;
+        }
+        return extendedRef;
+    }, [smooth, smoothAPI]);
+    // Resolve theme with overrides
+    const resolvedTheme = useMemo(() => {
+        var _a, _b, _c;
+        return ({
+            baseStyle: (_a = theme === null || theme === void 0 ? void 0 : theme.baseStyle) !== null && _a !== void 0 ? _a : scrollAreaTheme.baseStyle,
+            scrollbarStyle: (_b = theme === null || theme === void 0 ? void 0 : theme.scrollbarStyle) !== null && _b !== void 0 ? _b : scrollAreaTheme.scrollbarStyle,
+            thumbStyle: (_c = theme === null || theme === void 0 ? void 0 : theme.thumbStyle) !== null && _c !== void 0 ? _c : scrollAreaTheme.thumbStyle,
+        });
+    }, [theme]);
+    // Determine overflow classes based on orientation
+    const overflowClasses = useMemo(() => {
+        switch (orientation) {
+            case 'horizontal':
+                return 'overflow-x-auto overflow-y-hidden';
+            case 'both':
+                return 'overflow-x-auto overflow-y-auto';
+            case 'vertical':
+            default:
+                return 'overflow-y-auto overflow-x-hidden';
+        }
+    }, [orientation]);
+    // 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).
+    const snapClasses = useMemo(() => {
+        if (!snap)
+            return '';
+        const axisClass = orientation === 'horizontal'
+            ? 'snap-x'
+            : orientation === 'both'
+                ? 'snap-both'
+                : 'snap-y';
+        const strictnessClass = snap === 'proximity' ? 'snap-proximity' : 'snap-mandatory';
+        const alignClass = snapAlign === 'center'
+            ? '[&>*]:snap-center'
+            : snapAlign === 'end'
+                ? '[&>*]:snap-end'
+                : '[&>*]:snap-start';
+        const layoutClass = orientation === 'horizontal' || orientation === 'both' ? 'flex' : '';
+        return `${axisClass} ${strictnessClass} ${alignClass} ${layoutClass}`;
+    }, [snap, orientation, snapAlign]);
+    // Base scrollbar styling classes (shared across all types)
+    const scrollbarBase = [
+        '[&::-webkit-scrollbar]:w-2',
+        '[&::-webkit-scrollbar]:h-2',
+        '[&::-webkit-scrollbar-track]:bg-transparent',
+        '[&::-webkit-scrollbar-thumb]:rounded-full',
+        '[&::-webkit-scrollbar-corner]:bg-transparent',
+    ].join(' ');
+    // Scrollbar visibility classes based on type prop
+    const scrollbarVisibility = useMemo(() => {
+        switch (type) {
+            case 'always':
+                return [
+                    '[&::-webkit-scrollbar-thumb]:bg-[var(--color-border)]',
+                    '[&::-webkit-scrollbar-track]:bg-[var(--color-background-secondary)]',
+                ].join(' ');
+            case 'scroll':
+                return [
+                    '[&::-webkit-scrollbar-thumb]:bg-[var(--color-border)]',
+                ].join(' ');
+            case 'hover':
+                return [
+                    '[&::-webkit-scrollbar-thumb]:bg-transparent',
+                    '[&:hover::-webkit-scrollbar-thumb]:bg-[var(--color-border)]',
+                ].join(' ');
+            case 'auto':
+            default:
+                return [
+                    '[&::-webkit-scrollbar-thumb]:bg-[var(--color-border)]',
+                ].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 }));
+});
+ScrollArea.displayName = 'ScrollArea';
+
+export { ScrollArea };

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

@@ -0,0 +1,6 @@
+import { ScrollAreaTheme } from './ScrollArea.types';
+/**
+ * Default theme for the ScrollArea component
+ * Uses CSS custom scrollbar styling with design tokens
+ */
+export declare const scrollAreaTheme: ScrollAreaTheme;

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

@@ -0,0 +1,11 @@
+/**
+ * Default theme for the ScrollArea component
+ * Uses CSS custom scrollbar styling with design tokens
+ */
+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)]',
+};
+
+export { scrollAreaTheme };

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

@@ -0,0 +1,106 @@
+import { HTMLAttributes, ReactNode } from 'react';
+import { SmoothScrollConfig, ScrollProgress, PerformanceMetrics } from './smooth/SmoothScrollEngine.types';
+/**
+ * Scrollbar visibility behavior
+ * - 'auto': Standard browser behavior (show when content overflows)
+ * - 'always': Always show scrollbar
+ * - 'scroll': Always show scrollbar track
+ * - 'hover': Show scrollbar only on hover
+ */
+export type ScrollAreaType = 'auto' | 'always' | 'scroll' | 'hover';
+/**
+ * Theme structure for the ScrollArea component
+ */
+export interface ScrollAreaTheme {
+    baseStyle: string;
+    scrollbarStyle: string;
+    thumbStyle: string;
+}
+/**
+ * Theme overrides for customizing ScrollArea styles
+ */
+export interface ScrollAreaThemeOverrides {
+    baseStyle?: string;
+    scrollbarStyle?: string;
+    thumbStyle?: string;
+}
+/**
+ * Extended ScrollArea ref with smooth scroll API
+ */
+export interface ScrollAreaRef extends HTMLDivElement {
+    /** Programmatically scroll to position with smooth animation */
+    smoothScrollTo?: (position: number, options?: any) => void;
+    /** Get current scroll velocity */
+    getScrollVelocity?: () => number;
+    /** Pause smooth scrolling */
+    pauseSmoothScroll?: () => void;
+    /** Resume smooth scrolling */
+    resumeSmoothScroll?: () => void;
+    /** Refresh snap points */
+    refreshSnapPoints?: () => void;
+}
+/**
+ * ScrollArea component props
+ *
+ * @example
+ * ```tsx
+ * <ScrollArea className="h-72">
+ *   <div className="p-4">
+ *     {items.map(item => <div key={item.id}>{item.name}</div>)}
+ *   </div>
+ * </ScrollArea>
+ *
+ * <ScrollArea type="hover" orientation="horizontal" className="w-96">
+ *   <div className="flex gap-4">{children}</div>
+ * </ScrollArea>
+ *
+ * // With smooth scrolling
+ * <ScrollArea smooth smoothConfig={{ lerp: 0.1, elasticEdges: true }}>
+ *   {content}
+ * </ScrollArea>
+ * ```
+ */
+export interface ScrollAreaProps extends HTMLAttributes<HTMLDivElement> {
+    /** Content to render inside the scroll area */
+    children: ReactNode;
+    /** Scrollbar visibility behavior @default 'hover' */
+    type?: ScrollAreaType;
+    /** Scroll direction @default 'vertical' */
+    orientation?: 'vertical' | 'horizontal' | 'both';
+    /**
+     * Enable scroll snapping. Sets scroll-snap-type on the viewport (axis derived from orientation).
+     * Use 'mandatory' for strict snapping or 'proximity' for snap-when-close behavior.
+     * @default undefined (no snapping)
+     */
+    snap?: 'mandatory' | 'proximity';
+    /**
+     * Snap alignment applied to direct children via [&>*]:snap-*.
+     * Only takes effect when `snap` is set.
+     * @default 'start'
+     */
+    snapAlign?: 'start' | 'center' | 'end';
+    /**
+     * Enable smooth momentum-based scrolling
+     * @default false
+     */
+    smooth?: boolean;
+    /**
+     * Configuration for smooth scrolling
+     * Only applies when smooth={true}
+     */
+    smoothConfig?: Partial<SmoothScrollConfig>;
+    /**
+     * Callback fired on scroll progress updates
+     * Only applies when smooth={true}
+     */
+    onScrollProgress?: (progress: ScrollProgress) => void;
+    /**
+     * Callback fired on performance metrics updates
+     * Only applies when smooth={true}
+     */
+    onPerformanceUpdate?: (metrics: PerformanceMetrics) => void;
+    /** Custom class name for the scroll area */
+    className?: string;
+    /** Theme overrides */
+    theme?: ScrollAreaThemeOverrides;
+}

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

@@ -0,0 +1,5 @@
+export { ScrollArea } from './ScrollArea';
+export type { ScrollAreaProps, ScrollAreaRef, ScrollAreaTheme, ScrollAreaThemeOverrides, ScrollAreaType, } 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

@@ -0,0 +1,121 @@
+import { SmoothScrollConfig, ScrollProgress, ScrollToOptions } from './SmoothScrollEngine.types';
+/**
+ * Core smooth scroll engine
+ * Manages RAF loop, interpolation, snap detection, and effects
+ */
+export declare class SmoothScrollEngine {
+    private element;
+    private config;
+    private state;
+    private snapDetector;
+    private performanceMonitor;
+    private orientation;
+    private rafId;
+    private lastTime;
+    private isDestroyed;
+    private previousPosition;
+    private idleFrames;
+    private static readonly IDLE_THRESHOLD;
+    private animationStartTime;
+    private animationDuration;
+    private animationStartPosition;
+    private animationTargetPosition;
+    private animationEasing;
+    private animationOnComplete;
+    constructor(element: HTMLElement, config?: Partial<SmoothScrollConfig>, orientation?: 'vertical' | 'horizontal');
+    /**
+     * Bind wheel and touch events
+     */
+    private bindEvents;
+    /**
+     * Unbind events
+     */
+    private unbindEvents;
+    /**
+     * Wake the RAF loop if it went idle.
+     * Called from input handlers so the engine resumes on new input.
+     */
+    private wake;
+    /**
+     * Handle wheel event
+     */
+    private handleWheel;
+    private touchStartY;
+    private touchStartX;
+    /**
+     * Handle touch start
+     */
+    private handleTouchStart;
+    /**
+     * Handle touch move
+     */
+    private handleTouchMove;
+    /**
+     * Start the RAF loop
+     */
+    start(): void;
+    /**
+     * Stop the RAF loop
+     */
+    stop(): void;
+    /**
+     * Main RAF tick function
+     */
+    private tick;
+    /**
+     * Animate programmatic scrollTo
+     */
+    private animateProgrammaticScroll;
+    /**
+     * Animate to snap point using velocity-based smoothing
+     */
+    private animateSnap;
+    /**
+     * Interpolate scroll position
+     */
+    private interpolate;
+    /**
+     * Check if should snap to nearest point
+     */
+    private checkForSnap;
+    /**
+     * Apply visual effects (elastic, rubber-band)
+     */
+    private applyEffects;
+    /**
+     * Sync interpolated position to DOM
+     */
+    private syncToDOM;
+    /**
+     * Update callbacks with current progress
+     */
+    private updateCallbacks;
+    /**
+     * Programmatic scroll to position
+     */
+    scrollTo(position: number, options?: ScrollToOptions): void;
+    /**
+     * Scroll to element
+     */
+    scrollToElement(element: HTMLElement, options?: ScrollToOptions): void;
+    /**
+     * Get current velocity
+     */
+    getVelocity(): number;
+    /**
+     * Get current scroll progress
+     */
+    getProgress(): ScrollProgress;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<SmoothScrollConfig>): void;
+    /**
+     * Refresh snap points (call when DOM changes)
+     */
+    refreshSnapPoints(): void;
+    /**
+     * Destroy the engine
+     */
+    destroy(): void;
+}