@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/FavoriteButton/types/favoriteButton.ts

@@ -0,0 +1,87 @@
+import { ButtonHTMLAttributes, ComponentProps } from 'react';
+
+import { Tooltip } from '../../Tooltip/Tooltip';
+
+/**
+ * Available variants for the FavoriteButton component
+ * - `circle`: Shows only the heart icon in a circular button (default)
+ * - `square`: Shows only the heart icon in a square button
+ * - `labeled`: Shows a button with text and the heart icon
+ * - `labeled-animated`: Labeled variant with animation-ready DOM hooks
+ */
+export type FavoriteButtonVariant = 'circle' | 'square' | 'labeled' | 'labeled-animated';
+
+/**
+ * Base props shared by all FavoriteButton variants
+ */
+export interface BaseFavoriteButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+    favorited?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+}
+
+/**
+ * Props specific to the labeled variant
+ */
+export type LabeledFavoriteButtonProps = BaseFavoriteButtonProps & {
+    /**
+     * Label text to display when favorited
+     * @default 'Saved'
+     */
+    favoritedLabel?: string;
+    /**
+     * Label text to display when not favorited
+     * @default 'Save'
+     */
+    label?: string;
+};
+
+/**
+ * Props specific to the icon-only variants (circle and square)
+ */
+export type IconOnlyFavoriteButtonProps = BaseFavoriteButtonProps & {
+    /**
+     * Shape of the button
+     */
+    shape: 'circle' | 'square';
+};
+
+/**
+ * Props for the main FavoriteButton component
+ */
+export type FavoriteButtonProps = BaseFavoriteButtonProps & {
+    /**
+     * Label text to display when favorited (only for labeled variant)
+     * @default 'Saved'
+     */
+    favoritedLabel?: string;
+    /**
+     * When true, fires the save-click animation (pulse + heart pop).
+     * Only meaningful for the `labeled-animated` variant.
+     * Reset to false after ~500ms to re-arm.
+     */
+    isActivating?: boolean;
+    /**
+     * When true, fires the nudge animation (wiggle + twirl + shimmer).
+     * Only meaningful for the `labeled-animated` variant.
+     * Reset to false after ~1300ms to re-arm.
+     */
+    isWiggling?: boolean;
+    /**
+     * Label text to display when not favorited (only for labeled variant)
+     * @default 'Save'
+     */
+    label?: string;
+    tooltipProps?: ComponentProps<typeof Tooltip> & {
+        enabled?: boolean;
+    };
+    /**
+     * Button variant.
+     * - `circle`: Shows only the heart icon in a circular button (default)
+     * - `square`: Shows only the heart icon in a square button
+     * - `labeled`: Shows a button with text and the heart icon
+     * - `labeled-animated`: Shows a labeled button with animation-ready wrappers
+     *
+     * @default 'circle'
+     */
+    variant?: FavoriteButtonVariant;
+};

package/src/FeatureFlags/devTools/FeatureFlagDevToolsUI.tsx

@@ -0,0 +1,226 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useCallback, useState } from 'react';
+
+import { Button } from '../../Button/Button';
+import { Callout } from '../../Callout/Callout';
+import { ToggleSwitch } from '../../ToggleSwitch/ToggleSwitch';
+import { BodyPrimary, H2 } from '../../Typography/Text/Text';
+import { useFeatureFlags } from '../hooks/useFeatureFlags';
+import {
+    getFeatureFlagOverrides,
+    getFeatureFlagValueSource,
+    removeFeatureFlagOverride,
+    setFeatureFlagOverride,
+} from './utils/cookies';
+
+/**
+ * Props for FeatureFlagDevToolsUI component
+ */
+type Props = {
+    /** Additional CSS classes to apply to the component */
+    className?: string;
+    /** URL of your feature-flag service's management console. When provided, a "Manage Feature Flags" button is rendered. */
+    manageFlagsUrl?: string;
+};
+
+/**
+ * DevTool component for managing feature flag overrides via cookies
+ *
+ * This component displays all feature flags from the HammerUI provider and allows
+ * developers to locally override flag values using browser cookies for testing purposes.
+ *
+ * Features:
+ * - Displays all feature flags from your feature-flag service with their current values
+ * - Toggle switches to enable/disable flags locally via cookie overrides
+ * - Shows the source of each flag value (Remote, Cookie Override, or Default)
+ * - Remove button to clear cookie overrides and revert to remote values
+ * - Warning callout when changes require a page reload
+ * - Optional link to manage flags in your feature-flag service
+ *
+ * @example
+ * ```tsx
+ * <FeatureFlagDevToolsUI />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <FeatureFlagDevToolsUI className="max-w-full" manageFlagsUrl="https://flags.example.com" />
+ * ```
+ */
+export const FeatureFlagDevToolsUI = ({ className, manageFlagsUrl }: Props = {}) => {
+    // Get all feature flags from the HammerUI provider context
+    const featureFlagsObject = useFeatureFlags();
+    const featureFlags = Object.entries(featureFlagsObject) as Array<[string, boolean | undefined]>;
+
+    // State for forcing component re-render when overrides change
+    const [, setOverrideVersion] = useState(0);
+    const flagKeys = featureFlags.map(([key]) => key);
+
+    // Get current cookie overrides for all flags
+    const overrides = getFeatureFlagOverrides(flagKeys);
+
+    // Track if there are unsaved changes that require a page reload
+    const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
+
+    /**
+     * Forces component to re-render by incrementing version state
+     * Used after setting/removing cookie overrides to reflect changes in UI
+     */
+    const forceRefresh = useCallback(() => {
+        setOverrideVersion((v) => v + 1);
+    }, []);
+
+    /**
+     * Handles toggle switch changes - sets a cookie override for the flag
+     * Note: Page reload is required for the override to take effect in the app
+     */
+    const handleToggleChange = useCallback(
+        (key: string, toggled: boolean) => {
+            setFeatureFlagOverride(key, toggled);
+            setHasUnsavedChanges(true);
+            forceRefresh();
+        },
+        [forceRefresh]
+    );
+
+    /**
+     * Removes a cookie override, reverting the flag to its remote value
+     * Note: Page reload is required for the change to take effect in the app
+     */
+    const handleRemoveOverride = useCallback(
+        (key: string) => {
+            removeFeatureFlagOverride(key);
+            setHasUnsavedChanges(true);
+            forceRefresh();
+        },
+        [forceRefresh]
+    );
+
+    /**
+     * Gets the effective toggle value - prioritizes cookie override over the remote value
+     * Falls back to false if no value is set
+     */
+    const getToggleValue = useCallback(
+        (key: string, currentValue: boolean | undefined): boolean => {
+            if (key in overrides) {
+                return overrides[key];
+            }
+            return currentValue ?? false;
+        },
+        [overrides]
+    );
+
+    /**
+     * Checks if a flag has a local cookie override
+     */
+    const hasOverride = useCallback(
+        (key: string): boolean => {
+            return key in overrides;
+        },
+        [overrides]
+    );
+
+    return (
+        <div className={cn('mb-2xl flex w-3/4 flex-col gap-sm mdMax:w-full', className)}>
+            <H2>Feature Flags</H2>
+
+            {/* Info callout explaining the feature flag override system */}
+            <Callout
+                message="Feature flags are pulled from your feature-flag service. You can override them locally using cookie overrides for testing. Note: You'll need to refresh the page after toggling an override for the change to take effect."
+                primaryButton={
+                    manageFlagsUrl
+                        ? {
+                              onClick: () => window.open(manageFlagsUrl, '_blank'),
+                              text: 'Manage Feature Flags',
+                          }
+                        : undefined
+                }
+                status="info"
+                title="Feature Flag Overrides"
+            />
+
+            {/* Warning callout shown when changes have been made but page hasn't been reloaded */}
+            {hasUnsavedChanges && (
+                <Callout
+                    message="Feature flag overrides have been updated. Reload the page to apply the changes."
+                    primaryButton={{
+                        onClick: () => window.location.reload(),
+                        text: 'Reload Page',
+                    }}
+                    status="warning"
+                    title="Reload Required"
+                />
+            )}
+
+            {/* Empty state - no feature flags available */}
+            {featureFlags.length === 0 ? (
+                <BodyPrimary>No feature flags available</BodyPrimary>
+            ) : (
+                // Table showing all feature flags with their values and controls
+                <table className="w-full border-collapse border border-border-secondary">
+                    <colgroup>
+                        <col />
+                        <col className="w-64" />
+                        <col className="w-56" />
+                    </colgroup>
+                    <thead>
+                        <tr>
+                            <th className="border border-border-secondary p-2 text-left">Feature Flag</th>
+                            <th className="border border-border-secondary p-2 text-left">Current Value</th>
+                            <th className="border border-border-secondary p-2 text-left">Source</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {featureFlags.map(([key, currentValue]) => {
+                            const isOverridden = hasOverride(key);
+                            const cellClassName = 'border border-border-secondary p-2';
+
+                            return (
+                                <tr
+                                    className="odd:bg-background-secondary"
+                                    key={key}
+                                >
+                                    {/* Flag name column */}
+                                    <td className={cellClassName}>
+                                        <BodyPrimary>{key}</BodyPrimary>
+                                    </td>
+
+                                    {/* Toggle switch and remove button column */}
+                                    <td className={cellClassName}>
+                                        <div className="flex items-center gap-xs">
+                                            {/* Toggle to set cookie override */}
+                                            <ToggleSwitch
+                                                aria-label={`Toggle ${key}`}
+                                                id={`toggle-${key}`}
+                                                isToggled={getToggleValue(key, currentValue)}
+                                                onToggleChange={(toggled) => handleToggleChange(key, toggled ?? false)}
+                                            />
+                                            {/* Remove button only shows when a cookie override exists */}
+                                            {isOverridden && (
+                                                <Button
+                                                    onClick={() => handleRemoveOverride(key)}
+                                                    size="sm"
+                                                    style="critical"
+                                                    variant="outlined"
+                                                >
+                                                    Remove
+                                                </Button>
+                                            )}
+                                        </div>
+                                    </td>
+
+                                    {/* Source column - shows where the value comes from */}
+                                    <td className={cellClassName}>
+                                        <BodyPrimary>
+                                            {getFeatureFlagValueSource(isOverridden, currentValue)}
+                                        </BodyPrimary>
+                                    </td>
+                                </tr>
+                            );
+                        })}
+                    </tbody>
+                </table>
+            )}
+        </div>
+    );
+};

package/src/FeatureFlags/devTools/getFeatureFlagCookieOverrides.ts

@@ -0,0 +1,30 @@
+/**
+ * Extracts feature flag cookie overrides from the request cookies
+ *
+ * Only processes cookies for flags that exist in the API payload. This allows
+ * cookie-based overrides to take precedence over values from your feature-flag service.
+ *
+ * @param featureFlagsApiPayload - Feature flags from the API response
+ * @param cookies - Cookie name-value pairs from the server request
+ * @returns Feature flag overrides found in cookies (subset of API payload flags)
+ */
+export const getFeatureFlagCookieOverrides = (
+    featureFlagsApiPayload: Record<string, boolean>,
+    cookies: Record<string, string | undefined>
+): Record<string, boolean> => {
+    const overrides: Record<string, boolean> = {};
+
+    // Iterate through all defined feature flag keys
+    Object.keys(featureFlagsApiPayload).forEach((flagKey) => {
+        const cookieValue = cookies[flagKey];
+
+        // Only include if cookie exists
+        if (cookieValue !== undefined) {
+            // Convert cookie string value to boolean
+            // Handles: 'true', '1' -> true, everything else -> false
+            overrides[flagKey] = cookieValue === 'true' || cookieValue === '1';
+        }
+    });
+
+    return overrides;
+};

package/src/FeatureFlags/devTools/utils/cookies.ts

@@ -0,0 +1,169 @@
+/**
+ * Parses document.cookie string into a key-value object
+ * Returns empty object during SSR when document is not available
+ *
+ * @returns Object mapping cookie names to their decoded values
+ */
+const parseCookies = (): Record<string, string> => {
+    // Check if we're in the browser environment
+    if (typeof document === 'undefined' || !document.cookie) {
+        return {};
+    }
+
+    return document.cookie.split('; ').reduce(
+        (acc, cookie) => {
+            const equalIndex = cookie.indexOf('=');
+            if (equalIndex === -1) {
+                return acc;
+            }
+
+            const name = cookie.substring(0, equalIndex);
+            const value = cookie.substring(equalIndex + 1);
+
+            try {
+                acc[decodeURIComponent(name.trim())] = decodeURIComponent(value.trim());
+            } catch {
+                // Skip malformed cookies that can't be decoded
+            }
+
+            return acc;
+        },
+        {} as Record<string, string>
+    );
+};
+
+/**
+ * Gets a specific cookie value by name
+ */
+const getCookie = (name: string): string | undefined => {
+    const cookies = parseCookies();
+    return cookies[name];
+};
+
+/**
+ * Sets a cookie with the specified options
+ * Does nothing during SSR when document is not available
+ */
+const setCookie = (
+    name: string,
+    value: string | boolean,
+    options: {
+        expires?: Date;
+        path?: string;
+        sameSite?: 'strict' | 'lax' | 'none';
+        secure?: boolean;
+    }
+) => {
+    // Check if we're in the browser environment
+    if (typeof document === 'undefined') {
+        return;
+    }
+
+    let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(String(value))}`;
+
+    if (options.expires) {
+        cookie += `; expires=${options.expires.toUTCString()}`;
+    }
+
+    if (options.path) {
+        cookie += `; path=${options.path}`;
+    }
+
+    if (options.sameSite) {
+        cookie += `; samesite=${options.sameSite}`;
+    }
+
+    if (options.secure) {
+        cookie += '; secure';
+    }
+
+    document.cookie = cookie;
+};
+
+/**
+ * Removes a cookie by setting its expiry to the past
+ */
+const removeCookie = (name: string, options: { path?: string }) => {
+    setCookie(name, '', {
+        ...options,
+        expires: new Date(0),
+    });
+};
+
+/**
+ * Reads cookies to find feature flag overrides
+ *
+ * Looks for cookies that match feature flag key names and returns
+ * a FeatureFlags object with the overridden values
+ *
+ * @param flagKeys - Array of flag keys to check for cookie overrides
+ * @example
+ * // If a cookie named "ff_team-1234_home-page-is-green" exists with value "true"
+ * const overrides = getFeatureFlagOverrides(['ff_team-1234_home-page-is-green']);
+ * // Returns: { 'ff_team-1234_home-page-is-green': true }
+ */
+export const getFeatureFlagOverrides = (flagKeys: string[]) => {
+    const overrides: Record<string, boolean> = {};
+
+    flagKeys.forEach((flagKey) => {
+        const cookieValue = getCookie(flagKey);
+
+        // Only include if cookie exists and has a non-empty value
+        if (cookieValue !== undefined && cookieValue !== '') {
+            // Convert cookie value to boolean
+            // Handles: 'true', 'false', true, false, 1, 0, '1', '0'
+            overrides[flagKey] = cookieValue === 'true' || cookieValue === '1';
+        }
+    });
+
+    return overrides;
+};
+
+/**
+ * Sets a feature flag override cookie
+ *
+ * @param featureFlagKey - The feature flag key to override
+ * @param value - The boolean value to set
+ *
+ * Note: Cookies are set without a domain attribute to make them specific
+ * to the current hostname
+ */
+export const setFeatureFlagOverride = (featureFlagKey: string, value: boolean) => {
+    const expires = new Date();
+    expires.setDate(expires.getDate() + 30); // 30 days expiration
+
+    setCookie(featureFlagKey, value, {
+        expires,
+        path: '/',
+        sameSite: 'lax',
+        secure: true,
+    });
+};
+
+/**
+ * Removes a feature flag override cookie
+ *
+ * @param featureFlagKey - The feature flag key to remove
+ *
+ * Note: Cookies are removed without a domain attribute since they're
+ * specific to the current hostname
+ */
+export const removeFeatureFlagOverride = (featureFlagKey: string) => {
+    removeCookie(featureFlagKey, {
+        path: '/',
+    });
+};
+
+/**
+ * Determines the source of a feature flag's value
+ *
+ * @param hasOverride - Whether the flag has a local cookie override
+ * @param currentValue - The current value from the remote feature-flag service (undefined means not set)
+ * @returns A human-readable string indicating the value source
+ */
+export const getFeatureFlagValueSource = (hasOverride: boolean, currentValue: boolean | undefined): string => {
+    if (hasOverride) {
+        return 'Cookie Override';
+    }
+    return currentValue !== undefined ? 'Remote' : 'Default (false)';
+};

package/src/FeatureFlags/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useFeatureFlag } from './useFeatureFlag';
+export { useFeatureFlags } from './useFeatureFlags';

package/src/FeatureFlags/hooks/useFeatureFlag.tsx

@@ -0,0 +1,19 @@
+import { useFeatureFlagsContext } from '../../providers/featureFlagProvider';
+
+/**
+ * Hook to check if a specific feature flag is enabled
+ * @param key - The feature flag key to check
+ * @returns `true` if the feature flag exists and is enabled, `false` otherwise
+ *
+ * @example
+ * ```tsx
+ * const isGreenHomePage = useFeatureFlag('ff_team-1234_home-page-is-green');
+ * if (isGreenHomePage) {
+ *   return <GreenHomePage />;
+ * }
+ * ```
+ */
+export const useFeatureFlag = (key: string): boolean => {
+    const featureFlags = useFeatureFlagsContext();
+    return featureFlags[key] === true;
+};

package/src/FeatureFlags/hooks/useFeatureFlags.tsx

@@ -0,0 +1,15 @@
+import { useFeatureFlagsContext } from '../../providers/featureFlagProvider';
+
+/**
+ * Hook to get all feature flags
+ * @returns The complete feature flags object passed to DesignSystemProvider
+ *
+ * @example
+ * ```tsx
+ * const featureFlags = useFeatureFlags();
+ * console.log(featureFlags); // { 'ff_team-1234_home-page-is-green': true }
+ * ```
+ */
+export const useFeatureFlags = () => {
+    return useFeatureFlagsContext();
+};

package/src/FileUpload/components/FileCard/FileCard.tsx

@@ -0,0 +1,50 @@
+import { GridFileCard } from '../GridFileCard/GridFileCard';
+import { ListFileCard } from '../ListFileCard/ListFileCard';
+import { BaseFileCardProps, BaseFileCardStyle } from '../types';
+
+export type FileCardProps = BaseFileCardProps & {
+    badge?: string;
+    cardStyle?: BaseFileCardStyle;
+    'data-testid'?: string;
+    showActionsOnHover?: boolean;
+    statusText?: string;
+};
+
+export const FileCard = ({
+    badge,
+    cardStyle = 'contained',
+    'data-testid': dataTestId,
+    errorMessage,
+    progress,
+    showActionsOnHover = false,
+    status,
+    statusIcon,
+    statusText,
+    ...props
+}: FileCardProps) =>
+    cardStyle === 'card' ? (
+        <GridFileCard
+            {...props}
+            badge={badge}
+            data-testid={dataTestId}
+            errorMessage={errorMessage}
+            progress={progress}
+            status={status}
+            statusIcon={statusIcon}
+            statusText={statusText}
+        />
+    ) : (
+        <ListFileCard
+            {...props}
+            cardStyle={cardStyle}
+            data-testid={dataTestId}
+            errorMessage={errorMessage}
+            progress={progress}
+            showActionsOnHover={showActionsOnHover}
+            status={status}
+            statusIcon={statusIcon}
+            statusText={statusText}
+        />
+    );
+
+FileCard.displayName = 'FileCard';