@ionic/core 8.8.7-dev.11779467048.1641d05e → 8.8.7-dev.11779921691.1777274a

package/dist/collection/utils/theme.js

@@ -1,6 +1,22 @@
 /*!
  * (C) Ionic http://ionicframework.com - MIT License
  */
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s)
+        if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+            t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { printIonWarning } from "./logging/index";
+import { deepMerge } from "./helpers";
+export const CSS_PROPS_PREFIX = '--ion-';
+export const CSS_ROOT_SELECTOR = ':root';
 /**
  * Checks if an element has a parent matching the specified selector.
  * This handles an element in both light DOM and shadow DOM contexts.
@@ -50,16 +66,602 @@ export const getClassMap = (classes) => {
     getClassList(classes).forEach((c) => (map[c] = true));
     return map;
 };
-const SCHEME = /^[a-z][a-z0-9+\-.]*:/;
-export const openURL = async (url, ev, direction, animation) => {
-    if (url != null && url[0] !== '#' && !SCHEME.test(url)) {
-        const router = document.querySelector('ion-router');
-        if (router) {
-            if (ev != null) {
-                ev.preventDefault();
+/**
+ * Gets and merges custom themes based on mode
+ * @param customTheme The custom theme
+ * @param mode The current mode (ios | md)
+ * @returns The merged custom theme
+ */
+export const getCustomTheme = (customTheme, mode) => {
+    if (!customTheme)
+        return undefined;
+    // Check if the custom theme contains mode overrides (ios | md)
+    if (customTheme.ios || customTheme.md) {
+        const { ios, md } = customTheme, baseCustomTheme = __rest(customTheme, ["ios", "md"]);
+        // Flatten the mode-specific overrides based on current mode
+        if (mode === 'ios' && ios) {
+            return deepMerge(baseCustomTheme, ios);
+        }
+        else if (mode === 'md' && md) {
+            return deepMerge(baseCustomTheme, md);
+        }
+        return baseCustomTheme;
+    }
+    return customTheme;
+};
+/**
+ * Flattens the theme object into CSS custom properties
+ * @param theme The theme object to flatten
+ * @param prefix The CSS prefix to use (e.g., '--ion-')
+ * @returns CSS string with custom properties
+ */
+export const generateCSSVars = (theme, prefix = CSS_PROPS_PREFIX) => {
+    // Logs do not need to be printed because palette objects are optional
+    const themeValidity = isValidTheme(theme, 'generateCSSVars', false);
+    if (!themeValidity) {
+        return undefined;
+    }
+    const cssProps = Object.entries(theme)
+        .flatMap(([key, val]) => {
+        var _a, _b, _c, _d, _e, _f;
+        // Skip invalid keys or values
+        if (!key || typeof key !== 'string' || val === null || val === undefined) {
+            return [];
+        }
+        key = convertToKebabCase(key);
+        // Do not generate CSS variables for excluded keys
+        const excludedKeys = ['name', 'enabled', 'config'];
+        if (excludedKeys.includes(key)) {
+            return [];
+        }
+        // Special handling for 'base' property - don't add suffix
+        if (key === 'base') {
+            return [`${prefix.slice(0, -1)}: ${val};`];
+        }
+        // Generate rgb variables for base and contrast color variants
+        // These are only generated when processing global color objects,
+        // not component-level color overrides
+        // TODO(): this only works with hex values
+        if ((key === 'bold' || key === 'subtle') && prefix.includes('color')) {
+            if (typeof val === 'object' && val !== null) {
+                return Object.entries(val).flatMap(([property, hexValue]) => {
+                    if (typeof hexValue === 'string' && hexValue.startsWith('#')) {
+                        // For 'base' property, don't include the property name in the CSS variable
+                        const varName = property === 'base' ? `${prefix}${key}` : `${prefix}${key}-${property}`;
+                        const cssVars = [`${varName}: ${hexValue};`];
+                        // Only add RGB values for base and contrast
+                        if (property === 'base' || property === 'contrast') {
+                            const rgbVarName = property === 'base' ? `${prefix}${key}-rgb` : `${prefix}${key}-${property}-rgb`;
+                            cssVars.push(`${rgbVarName}: ${hexToRgb(hexValue)};`);
+                        }
+                        return cssVars;
+                    }
+                    return [];
+                });
             }
-            return router.push(url, direction, animation);
         }
+        // If it's a font-sizes key, create rem version
+        // This is necessary to support the dynamic font size feature
+        if (key === 'font-sizes' && typeof val === 'object' && val !== null) {
+            // Access the root font size from the global theme context
+            const fontSizeBase = parseFloat((_f = (_e = (_d = (_c = (_b = (_a = window.Ionic) === null || _a === void 0 ? void 0 : _a.config) === null || _b === void 0 ? void 0 : _b.get) === null || _c === void 0 ? void 0 : _c.call(_b, 'theme')) === null || _d === void 0 ? void 0 : _d.fontSizes) === null || _e === void 0 ? void 0 : _e.root) !== null && _f !== void 0 ? _f : '16');
+            return Object.entries(val).flatMap(([sizeKey, sizeValue]) => {
+                if (!sizeKey || sizeValue == null)
+                    return [];
+                const remValue = `${parseFloat(sizeValue) / fontSizeBase}rem`;
+                // Return both px and rem values as separate array items
+                return [
+                    `${prefix}${key}-${sizeKey}: ${sizeValue};`, // original px value
+                    `${prefix}${key}-${sizeKey}-rem: ${remValue};`, // rem value
+                ];
+            });
+        }
+        return typeof val === 'object' && val !== null
+            ? generateCSSVars(val, `${prefix}${key}-`)
+            : [`${prefix}${key}: ${val};`];
+    })
+        .filter(Boolean);
+    return cssProps.join('\n');
+};
+/**
+ * Generates a CSS class containing the CSS variables for each color
+ * in the theme. Each color has generic bold and subtle variables that are mapped
+ * to the specific color's bold and subtle variables. The bold colors will temporarily
+ * include a fallback to remove the bold prefix. For example, the primary
+ * color will return the following CSS class:
+ *
+ * ```css
+ * :root .ion-color-primary {
+ *   --ion-color-base: var(--ion-color-primary, var(--ion-color-primary-bold));
+ *   --ion-color-base-rgb: var(--ion-color-primary-rgb, var(--ion-color-primary-bold-rgb));
+ *   --ion-color-contrast: var(--ion-color-primary-contrast, var(--ion-color-primary-bold-contrast));
+ *   --ion-color-contrast-rgb: var(--ion-color-primary-contrast-rgb, var(--ion-color-primary-bold-contrast-rgb));
+ *   --ion-color-shade: var(--ion-color-primary-shade, var(--ion-color-primary-bold-shade));
+ *   --ion-color-tint: var(--ion-color-primary-tint, var(--ion-color-primary-bold-tint));
+ *   --ion-color-foreground: var(--ion-color-primary, var(--ion-color-primary-foreground, var(--ion-color-primary-bold-foreground)));
+ *
+ *   --ion-color-subtle-base: var(--ion-color-primary-subtle);
+ *   --ion-color-subtle-base-rgb: var(--ion-color-primary-subtle-rgb);
+ *   --ion-color-subtle-contrast: var(--ion-color-primary-subtle-contrast);
+ *   --ion-color-subtle-contrast-rgb: var(--ion-color-primary-subtle-contrast-rgb);
+ *   --ion-color-subtle-shade: var(--ion-color-primary-subtle-shade);
+ *   --ion-color-subtle-tint: var(--ion-color-primary-subtle-tint);
+ *   --ion-color-subtle-foreground: var(--ion-color-primary-subtle-foreground);
+ * }
+ * ```
+ *
+ * @param theme The theme object containing color definitions
+ * @returns CSS string with .ion-color-{colorName} utility classes
+ */
+export const generateColorClasses = (theme) => {
+    var _a, _b;
+    // Look for colors in the light palette first, then fallback to the
+    // direct color property if there is no light palette
+    const colors = ((_b = (_a = theme === null || theme === void 0 ? void 0 : theme.palette) === null || _a === void 0 ? void 0 : _a.light) === null || _b === void 0 ? void 0 : _b.color) || (theme === null || theme === void 0 ? void 0 : theme.color);
+    if (!colors) {
+        return '';
+    }
+    if (typeof colors !== 'object' || Array.isArray(colors)) {
+        const colorsType = Array.isArray(colors) ? 'array' : typeof colors;
+        printIonWarning(`Invalid color configuration in theme. Expected color to be an object, but found ${colorsType}.`, theme);
+        return '';
+    }
+    const generatedColorClasses = [];
+    Object.keys(colors).forEach((colorName) => {
+        const colorVariants = colors[colorName];
+        if (!colorVariants || typeof colorVariants !== 'object')
+            return;
+        const cssVariableRules = [];
+        // Generate CSS variables for bold variant
+        // Includes base color variables without the bold modifier for
+        // backwards compatibility.
+        // TODO: Remove the fallbacks once the bold variables are the default
+        if (colorVariants.bold) {
+            cssVariableRules.push(`--ion-color-base: var(--ion-color-${colorName}, var(--ion-color-${colorName}-bold)) !important;`, `--ion-color-base-rgb: var(--ion-color-${colorName}-rgb, var(--ion-color-${colorName}-bold-rgb)) !important;`, `--ion-color-contrast: var(--ion-color-${colorName}-contrast, var(--ion-color-${colorName}-bold-contrast)) !important;`, `--ion-color-contrast-rgb: var(--ion-color-${colorName}-contrast-rgb, var(--ion-color-${colorName}-bold-contrast-rgb)) !important;`, `--ion-color-shade: var(--ion-color-${colorName}-shade, var(--ion-color-${colorName}-bold-shade)) !important;`, `--ion-color-tint: var(--ion-color-${colorName}-tint, var(--ion-color-${colorName}-bold-tint)) !important;`, `--ion-color-foreground: var(--ion-color-${colorName}-foreground, var(--ion-color-${colorName}-bold-foreground)) !important;`);
+        }
+        // Generate CSS variables for subtle variant
+        if (colorVariants.subtle) {
+            cssVariableRules.push(`--ion-color-subtle-base: var(--ion-color-${colorName}-subtle) !important;`, `--ion-color-subtle-base-rgb: var(--ion-color-${colorName}-subtle-rgb) !important;`, `--ion-color-subtle-contrast: var(--ion-color-${colorName}-subtle-contrast) !important;`, `--ion-color-subtle-contrast-rgb: var(--ion-color-${colorName}-subtle-contrast-rgb) !important;`, `--ion-color-subtle-shade: var(--ion-color-${colorName}-subtle-shade) !important;`, `--ion-color-subtle-tint: var(--ion-color-${colorName}-subtle-tint) !important;`, `--ion-color-subtle-foreground: var(--ion-color-${colorName}-subtle-foreground) !important;`);
+        }
+        if (cssVariableRules.length > 0) {
+            const colorUtilityClass = `
+        :root .ion-color-${colorName} {
+          ${cssVariableRules.join('\n  ')}
+        }
+      `;
+            generatedColorClasses.push(colorUtilityClass);
+        }
+    });
+    return generatedColorClasses.join('\n');
+};
+/**
+ * Creates a style element and injects its CSS into a target element
+ * @param css The CSS string to inject
+ * @param target The target element to inject into
+ */
+export const injectCSS = (css, target = document.head) => {
+    const style = document.createElement('style');
+    style.innerHTML = css;
+    target.appendChild(style);
+};
+/**
+ * Generates global CSS variables from a theme object
+ * @param theme The theme object to generate CSS for
+ * @returns The generated CSS string
+ */
+export const generateGlobalThemeCSS = (theme) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const themeValidity = isValidTheme(theme, 'generateGlobalThemeCSS');
+    if (!themeValidity) {
+        return '';
+    }
+    // Exclude palette, components, and config from the default tokens
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { palette, components, config } = theme, defaultTokens = __rest(theme, ["palette", "components", "config"]);
+    // Generate CSS variables for the default design tokens
+    const defaultTokensCSS = generateCSSVars(defaultTokens);
+    // Generate CSS variables for the light color palette
+    const lightTokensCSS = generateCSSVars(palette.light);
+    // Generate CSS variables for the dark color palette
+    const darkTokensCSS = generateCSSVars(palette.dark);
+    // Generate CSS variable for the high contrast color palette
+    const highContrastTokensCSS = generateCSSVars(palette.highContrast);
+    // Generate CSS variable for the high contrast dark color palette
+    const highContrastDarkTokensCSS = generateCSSVars(palette.highContrastDark);
+    let paletteTokensCSS = lightTokensCSS;
+    if (((_a = palette.highContrastDark) === null || _a === void 0 ? void 0 : _a.enabled) === 'always') {
+        // Include CSS variables for the high contrast dark color palette instead of
+        // the light palette if high contrast dark palette enabled is 'always'
+        paletteTokensCSS = highContrastDarkTokensCSS;
+    }
+    else if (((_b = palette.highContrast) === null || _b === void 0 ? void 0 : _b.enabled) === 'always') {
+        // Include CSS variables for the dark color palette instead of
+        // the light palette if dark palette enabled is 'always'
+        paletteTokensCSS = highContrastTokensCSS;
+    }
+    else if (((_c = palette.dark) === null || _c === void 0 ? void 0 : _c.enabled) === 'always') {
+        // Include CSS variables for the dark color palette instead of
+        // the light palette if dark palette enabled is 'always'
+        paletteTokensCSS = darkTokensCSS;
+    }
+    let css = `
+    ${CSS_ROOT_SELECTOR} {
+      ${defaultTokensCSS}
+      ${paletteTokensCSS || ''}
+    }
+  `;
+    if (((_d = palette.highContrastDark) === null || _d === void 0 ? void 0 : _d.enabled) === 'class' && highContrastDarkTokensCSS) {
+        // Include CSS variables for the high contrast dark color palette inside of a
+        // class if high contrast dark palette enabled is 'class'
+        css += `
+      .ion-palette-high-contrast.ion-palette-dark {
+        ${highContrastDarkTokensCSS}
+      }
+    `;
+    }
+    else if (((_e = palette.highContrast) === null || _e === void 0 ? void 0 : _e.enabled) === 'class' && highContrastTokensCSS) {
+        // Include CSS variables for the high contrast color palette inside of a
+        // class if high contrast palette enabled is 'class'
+        css += `
+      .ion-palette-high-contrast {
+        ${highContrastTokensCSS}
+      }
+    `;
+    }
+    else if (((_f = palette.dark) === null || _f === void 0 ? void 0 : _f.enabled) === 'class' && darkTokensCSS) {
+        // Include CSS variables for the dark color palette inside of a
+        // class if dark palette enabled is 'class'
+        css += `
+      .ion-palette-dark {
+        ${darkTokensCSS}
+      }
+    `;
+    }
+    if (((_g = palette.highContrastDark) === null || _g === void 0 ? void 0 : _g.enabled) === 'system' && highContrastDarkTokensCSS) {
+        // Include CSS variables for the high contrast dark color palette inside of the
+        // high contrast dark media query if high contrast dark palette enabled is 'system'
+        css += `
+      @media (prefers-contrast: more) and (prefers-color-scheme: dark) {
+        ${CSS_ROOT_SELECTOR} {
+          ${highContrastDarkTokensCSS}
+        }
+      }
+    `;
+    }
+    else if (((_h = palette.highContrast) === null || _h === void 0 ? void 0 : _h.enabled) === 'system' && highContrastTokensCSS) {
+        // Include CSS variables for the high contrast color palette inside of the
+        // high contrast media query if high contrast palette enabled is 'system'
+        css += `
+      @media (prefers-contrast: more) {
+        ${CSS_ROOT_SELECTOR} {
+          ${highContrastTokensCSS}
+        }
+      }
+    `;
+    }
+    else if (((_j = palette.dark) === null || _j === void 0 ? void 0 : _j.enabled) === 'system' && darkTokensCSS) {
+        // Include CSS variables for the dark color palette inside of the
+        // dark color scheme media query if dark palette enabled is 'system'
+        css += `
+      @media (prefers-color-scheme: dark) {
+        ${CSS_ROOT_SELECTOR} {
+          ${darkTokensCSS}
+        }
+      }
+    `;
+    }
+    // Add color classes
+    const colorClasses = generateColorClasses(theme);
+    return css + '\n' + colorClasses;
+};
+/**
+ * Applies the global theme from the provided base theme and user theme
+ * @param baseTheme The default theme
+ * @param userTheme The user's custom theme (optional)
+ * @returns The combined theme object (or base theme if no user theme was provided)
+ */
+export const applyGlobalTheme = (baseTheme, userTheme) => {
+    // If no base theme provided, error
+    if (typeof baseTheme !== 'object' || Array.isArray(baseTheme)) {
+        console.error('applyGlobalTheme: Valid base theme object is required', baseTheme);
+        return {};
+    }
+    // If no user theme provided or it is invalid, apply base theme
+    if (!userTheme || typeof userTheme !== 'object' || Array.isArray(userTheme)) {
+        if (userTheme) {
+            console.error('applyGlobalTheme: Invalid user theme provided', userTheme);
+        }
+        injectCSS(generateGlobalThemeCSS(baseTheme));
+        return baseTheme;
+    }
+    // Merge themes and apply
+    const mergedTheme = deepMerge(baseTheme, userTheme);
+    injectCSS(generateGlobalThemeCSS(mergedTheme));
+    return mergedTheme;
+};
+/**
+ * Generates component's themed CSS class with CSS variables
+ * from its theme object
+ * @param componentTheme The component's object to generate CSS for (e.g., IonChip { })
+ * @param components An object mapping component names (e.g. `IonChip`) to a nested
+ * design-token configuration. Each configuration can contain arbitrary levels of
+ * token groups (such as `size`, `state`, `shape`, `variant`, etc.), where leaf values
+ * are CSS-compatible values. The structure is recursively flattened into CSS custom
+ * properties using kebab-case keys and an `--ion-<component>-` prefix.
+ *
+ * Example:
+ * ```json
+ * {
+ *   IonChip: {
+ *     size: { small: { height: "24px" } },
+ *     state: { disabled: { opacity: "0.4" } }
+ *   }
+ * }
+ * ```
+ *
+ * Becomes:
+ * ```css
+ * ion-chip {
+ *   --ion-chip-size-small-height: 24px;
+ *   --ion-chip-state-disabled-opacity: 0.4;
+ * }
+ * ```
+ * @returns string containing the component's themed CSS variables
+ */
+export const generateComponentsThemeCSS = (components) => {
+    let css = '';
+    for (const [component, componentTokens] of Object.entries(components)) {
+        const componentTag = convertToKebabCase(component);
+        const vars = generateCSSVars(componentTokens, `--${componentTag}-`);
+        const componentBlock = `
+      ${componentTag} {
+        ${vars}
+      }
+    `;
+        css += componentBlock;
+    }
+    return css;
+};
+/**
+ * Applies a component theme to an element if it exists in the custom theme
+ * @param element The element to apply the theme to
+ * @returns true if theme was applied, false otherwise
+ */
+export const applyComponentsTheme = (theme) => {
+    const themeValidity = isValidTheme(theme, 'applyComponentsTheme');
+    if (!themeValidity) {
+        return '';
+    }
+    const { components } = theme;
+    if (!components) {
+        return '';
+    }
+    injectCSS(generateComponentsThemeCSS(components));
+    return components;
+};
+/**
+ * Parses a hex color string and returns RGB values as an array.
+ *
+ * @param hex Hex color (e.g. `'#ffffff'` or `'#fff'`)
+ *
+ * @returns RGB values as `[r, g, b]` array
+ */
+const parseHex = (hex) => {
+    const cleanHex = hex.replace('#', '');
+    // Short hex format like 'fff' → expand to 'ffffff'
+    if (cleanHex.length === 3) {
+        return [
+            parseInt(cleanHex[0] + cleanHex[0], 16),
+            parseInt(cleanHex[1] + cleanHex[1], 16),
+            parseInt(cleanHex[2] + cleanHex[2], 16),
+        ];
+        // Full hex format like 'ffffff'
+    }
+    else {
+        return [
+            parseInt(cleanHex.substring(0, 2), 16),
+            parseInt(cleanHex.substring(2, 4), 16),
+            parseInt(cleanHex.substring(4, 6), 16),
+        ];
+    }
+};
+/**
+ * Converts a hex color to a string of RGB comma-separated values.
+ *
+ * @param hex Hex color (e.g. `'#ffffff'` or `'#fff'`)
+ *
+ * @returns RGB string (e.g. `'255, 255, 255'`)
+ */
+export const hexToRgb = (hex) => {
+    const [r, g, b] = parseHex(hex);
+    return `${r}, ${g}, ${b}`;
+};
+/**
+ * Mixes two hex colors by a given weight percentage and returns
+ * it as a hex color.
+ *
+ * @param baseColor Base color (e.g. `'#0054e9'`)
+ * @param mixColor Color to mix in (e.g. `'#000000'` or `'#fff'`)
+ * @param weight Weight percentage as string - how much of mixColor to mix into baseColor (e.g. `'12%'`)
+ *
+ * @returns Mixed hex color (e.g. `'#004acd'`)
+ */
+export const mix = (baseColor, mixColor, weight) => {
+    // Parse weight percentage
+    const w = parseFloat(weight.replace('%', '')) / 100;
+    // Parse both colors
+    const [baseR, baseG, baseB] = parseHex(baseColor);
+    const [mixR, mixG, mixB] = parseHex(mixColor);
+    // Mix mixColor into baseColor by weight
+    const r = Math.round(baseR * (1 - w) + mixR * w);
+    const g = Math.round(baseG * (1 - w) + mixG * w);
+    const b = Math.round(baseB * (1 - w) + mixB * w);
+    const toHex = (n) => n.toString(16).padStart(2, '0');
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+};
+/**
+ * Converts a string to kebab-case
+ *
+ * @internal
+ * @param str The string to convert (e.g., 'IonChip')
+ * @returns The kebab-case string (e.g., 'ion-chip')
+ */
+const convertToKebabCase = (str) => {
+    return str
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[\s_]+/g, '-')
+        .toLowerCase();
+};
+/**
+ * Verifies that a theme object is valid
+ *
+ * @internal
+ * @param theme The theme object to validate
+ * @param source The source or context where the theme is being validated
+ * @returns A boolean indicating whether the theme is valid
+ */
+const isValidTheme = (theme, source, showLog = true) => {
+    if (typeof theme !== 'object' || Array.isArray(theme)) {
+        if (showLog) {
+            printIonWarning(`${source}: Invalid theme object provided`, theme);
+        }
+        return false;
+    }
+    if (Object.keys(theme).length === 0) {
+        if (showLog) {
+            printIonWarning(`${source}: Empty theme object provided`, theme);
+        }
+        return false;
     }
-    return false;
+    return true;
+};
+/**
+ * Mimics the Sass `rgba` function logic to construct CSS rgba() values.
+ *
+ * @internal
+ * @param colorRgb The RGB color components as a string (e.g., '255, 0, 0').
+ * @param alpha The opacity value (0 to 1).
+ * @returns A string containing the CSS rgba() function call.
+ */
+export function rgba(colorRgb, alpha) {
+    // This directly constructs the rgba() function call using the provided values.
+    return `rgba(${colorRgb}, ${alpha})`;
+}
+/**
+ * Mimics the Ionic Framework `current-color` function logic to construct CSS color values.
+ *
+ * @internal
+ * @param variation The color variation (e.g., 'primary', 'secondary', 'base').
+ * @param alpha The opacity value (0 to 1). If null, returns the full color variable.
+ * @param subtle If true, uses the '--ion-color-subtle-' prefix.
+ * @returns A string containing the CSS value (e.g., 'var(--ion-color-primary)' or 'rgba(var(--ion-color-primary-rgb), 0.16)').
+ */
+export function currentColor(variation, options = {}) {
+    const { alpha = null, subtle = false } = options;
+    // 1. Determine the base CSS variable name
+    const variable = subtle ? `--ion-color-subtle-${variation}` : `--ion-color-${variation}`;
+    // 2. Handle the case where no alpha is provided
+    if (alpha === null) {
+        // Corresponds to: @return var(#{$variable});
+        return `var(${variable})`;
+    }
+    // 3. Handle the case where alpha is provided
+    // Corresponds to: @return rgba(var(#{$variable}-rgb), #{$alpha});
+    // NOTE: The resulting string uses the CSS variable for the RGB components
+    // (e.g., '255, 0, 0') and the provided alpha.
+    return `rgba(var(${variable}-rgb), ${alpha})`;
+}
+export function ionColor(name, variation, options = {}) {
+    const { alpha = null, subtle = false } = options;
+    // Build base variable name
+    const base = subtle ? `--ion-color-${name}-subtle` : `--ion-color-${name}`;
+    const variationSuffix = variation === 'base' ? '' : `-${variation}`;
+    const variable = `${base}${variationSuffix}`;
+    // Build the fallback variable name (only for bold colors)
+    let fallbackVariable = null;
+    if (!subtle) {
+        const fallbackBase = `--ion-color-${name}-bold`;
+        fallbackVariable = `${fallbackBase}${variationSuffix}`;
+    }
+    // Handle alpha transparency
+    if (alpha !== null) {
+        const rgbVar = `${variable}-rgb`;
+        const fallbackRgb = fallbackVariable ? `${fallbackVariable}-rgb` : null;
+        return fallbackRgb ? `rgba(var(${rgbVar}, var(${fallbackRgb})), ${alpha})` : `rgba(var(${rgbVar}), ${alpha})`;
+    }
+    return fallbackVariable ? `var(${variable}, var(${fallbackVariable}))` : `var(${variable})`;
+}
+/**
+ * Mimics the CSS `clamp` function logic.
+ *
+ * @internal
+ * @param min The minimum value
+ * @param val The preferred value
+ * @param max The maximum value
+ * @returns A string containing the CSS clamp() function call (e.g., 'clamp(1rem, 2vw, 3rem)').
+ */
+export function clamp(min, val, max) {
+    return `clamp(${min}, ${val}, ${max})`;
+}
+/**
+ * Generates a series of color steps between a base color and a mix color.
+ *
+ * @param baseColor Base color (e.g. `'#0054e9'`)
+ * @param mixColor Color to mix in (e.g. `'#000000'` or `'#fff'`)
+ *
+ * @internal
+ * @returns An object containing the generated color steps
+ */
+export const generateColorSteps = (baseColor, mixColor) => {
+    const colorSteps = {};
+    for (let step = 50; step <= 950; step += 50) {
+        const weight = `${step / 10}%`;
+        colorSteps[`${step}`] = mix(baseColor, mixColor, weight);
+    }
+    return colorSteps;
+};
+const baselineUnit = 'rem';
+/**
+ * Converts a pixel value to a dynamic unit (defaulting to rem).
+ *
+ * Examples based on a root font size of 16px:
+ * - `dynamicFont('16px', 16)` returns `'1rem'`
+ * - `dynamicFont('16px', 20, 'em')` returns `'1.25em'`
+ *
+ * @internal
+ * @param configRootFontSize - The root font size from the theme config.
+ * @param size - The numeric pixel value.
+ * @param unit - The CSS unit string.
+ * @returns The calculated CSS value string.
+ */
+export const dynamicFont = (configRootFontSize, size, unit = baselineUnit) => {
+    let baselinePixelSize = 16;
+    const cleanSize = typeof configRootFontSize === 'string' ? parseFloat(configRootFontSize) : configRootFontSize;
+    if (!isNaN(cleanSize)) {
+        baselinePixelSize = cleanSize;
+    }
+    else {
+        printIonWarning(`Invalid root font size in theme config: ${configRootFontSize}. Falling back to default of ${baselinePixelSize}px.`);
+    }
+    return `${size / baselinePixelSize}${unit}`;
+};
+/**
+ * Converts a pixel value to a dynamic unit (defaulting to rem)
+ * but imposes a minimum font size using CSS max().
+ *
+ * Examples based on a root font size of 16px:
+ * - `dynamicFontMin('16px', 0.8, 11)` returns `'max(8.8px, 0.6875rem)'`
+ * - A minimum of 80% of 11px = 8.8px, but the rem value scales with root font size
+ *
+ * @internal
+ * @param configRootFontSize - The root font size from the theme config.
+ * @param minScale - The minimum scale of the font (e.g. 0.8 for 80%).
+ * @param size - The numeric pixel value.
+ * @param unit - The CSS unit string.
+ * @returns A string containing the CSS max() function with the minimum pixel value and the dynamic font value (e.g., 'max(8.8px, 0.6875rem)').
+ */
+export const dynamicFontMin = (configRootFontSize, minScale, size, unit = baselineUnit) => {
+    const baseScale = dynamicFont(configRootFontSize, size, unit);
+    const minSize = size * minScale;
+    return `max(${minSize}px, ${baseScale})`;
 };