@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/mixins/propMixins.ts

@@ -0,0 +1,389 @@
+import type { CleanTheme, Theme } from '@evolve.ui/theme-system/themes/themeType';
+
+import { cn } from '@evolve.ui/theme-system';
+import { spacing } from '@evolve.ui/theme-system/themes/common';
+
+export type LocationProp = { $gridLocation?: string };
+
+export type LineClampProp = { $lineClamp?: number };
+
+export type PaddingProps = {
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     *
+     * If it matches a key in the spacing scale, it will use the corresponding Tailwind token.
+     * IE if set to `sm` it would produce `p-sm`.
+     *
+     * If it matches multiple keys separated by `+` or `-`, it will compute the result and
+     * emit a Tailwind arbitrary value. IE `sm+md` -> `[padding:40px]`.
+     *
+     * Otherwise, it will emit a Tailwind arbitrary value directly. IE `auto 3px` -> `[padding:auto_3px]`.
+     */
+    $padding?: string;
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     */
+    $paddingBottom?: string;
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     */
+    $paddingLeft?: string;
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     */
+    $paddingRight?: string;
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     */
+    $paddingTop?: string;
+};
+
+export type MarginProps = {
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     */
+    $margin?: string;
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     */
+    $marginBottom?: string;
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     */
+    $marginLeft?: string;
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     */
+    $marginRight?: string;
+    /**
+     * String used for formatting.
+     *
+     * Quick reference (px): `xxxs(2)` `xxs(4)` `xs(8)` `sm(16)` `md(24)` `lg(32)` `xl(48)` `xxl(64)` `xxxl(128)`
+     */
+    $marginTop?: string;
+};
+
+type ThemeSpacings = keyof Theme['spacing'];
+export type SimplifiedThemeSpacings = Extract<
+    ThemeSpacings,
+    'lg' | 'md' | 'sm' | 'xl' | 'xs' | 'xxl' | 'xxs' | 'xxxl' | 'xxxs'
+>;
+
+const themeKeys: SimplifiedThemeSpacings[] = ['xxxl', 'xxl', 'xl', 'lg', 'md', 'sm', 'xs', 'xxs', 'xxxs'];
+
+/**
+ * Maps theme spacing key names to their Tailwind token equivalents.
+ * There is no shared source for this mapping because the runtime theme has no
+ * concept of Tailwind token names.
+ */
+const SPACING_TO_TAILWIND: Record<SimplifiedThemeSpacings, string> = {
+    lg: 'lg',
+    md: 'md',
+    sm: 'sm',
+    xl: 'xl',
+    xs: 'xs',
+    xxl: '2xl',
+    xxs: '2xs',
+    xxxl: '3xl',
+    xxxs: '3xs',
+};
+
+/**
+ * Static Tailwind tokens used by `getMixinClasses` for named spacing values.
+ * Keep these literal strings in source so Tailwind content scanning can include
+ * the named mixin classes in production CSS.
+ */
+export const MIXIN_TAILWIND_STATIC_CLASSES = [
+    'p-3xl',
+    'p-2xl',
+    'p-xl',
+    'p-lg',
+    'p-md',
+    'p-sm',
+    'p-xs',
+    'p-2xs',
+    'p-3xs',
+    'pb-3xl',
+    'pb-2xl',
+    'pb-xl',
+    'pb-lg',
+    'pb-md',
+    'pb-sm',
+    'pb-xs',
+    'pb-2xs',
+    'pb-3xs',
+    'pl-3xl',
+    'pl-2xl',
+    'pl-xl',
+    'pl-lg',
+    'pl-md',
+    'pl-sm',
+    'pl-xs',
+    'pl-2xs',
+    'pl-3xs',
+    'pr-3xl',
+    'pr-2xl',
+    'pr-xl',
+    'pr-lg',
+    'pr-md',
+    'pr-sm',
+    'pr-xs',
+    'pr-2xs',
+    'pr-3xs',
+    'pt-3xl',
+    'pt-2xl',
+    'pt-xl',
+    'pt-lg',
+    'pt-md',
+    'pt-sm',
+    'pt-xs',
+    'pt-2xs',
+    'pt-3xs',
+    'm-3xl',
+    'm-2xl',
+    'm-xl',
+    'm-lg',
+    'm-md',
+    'm-sm',
+    'm-xs',
+    'm-2xs',
+    'm-3xs',
+    'mb-3xl',
+    'mb-2xl',
+    'mb-xl',
+    'mb-lg',
+    'mb-md',
+    'mb-sm',
+    'mb-xs',
+    'mb-2xs',
+    'mb-3xs',
+    'ml-3xl',
+    'ml-2xl',
+    'ml-xl',
+    'ml-lg',
+    'ml-md',
+    'ml-sm',
+    'ml-xs',
+    'ml-2xs',
+    'ml-3xs',
+    'mr-3xl',
+    'mr-2xl',
+    'mr-xl',
+    'mr-lg',
+    'mr-md',
+    'mr-sm',
+    'mr-xs',
+    'mr-2xs',
+    'mr-3xs',
+    'mt-3xl',
+    'mt-2xl',
+    'mt-xl',
+    'mt-lg',
+    'mt-md',
+    'mt-sm',
+    'mt-xs',
+    'mt-2xs',
+    'mt-3xs',
+    'line-clamp-1',
+    'line-clamp-2',
+    'line-clamp-3',
+    'line-clamp-4',
+    'line-clamp-5',
+    'line-clamp-6',
+] as const;
+
+const SPACING_PX: Record<SimplifiedThemeSpacings, number> = {
+    lg: spacing.lgValue,
+    md: spacing.mdValue,
+    sm: spacing.smValue,
+    xl: spacing.xlValue,
+    xs: spacing.xsValue,
+    xxl: spacing.xxlValue,
+    xxs: spacing.xxsValue,
+    xxxl: spacing.xxxlValue,
+    xxxs: spacing.xxxsValue,
+};
+
+const splitRegex = /([+-])/;
+
+const isThemeSpacing = (value: string): value is SimplifiedThemeSpacings =>
+    themeKeys.includes(value as SimplifiedThemeSpacings);
+
+const resolveArithmeticSpacing = (styles: string): string => {
+    const trimmedFirst = styles.trim();
+
+    if (isThemeSpacing(trimmedFirst)) {
+        return `${SPACING_PX[trimmedFirst]}px`;
+    }
+
+    const splitStyles = styles.split(splitRegex);
+    if (splitStyles.length <= 1) {
+        return styles;
+    }
+
+    const trimmedFirstValue = splitStyles[0].trim();
+    if (!isThemeSpacing(trimmedFirstValue)) {
+        return styles;
+    }
+
+    let acc = SPACING_PX[trimmedFirstValue];
+
+    for (let i = 2; i < splitStyles.length; i += 2) {
+        const trimmedValue = splitStyles[i].trim();
+        if (!isThemeSpacing(trimmedValue)) {
+            return styles;
+        }
+
+        if (splitStyles[i - 1] === '+') {
+            acc += SPACING_PX[trimmedValue];
+        } else {
+            acc -= SPACING_PX[trimmedValue];
+        }
+    }
+
+    return `${acc}px`;
+};
+
+/**
+ * Converts a spacing prop value to a Tailwind class.
+ *
+ * - Named key (`sm`, `md`, etc.) -> `{twShorthand}-{tailwindToken}` (e.g. `p-sm`, `mt-2xl`)
+ * - Arithmetic (`sm+md`) -> resolved pixel value as a Tailwind arbitrary class (e.g. `[padding:40px]`)
+ * - Arbitrary (`auto 3px`, `calc(10vw + 3px)`) -> Tailwind arbitrary class with spaces escaped to `_`
+ */
+const spacingToClass = (twShorthand: string, cssProp: string, value: string): string => {
+    const trimmed = value.trim();
+
+    if (isThemeSpacing(trimmed)) {
+        return `${twShorthand}-${SPACING_TO_TAILWIND[trimmed]}`;
+    }
+
+    const resolved = resolveArithmeticSpacing(trimmed);
+    const escaped = resolved.replace(/\s+/g, '_');
+    return `[${cssProp}:${escaped}]`;
+};
+
+/**
+ * Converts `GenericCSSMixinProps` to a Tailwind class string using `cn()`.
+ *
+ * Use this in place of the removed `genericCSSMixins` CSS-in-JS template to apply
+ * spacing, grid-area, and line-clamp props in plain components.
+ */
+export const getMixinClasses = ({
+    $gridLocation,
+    $lineClamp,
+    $margin,
+    $marginBottom,
+    $marginLeft,
+    $marginRight,
+    $marginTop,
+    $padding,
+    $paddingBottom,
+    $paddingLeft,
+    $paddingRight,
+    $paddingTop,
+}: GenericCSSMixinProps): string =>
+    cn(
+        $padding && $padding.length > 0 && spacingToClass('p', 'padding', $padding),
+        $paddingBottom && $paddingBottom.length > 0 && spacingToClass('pb', 'padding-bottom', $paddingBottom),
+        $paddingLeft && $paddingLeft.length > 0 && spacingToClass('pl', 'padding-left', $paddingLeft),
+        $paddingRight && $paddingRight.length > 0 && spacingToClass('pr', 'padding-right', $paddingRight),
+        $paddingTop && $paddingTop.length > 0 && spacingToClass('pt', 'padding-top', $paddingTop),
+        $margin && $margin.length > 0 && spacingToClass('m', 'margin', $margin),
+        $marginBottom && $marginBottom.length > 0 && spacingToClass('mb', 'margin-bottom', $marginBottom),
+        $marginLeft && $marginLeft.length > 0 && spacingToClass('ml', 'margin-left', $marginLeft),
+        $marginRight && $marginRight.length > 0 && spacingToClass('mr', 'margin-right', $marginRight),
+        $marginTop && $marginTop.length > 0 && spacingToClass('mt', 'margin-top', $marginTop),
+        $gridLocation && `[grid-area:${$gridLocation}]`,
+        $lineClamp !== undefined && `line-clamp-${$lineClamp}`
+    );
+
+export type GenericCSSMixinProps = LocationProp & PaddingProps & MarginProps & LineClampProp;
+
+/**
+ * @deprecated Use `getMixinClasses` with `cn()` in plain components instead.
+ *
+ * Kept for type-level reference only. Consumers using CSS-in-JS template mixins
+ * should migrate to `cn(getMixinClasses(props), ...)` in a non-styled component.
+ */
+export const genericCSSMixins = '';
+
+/**
+ * @deprecated Use `getMixinClasses` with `cn()` in plain components instead.
+ * @see genericCSSMixins
+ */
+export const paddingMixin = '';
+
+/**
+ * @deprecated Use `getMixinClasses` with `cn()` in plain components instead.
+ * @see genericCSSMixins
+ */
+export const marginMixin = '';
+
+/**
+ * @deprecated Use `getMixinClasses` with `cn()` in plain components instead.
+ * @see genericCSSMixins
+ */
+export const locationMixin = '';
+
+/**
+ * @deprecated Use `getMixinClasses` with `cn()` in plain components instead.
+ * @see genericCSSMixins
+ */
+export const lineClampMixin = '';
+
+/**
+ * Parses a spacing prop string against a theme spacing object.
+ *
+ * @deprecated Prefer `getMixinClasses` for Tailwind-based components.
+ * Kept for backward compatibility where a theme spacing object is available.
+ */
+export const themeSpacingParser = (themeSpacing: CleanTheme['spacing'], styles: string): string => {
+    if (isThemeSpacing(styles)) {
+        return themeSpacing[styles];
+    }
+
+    const splitStyles = styles.split(splitRegex);
+    if (splitStyles.length > 1) {
+        const trimmedFirstValue = splitStyles[0].trim();
+        if (!isThemeSpacing(trimmedFirstValue)) {
+            return styles;
+        }
+
+        let acc = themeSpacing[`${trimmedFirstValue}Value`];
+        for (let i = 2; i < splitStyles.length; i += 2) {
+            const trimmedValue = splitStyles[i].trim();
+            if (!isThemeSpacing(trimmedValue)) {
+                return styles;
+            }
+
+            if (splitStyles[i - 1] === '+') {
+                acc += themeSpacing[`${trimmedValue}Value`];
+            } else {
+                acc -= themeSpacing[`${trimmedValue}Value`];
+            }
+        }
+
+        return `${acc}px`;
+    }
+
+    return styles;
+};

package/src/providers/createContextProvider.ts

@@ -0,0 +1,22 @@
+import { createContext, useContext } from 'react';
+
+export const createContextProvider = <T>(defaultValue: T, contextName: string) => {
+    const Context = createContext<T>(defaultValue);
+    Context.displayName = contextName;
+
+    const useContextHook = () => {
+        const context = useContext(Context);
+
+        if (!context) {
+            throw new Error(`use${contextName}Context must be used within ${contextName}Provider`);
+        }
+
+        return context;
+    };
+
+    return {
+        Context,
+        Provider: Context.Provider,
+        useContext: useContextHook,
+    };
+};

package/src/providers/designSystemProvider.tsx

@@ -0,0 +1,218 @@
+import { type CleanTheme } from '@evolve.ui/theme-system/themes/themeType';
+import { Provider } from 'jotai';
+import { type ComponentProps, type ErrorInfo, type ReactNode, StrictMode } from 'react';
+
+import { GridHighlighter } from '../grid/gridHighlighter';
+import { nodeEnv } from '../utils/nodeEnv';
+import { type ErrorBoundaryMeta, ErrorBoundaryProvider } from './errorBoundaryProvider';
+import { FeatureFlagProvider, type FeatureFlags } from './featureFlagProvider';
+import { LinkProvider } from './linkProvider';
+import { GlobalNormalize, LocalNormalize } from './normalize';
+import { DatePickerTarget } from './targets/DatePickerTarget';
+import { ModalTarget } from './targets/ModalTarget';
+import { TimePickerTarget } from './targets/TimePickerTarget';
+import { ThemeProvider } from './themeContext';
+import { WindowSizeProvider } from './windowSizeProvider';
+
+type DesignSystemProviderProps = {
+    children: ReactNode;
+    /**
+     * Optional default fallback UI for all ErrorBoundaries.
+     * Individual ErrorBoundaries can override this with their own `fallback` prop.
+     */
+    defaultFallback?: (error: Error, resetError: () => void) => ReactNode;
+    /**
+     * Feature flags object with string keys and boolean values.
+     * Can be accessed via `useFeatureFlagsContext`.
+     */
+    featureFlags?: FeatureFlags;
+    /**
+     * Where to apply the normalization, either globally or to this provider subtree.
+     * Global normalization is preferred; scoped normalization helps when integrating into an existing reset.
+     */
+    normalizationType?: 'global' | 'scoped';
+    /**
+     * Adds an `ErrorBoundaryProvider` when passed.
+     * The consuming app should handle the error, such as logging, redirecting, or showing a toast.
+     */
+    onError?: (error: Error, errorInfo?: ErrorInfo, meta?: ErrorBoundaryMeta) => void;
+    /**
+     * Adds a `LinkProvider` when passed and can be overridden by a more specific provider.
+     */
+    onLinkClick?: (href: string) => void;
+    /**
+     * Runtime theme object supplied by `@evolve.ui/theme-system`.
+     * This installs the local `ThemeProvider` unless `withoutThemeProvider` is true.
+     */
+    theme?: CleanTheme;
+    /**
+     * Whether to remove DatePickerTarget from the DOM. You will need to provide it manually.
+     */
+    withoutDatePickerTarget?: boolean;
+    /**
+     * Disable the grid highlighter.
+     */
+    withoutHighlighter?: boolean;
+    /**
+     * Whether to disable the `jotai` `Provider`. You will need to provide it manually.
+     */
+    withoutJotaiProvider?: boolean;
+    /**
+     * Whether to remove ModalTarget from the DOM. You will need to provide it manually.
+     */
+    withoutModalTarget?: boolean;
+    /**
+     * Disable normalization CSS.
+     */
+    withoutNormalization?: boolean;
+    /**
+     * Skips the React context ThemeProvider.
+     * This repo does not install styled-components' ThemeProvider.
+     */
+    withoutThemeProvider?: boolean;
+    /**
+     * Whether to remove TimePickerTarget from the DOM. You will need to provide it manually.
+     */
+    withoutTimePickerTarget?: boolean;
+    /**
+     * Whether to disable the `WindowSizeProvider`. You will need to provide it manually.
+     */
+    withoutWindowSizeProvider?: boolean;
+};
+
+type Props = DesignSystemProviderProps &
+    Partial<ComponentProps<typeof WindowSizeProvider>> &
+    Partial<ComponentProps<typeof GridHighlighter>>;
+
+/**
+ * Root design-system provider runtime.
+ *
+ * Features:
+ * - Runtime theme context
+ * - Normalization
+ * - Window and grid sizing
+ * - Grid highlighter
+ * - Error boundary provider
+ * - React.StrictMode when not testing
+ */
+export const DesignSystemProvider = ({
+    children,
+    defaultFallback,
+    defaultHeight,
+    defaultWidth,
+    featureFlags = {},
+    forceGridHighlight,
+    normalizationType = 'global',
+    onError,
+    onLinkClick,
+    theme,
+    windowSizeThrottle,
+    withoutDatePickerTarget = nodeEnv === 'test',
+    withoutHighlighter,
+    withoutJotaiProvider,
+    withoutModalTarget = nodeEnv === 'test',
+    withoutNormalization,
+    withoutThemeProvider,
+    withoutTimePickerTarget = nodeEnv === 'test',
+    withoutWindowSizeProvider,
+}: Props) => {
+    let newChildren = children;
+
+    if (nodeEnv !== 'test') {
+        newChildren = <StrictMode>{newChildren}</StrictMode>;
+    }
+
+    newChildren = <FeatureFlagProvider featureFlags={featureFlags}>{newChildren}</FeatureFlagProvider>;
+
+    if (!withoutNormalization && normalizationType === 'scoped') {
+        newChildren = <LocalNormalize>{newChildren}</LocalNormalize>;
+    }
+
+    if (!withoutHighlighter) {
+        newChildren = (
+            <>
+                <GridHighlighter forceGridHighlight={forceGridHighlight} />
+                {newChildren}
+            </>
+        );
+    }
+
+    if (!withoutWindowSizeProvider) {
+        newChildren = (
+            <WindowSizeProvider
+                defaultHeight={defaultHeight}
+                defaultWidth={defaultWidth}
+                windowSizeThrottle={windowSizeThrottle}
+            >
+                {newChildren}
+            </WindowSizeProvider>
+        );
+    }
+
+    if (!withoutNormalization && normalizationType === 'global') {
+        newChildren = (
+            <>
+                <GlobalNormalize />
+                {newChildren}
+            </>
+        );
+    }
+
+    if (!withoutModalTarget) {
+        newChildren = (
+            <>
+                <ModalTarget />
+                {newChildren}
+            </>
+        );
+    }
+
+    if (!withoutDatePickerTarget) {
+        newChildren = (
+            <>
+                <DatePickerTarget />
+                {newChildren}
+            </>
+        );
+    }
+
+    if (!withoutTimePickerTarget) {
+        newChildren = (
+            <>
+                <TimePickerTarget />
+                {newChildren}
+            </>
+        );
+    }
+
+    if (theme && !withoutThemeProvider) {
+        newChildren = <ThemeProvider value={theme}>{newChildren}</ThemeProvider>;
+    }
+
+    if (onLinkClick) {
+        newChildren = <LinkProvider onLinkClick={onLinkClick}>{newChildren}</LinkProvider>;
+    }
+
+    if (onError) {
+        newChildren = (
+            <ErrorBoundaryProvider
+                defaultFallback={defaultFallback}
+                onError={onError}
+            >
+                {newChildren}
+            </ErrorBoundaryProvider>
+        );
+    }
+
+    // Jotai provider should likely always be last so all atom consumers share the same store.
+    if (!withoutJotaiProvider) {
+        newChildren = <Provider>{newChildren}</Provider>;
+    }
+
+    return <>{newChildren}</>;
+};
+
+DesignSystemProvider.displayName = 'DesignSystemProvider';
+
+/** @deprecated Renamed to `DesignSystemProvider`. This alias ships for one major and is removed in a future release. */
+export const HammerUIProvider = DesignSystemProvider;