@evolve.ui/core-components 1.0.1 → 1.2.0

package/src/BottomSheet/components/BottomSheetOverlay/BottomSheetOverlayTranslate3d.tsx

@@ -0,0 +1,199 @@
+import { cn, wrapVarRgb } from '@evolve.ui/theme-system';
+import { memo, ReactNode, RefObject } from 'react';
+
+import type { DragBind } from '../../types';
+
+import { SheetDescription, SheetTitle } from '..';
+import { BottomSheetContentArea } from '../BottomSheetContentArea/BottomSheetContentArea';
+
+/**
+ * Props for the BottomSheetOverlayTranslate3d component
+ */
+type Props = {
+    /** Drag bind function */
+    bind: DragBind;
+    /** The main content to display */
+    children: ReactNode;
+    /** Reference to the content container */
+    contentRef: RefObject<HTMLDivElement | null>;
+    /** Whether to disable the BottomSheet's own scrolling (useful when children handle their own scrolling) */
+    disableScroll?: boolean;
+    /** Footer content */
+    footer?: ReactNode;
+    /** Reference to the footer container */
+    footerRef: RefObject<HTMLDivElement | null>;
+    /** Header configuration */
+    header?: {
+        description: ReactNode;
+        title: ReactNode;
+    };
+    /** Reference to the header container */
+    headerRef: RefObject<HTMLDivElement | null>;
+    /** Whether the content is scrollable */
+    isScrollable: boolean;
+    /** Whether the content is scrolled to the bottom */
+    isScrolledToBottom: boolean;
+    /** Dismiss handler function */
+    onDismiss?: () => void;
+    /** Reference to the overlay container */
+    overlayRef: RefObject<HTMLDivElement | null>;
+    /** Reference to the scroll container */
+    scrollRef: RefObject<HTMLDivElement | null>;
+};
+
+/**
+ * EXPERIMENTAL: BottomSheetOverlayTranslate3d - GPU-accelerated version using translate3d
+ *
+ * This version uses a static height and translate3d transforms for better performance.
+ * Key differences from the original:
+ * 1. Static height instead of animated height
+ * 2. translate3d for positioning (GPU accelerated)
+ * 3. Optimized for mobile device performance
+ * 4. Memoized to prevent unnecessary re-renders
+ */
+export const BottomSheetOverlayTranslate3d = memo<Props>(
+    ({
+        bind,
+        children,
+        contentRef,
+        disableScroll,
+        footer,
+        footerRef,
+        header,
+        headerRef,
+        isScrollable,
+        isScrolledToBottom,
+        onDismiss,
+        overlayRef,
+        scrollRef,
+    }: Props) => {
+        return (
+            // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
+            <div
+                aria-describedby={header?.description ? 'bottom-sheet-description' : undefined}
+                aria-label={header?.title ? undefined : 'Bottom Sheet'}
+                aria-labelledby={header?.title ? 'bottom-sheet-title' : undefined}
+                aria-modal="true"
+                className={cn(
+                    // Base styling
+                    'bg-background-primary p-md',
+                    // Layout
+                    'flex flex-col',
+                    // Position relative for absolute drag handle
+                    'relative',
+                    // Border radius (dynamic via CSS custom property with fallback)
+                    'rounded-t-xl',
+                    // focus-convention: intentional — this is a role="dialog" tabIndex={-1} programmatic focus
+                    // target, never Tab-reachable, so suppressing the outline is correct; a ring around
+                    // the whole sheet on open would be the regression. The hui- class was dead here:
+                    // outline-none (utilities, later) already beat it at equal specificity (DS-98 Phase 0).
+                    'focus:outline-none',
+                    // EXPERIMENTAL: Static height instead of animated height
+                    'h-[var(--rsbs-overlay-h-static,100vh)]',
+                    // EXPERIMENTAL: translate3d for GPU acceleration
+                    // Using transform-gpu class to enable GPU acceleration
+                    'transform-gpu',
+                    // Performance optimizations - specify only transform for will-change
+                    'will-change-transform',
+                    // Drag handle positioned at the very top
+                    'before:absolute before:left-1/2 before:top-2xs before:block',
+                    'before:h-2xs before:w-9 before:-translate-x-1/2 before:rounded-sm',
+                    'before:bg-icon-secondary/20 before:content-[""]'
+                )}
+                key="overlay"
+                onKeyDown={(event) => {
+                    if (event.key === 'Escape') {
+                        // Always stop propagation, to avoid weirdness for bottom sheets inside other bottom sheets
+                        event.stopPropagation();
+                        if (onDismiss) {
+                            onDismiss();
+                        }
+                    }
+                }}
+                ref={overlayRef}
+                role="dialog"
+                style={{
+                    // EXPERIMENTAL: Apply translate3d transform via CSS custom property
+                    // Fallback uses the static height variable to ensure proper initial positioning
+                    transform:
+                        'var(--rsbs-overlay-translate3d, translate3d(0, var(--rsbs-overlay-h-static, 100vh), 0))',
+                }}
+                tabIndex={-1}
+            >
+                {/* Absolute drag area overlay - covers the top section including visual handle */}
+                <div
+                    className={cn(
+                        // Position absolutely to overlay the top section
+                        'absolute left-0 right-0 top-0',
+                        // Height to cover visual handle + top padding space (4px + 8px + extra touch area)
+                        'h-md',
+                        // Make it draggable
+                        'cursor-ns-resize select-none',
+                        // Z-index to be above content but allow header text to be selectable
+                        'z-10'
+                    )}
+                    style={{ touchAction: 'none' }}
+                    {...bind()}
+                />
+
+                {/* Header content - normal layout */}
+                {header && (
+                    <div
+                        className="flex flex-col gap-2xs pb-sm"
+                        key="header"
+                        ref={headerRef}
+                    >
+                        <SheetTitle id="bottom-sheet-title">{header.title}</SheetTitle>
+                        <SheetDescription id="bottom-sheet-description">{header.description}</SheetDescription>
+                    </div>
+                )}
+
+                {/* If no header, still need ref for measurements */}
+                {!header && (
+                    <div
+                        className="hidden"
+                        ref={headerRef}
+                    />
+                )}
+
+                <BottomSheetContentArea
+                    contentRef={contentRef}
+                    disableScroll={disableScroll}
+                    scrollRef={scrollRef}
+                >
+                    {children}
+                </BottomSheetContentArea>
+
+                {/* Footer area - always render for padding and gradient overlay */}
+                <div
+                    className={cn(
+                        // Base styling - always apply padding and ensure minimum height
+                        'relative flex-shrink-0',
+                        footer ? 'pt-lg' : 'min-h-[1px] pb-md',
+                        // Footer specific drag behavior - only when footer exists
+                        footer && 'cursor-ns-resize'
+                    )}
+                    key="footer"
+                    ref={footerRef}
+                    style={footer ? { touchAction: 'none' } : undefined}
+                    {...(footer ? bind() : {})}
+                >
+                    {/* Gradient overlay - show when scrollable and not at bottom */}
+                    {!disableScroll && isScrollable && !isScrolledToBottom && (
+                        <div
+                            className="pointer-events-none absolute -top-[42px] left-0 right-0 h-xl w-full"
+                            data-testid="gradient-overlay"
+                            style={{
+                                background: `linear-gradient(to bottom, transparent, ${wrapVarRgb('--color-background-primary')})`,
+                            }}
+                        />
+                    )}
+                    {footer}
+                </div>
+            </div>
+        );
+    }
+);
+
+// Add display name for better debugging
+BottomSheetOverlayTranslate3d.displayName = 'BottomSheetOverlayTranslate3d';

package/src/BottomSheet/components/SheetDescription/SheetDescription.tsx

@@ -0,0 +1,22 @@
+import { ReactNode } from 'react';
+
+import { BodySecondary } from '../../../Typography/Text/Text';
+
+type Props = {
+    children: ReactNode;
+    className?: string;
+    id?: string;
+};
+
+export const SheetDescription = ({ children, className, id }: Props) => {
+    return (
+        <BodySecondary
+            className={className}
+            color="secondary"
+            data-testid="sheet-description"
+            id={id}
+        >
+            {children}
+        </BodySecondary>
+    );
+};

package/src/BottomSheet/components/SheetTitle/SheetTitle.tsx

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+
+import { H2 } from '../../../Typography/Text/Text';
+
+type Props = {
+    children: ReactNode;
+    className?: string;
+    id?: string;
+};
+
+export const SheetTitle = ({ children, className, id }: Props) => {
+    return (
+        <H2
+            className={className}
+            data-testid="sheet-title"
+            id={id}
+        >
+            {children}
+        </H2>
+    );
+};

package/src/BottomSheet/components/index.tsx

@@ -0,0 +1,5 @@
+export { SheetDescription } from './SheetDescription/SheetDescription';
+export { SheetTitle } from './SheetTitle/SheetTitle';
+export { BottomSheetBackdrop } from './BottomSheetBackdrop/BottomSheetBackdrop';
+export { BottomSheetContentArea } from './BottomSheetContentArea/BottomSheetContentArea';
+export { BottomSheetOverlayTranslate3d as BottomSheetOverlay } from './BottomSheetOverlay/BottomSheetOverlayTranslate3d';

package/src/BottomSheet/hooks/index.tsx

@@ -0,0 +1,13 @@
+export { useAriaHider } from './useAriaHider';
+export { useFocusTrap } from './useFocusTrap';
+export { useLayoutEffect } from './useLayoutEffect';
+export { useOptimizedResizeObserver } from './useOptimizedResizeObserver';
+export { useOptimizedScrollState } from './useOptimizedScrollState';
+export { useReady } from './useReady';
+export { useReducedMotion } from './useReducedMotion';
+export { useScrollLock } from './useScrollLock';
+export { useSnapPoints } from './useSnapPoints';
+export { useSpring } from './useSpring';
+export { useSpringInterpolationsTranslate3d } from './useSpringInterpolationsTranslate3d';
+export { useDragHandler } from './useDragHandler';
+export { useBottomSheetServices } from './useBottomSheetServices';

package/src/BottomSheet/hooks/useAriaHider.tsx

@@ -0,0 +1,91 @@
+import { RefObject, useDebugValue, useEffect, useRef } from 'react';
+
+// Handle hiding and restoring aria-hidden attributes
+export const useAriaHider = ({ enabled, targetRef }: { enabled: boolean; targetRef: RefObject<Element> }) => {
+    // eslint-disable-next-line func-call-spacing
+    const ref = useRef<{ activate: () => void; deactivate: () => void }>({
+        activate: () => {
+            throw new TypeError('Tried to activate aria hider too early');
+        },
+        deactivate: () => {},
+    });
+
+    useDebugValue(enabled ? 'Enabled' : 'Disabled');
+
+    useEffect(() => {
+        if (!enabled) {
+            ref.current.deactivate();
+            ref.current = { activate: () => {}, deactivate: () => {} };
+            return;
+        }
+
+        const target = targetRef.current;
+        let active = false;
+        let originalValues: (null | string)[] = [];
+        let rootNodes: Element[] = [];
+
+        ref.current = {
+            activate: () => {
+                if (active) {
+                    return;
+                }
+                active = true;
+
+                // For fixed positioned elements (like BottomSheet), we need to hide siblings at the body level
+                // but exclude the target element itself and its ancestors
+                const targetElement = target;
+
+                // Find all elements to potentially hide
+                const candidates = Array.from(document.querySelectorAll('body > *'));
+
+                candidates.forEach((node) => {
+                    // Don't hide the target element itself
+                    if (node === targetElement) {
+                        return;
+                    }
+
+                    // Don't hide if target is a descendant of this node (prevents hiding containers)
+                    if (node.contains(targetElement)) {
+                        return;
+                    }
+
+                    // Don't hide if already hidden
+                    const attr = node.getAttribute('aria-hidden');
+                    const alreadyHidden = attr !== null && attr !== 'false';
+                    if (alreadyHidden) {
+                        return;
+                    }
+
+                    // Don't hide script, style, or other non-interactive elements
+                    const tagName = node.tagName.toLowerCase();
+                    if (['script', 'style', 'meta', 'title', 'link'].includes(tagName)) {
+                        return;
+                    }
+
+                    originalValues.push(attr);
+                    rootNodes.push(node);
+                    node.setAttribute('aria-hidden', 'true');
+                });
+            },
+            deactivate: () => {
+                if (!active) {
+                    return;
+                }
+                active = false;
+
+                rootNodes.forEach((node, index) => {
+                    const originalValue = originalValues[index];
+                    if (originalValue === null) {
+                        node.removeAttribute('aria-hidden');
+                    } else {
+                        node.setAttribute('aria-hidden', originalValue);
+                    }
+                });
+                originalValues = [];
+                rootNodes = [];
+            },
+        };
+    }, [targetRef, enabled]);
+
+    return ref;
+};

package/src/BottomSheet/hooks/useBottomSheetServices.tsx

@@ -0,0 +1,224 @@
+import { RefObject, useCallback } from 'react';
+
+import type { BottomSheetServices } from '../state/useBottomSheetStateMachine';
+import type { ResizeSource, SpringEvent } from '../types';
+import type { SpringSetOptions } from './useSpring';
+
+/**
+ * Props for the bottom sheet services hook
+ */
+type UseBottomSheetServicesProps = {
+    /** Aria hider ref with activate/deactivate methods */
+    ariaHiderRef: RefObject<{ activate: () => void; deactivate: () => void }>;
+    /** Async spring setter function */
+    asyncSet: (config: SpringSetOptions) => Promise<void>;
+    /** Reference to track if dragging is allowed */
+    canDragRef: RefObject<boolean>;
+    /** Reference to the default snap value */
+    defaultSnapRef: RefObject<number>;
+    /** Reference to the find snap function */
+    findSnapRef: RefObject<(y: number, velocity?: number) => number>;
+    /** Focus trap ref with activate/deactivate methods */
+    focusTrapRef: RefObject<{ activate: () => void; deactivate: () => void }>;
+    /** Reference to the current height */
+    heightRef: RefObject<number>;
+    /** Reference to the last snap value */
+    lastSnapRef: RefObject<number | null>;
+    /** Reference to the current max height value */
+    maxHeightRef: RefObject<number>;
+    /** Reference to the current max snap value */
+    maxSnapRef: RefObject<number>;
+    /** Reference to the current min snap value */
+    minSnapRef: RefObject<number>;
+    /** Spring cancel callback ref */
+    onSpringCancelRef: RefObject<((event: SpringEvent) => void) | undefined>;
+    /** Spring end callback ref */
+    onSpringEndRef: RefObject<((event: SpringEvent) => void) | undefined>;
+    /** Spring start callback ref */
+    onSpringStartRef: RefObject<((event: SpringEvent) => void) | undefined>;
+    /** Reference to check if reduced motion is preferred */
+    prefersReducedMotion: RefObject<boolean | undefined>;
+    /** Reference to track resize source */
+    resizeSourceRef: RefObject<ResizeSource>;
+    /** Scroll lock ref with activate/deactivate methods */
+    scrollLockRef: RefObject<{ activate: () => void; deactivate: () => void }>;
+};
+
+/**
+ * Custom hook to provide state machine services for the bottom sheet
+ */
+export const useBottomSheetServices = ({
+    ariaHiderRef,
+    asyncSet,
+    canDragRef,
+    defaultSnapRef,
+    findSnapRef,
+    focusTrapRef,
+    heightRef,
+    lastSnapRef,
+    maxHeightRef,
+    maxSnapRef,
+    minSnapRef,
+    onSpringEndRef,
+    onSpringStartRef,
+    prefersReducedMotion,
+    resizeSourceRef,
+    scrollLockRef,
+}: UseBottomSheetServicesProps) => {
+    const services = useCallback(
+        (): BottomSheetServices => ({
+            activate: async () => {
+                canDragRef.current = true;
+                await Promise.all(
+                    [
+                        scrollLockRef.current.activate(),
+                        focusTrapRef.current.activate(),
+                        ariaHiderRef.current.activate(),
+                    ].filter(Boolean)
+                );
+            },
+            closeSmoothly: async () => {
+                // Avoid animating the height property on close and stay within FLIP bounds by upping the minSnap
+                asyncSet({
+                    immediate: true,
+                    minSnap: heightRef.current,
+                });
+
+                heightRef.current = 0;
+
+                await asyncSet({
+                    immediate: prefersReducedMotion.current || false,
+                    maxHeight: maxHeightRef.current,
+                    maxSnap: maxSnapRef.current,
+                    y: 0,
+                });
+            },
+            deactivate: async () => {
+                // Deactivate focus trap to restore focus (if any element was previously focused)
+                focusTrapRef.current.deactivate();
+
+                // Deactivate scroll lock and aria hider
+                scrollLockRef.current.deactivate();
+                ariaHiderRef.current.deactivate();
+
+                canDragRef.current = false;
+            },
+            onCloseEnd: async () => {
+                // Final cleanup after close animation completes
+                // The spring end callback has already been called by this point
+            },
+            onCloseStart: async () => onSpringStartRef.current?.({ type: 'CLOSE' }),
+            onOpenEnd: async () => onSpringEndRef.current?.({ type: 'OPEN' }),
+            onOpenStart: async () => onSpringStartRef.current?.({ type: 'OPEN' }),
+            onResizeEnd: async () =>
+                onSpringEndRef.current?.({
+                    source: resizeSourceRef.current,
+                    type: 'RESIZE',
+                }),
+            onResizeStart: async () =>
+                onSpringStartRef.current?.({
+                    source: resizeSourceRef.current,
+                    type: 'RESIZE',
+                }),
+            onSnapEnd: async (context) =>
+                onSpringEndRef.current?.({
+                    source: context.snapSource || 'custom',
+                    type: 'SNAP',
+                }),
+            onSnapStart: async (context) =>
+                onSpringStartRef.current?.({
+                    source: context.snapSource || 'custom',
+                    type: 'SNAP',
+                }),
+            openImmediately: async () => {
+                heightRef.current = defaultSnapRef.current;
+                await asyncSet({
+                    immediate: true,
+                    maxHeight: maxHeightRef.current,
+                    maxSnap: maxSnapRef.current,
+                    // Using defaultSnapRef instead of minSnapRef to avoid animating `height` on open
+                    minSnap: defaultSnapRef.current,
+                    y: defaultSnapRef.current,
+                });
+            },
+            openSmoothly: async () => {
+                // Use fallback values if measurements aren't ready yet for faster initial render
+                const maxHeight = maxHeightRef.current || (typeof window !== 'undefined' ? window.innerHeight : 800);
+                const defaultSnap = defaultSnapRef.current || 300; // Fallback to reasonable default
+                const maxSnap = maxSnapRef.current || maxHeight;
+
+                // MOBILE OPTIMIZATION: Single animation instead of double animation
+                // This eliminates the jarring transition that causes FPS drops on mobile
+                heightRef.current = defaultSnap;
+
+                await asyncSet({
+                    // Start from closed position and animate to open in one smooth motion
+                    from: { maxHeight, maxSnap, minSnap: defaultSnap, y: 0 },
+                    immediate: prefersReducedMotion.current || false,
+                    to: { maxHeight, maxSnap, minSnap: defaultSnap, y: defaultSnap },
+                });
+            },
+            renderVisuallyHidden: async () => {
+                // Use fallback values if measurements aren't ready yet
+                const maxHeight = maxHeightRef.current || (typeof window !== 'undefined' ? window.innerHeight : 800);
+                const defaultSnap = defaultSnapRef.current || 300;
+                const maxSnap = maxSnapRef.current || maxHeight;
+
+                await asyncSet({
+                    immediate: true,
+                    maxHeight,
+                    maxSnap,
+                    // Using defaultSnapRef instead of minSnapRef to avoid animating `height` on open
+                    minSnap: defaultSnap,
+                    y: defaultSnap,
+                });
+            },
+            resizeSmoothly: async () => {
+                const snap = findSnapRef.current(heightRef.current);
+                heightRef.current = snap;
+                lastSnapRef.current = snap;
+                await asyncSet({
+                    immediate: resizeSourceRef.current === 'element' ? prefersReducedMotion.current || false : true,
+                    maxHeight: maxHeightRef.current,
+                    maxSnap: maxSnapRef.current,
+                    minSnap: minSnapRef.current,
+                    y: snap,
+                });
+            },
+            snapSmoothly: async (context) => {
+                const snap = findSnapRef.current(context.y || 0, context.velocity);
+
+                heightRef.current = snap;
+                lastSnapRef.current = snap;
+                await asyncSet({
+                    config: { velocity: context.velocity || 1 },
+                    immediate: prefersReducedMotion.current || false,
+                    maxHeight: maxHeightRef.current,
+                    maxSnap: maxSnapRef.current,
+                    minSnap: minSnapRef.current,
+                    y: snap,
+                });
+            },
+        }),
+        [
+            canDragRef,
+            heightRef,
+            lastSnapRef,
+            defaultSnapRef,
+            maxHeightRef,
+            maxSnapRef,
+            minSnapRef,
+            findSnapRef,
+            resizeSourceRef,
+            prefersReducedMotion,
+            asyncSet,
+            scrollLockRef,
+            focusTrapRef,
+            ariaHiderRef,
+            onSpringStartRef,
+            onSpringEndRef,
+        ]
+    );
+
+    return services;
+};