@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/JumpMenu/hooks/useIntersectionObserver.ts

@@ -0,0 +1,77 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Options for the useIntersectionObserver hook
+ */
+type UseIntersectionObserverOptions = {
+    /** The element to use as the root for intersection calculations */
+    root?: Element | null;
+    /** Margin around the root element */
+    rootMargin?: string;
+    /** Threshold(s) at which to trigger the callback */
+    threshold?: number | number[];
+};
+
+/**
+ * Hook that provides intersection observer functionality
+ * @param callback - Function called when intersection changes
+ * @param options - IntersectionObserver options
+ * @returns Object with observe and unobserve functions
+ */
+export const useIntersectionObserver = (
+    callback: (entries: IntersectionObserverEntry[]) => void,
+    options: UseIntersectionObserverOptions = {}
+) => {
+    const observerRef = useRef<IntersectionObserver | null>(null);
+    const callbackRef = useRef(callback);
+    const [isSupported] = useState(() => typeof IntersectionObserver !== 'undefined');
+
+    // Update callback ref when callback changes
+    useEffect(() => {
+        callbackRef.current = callback;
+    }, [callback]);
+
+    useEffect(() => {
+        if (!isSupported) {
+            return;
+        }
+
+        // Use stable callback ref to avoid recreating observer
+        observerRef.current = new IntersectionObserver((entries) => {
+            callbackRef.current(entries);
+        }, options);
+
+        return () => {
+            if (observerRef.current) {
+                observerRef.current.disconnect();
+            }
+        };
+    }, [options, isSupported]);
+
+    const observe = (element: Element) => {
+        if (!observerRef.current && isSupported) {
+            // Observer hasn't been created yet, create it synchronously
+            observerRef.current = new IntersectionObserver((entries) => {
+                callbackRef.current(entries);
+            }, options);
+        }
+
+        if (observerRef.current && isSupported) {
+            observerRef.current.observe(element);
+        }
+    };
+
+    const unobserve = (element: Element) => {
+        if (observerRef.current && isSupported) {
+            observerRef.current.unobserve(element);
+        }
+    };
+
+    const disconnect = () => {
+        if (observerRef.current && isSupported) {
+            observerRef.current.disconnect();
+        }
+    };
+
+    return { disconnect, isSupported, observe, unobserve };
+};

package/src/JumpMenu/hooks/useKeyboardNavigation.ts

@@ -0,0 +1,102 @@
+import { KeyboardEvent, RefObject, useCallback } from 'react';
+
+/**
+ * Props for the keyboard navigation hook
+ */
+type UseKeyboardNavigationProps<T> = {
+    /** Current active item ID */
+    activeItemId: string | null;
+    /** Ref to the container element for focusing items */
+    containerRef: RefObject<HTMLElement | null>;
+    /** Function to extract ID from an item */
+    getItemId: (item: T) => string;
+    /** Array of items to navigate through */
+    items: T[];
+    /** Ref to track user-initiated actions */
+    lastUserActionRef: RefObject<number>;
+    /** Callback when active item changes */
+    onActiveChange?: (itemId: string) => void;
+    /** Function to scroll item into view */
+    scrollItemIntoView: (itemId: string) => void;
+};
+
+/**
+ * Return type for the keyboard navigation hook
+ */
+type UseKeyboardNavigationReturn = {
+    /** Keyboard event handler for the navigation container */
+    handleKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+};
+
+/**
+ * Custom hook for handling keyboard navigation in horizontal menu components
+ *
+ * Supports Arrow Left/Right, Home, and End keys for navigation with wrapping
+ * and automatic focus management.
+ */
+export const useKeyboardNavigation = <T>({
+    activeItemId,
+    containerRef,
+    getItemId,
+    items,
+    lastUserActionRef,
+    onActiveChange,
+    scrollItemIntoView,
+}: UseKeyboardNavigationProps<T>): UseKeyboardNavigationReturn => {
+    /**
+     * Handles keyboard navigation within the menu
+     * Supports Arrow Left/Right, Home, and End keys for navigation
+     */
+    const handleKeyDown = useCallback(
+        (event: KeyboardEvent<HTMLDivElement>) => {
+            if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) {
+                return;
+            }
+
+            event.preventDefault();
+
+            const currentEnabledIndex = items.findIndex((item) => getItemId(item) === activeItemId);
+
+            let nextIndex: number;
+
+            switch (event.key) {
+                case 'ArrowLeft':
+                    nextIndex = currentEnabledIndex > 0 ? currentEnabledIndex - 1 : items.length - 1;
+                    break;
+                case 'ArrowRight':
+                    nextIndex = currentEnabledIndex < items.length - 1 ? currentEnabledIndex + 1 : 0;
+                    break;
+                case 'Home':
+                    nextIndex = 0;
+                    break;
+                case 'End':
+                    nextIndex = items.length - 1;
+                    break;
+                default:
+                    return;
+            }
+
+            const nextItem = items[nextIndex];
+            const nextItemId = getItemId(nextItem);
+
+            // Mark this as a user-initiated action
+            lastUserActionRef.current = Date.now();
+
+            onActiveChange?.(nextItemId);
+
+            // Scroll the selected item into view
+            scrollItemIntoView(nextItemId);
+
+            // Focus the next item
+            const nextElement = containerRef.current?.querySelector(
+                `[data-item-id="${nextItemId}"]`
+            ) as HTMLElement | null;
+            nextElement?.focus();
+        },
+        [activeItemId, items, getItemId, onActiveChange, scrollItemIntoView, containerRef, lastUserActionRef]
+    );
+
+    return {
+        handleKeyDown,
+    };
+};

package/src/JumpMenu/hooks/useResizeObserver.ts

@@ -0,0 +1,53 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Callback function for resize events
+ */
+type ResizeCallback = (entry: ResizeObserverEntry) => void;
+
+/**
+ * Hook that provides ResizeObserver functionality
+ * @param callback - Function called when element size changes
+ * @returns Object with observe and unobserve functions
+ */
+export const useResizeObserver = (callback: ResizeCallback) => {
+    const observerRef = useRef<ResizeObserver | null>(null);
+    const [isSupported] = useState(() => typeof ResizeObserver !== 'undefined');
+
+    useEffect(() => {
+        if (!isSupported) {
+            return;
+        }
+
+        observerRef.current = new ResizeObserver((entries) => {
+            // Call the callback for each entry
+            entries.forEach(callback);
+        });
+
+        return () => {
+            if (observerRef.current) {
+                observerRef.current.disconnect();
+            }
+        };
+    }, [callback, isSupported]);
+
+    const observe = (element: Element) => {
+        if (observerRef.current && isSupported) {
+            observerRef.current.observe(element);
+        }
+    };
+
+    const unobserve = (element: Element) => {
+        if (observerRef.current && isSupported) {
+            observerRef.current.unobserve(element);
+        }
+    };
+
+    const disconnect = () => {
+        if (observerRef.current && isSupported) {
+            observerRef.current.disconnect();
+        }
+    };
+
+    return { disconnect, isSupported, observe, unobserve };
+};

package/src/JumpMenu/hooks/useSectionObserver.ts

@@ -0,0 +1,102 @@
+import { useEffect, useMemo, useRef } from 'react';
+
+import { useIntersectionObserver } from './useIntersectionObserver';
+
+/**
+ * Configuration for section observation
+ */
+type SectionConfig = {
+    /** The ID of the section */
+    id: string;
+    /** The selector or href for the section element */
+    selector: string;
+};
+
+/**
+ * Hook that observes multiple sections and reports which one is most visible
+ * @param sections - Array of section configurations
+ * @param onActiveChange - Callback when the active section changes
+ * @param enabled - Whether section observation is enabled
+ */
+export const useSectionObserver = (
+    sections: SectionConfig[],
+    onActiveChange: (sectionId: string) => void,
+    enabled: boolean = true
+) => {
+    const activeEntriesRef = useRef<Map<string, IntersectionObserverEntry>>(new Map());
+
+    // Memoize intersection observer options for better performance
+    const observerOptions = useMemo(
+        () => ({
+            rootMargin: '-10% 0px -10% 0px', // Trigger when section is 10% visible from top/bottom
+            threshold: [0, 0.1, 0.25, 0.5, 0.75, 1], // Multiple thresholds for better accuracy
+        }),
+        []
+    );
+
+    const handleIntersection = (entries: IntersectionObserverEntry[]) => {
+        // Update our map of active entries
+        entries.forEach((entry) => {
+            const sectionId = sections.find(
+                (s) => entry.target.matches(s.selector) || entry.target.id === s.selector.replace('#', '')
+            )?.id;
+
+            if (sectionId) {
+                if (entry.isIntersecting) {
+                    activeEntriesRef.current.set(sectionId, entry);
+                } else {
+                    activeEntriesRef.current.delete(sectionId);
+                }
+            }
+        });
+
+        // Find the topmost visible section (prioritize by vertical position, not intersection ratio)
+        if (activeEntriesRef.current.size > 0) {
+            let topmostSection = '';
+            let smallestTop = Infinity;
+
+            activeEntriesRef.current.forEach((entry, sectionId) => {
+                // Use boundingClientRect.top to find which section is highest on screen
+                const topPosition = entry.boundingClientRect.top;
+
+                // Prioritize sections that are actually in the viewport (positive intersection ratio)
+                if (entry.intersectionRatio > 0 && topPosition < smallestTop) {
+                    smallestTop = topPosition;
+                    topmostSection = sectionId;
+                }
+            });
+
+            if (topmostSection) {
+                onActiveChange(topmostSection);
+            }
+        }
+    };
+
+    const { disconnect, isSupported, observe } = useIntersectionObserver(handleIntersection, observerOptions);
+
+    useEffect(() => {
+        if (!enabled || !isSupported) {
+            return;
+        }
+
+        // Clear previous observations
+        activeEntriesRef.current.clear();
+        disconnect();
+
+        // Observe all section elements
+        sections.forEach(({ selector }) => {
+            const element = document.querySelector(selector);
+            if (element) {
+                observe(element);
+            }
+        });
+
+        return () => {
+            disconnect();
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+            activeEntriesRef.current.clear();
+        };
+    }, [sections, enabled, isSupported, observe, disconnect]);
+
+    return { isSupported };
+};

package/src/JumpMenu/index.ts

@@ -0,0 +1,2 @@
+export { JumpMenu } from './JumpMenu';
+export { type JumpMenuItem } from './types';

package/src/JumpMenu/types/index.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+
+/**
+ * Base jump menu item data without handlers
+ */
+export type JumpMenuItem = {
+    /** The href attribute for the link (for anchor navigation) - deprecated, use target */
+    href?: string;
+    /** Unique identifier for the menu item */
+    id: string;
+    /** Whether this item is currently active/selected */
+    isActive?: boolean;
+    /** The text or content to display in the menu item */
+    label: string | ReactNode;
+    /** Click handler function that receives the item id */
+    onClick?: (id: string) => void;
+    /** Target element selector (e.g., 'section1' for element with id='section1') */
+    target?: string;
+};

package/src/Loading/Loading.tsx

@@ -0,0 +1,39 @@
+import { cn } from '@evolve.ui/theme-system';
+
+import { LoadingDot } from './components/LoadingDot/LoadingDot';
+
+export type Props = {
+    className?: string;
+    'data-testid'?: string;
+    /**
+     * Size in pixels to make the loading animation (square)
+     *
+     * @default 20
+     */
+    size?: number;
+};
+
+export const Loading = ({ className, 'data-testid': dataTestId = 'loading-animation', size = 20 }: Props) => (
+    <div>
+        <div
+            aria-label="Loading Animation"
+            className={cn('relative inline-block text-icon-secondary', className)}
+            data-hui-id="Loading"
+            data-testid={dataTestId}
+            style={{ height: `${size}px`, width: `${size}px` }}
+        >
+            <LoadingDot
+                delay="-0.32s"
+                left={20}
+            />
+            <LoadingDot
+                delay="-0.16s"
+                left={50}
+            />
+            <LoadingDot
+                delay="0s"
+                left={80}
+            />
+        </div>
+    </div>
+);

package/src/Loading/components/LoadingDot/LoadingDot.tsx

@@ -0,0 +1,16 @@
+type Props = {
+    delay: string;
+    left: number;
+};
+
+export const LoadingDot = ({ delay = '-0.32s', left = 20 }: Props) => {
+    return (
+        <div
+            className="absolute top-[35%] h-1/3 w-1/3 animate-loading rounded-full bg-current"
+            style={{
+                animationDelay: delay,
+                left: `${left}%`,
+            }}
+        />
+    );
+};

package/src/LoadingSpinner/LoadingSpinner.tsx

@@ -0,0 +1,20 @@
+import { ComponentProps } from 'react';
+
+import { SpinnerGap } from '../Icons';
+
+export const LoadingSpinner = ({ className, color = 'inverse', size, ...rest }: ComponentProps<typeof SpinnerGap>) => {
+    return (
+        <span className={className}>
+            <SpinnerGap
+                className="animate-spin"
+                color={color}
+                data-testid="loading-spinner-animation"
+                size={size}
+                style="bold"
+                {...rest}
+            />
+        </span>
+    );
+};
+
+LoadingSpinner.displayName = 'LoadingSpinner';