@evolve.ui/theme-system 1.0.1 → 1.2.0

package/src/themes/themeValues.ts

@@ -0,0 +1,374 @@
+import type { ColorAliasesObject } from './generateCSSVars';
+
+import { borderRadius } from '../tailwind/borderRadius';
+import { fontFamily } from '../tailwind/fontFamily';
+import { tailwindTheme, themePlugin } from '../tailwind/plugin';
+import { screens } from '../tailwind/screens';
+import { spacing } from '../tailwind/spacing';
+import { textComponents } from '../tailwind/text';
+import { generateNormalColorSteps, generateSurfaceColorSteps, type Steps } from '../utils/color';
+import { brandSources } from './brandSources';
+import {
+    FILLED_BUTTON_FAMILIES,
+    FILLED_BUTTON_STEPS,
+    TEXT_AA,
+    TEXT_AAA_BODY,
+    TEXT_CONTRAST_TOKENS,
+    UI_AA,
+    UI_CONTRAST_TOKENS,
+} from './contrastFloors';
+
+export const LOCKED_BRANDS = ['BasketballTraining', 'Default', 'ProfessionalBrand'] as const;
+
+export const COLOR_GENERATOR_SEEDS = ['#112233', '#2563EB', '#D92525'] as const;
+
+export type BrandSource = {
+    colorAliases: ColorAliasesObject;
+    nonColorVariables: Record<string, string>;
+};
+
+export type TokenValue = {
+    binding: string;
+    resolved: string;
+};
+
+export type BrandValues = {
+    palette: Record<string, string>;
+    tokens: Record<string, TokenValue>;
+};
+
+export type OrderedEntries<T> = readonly (readonly [string, T])[];
+
+export type OrderedValue = string | number | boolean | null | readonly OrderedValue[];
+
+export type ContrastValues = {
+    filledButtonFamilies: readonly string[];
+    filledButtonSteps: readonly string[];
+    textAa: number;
+    textAaaBody: number;
+    textTokens: readonly (readonly [string, number])[];
+    uiAa: number;
+    uiTokens: readonly string[];
+};
+
+export type ThemeValueInput = {
+    borderRadius?: Record<string, string>;
+    brands?: Record<string, BrandSource>;
+    contrast?: ContrastValues;
+    fontFamily?: Record<string, string>;
+    generateNormalColorSteps?: (color: string) => string[];
+    generateSurfaceColorSteps?: (color: string, isNeutral?: boolean) => string[];
+    screens?: Record<string, Record<string, string>>;
+    spacing?: Record<string, string>;
+    tailwind?: typeof tailwindTheme;
+    textComponents?: Record<string, unknown>;
+};
+
+const brandSource = (colorAliases: ColorAliasesObject, nonColorVariables: Record<string, string>): BrandSource => ({
+    colorAliases,
+    nonColorVariables,
+});
+
+export const themeBrandSources = (): Record<string, BrandSource> =>
+    Object.fromEntries(
+        Object.entries(brandSources).map(([brand, source]) => [
+            brand,
+            brandSource(source.colorAliases, source.nonColorVariables as Record<string, string>),
+        ])
+    );
+
+const COLOR_STEPS = new Set<string>(['50', '100', '200', '300', '400', '500', '600', '700', '800', '900']);
+
+const isColorAlias = (alias: string, aliases: ColorAliasesObject): alias is keyof ColorAliasesObject =>
+    Object.prototype.hasOwnProperty.call(aliases, alias);
+
+const isStep = (step: string): step is Steps => COLOR_STEPS.has(step);
+
+const resolveRefs = (value: string, aliases: BrandSource['colorAliases']): string =>
+    value.replace(/var\(--color-([a-z]+)-(\d+)\)/g, (full, alias: string, step: string) => {
+        if (!isColorAlias(alias, aliases) || !isStep(step)) {
+            return full;
+        }
+        return aliases[alias][step];
+    });
+
+const paletteOf = (aliases: BrandSource['colorAliases']): Record<string, string> => {
+    const palette: Record<string, string> = {};
+    for (const [alias, steps] of Object.entries(aliases)) {
+        for (const [step, channels] of Object.entries(steps)) {
+            palette[`${alias}.${step}`] = channels;
+        }
+    }
+    return palette;
+};
+
+const tokensOf = (brand: BrandSource): Record<string, TokenValue> => {
+    const tokens: Record<string, TokenValue> = {};
+    for (const [name, binding] of Object.entries(brand.nonColorVariables)) {
+        tokens[name] = { binding, resolved: resolveRefs(binding, brand.colorAliases) };
+    }
+    return tokens;
+};
+
+const isTailwindTheme = (value: unknown): value is typeof tailwindTheme =>
+    value !== null &&
+    typeof value === 'object' &&
+    'borderWidth' in value &&
+    'colors' in value &&
+    'fontFamily' in value &&
+    'screens' in value;
+
+const pluginTailwindTheme = (): typeof tailwindTheme => {
+    const theme = themePlugin.config?.theme;
+    if (!isTailwindTheme(theme)) {
+        throw new Error('theme plugin is not passing a theme object');
+    }
+    return theme;
+};
+
+const isSerializable = (value: unknown): value is string | number | boolean | null =>
+    typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null;
+
+// Identity only. A lookalike null-parent object, and another realm's Object.prototype, are not these.
+const hasAllowedPrototype = (value: object): boolean => {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === Array.prototype || proto === null;
+};
+
+const assertRecordableObject = (value: object): void => {
+    if (!hasAllowedPrototype(value)) {
+        throw new Error('theme value has an unexpected prototype');
+    }
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+        throw new Error('theme value has a symbol key');
+    }
+    for (const key of Object.getOwnPropertyNames(value)) {
+        if (Array.isArray(value) && key === 'length') {
+            continue;
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor) {
+            continue;
+        }
+        if (descriptor.get !== undefined || descriptor.set !== undefined) {
+            throw new Error('theme value has an accessor property');
+        }
+        if (!descriptor.enumerable) {
+            throw new Error('theme value has a non-enumerable property');
+        }
+    }
+};
+
+const orderValue = (value: unknown): OrderedValue => {
+    if (value !== null && typeof value === 'object') {
+        assertRecordableObject(value);
+    }
+    if (Array.isArray(value)) {
+        return ['array', value.map(orderValue)] as const;
+    }
+    if (value !== null && typeof value === 'object') {
+        return [
+            'object',
+            Object.keys(value).map((key) => {
+                const child = Object.getOwnPropertyDescriptor(value, key)?.value;
+                return [key, orderValue(child)] as const;
+            }),
+        ] as const;
+    }
+    if (isSerializable(value)) {
+        return value;
+    }
+    throw new Error('theme value is not serializable');
+};
+
+const MATCH_UTILITY_PROBE = 'probe';
+
+type UtilityCallback = (value: unknown, extra: { modifier: string | null }) => unknown;
+
+const isUtilityCallback = (value: unknown): value is UtilityCallback => typeof value === 'function';
+
+const valuesOf = (options: unknown): object | undefined => {
+    if (options === null || typeof options !== 'object') {
+        return undefined;
+    }
+    assertRecordableObject(options);
+    const values = Object.getOwnPropertyDescriptor(options, 'values')?.value;
+    if (values === undefined) {
+        return undefined;
+    }
+    if (values === null || typeof values !== 'object') {
+        throw new Error('theme value is not serializable');
+    }
+    assertRecordableObject(values);
+    return values;
+};
+
+const callUtility = (callback: UtilityCallback, value: unknown): unknown => callback(value, { modifier: null });
+
+const recordCallbackOutputs = (callback: UtilityCallback, values: object | undefined): object => {
+    const recorded: Record<string, unknown> = {
+        probe: callUtility(callback, MATCH_UTILITY_PROBE),
+    };
+    if (values) {
+        const outputs: Record<string, unknown> = {};
+        for (const key of Object.keys(values)) {
+            outputs[key] = callUtility(callback, Object.getOwnPropertyDescriptor(values, key)?.value);
+        }
+        recorded.values = outputs;
+    }
+    return recorded;
+};
+
+const probeUtilities = (utilities: object, options: unknown): object => {
+    assertRecordableObject(utilities);
+    const values = valuesOf(options);
+    const probed: object = Object.create(Object.getPrototypeOf(utilities));
+    for (const key of Object.keys(utilities)) {
+        const child = Object.getOwnPropertyDescriptor(utilities, key)?.value;
+        const recorded = isUtilityCallback(child) ? recordCallbackOutputs(child, values) : child;
+        Object.defineProperty(probed, key, {
+            configurable: true,
+            enumerable: true,
+            value: recorded,
+            writable: true,
+        });
+    }
+    return probed;
+};
+
+const pluginConfig = (): object => {
+    const config = themePlugin.config;
+    if (!config) {
+        throw new Error('theme plugin is not passing a config');
+    }
+    return config;
+};
+
+const PLUGIN_API_METHODS = new Set([
+    'addBase',
+    'addComponents',
+    'addDefaults',
+    'addUtilities',
+    'addVariant',
+    'config',
+    'corePlugins',
+    'e',
+    'matchComponents',
+    'matchUtilities',
+    'matchVariant',
+    'postcss',
+    'prefix',
+    'theme',
+    'variants',
+]);
+
+const recordPluginCalls = (): readonly unknown[] => {
+    const calls: unknown[] = [];
+    const record =
+        (method: string) =>
+        (...args: readonly unknown[]) => {
+            if (method === 'matchUtilities' || method === 'matchComponents') {
+                const [utilities, options] = args;
+                const recorded =
+                    utilities !== null && typeof utilities === 'object'
+                        ? probeUtilities(utilities, options)
+                        : utilities;
+                calls.push([method, recorded, ...args.slice(1)]);
+                return;
+            }
+            if (method === 'matchVariant') {
+                const [name, callback, options] = args;
+                const recorded = isUtilityCallback(callback)
+                    ? recordCallbackOutputs(callback, valuesOf(options))
+                    : callback;
+                calls.push([method, name, recorded, ...args.slice(2)]);
+                return;
+            }
+            calls.push([method, ...args]);
+        };
+    const api: Record<string, (...args: readonly unknown[]) => void> = new Proxy(
+        {},
+        {
+            get: (_target, property) => {
+                if (typeof property !== 'string' || !PLUGIN_API_METHODS.has(property)) {
+                    throw new Error(`theme plugin API method is not recorded: ${String(property)}`);
+                }
+                return record(property);
+            },
+        }
+    );
+    themePlugin.handler(api as unknown as Parameters<typeof themePlugin.handler>[0]);
+    return calls;
+};
+
+const isObjectShape = (value: unknown): value is readonly ['object', OrderedEntries<OrderedValue>] =>
+    Array.isArray(value) &&
+    value.length === 2 &&
+    value[0] === 'object' &&
+    Array.isArray(value[1]) &&
+    value[1].every(
+        (entry): entry is readonly [string, OrderedValue] =>
+            Array.isArray(entry) && entry.length === 2 && typeof entry[0] === 'string'
+    );
+
+const LOCKED_BRAND_NAMES: ReadonlySet<string> = new Set(LOCKED_BRANDS);
+
+export const themeContrastValues = (): ContrastValues => ({
+    filledButtonFamilies: FILLED_BUTTON_FAMILIES,
+    filledButtonSteps: FILLED_BUTTON_STEPS,
+    textAa: TEXT_AA,
+    textAaaBody: TEXT_AAA_BODY,
+    textTokens: TEXT_CONTRAST_TOKENS,
+    uiAa: UI_AA,
+    uiTokens: UI_CONTRAST_TOKENS,
+});
+
+export const collectThemeValues = (input: ThemeValueInput = {}): OrderedValue => {
+    const brands = input.brands ?? themeBrandSources();
+    const normal = input.generateNormalColorSteps ?? generateNormalColorSteps;
+    const surface = input.generateSurfaceColorSteps ?? generateSurfaceColorSteps;
+    const recordedBrands: Record<string, BrandValues> = {};
+    for (const [name, brand] of Object.entries(brands)) {
+        recordedBrands[name] = { palette: paletteOf(brand.colorAliases), tokens: tokensOf(brand) };
+    }
+    const generatorFor = (run: (seed: string) => string[]) => {
+        const out: Record<string, string[]> = {};
+        for (const seed of COLOR_GENERATOR_SEEDS) {
+            out[seed] = run(seed);
+        }
+        return out;
+    };
+    const tailwind = input.tailwind ?? pluginTailwindTheme();
+    return orderValue({
+        brands: recordedBrands,
+        colorGenerator: {
+            normal: generatorFor(normal),
+            surface: generatorFor((seed) => surface(seed)),
+            surfaceNeutral: generatorFor((seed) => surface(seed, true)),
+        },
+        contrast: input.contrast ?? themeContrastValues(),
+        fontFamilies: input.fontFamily ?? (fontFamily as Record<string, string>),
+        radius: input.borderRadius ?? (borderRadius as Record<string, string>),
+        pluginCalls: recordPluginCalls(),
+        pluginConfig: pluginConfig(),
+        screens: input.screens ?? screens,
+        spacing: input.spacing ?? (spacing as Record<string, string>),
+        tailwind,
+        typeScale: input.textComponents ?? (textComponents as Record<string, unknown>),
+    });
+};
+
+export const lockThemeValues = (values: OrderedValue): OrderedValue => {
+    if (!isObjectShape(values)) {
+        throw new Error('theme values are not an object');
+    }
+    return [
+        'object',
+        values[1].map(([key, child]) => {
+            if (key !== 'brands' || !isObjectShape(child)) {
+                return [key, child] as const;
+            }
+            return [key, ['object', child[1].filter(([name]) => LOCKED_BRAND_NAMES.has(name))] as const] as const;
+        }),
+    ] as const;
+};

package/src/themes/wcag.ts

@@ -0,0 +1,48 @@
+/**
+ * WCAG 2.1 relative luminance and contrast ratio, independent of the colour generator (no tinycolor).
+ * Shared by contrast.spec.ts and EverydayHarbor.spec.ts so every contrast gate uses ONE formula.
+ * Inputs are the generator's channel strings ("R G B", as `removeRGB` in utils/color.ts emits).
+ */
+
+/** Parse a channel string such as "51 65 92". Throws on anything that is not three 0-255 numbers. */
+export const parseChannels = (value: string): [number, number, number] => {
+    const parts = value
+        .trim()
+        .split(/[\s,]+/)
+        .map(Number);
+    if (parts.length !== 3 || parts.some((c) => !Number.isFinite(c) || c < 0 || c > 255)) {
+        throw new Error(`Not an "R G B" channel string: ${JSON.stringify(value)}`);
+    }
+    return parts as [number, number, number];
+};
+
+/** `#RRGGBB` to the generator's channel string. Throws on a malformed literal. */
+export const hexToChannels = (hex: string): string => {
+    if (!/^#[0-9a-f]{6}$/i.test(hex)) {
+        throw new Error(`Not a #RRGGBB literal: ${JSON.stringify(hex)}`);
+    }
+    return [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)).join(' ');
+};
+
+/** Generator channel string to `#RRGGBB` (uppercase). */
+export const channelsToHex = (channels: string): string =>
+    `#${parseChannels(channels)
+        .map((c) => c.toString(16).padStart(2, '0'))
+        .join('')
+        .toUpperCase()}`;
+
+/** WCAG 2.1 relative luminance. */
+export const luminance = ([r, g, b]: [number, number, number]): number => {
+    const [lr, lg, lb] = [r, g, b].map((channel) => {
+        const c = channel / 255;
+        return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+};
+
+/** WCAG 2.1 contrast ratio between two channel strings. */
+export const contrast = (a: string, b: string): number => {
+    const [la, lb] = [luminance(parseChannels(a)), luminance(parseChannels(b))];
+    const [lighter, darker] = la >= lb ? [la, lb] : [lb, la];
+    return (lighter + 0.05) / (darker + 0.05);
+};

package/src/themes/writeToCSSFile.ts

@@ -0,0 +1,11 @@
+import { writeFile } from 'fs';
+
+export const writeToCSSFile = (css: string, path: string): void => {
+    writeFile(path, css, (err) => {
+        if (err) {
+            // eslint-disable-next-line no-console
+            console.error(err);
+            process.exit(1);
+        }
+    });
+};

package/src/utils/cn.ts

@@ -0,0 +1,35 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Utility function to merge Tailwind CSS classes with proper conflict resolution
+ *
+ * Combines clsx for conditional class names and tailwind-merge for
+ * deduplication and conflict resolution
+ *
+ * @example
+ * ```typescript
+ * import { cn } from '@evolve.ui/theme-system';
+ *
+ * // Basic usage
+ * cn('px-2 py-1', 'rounded-md');
+ * // => 'px-2 py-1 rounded-md'
+ *
+ * // With conditionals
+ * cn('button', isActive && 'button-active', isDisabled && 'opacity-50');
+ * // => 'button button-active' (if isActive is true)
+ *
+ * // Object syntax
+ * cn('button', {
+ *     'button-primary': variant === 'primary',
+ *     'button-secondary': variant === 'secondary',
+ * });
+ *
+ * // Conflict resolution (last wins)
+ * cn('p-4', 'p-2');
+ * // => 'p-2'
+ * ```
+ */
+export const cn = (...inputs: ClassValue[]) => {
+    return twMerge(clsx(inputs));
+};

package/src/utils/color.ts

@@ -0,0 +1,82 @@
+import tinycolor from 'tinycolor2';
+
+// https://github.com/bgrins/TinyColor
+
+export const lighten = (percentAsInt: number, unprocessedColor: string): tinycolor.Instance => {
+    const color = tinycolor(unprocessedColor);
+    const amount = (percentAsInt * ((1 - color.toHsl().l) * 100)) / 100;
+    return color.lighten(amount);
+};
+
+export const darken = (percentAsInt: number, unprocessedColor: string): tinycolor.Instance => {
+    const color = tinycolor(unprocessedColor);
+    const amount = (percentAsInt * (color.toHsl().l * 100)) / 100;
+    return color.darken(amount);
+};
+
+// https://tailwindcss.com/docs/customizing-colors#using-custom-colors
+const removeRGB = (color: string) => color.replace(/rgb\(|,|\)/g, '');
+
+/**
+ * Generate a set of color steps from a base color. Base color becomes 500.
+ *
+ * @param color The color to generate the steps from
+ * @returns An array of 50, 100, 200, 300, 400, 500, 600, 700, 800, 900 color values.
+ */
+export const generateNormalColorSteps = (color: string) => {
+    return [
+        removeRGB(lighten(95, color).toRgbString()),
+        removeRGB(lighten(85, color).toRgbString()),
+        removeRGB(lighten(70, color).toRgbString()),
+        removeRGB(lighten(40, color).toRgbString()),
+        removeRGB(lighten(20, color).toRgbString()),
+        removeRGB(tinycolor(color).toRgbString()),
+        removeRGB(darken(20, color).toRgbString()),
+        removeRGB(darken(40, color).toRgbString()),
+        removeRGB(darken(50, color).toRgbString()),
+        removeRGB(darken(70, color).toRgbString()),
+    ];
+};
+
+/**
+ * Generate a set of color steps from a base color. Base color becomes 500.
+ *
+ * @param color The color to generate the steps from
+ * @param isNeutral Whether the color is a neutral color to make surface-50 true white
+ * @returns An array of 50, 100, 200, 300, 400, 500, 600, 700, 800, 900 color values.
+ */
+export const generateSurfaceColorSteps = (color: string, isNeutral: boolean = false) => {
+    return [
+        removeRGB(lighten(isNeutral ? 100 : 99, color).toRgbString()),
+        removeRGB(lighten(95, color).toRgbString()),
+        removeRGB(lighten(80, color).toRgbString()),
+        removeRGB(lighten(50, color).toRgbString()),
+        removeRGB(lighten(30, color).toRgbString()),
+        removeRGB(tinycolor(color).toRgbString()),
+        removeRGB(darken(20, color).toRgbString()),
+        removeRGB(darken(40, color).toRgbString()),
+        removeRGB(darken(50, color).toRgbString()),
+        removeRGB(darken(70, color).toRgbString()),
+    ];
+};
+
+export type Steps = '50' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+export const steps: Steps[] = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900'];
+export type StepObject = Record<Steps, string>;
+
+export const colorStepArrayToObject = (colorStepArray: string[]): StepObject => {
+    return {
+        '100': colorStepArray[1],
+        '200': colorStepArray[2],
+        '300': colorStepArray[3],
+        '400': colorStepArray[4],
+        '50': colorStepArray[0],
+        '500': colorStepArray[5],
+        '600': colorStepArray[6],
+        '700': colorStepArray[7],
+        '800': colorStepArray[8],
+        '900': colorStepArray[9],
+    };
+};
+
+export { tinycolor };

package/src/utils/wrapVar.ts

@@ -0,0 +1,24 @@
+/**
+ * CSS variable wrapping utilities for Tailwind CSS configuration
+ *
+ * These utilities handle the conversion of CSS custom property names
+ * into proper var() references, with optional opacity support for
+ * Tailwind's alpha modifier syntax (e.g., `bg-primary-500/50`).
+ *
+ * @see https://tailwindcss.com/docs/customizing-colors#using-css-variables
+ * Internal reference: Hammer UI patterns
+ * Ported from the upstream theme system.
+ */
+
+/** Wraps a CSS variable name in var() */
+export const wrapVar = (value: string): string => `var(${value})`;
+
+/** Wraps a CSS variable name in rgb(var()) */
+export const wrapVarRgb = (value: string): string => `rgb(var(${value}))`;
+
+/** Wraps a variable reference with a fixed percentage opacity */
+export const wrapOpacity = (wrappedVariable: string, percentOpacity: number): string =>
+    `rgb(${wrappedVariable} / ${percentOpacity}%)`;
+
+/** Wraps a variable reference with Tailwind's alpha-value placeholder for dynamic opacity */
+export const wrapVariableOpacity = (wrappedVariable: string): string => `rgb(${wrappedVariable} / <alpha-value>)`;

package/tailwind/plugin.cjs

@@ -2,5 +2,9 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_plugin = require("../plugin-DPtvp4lp.cjs");
+const require_plugin = require("../plugin-B3PF4RMI.cjs");
+exports.autofillStyles = require_plugin.autofillStyles;
+exports.pluginBaseStyles = require_plugin.pluginBaseStyles;
+exports.pluginComponentStyles = require_plugin.pluginComponentStyles;
+exports.tailwindTheme = require_plugin.tailwindTheme;
 exports.themePlugin = require_plugin.themePlugin;