@evolve.ui/core-components 1.0.1 → 1.2.0

package/src/providers/errorBoundaryProvider.tsx

@@ -0,0 +1,179 @@
+import { type ErrorInfo, Component, createContext, type ReactNode, useCallback, useContext } from 'react';
+
+import { Button } from '../Button/Button';
+import { BodyPrimary, BodySecondary } from '../Typography/Text/Text';
+
+export type ErrorBoundaryMeta = {
+    /** Additional metadata properties. */
+    [key: string]: unknown;
+    /** Required name to identify the error boundary. */
+    name: string;
+};
+
+/**
+ * Callback function when an error is caught.
+ */
+type OnErrorCallback = (error: Error, errorInfo: ErrorInfo, meta: ErrorBoundaryMeta) => void;
+/**
+ * Default fallback render function.
+ */
+type DefaultFallbackFunction = (error: Error, resetError: () => void) => ReactNode;
+
+type ErrorBoundaryContextValue = {
+    defaultFallback?: DefaultFallbackFunction;
+    onError: OnErrorCallback;
+};
+
+const ErrorBoundaryContext = createContext<ErrorBoundaryContextValue | undefined>(undefined);
+
+type ErrorBoundaryProviderProps = {
+    children: ReactNode;
+    /**
+     * Optional default fallback UI to use across all ErrorBoundaries in this provider.
+     * Individual ErrorBoundaries can still override this with their own `fallback` prop.
+     */
+    defaultFallback?: DefaultFallbackFunction;
+    /** Callback when an error is caught. */
+    onError: OnErrorCallback;
+};
+
+/**
+ * Provider that powers all ErrorBoundary components below it.
+ * A global provider can be overwritten by a more specific provider for section-level handling.
+ */
+export const ErrorBoundaryProvider = ({ children, defaultFallback, onError }: ErrorBoundaryProviderProps) => (
+    <ErrorBoundaryContext.Provider value={{ defaultFallback, onError }}>{children}</ErrorBoundaryContext.Provider>
+);
+
+ErrorBoundaryProvider.displayName = 'ErrorBoundaryProvider';
+
+/**
+ * Hook to get the error callback from context.
+ */
+export const useOnError = () => {
+    const context = useContext(ErrorBoundaryContext);
+    return context?.onError;
+};
+
+/**
+ * Hook that provides a callback with resetError functionality.
+ * Useful for creating custom error UIs that need to reset the boundary.
+ */
+export const useErrorBoundaryReset = () => {
+    const onError = useOnError();
+
+    return useCallback(
+        (error: Error, errorInfo: ErrorInfo, meta: ErrorBoundaryMeta) => {
+            onError?.(error, errorInfo, meta);
+        },
+        [onError]
+    );
+};
+
+type ErrorBoundaryState = {
+    hasError: boolean;
+};
+
+type ErrorBoundaryProps = {
+    children: ReactNode;
+    /** Optional custom fallback UI to render when an error occurs. */
+    fallback?: (error: Error, resetError: () => void) => ReactNode;
+    /**
+     * Force the error boundary to throw an error for testing/demo purposes.
+     * Useful for previewing fallback UI in Storybook or tests.
+     */
+    forceError?: boolean;
+    /**
+     * Metadata to identify and provide context about this error boundary.
+     * The `name` field is required.
+     */
+    meta: ErrorBoundaryMeta;
+    /** Optional custom onError callback that overrides the context callback. */
+    onError?: OnErrorCallback;
+};
+
+/**
+ * Component that throws an error for testing/demo purposes.
+ */
+const ErrorThrower = ({ message }: { message: string }) => {
+    throw new Error(message);
+};
+
+// React error boundaries still require class components.
+/**
+ * Catches errors in children, reports them through props or provider context, then renders a fallback UI.
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    static contextType = ErrorBoundaryContext;
+
+    static getDerivedStateFromError(): ErrorBoundaryState {
+        return { hasError: true };
+    }
+
+    declare context: React.ContextType<typeof ErrorBoundaryContext>;
+    private errorCache: { error: Error; errorInfo: ErrorInfo } | null = null;
+
+    constructor(props: ErrorBoundaryProps) {
+        super(props);
+        this.state = { hasError: false };
+    }
+
+    componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+        // Cache the error for the fallback render.
+        this.errorCache = { error, errorInfo };
+        // Force a re-render now that errorCache is set.
+        this.forceUpdate();
+
+        // Call the onError callback from props or context with metadata.
+        const onError = this.props.onError || this.context?.onError;
+        onError?.(error, errorInfo, this.props.meta);
+    }
+
+    resetError = () => {
+        this.errorCache = null;
+        this.setState({ hasError: false });
+    };
+
+    render() {
+        if (this.state.hasError) {
+            // Wait for errorCache to be populated by componentDidCatch.
+            if (!this.errorCache) {
+                return null;
+            }
+
+            // Priority 1: If a custom fallback is provided on the ErrorBoundary, use it.
+            if (this.props.fallback) {
+                return this.props.fallback(this.errorCache.error, this.resetError);
+            }
+
+            // Priority 2: If a default fallback is provided by the provider, use it.
+            if (this.context?.defaultFallback) {
+                return this.context.defaultFallback(this.errorCache.error, this.resetError);
+            }
+
+            // Priority 3: Built-in default fallback.
+            return (
+                <div className="flex h-full w-full flex-col items-center justify-center gap-sm rounded-container border border-border-secondary p-md text-center">
+                    <div className="flex flex-col gap-xs">
+                        <BodyPrimary>Something went wrong</BodyPrimary>
+                        <BodySecondary color="secondary">We&apos;re working on resolving the issue</BodySecondary>
+                    </div>
+                    <Button
+                        onClick={this.resetError}
+                        size="sm"
+                        variant="outlined"
+                    >
+                        Try Again
+                    </Button>
+                </div>
+            );
+        }
+
+        // Force an error for testing/demo purposes.
+        if (this.props.forceError) {
+            return <ErrorThrower message={`Forced error in ${this.props.meta.name}`} />;
+        }
+
+        return this.props.children;
+    }
+}

package/src/providers/featureFlagProvider.tsx

@@ -0,0 +1,18 @@
+import { createContext, type ReactNode, useContext } from 'react';
+
+export type FeatureFlags = Record<string, boolean | undefined>;
+
+const FeatureFlagContext = createContext<FeatureFlags>({});
+
+type FeatureFlagProviderProps = {
+    children: ReactNode;
+    featureFlags: FeatureFlags;
+};
+
+export const FeatureFlagProvider = ({ children, featureFlags }: FeatureFlagProviderProps) => (
+    <FeatureFlagContext.Provider value={featureFlags}>{children}</FeatureFlagContext.Provider>
+);
+
+FeatureFlagProvider.displayName = 'FeatureFlagProvider';
+
+export const useFeatureFlagsContext = () => useContext(FeatureFlagContext);

package/src/providers/gridSizeProvider.tsx

@@ -0,0 +1,23 @@
+import { breakpoints } from '@evolve.ui/theme-system/themes/common';
+import { atom, useAtomValue } from 'jotai';
+
+import { mobileAtom, widthAtom } from './windowSizeProvider';
+
+const gridSizeAtom = atom<{
+    columnCount: number;
+    columnSize: number;
+    gapSize: number;
+}>((get) => {
+    const width = get(widthAtom);
+    const mobile = get(mobileAtom);
+
+    return mobile
+        ? { columnCount: 4, columnSize: (width - 16 * 5) / 4, gapSize: 16 }
+        : {
+              columnCount: 12,
+              columnSize: (Math.min(width, breakpoints.mdMaxValue) - 24 * 13) / 12,
+              gapSize: 24,
+          };
+});
+
+export const useGridSize = () => useAtomValue(gridSizeAtom);

package/src/providers/index.ts

@@ -0,0 +1,12 @@
+export * from './windowSizeProvider';
+export * from './gridSizeProvider';
+export * from './designSystemProvider';
+export * from './linkProvider';
+export * from './errorBoundaryProvider';
+export * from './featureFlagProvider';
+export * from './themeContext';
+export * from './createContextProvider';
+export * from './normalize';
+export * from './targets/ModalTarget';
+export * from './targets/DatePickerTarget';
+export * from './targets/TimePickerTarget';

package/src/providers/linkProvider.tsx

@@ -0,0 +1,32 @@
+import { createContext, type MouseEvent, type ReactNode, useCallback, useContext } from 'react';
+
+const LinkContext = createContext<(href: string) => void>(() => {
+    throw new Error(
+        'No onLinkClick found. Did you forget to add onLinkClick to DesignSystemProvider (or the separate LinkProvider)?'
+    );
+});
+
+type LinkProviderProps = {
+    children: ReactNode;
+    onLinkClick: (href: string) => void;
+};
+
+export const LinkProvider = ({ children, onLinkClick }: LinkProviderProps) => (
+    <LinkContext.Provider value={onLinkClick}>{children}</LinkContext.Provider>
+);
+
+LinkProvider.displayName = 'LinkProvider';
+
+export const useOnLinkClick = () => useContext(LinkContext);
+
+export const usePreventDefaultLinkOnClick = () => {
+    const onLinkClick = useOnLinkClick();
+
+    return useCallback(
+        (href: string) => (event: MouseEvent<HTMLAnchorElement>) => {
+            event.preventDefault();
+            onLinkClick(href);
+        },
+        [onLinkClick]
+    );
+};

package/src/providers/normalize.tsx

@@ -0,0 +1,93 @@
+import { cn } from '@evolve.ui/theme-system/cn';
+import { forwardRef, type HTMLProps, useEffect } from 'react';
+
+export const GLOBAL_NORMALIZE_CSS = `
+html {
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+}
+body {
+    margin: 0;
+}
+main {
+    display: block;
+}
+a {
+    background-color: transparent;
+}
+img {
+    border-style: none;
+}
+button,
+input,
+optgroup,
+select,
+textarea {
+    font-family: inherit;
+    font-size: 100%;
+    line-height: 1.15;
+    margin: 0;
+}
+button,
+input {
+    overflow: visible;
+}
+button,
+select {
+    text-transform: none;
+}
+button,
+[type="button"],
+[type="reset"],
+[type="submit"] {
+    -webkit-appearance: button;
+}
+button::-moz-focus-inner,
+[type="button"]::-moz-focus-inner,
+[type="reset"]::-moz-focus-inner,
+[type="submit"]::-moz-focus-inner {
+    border-style: none;
+    padding: 0;
+}
+*,
+::before,
+::after {
+    box-sizing: border-box;
+}
+`.trim();
+
+export const GlobalNormalize = () => {
+    useEffect(() => {
+        const style = document.createElement('style');
+        style.textContent = GLOBAL_NORMALIZE_CSS;
+        document.head.appendChild(style);
+
+        return () => {
+            style.remove();
+        };
+    }, []);
+
+    return null;
+};
+
+GlobalNormalize.displayName = 'GlobalNormalize';
+
+export const LocalNormalize = forwardRef<HTMLDivElement, HTMLProps<HTMLDivElement>>(
+    ({ children, className, ...rest }, ref) => (
+        <div
+            className={cn(
+                '[text-size-adjust:100%]',
+                'm-0',
+                'antialiased',
+                'box-border [&_*]:box-border [&_::after]:box-border [&_::before]:box-border',
+                className
+            )}
+            ref={ref}
+            {...rest}
+        >
+            {children}
+        </div>
+    )
+);
+
+LocalNormalize.displayName = 'LocalNormalize';

package/src/providers/targets/DatePickerTarget.tsx

@@ -0,0 +1,10 @@
+/**
+ * The place where the date picker popover is rendered using `createPortal`.
+ *
+ * DatePicker's `FloatingPortal` locates this slot via the `hui-datepicker-target` id.
+ */
+export const DatePickerTargetId = 'hui-datepicker-target';
+
+export const DatePickerTarget = () => <div id={DatePickerTargetId} />;
+
+DatePickerTarget.displayName = 'DatePickerTarget';

package/src/providers/targets/ModalTarget.tsx

@@ -0,0 +1,14 @@
+/**
+ * The place where the modal is rendered using `createPortal`.
+ *
+ * Consumers that portal into this slot (Modal, BottomSheet) locate it via the
+ * `hui-modal-target` class / id.
+ */
+export const ModalTarget = () => (
+    <div
+        className="hui-modal-target"
+        id="hui-modal-target"
+    />
+);
+
+ModalTarget.displayName = 'ModalTarget';

package/src/providers/targets/TimePickerTarget.tsx

@@ -0,0 +1,10 @@
+/**
+ * The place where the time picker popover is rendered using `createPortal`.
+ *
+ * TimePicker's `FloatingPortal` locates this slot via the `hui-timepicker-target` id.
+ */
+export const TimePickerTargetId = 'hui-timepicker-target';
+
+export const TimePickerTarget = () => <div id={TimePickerTargetId} />;
+
+TimePickerTarget.displayName = 'TimePickerTarget';

package/src/providers/themeContext.tsx

@@ -0,0 +1,24 @@
+import type { CleanTheme } from '@evolve.ui/theme-system/themes/themeType';
+
+import { createContext, useContext } from 'react';
+
+const ThemeContext = createContext<CleanTheme | undefined>(undefined);
+ThemeContext.displayName = 'ThemeContext';
+
+export const ThemeProvider = ThemeContext.Provider;
+
+export const useTheme = (): CleanTheme => {
+    const theme = useContext(ThemeContext);
+
+    if (!theme) {
+        throw new Error('useTheme must be used within DesignSystemProvider');
+    }
+
+    return theme;
+};
+
+/** @deprecated Renamed to `ThemeProvider`. This alias ships for one major and is removed in a future release. */
+export const HammerThemeProvider = ThemeProvider;
+
+/** @deprecated Renamed to `useTheme`. This alias ships for one major and is removed in a future release. */
+export const useHammerTheme = useTheme;

package/src/providers/windowSizeProvider.tsx

@@ -0,0 +1,125 @@
+import { breakpoints } from '@evolve.ui/theme-system/themes/common';
+import { atom, useAtomValue, useStore } from 'jotai';
+import { type ReactNode, useEffect, useMemo } from 'react';
+import { useThrottledCallback } from 'use-debounce';
+
+import { isClientSide } from '../utils/isClientSide';
+
+export const heightAtom = atom(isClientSide ? window.innerHeight : 0);
+// Use window.innerWidth for accurate viewport width, including the scrollbar measurement area.
+export const widthAtom = atom(isClientSide ? window.innerWidth : 0);
+
+export const desktopAtom = atom((get) => get(widthAtom) >= breakpoints.smMinValue);
+export const mobileAtom = atom((get) => get(widthAtom) <= breakpoints.xsMaxValue);
+export const tabletAtom = atom(
+    (get) => get(widthAtom) >= breakpoints.smMinValue && get(widthAtom) <= breakpoints.smMaxValue
+);
+export const tabletOrMobileAtom = atom((get) => get(widthAtom) <= breakpoints.smMaxValue);
+
+type WindowSizeProviderProps = {
+    children: ReactNode;
+    /**
+     * Only applies to first render. Useful for SSR when the screen height is known.
+     *
+     * @default window.innerHeight ?? 0
+     */
+    defaultHeight?: number;
+    /**
+     * Only applies to first render. Useful for SSR when the screen width is known.
+     *
+     * @default window.innerWidth ?? 0
+     */
+    defaultWidth?: number;
+    /**
+     * How often to refresh window size while resizing.
+     *
+     * Set this to milliseconds to wait, or `0` for per-animation-frame updates.
+     */
+    windowSizeThrottle?: number;
+};
+
+export const WindowSizeProvider = ({
+    children,
+    defaultHeight: givenDefaultHeight,
+    defaultWidth: givenDefaultWidth,
+    windowSizeThrottle = 0,
+}: WindowSizeProviderProps) => {
+    const store = useStore();
+
+    useMemo(() => {
+        if (!isClientSide) {
+            // SSR: use provided defaults when available.
+            if (givenDefaultHeight) {
+                store.set(heightAtom, givenDefaultHeight);
+            }
+            if (givenDefaultWidth) {
+                store.set(widthAtom, givenDefaultWidth);
+            }
+            return;
+        }
+
+        // Client-side: use provided defaults only when the browser reports zero.
+        const initialHeight = window.innerHeight === 0 && givenDefaultHeight ? givenDefaultHeight : window.innerHeight;
+        const initialWidth = window.innerWidth === 0 && givenDefaultWidth ? givenDefaultWidth : window.innerWidth;
+
+        if (initialHeight !== 0 && store.get(heightAtom) !== initialHeight) {
+            store.set(heightAtom, initialHeight);
+        }
+        if (initialWidth !== 0 && store.get(widthAtom) !== initialWidth) {
+            store.set(widthAtom, initialWidth);
+        }
+        // No need to rerender since we only want to allow initial values.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    useEffect(() => {
+        if (!isClientSide) {
+            return;
+        }
+
+        // Update from window if different and not using defaults.
+        const currentHeight = window.innerHeight === 0 && givenDefaultHeight ? givenDefaultHeight : window.innerHeight;
+        const currentWidth = window.innerWidth === 0 && givenDefaultWidth ? givenDefaultWidth : window.innerWidth;
+
+        if (store.get(heightAtom) !== currentHeight && currentHeight !== 0) {
+            store.set(heightAtom, currentHeight);
+        }
+        if (store.get(widthAtom) !== currentWidth && currentWidth !== 0) {
+            store.set(widthAtom, currentWidth);
+        }
+    }, [givenDefaultHeight, givenDefaultWidth, store]);
+
+    const handleResize = useThrottledCallback(
+        () => {
+            store.set(heightAtom, window.innerHeight);
+            store.set(widthAtom, window.innerWidth);
+        },
+        windowSizeThrottle,
+        { trailing: true }
+    );
+
+    useEffect(() => {
+        if (!isClientSide) {
+            return;
+        }
+
+        window.addEventListener('resize', handleResize);
+        window.addEventListener('orientationchange', handleResize);
+
+        return () => {
+            window.removeEventListener('resize', handleResize);
+            window.removeEventListener('orientationchange', handleResize);
+        };
+    }, [handleResize]);
+
+    return children;
+};
+
+WindowSizeProvider.displayName = 'WindowSizeProvider';
+
+export const useWindowIsDesktop = () => useAtomValue(desktopAtom);
+export const useWindowIsMobile = () => useAtomValue(mobileAtom);
+export const useWindowIsTablet = () => useAtomValue(tabletAtom);
+export const useWindowIsTabletOrMobile = () => useAtomValue(tabletOrMobileAtom);
+export const useWindowHeight = () => useAtomValue(heightAtom);
+export const useWindowWidth = () => useAtomValue(widthAtom);

package/src/spacing/index.ts

@@ -0,0 +1 @@
+export { LG, MD, SM, XL, XS, XXL, XXS, XXXL, XXXS } from './spacing';

package/src/spacing/spacing.ts

@@ -0,0 +1,11 @@
+import { spacing as themeSpacing } from '@evolve.ui/theme-system/themes/common';
+
+export const XXXS = themeSpacing.xxxs;
+export const XXS = themeSpacing.xxs;
+export const XS = themeSpacing.xs;
+export const SM = themeSpacing.sm;
+export const MD = themeSpacing.md;
+export const LG = themeSpacing.lg;
+export const XL = themeSpacing.xl;
+export const XXL = themeSpacing.xxl;
+export const XXXL = themeSpacing.xxxl;