@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/JumpMenu/JumpMenu.tsx

@@ -0,0 +1,395 @@
+import { cn } from '@evolve.ui/theme-system';
+import { HTMLProps, MouseEvent, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { useHorizontalScrollFadeMixin } from '../mixins/horizontalScrollFadeMixin';
+import { useWindowIsMobile } from '../providers/windowSizeProvider';
+import { Caption } from '../Typography/Text/Text';
+import { isClientSide } from '../utils/isClientSide';
+import { JumpMenuItem } from './components/JumpMenuItem/JumpMenuItem';
+import { useContainerTracking } from './hooks/useContainerTracking';
+import { useKeyboardNavigation } from './hooks/useKeyboardNavigation';
+import { useSectionObserver } from './hooks/useSectionObserver';
+import { JumpMenuItem as JumpMenuItemType } from './types';
+
+/**
+ * Props for the JumpMenu component
+ */
+type Props = HTMLProps<HTMLElement> & {
+    /** Custom aria-label for the navigation (defaults to 'Jump to section') */
+    ariaLabel?: string;
+    /** Additional CSS classes for the menu container */
+    className?: string;
+    /** CSS selector for the container element that defines the scope of fixed positioning behavior */
+    containerSelector?: string;
+    /** Array of menu items to display in the jump navigation */
+    items: JumpMenuItemType[];
+    /** Callback when active section changes via scroll or user interaction */
+    onActiveChange?: (activeId: string | null) => void;
+    /** Additional CSS classes for the outer container of the menu */
+    outerContainerClassName?: string;
+    /** Scroll offset in pixels to account for sticky headers when navigating to sections (defaults to 0) */
+    scrollOffset?: number;
+    /** Scroll offset in pixels for mobile viewports (overrides scrollOffset on mobile, defaults to scrollOffset value) */
+    scrollOffsetMobile?: number;
+};
+
+/**
+ * JumpMenu component for horizontal scrollable navigation between page sections
+ *
+ * Features:
+ * - Horizontal scrolling with fade indicators on overflow
+ * - Automatic section highlighting based on scroll position
+ * - Keyboard navigation (Arrow keys, Home, End)
+ * - Smooth scrolling to target sections
+ * - Accessibility compliant with ARIA labels and roles
+ * - Fixed positioning with container visibility tracking
+ *
+ * @param ariaLabel - Custom aria-label for the navigation (defaults to 'Jump to section')
+ * @param className - Additional CSS classes for the menu container
+ * @param containerSelector - CSS selector for the container element that defines the scope of fixed positioning behavior
+ * @param items - Array of menu items to display - each item should have an id and either target or href
+ * @param onActiveChange - Callback when active section changes via scroll or user interaction
+ * @param outerContainerClassName - Additional CSS classes for the outer container of the menu
+ * @param scrollOffset - Scroll offset in pixels to account for sticky headers when navigating to sections (defaults to 0)
+ * @param scrollOffsetMobile - Scroll offset in pixels for mobile viewports (overrides scrollOffset on mobile, defaults to scrollOffset value)
+ *
+ *
+ * @example
+ * ```tsx
+ * const menuItems = [
+ *   { id: 'overview', label: 'Overview', href: '#overview-section' },
+ *   { id: 'details', label: 'Details', href: '#details-section' },
+ * ];
+ *
+ * <div id="container">
+ *  <JumpMenu
+ *   items={menuItems}
+ *   containerSelector="#container"
+ *   onActiveChange={(activeId) => console.log('Active section:', activeId)}
+ *   scrollOffset={80}        // Optional: Account for 80px sticky header
+ *   scrollOffsetMobile={120} // Optional: Account for larger mobile header
+ *  />
+ *  <section id="overview-section">Overview content</section>
+ *  <section id="details-section">Details content</section>
+ * </div>
+ * ```
+ */
+export const JumpMenu = ({
+    ariaLabel = 'Jump to section',
+    className,
+    containerSelector,
+    items,
+    onActiveChange,
+    outerContainerClassName = '',
+    scrollOffset = 0,
+    scrollOffsetMobile,
+    ...htmlProps
+}: Props) => {
+    // Track user-initiated actions with timestamp to ignore subsequent intersection observer events
+    const userActionIgnoreDuration = 1000;
+    const lastUserActionRef = useRef<number>(0);
+
+    const [activeItemId, setActiveItemId] = useState<string | null>(
+        items.find((item) => item.isActive)?.id || items[0]?.id || null
+    );
+    const menuRef = useRef<HTMLDivElement>(null);
+    const scrollContainerRef = useRef<HTMLDivElement>(null);
+    const horizontalScrollFadeProps = useHorizontalScrollFadeMixin(0);
+    const [navBackgroundColor, setNavBackgroundColor] = useState<string>('rgb(255, 255, 255)');
+
+    // Use the container tracking hook for visibility and width management
+    const { isContainerVisible, menuHeight, menuWidth } = useContainerTracking({
+        containerSelector,
+        menuRef,
+    });
+
+    // Determine if container top has passed viewport top (need to check position separately from visibility)
+    const [containerTopPassed, setContainerTopPassed] = useState(false);
+
+    // Track pending scroll when clicking item before menu becomes fixed
+    const pendingScrollItemRef = useRef<string | null>(null);
+
+    useEffect(() => {
+        if (!containerSelector || !isClientSide) {
+            return;
+        }
+
+        const containerElement = document.querySelector(containerSelector);
+        if (!containerElement) {
+            return;
+        }
+
+        const checkPosition = () => {
+            const rect = containerElement.getBoundingClientRect();
+            setContainerTopPassed(rect.top <= 0);
+        };
+
+        checkPosition();
+        window.addEventListener('scroll', checkPosition, { passive: true });
+        return () => window.removeEventListener('scroll', checkPosition);
+    }, [containerSelector]);
+
+    const isMobile = useWindowIsMobile();
+
+    /**
+     * Gets the appropriate scroll offset based on viewport size
+     * @returns The scroll offset to use for the current viewport
+     */
+    const getScrollOffset = useCallback(() => {
+        return isMobile && scrollOffsetMobile !== undefined ? scrollOffsetMobile : scrollOffset;
+    }, [scrollOffset, scrollOffsetMobile, isMobile]);
+
+    /**
+     * Scrolls the specified menu item into view within the horizontal scroll container
+     * Only scrolls when menu is in fixed position to prevent viewport shifts
+     * @param itemId - The ID of the menu item to scroll into view
+     * @param inline - Scroll alignment: 'center' shows neighbors, 'nearest' minimal scroll
+     */
+    const scrollActiveItemIntoView = useCallback((itemId: string, inline: 'center' | 'nearest' = 'nearest') => {
+        const activeElement = scrollContainerRef.current?.querySelector(
+            `[data-item-id="${itemId}"]`
+        ) as HTMLElement | null;
+
+        if (activeElement) {
+            activeElement.scrollIntoView({
+                behavior: 'smooth',
+                block: 'nearest',
+                inline,
+            });
+        }
+    }, []);
+
+    // When menu becomes fixed and we have a pending scroll, execute it
+    useEffect(() => {
+        if (containerTopPassed && pendingScrollItemRef.current) {
+            scrollActiveItemIntoView(pendingScrollItemRef.current, 'center');
+            pendingScrollItemRef.current = null;
+        }
+    }, [containerTopPassed, scrollActiveItemIntoView]);
+
+    // Update active item when external state changes
+    useEffect(() => {
+        const externalActiveItem = items.find((item) => item.isActive);
+        if (externalActiveItem && externalActiveItem.id !== activeItemId) {
+            setActiveItemId(externalActiveItem.id);
+        }
+    }, [items, activeItemId]);
+
+    /**
+     * Handles active section changes from the intersection observer
+     * Ignores updates that occur shortly after user interactions to prevent conflicts
+     * @param sectionId - The ID of the section that became active
+     */
+    const handleActiveChange = useCallback(
+        (sectionId: string) => {
+            // Skip if this is a scroll-based update and we recently had a user action
+            const timeSinceLastUserAction = Date.now() - lastUserActionRef.current;
+            if (timeSinceLastUserAction < userActionIgnoreDuration) {
+                return;
+            }
+
+            if (sectionId !== activeItemId) {
+                setActiveItemId(sectionId);
+                onActiveChange?.(sectionId);
+                // Auto-scroll with 'center' to show neighboring items (only when fixed)
+                if (containerTopPassed) {
+                    scrollActiveItemIntoView(sectionId, 'center');
+                }
+            }
+        },
+        [activeItemId, onActiveChange, userActionIgnoreDuration, scrollActiveItemIntoView, containerTopPassed]
+    );
+
+    // Prepare sections for the observer
+    const sections = useMemo(
+        () =>
+            items
+                .filter((item) => item.target || item.href)
+                .map((item) => ({
+                    id: item.id,
+                    selector: item.target ? `#${item.target}` : item.href!,
+                })),
+        [items]
+    );
+
+    // Use modern IntersectionObserver for section detection
+    useSectionObserver(sections, handleActiveChange);
+
+    // Handle keyboard navigation with the dedicated hook
+    const { handleKeyDown } = useKeyboardNavigation({
+        activeItemId,
+        containerRef: menuRef,
+        getItemId: (item: JumpMenuItemType) => item.id,
+        items,
+        lastUserActionRef,
+        onActiveChange: (itemId: string) => {
+            setActiveItemId(itemId);
+            onActiveChange?.(itemId);
+        },
+        scrollItemIntoView: scrollActiveItemIntoView,
+    });
+
+    /**
+     * Handles menu item click events
+     * Updates active state, calls custom onClick handler, and navigates to target section
+     * @param item - The clicked menu item
+     * @param event - The mouse event
+     */
+    const handleItemClick = useCallback(
+        (item: JumpMenuItemType, event: MouseEvent) => {
+            // Mark this as a user-initiated action
+            lastUserActionRef.current = Date.now();
+
+            // Scroll the clicked menu item into view FIRST, using 'center' to show neighbors
+            // Only scroll horizontally when menu is in fixed position to prevent viewport shifts
+            if (containerTopPassed) {
+                scrollActiveItemIntoView(item.id, 'center');
+            } else {
+                // Store pending scroll to execute once menu becomes fixed
+                pendingScrollItemRef.current = item.id;
+            }
+
+            setActiveItemId(item.id);
+            onActiveChange?.(item.id);
+            item.onClick?.(item.id);
+
+            // Navigate to section if target or href is provided
+            const targetSelector = item.target ? `#${item.target}` : item.href;
+
+            if (targetSelector) {
+                // Always prevent default since we're using buttons now
+                event.preventDefault();
+
+                // Handle navigation manually
+                const targetElement = document.querySelector(targetSelector);
+                if (targetElement) {
+                    const offset = getScrollOffset();
+
+                    if (offset > 0) {
+                        // Calculate position with offset
+                        const elementPosition = targetElement.getBoundingClientRect().top + window.pageYOffset;
+                        const offsetPosition = elementPosition - offset;
+
+                        window.scrollTo({
+                            behavior: 'smooth',
+                            top: offsetPosition,
+                        });
+                    } else {
+                        // Use default scroll behavior when no offset
+                        targetElement.scrollIntoView({
+                            behavior: 'smooth',
+                            block: 'start',
+                        });
+                    }
+                }
+            }
+        },
+        [onActiveChange, getScrollOffset, scrollActiveItemIntoView, containerTopPassed]
+    );
+
+    // Simple positioning logic - no complex state management needed
+    // Fixed when we've scrolled past container top AND container hasn't scrolled past bottom
+    const shouldUseFixedPosition = containerSelector && containerTopPassed && isContainerVisible;
+
+    // Extract background color from nav element for dynamic gradient overlays
+    useEffect(() => {
+        if (menuRef.current && isClientSide) {
+            const computedStyle = window.getComputedStyle(menuRef.current);
+            const backgroundColor = computedStyle.backgroundColor;
+            if (backgroundColor && backgroundColor !== 'rgba(0, 0, 0, 0)' && backgroundColor !== 'transparent') {
+                setNavBackgroundColor(backgroundColor);
+            }
+        }
+    }, []);
+
+    return (
+        <div className={cn(outerContainerClassName)}>
+            {/* Simple placeholder to maintain layout when menu becomes fixed or is fading out */}
+            {(shouldUseFixedPosition || !isContainerVisible) && (
+                <div
+                    aria-hidden="true"
+                    style={{
+                        height: menuHeight,
+                    }}
+                />
+            )}
+
+            <nav
+                aria-label={ariaLabel}
+                className={cn(
+                    'z-10 w-full bg-background-primary transition-opacity duration-300',
+                    {
+                        'fixed top-0': shouldUseFixedPosition || !isContainerVisible, // Keep fixed during fade-out
+                        'pointer-events-none': !isContainerVisible, // Disable interaction when hidden
+                        relative: !shouldUseFixedPosition && isContainerVisible,
+                    },
+                    className
+                )}
+                ref={menuRef}
+                style={{
+                    opacity: isContainerVisible ? 1 : 0,
+                    width: shouldUseFixedPosition || !isContainerVisible ? `${menuWidth}px` : undefined,
+                    ...htmlProps.style,
+                }}
+                {...htmlProps}
+            >
+                <div className="flex w-full flex-col gap-xs py-xs">
+                    <Caption
+                        // z-[11] is to prevent the caption from being hidden by fade
+                        className="z-[11] w-full px-xs"
+                        color="secondary"
+                    >
+                        {ariaLabel}
+                    </Caption>
+                    {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions -- Keyboard events bubble from focusable menu items */}
+                    <div
+                        className="scrollbar-hide flex w-full overflow-x-auto px-xs py-3xs"
+                        onKeyDown={handleKeyDown}
+                        ref={(element) => {
+                            horizontalScrollFadeProps.ref(element);
+                            scrollContainerRef.current = element;
+                            menuRef.current = element;
+                        }}
+                    >
+                        {/* Left fade overlay */}
+                        <div
+                            className={cn(
+                                'pointer-events-none absolute bottom-0 left-0 top-0 z-10 w-[48px] transition-opacity duration-300 ease-in-out',
+                                {
+                                    'opacity-0': !horizontalScrollFadeProps.shouldShowLeftFade,
+                                    'opacity-100': horizontalScrollFadeProps.shouldShowLeftFade,
+                                }
+                            )}
+                            style={{
+                                background: `linear-gradient(to right, ${navBackgroundColor}, transparent)`,
+                            }}
+                        />
+
+                        {/* Right fade overlay */}
+                        <div
+                            className={cn(
+                                'pointer-events-none absolute bottom-0 right-0 top-0 z-10 w-[48px] transition-opacity duration-300 ease-in-out',
+                                {
+                                    'opacity-0': !horizontalScrollFadeProps.shouldShowRightFade,
+                                    'opacity-100': horizontalScrollFadeProps.shouldShowRightFade,
+                                }
+                            )}
+                            style={{
+                                background: `linear-gradient(to left, ${navBackgroundColor}, transparent)`,
+                            }}
+                        />
+
+                        {items.map((item) => (
+                            <JumpMenuItem
+                                {...item}
+                                activeItemId={activeItemId}
+                                handleItemClick={handleItemClick}
+                                key={item.id}
+                            />
+                        ))}
+                    </div>
+                </div>
+            </nav>
+        </div>
+    );
+};

package/src/JumpMenu/components/JumpMenuItem/JumpMenuItem.tsx

@@ -0,0 +1,62 @@
+import { cn } from '@evolve.ui/theme-system';
+
+import { JumpMenuItem as JumpMenuItemData } from '../../types';
+
+/**
+ * Single jump menu item configuration with click handler
+ */
+export type Props<T extends JumpMenuItemData = JumpMenuItemData> = T & {
+    /** Unique identifier for the menu item */
+    activeItemId: string | null;
+    /** Additional CSS classes for the individual item */
+    className?: string;
+    /** Handle item click function */
+    handleItemClick: (item: T, event: React.MouseEvent) => void;
+};
+
+export const JumpMenuItem = ({
+    activeItemId,
+    className,
+    handleItemClick,
+    href,
+    id,
+    isActive: isActiveProp,
+    label,
+    target,
+    ...restProps
+}: Props) => {
+    const isActive = isActiveProp || id === activeItemId;
+
+    return (
+        <button
+            aria-current={isActive ? 'page' : undefined}
+            className={cn(
+                // Base styles - use consistent typography class for both states
+                'hui-text-body-secondary relative whitespace-nowrap rounded-md px-xs py-2xs last:mr-sm [&:not(:last-child)]:mr-xs',
+                // Default state (Selected=Off, Hover=Off, Focused=Off)
+                'text-text-secondary',
+                // Focus styles - inset focus ring to stay within button dimensions
+                'focus-visible:shadow-[inset_0_0_0_4px_rgb(var(--color-focus-primary)/0.50)] focus-visible:outline-none',
+                // Interactive states
+                'cursor-pointer',
+                // Hover states - completely remove hover on touch devices, only show on pointer devices
+                '[&:hover]:[@media(pointer:fine)]:bg-background-hover',
+                !isActive && '[&:hover]:[@media(pointer:fine)]:text-text-primary',
+                // Touch/Active states for mobile - brief visual feedback on tap
+                !isActive && 'active:bg-background-hover active:text-text-primary active:duration-75',
+                // Selected states (Selected=On) - using ring for border without affecting dimensions
+                isActive && 'bg-background-primary font-bold text-text-primary ring-1 ring-inset ring-border-selected',
+                className
+            )}
+            data-item-id={id}
+            data-target={target || href?.replace('#', '')}
+            key={id}
+            onClick={(event) => {
+                handleItemClick({ href, id, isActive: isActiveProp, label, target, ...restProps }, event);
+            }}
+            type="button"
+        >
+            {label}
+        </button>
+    );
+};

package/src/JumpMenu/hooks/useContainerTracking.ts

@@ -0,0 +1,171 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { isClientSide } from '../../utils/isClientSide';
+
+/**
+ * Configuration for container tracking
+ */
+type ContainerTrackingConfig = {
+    /** CSS selector for the container element */
+    containerSelector?: string;
+    /** Reference to the menu element for height tracking */
+    menuRef?: React.RefObject<HTMLElement | null>;
+};
+
+/**
+ * Return type for the container tracking hook
+ */
+type UseContainerTrackingReturn = {
+    /** Whether the container is currently visible */
+    isContainerVisible: boolean;
+    /** Current height of the menu element in pixels */
+    menuHeight: number;
+    /** Current width of the container in pixels */
+    menuWidth: number;
+};
+
+/**
+ * Hook that tracks container visibility and dimensions for fixed positioning behavior
+ *
+ * This hook provides:
+ * - Simple container visibility tracking via scroll detection
+ * - Container width tracking for maintaining consistent sizing when position changes
+ * - Menu height tracking for placeholder div
+ * - Automatic event listener management with cleanup
+ * - SSR safety by checking client-side rendering
+ *
+ * @param config - Configuration object for container tracking
+ * @returns Object containing visibility state and dimensions
+ *
+ * @example
+ * ```tsx
+ * const { isContainerVisible, menuWidth, menuHeight } = useContainerTracking({
+ *   containerSelector: '#main-container',
+ *   menuRef
+ * });
+ * ```
+ */
+export const useContainerTracking = ({
+    containerSelector,
+    menuRef,
+}: ContainerTrackingConfig): UseContainerTrackingReturn => {
+    const [isContainerVisible, setIsContainerVisible] = useState<boolean>(true);
+    const [menuWidth, setMenuWidth] = useState<number>(0);
+    const [menuHeight, setMenuHeight] = useState<number>(0);
+    const resizeObserverRef = useRef<ResizeObserver | null>(null);
+
+    /**
+     * Sets up simple scroll-based visibility tracking for the container
+     * Menu becomes fixed when container top reaches viewport top and stays fixed until container scrolls past
+     */
+    useEffect(() => {
+        // We don't want to run this in SSR since we are using the window object
+        if (!isClientSide) {
+            return;
+        }
+
+        if (!containerSelector) {
+            setIsContainerVisible(true);
+            return;
+        }
+
+        const containerElement = document.querySelector(containerSelector);
+        if (!containerElement) {
+            setIsContainerVisible(true);
+            return;
+        }
+
+        const onScroll = () => {
+            const rect = containerElement.getBoundingClientRect();
+
+            // Menu should be visible when:
+            // 1. Before we scroll to container (rect.top > 0) - show in relative position
+            // 2. While scrolling through container (rect.top <= 0 && rect.bottom > 0) - show in fixed position
+            // 3. After scrolling past container (rect.bottom <= 0) - hide completely
+            const shouldBeVisible = rect.bottom > 0; // Visible as long as container hasn't scrolled completely past
+
+            setIsContainerVisible(shouldBeVisible);
+        };
+
+        // Initial check
+        onScroll();
+
+        // Listen to scroll events with passive flag for performance
+        window.addEventListener('scroll', onScroll, { passive: true });
+
+        return () => {
+            window.removeEventListener('scroll', onScroll);
+        };
+    }, [containerSelector]);
+
+    /**
+     * Updates menu width and height for fixed positioning
+     * This ensures the fixed menu maintains the same dimensions as its static position
+     * Uses ResizeObserver for precise, real-time dimension tracking
+     */
+    useEffect(() => {
+        // We don't want to run this in SSR since we are using the window object
+        if (!isClientSide) {
+            return;
+        }
+
+        const updateContainerWidth = () => {
+            if (containerSelector) {
+                const containerElement = document.querySelector(containerSelector);
+                if (containerElement) {
+                    const containerRect = containerElement.getBoundingClientRect();
+                    setMenuWidth(containerRect.width);
+                }
+            }
+        };
+
+        const updateMenuHeight = () => {
+            if (menuRef?.current) {
+                // Use offsetHeight for more accurate measurement including borders and padding
+                const height = menuRef.current.offsetHeight;
+                if (height > 0) {
+                    setMenuHeight(height);
+                }
+            }
+        };
+
+        // Set up ResizeObserver for menu element height tracking
+        if (menuRef?.current && 'ResizeObserver' in window) {
+            resizeObserverRef.current = new ResizeObserver((entries) => {
+                for (const entry of entries) {
+                    // Use contentRect height for reliable measurement
+                    const height = entry.contentRect.height;
+                    if (height > 0) {
+                        setMenuHeight(height);
+                    }
+                }
+            });
+
+            resizeObserverRef.current.observe(menuRef.current);
+        }
+
+        // Initial measurements
+        updateContainerWidth();
+        updateMenuHeight();
+
+        // Listen for window resize for container width updates
+        window.addEventListener('resize', updateContainerWidth);
+
+        return () => {
+            window.removeEventListener('resize', updateContainerWidth);
+            if (resizeObserverRef.current) {
+                resizeObserverRef.current.disconnect();
+                resizeObserverRef.current = null;
+            }
+        };
+    }, [containerSelector, menuRef]);
+
+    return useMemo(
+        () => ({
+            isContainerVisible,
+            menuHeight,
+            menuWidth,
+        }),
+        [isContainerVisible, menuHeight, menuWidth]
+    );
+};