@codecademy/variance 0.24.1-alpha.3e8b72.0 → 0.24.1-alpha.43251f.0

package/dist/core.d.ts

@@ -0,0 +1,10 @@
+import { AbstractParser, AbstractPropTransformer, Compose, CSS, Parser, Prop, PropTransformer, States, TransformerMap, Variant } from './types/config';
+export declare const variance: {
+    createParser<Config extends Record<string, AbstractPropTransformer>>(config: Config): Parser<Config>;
+    createTransform<P extends string, Config_1 extends Prop>(prop: P, config: Config_1): PropTransformer<P, Config_1>;
+    compose<Args extends AbstractParser[]>(...parsers: Args): Parser<Compose<Args>>;
+    createCss<Config_2 extends Record<string, Prop>, P_1 extends Parser<TransformerMap<Config_2>>>(config: Config_2): CSS<P_1>;
+    createVariant<Config_3 extends Record<string, Prop>, P_2 extends Parser<TransformerMap<Config_3>>>(config: Config_3): Variant<P_2>;
+    createStates<Config_4 extends Record<string, Prop>, P_3 extends Parser<TransformerMap<Config_4>>>(config: Config_4): States<P_3>;
+    create<Config_5 extends Record<string, Prop>>(config: Config_5): Parser<TransformerMap<Config_5>>;
+};

package/dist/core.js

@@ -0,0 +1,223 @@
+import get from 'lodash/get';
+import identity from 'lodash/identity';
+import isArray from 'lodash/isArray';
+import isObject from 'lodash/isObject';
+import isUndefined from 'lodash/isUndefined';
+import merge from 'lodash/merge';
+import { createScaleLookup } from './scales/createScaleLookup';
+import { getStaticCss } from './utils/getStaticProperties';
+import { orderPropNames } from './utils/propNames';
+import { arrayParser, isMediaArray, isMediaMap, objectParser, orderBreakpoints, parseBreakpoints } from './utils/responsive';
+export const variance = {
+  // Parser to handle any set of configured props
+  createParser(config) {
+    const propNames = orderPropNames(config);
+    let breakpoints;
+    const parser = props => {
+      const styles = {};
+      const {
+        theme
+      } = props;
+      // Attempt to cache the breakpoints if we have not yet or if theme has become available.
+      if (breakpoints === undefined || breakpoints === null && theme?.breakpoints) {
+        // Save the breakpoints if we can
+        breakpoints = parseBreakpoints(theme?.breakpoints);
+      }
+
+      // Loops over all prop names on the configured config to check for configured styles
+      propNames.forEach(prop => {
+        const property = config[prop];
+        const value = get(props, prop);
+        switch (typeof value) {
+          case 'string':
+          case 'number':
+          case 'function':
+            return Object.assign(styles, property.styleFn(value, prop, props));
+          // handle any props configured with the responsive notation
+          case 'object':
+            if (!breakpoints) {
+              return;
+            }
+            // If it is an array the order of values is smallest to largest: [_, xs, ...]
+            if (isMediaArray(value)) {
+              return merge(styles, arrayParser(value, props, property, breakpoints.array));
+            }
+            // Check to see if value is an object matching the responsive syntax and generate the styles.
+            if (isMediaMap(value)) {
+              return merge(styles, objectParser(value, props, property, breakpoints.map));
+            }
+        }
+      });
+      return breakpoints ? orderBreakpoints(styles, breakpoints.array) : styles;
+    };
+    // return the parser function with the resulting meta information for further composition
+    return Object.assign(parser, {
+      propNames,
+      config
+    });
+  },
+  // Given a single property configuration enrich the config with a transform function
+  // that traverses the properties the function is responsible for.
+  createTransform(prop, config) {
+    const {
+      transform = identity,
+      property,
+      properties = [property],
+      scale
+    } = config;
+    const getScaleValue = createScaleLookup(scale);
+    const alwaysTransform = scale === undefined || isArray(scale);
+    return {
+      ...config,
+      prop,
+      styleFn: (value, prop, props) => {
+        const styles = {};
+        if (isUndefined(value)) {
+          return styles;
+        }
+        let useTransform = false;
+        let intermediateValue;
+        let scaleValue;
+        switch (typeof value) {
+          case 'number':
+          case 'string':
+            scaleValue = getScaleValue(value, props);
+            useTransform = scaleValue !== undefined || alwaysTransform;
+            intermediateValue = scaleValue ?? value;
+            break;
+          case 'function':
+            if (props.theme) {
+              intermediateValue = value(props.theme);
+            }
+            break;
+          default:
+            return styles;
+        }
+
+        // for each property look up the scale value from theme if passed and apply any
+        // final transforms to the value
+        properties.forEach(property => {
+          let styleValue = intermediateValue;
+          if (useTransform && !isUndefined(styleValue)) {
+            styleValue = transform(styleValue, property, props);
+          }
+          switch (typeof styleValue) {
+            case 'number':
+            case 'string':
+              return styles[property] = styleValue;
+            case 'object':
+              return Object.assign(styles, styleValue);
+            default:
+          }
+        });
+        // return the resulting styles object
+        return styles;
+      }
+    };
+  },
+  compose(...parsers) {
+    return this.createParser(parsers.reduce((carry, parser) => ({
+      ...carry,
+      ...parser.config
+    }), {}));
+  },
+  createCss(config) {
+    const parser = this.create(config);
+    const filteredProps = parser.propNames;
+    return cssProps => {
+      let cache;
+      const allKeys = Object.keys(cssProps);
+
+      /** Any key of the CSSProps that is not a System Prop or a Static CSS Property is treated as a nested selector */
+      const selectors = allKeys.filter(key => !filteredProps.includes(key) && isObject(cssProps[key]));
+
+      /** Static CSS Properties get extracted if they match neither syntax */
+      const staticCss = getStaticCss(cssProps, ['theme',
+      // Just in case this gets passed somehow
+      ...selectors, ...filteredProps]);
+      return ({
+        theme
+      }) => {
+        if (cache) return cache;
+        const css = parser({
+          ...cssProps,
+          theme
+        });
+        selectors.forEach(selector => {
+          const selectorConfig = cssProps[selector] ?? {};
+          css[selector] = {
+            ...getStaticCss(selectorConfig, filteredProps),
+            ...parser({
+              ...selectorConfig,
+              theme
+            })
+          };
+        });
+
+        /** Merge the static and generated css and save it to the cache */
+        cache = {
+          ...staticCss,
+          ...css
+        };
+        return cache;
+      };
+    };
+  },
+  createVariant(config) {
+    const css = this.createCss(config);
+    return ({
+      prop = 'variant',
+      defaultVariant,
+      base = {},
+      variants
+    }) => {
+      const baseFn = css(base);
+      const variantFns = {};
+      Object.keys(variants).forEach(key => {
+        const variantKey = key;
+        const cssProps = variants[variantKey];
+        variantFns[variantKey] = css(cssProps);
+      });
+      return props => {
+        const {
+          [prop]: selected = defaultVariant
+        } = props;
+        const styles = {};
+        if (!selected) return styles;
+        return merge(styles, baseFn(props), variantFns?.[selected]?.(props));
+      };
+    };
+  },
+  createStates(config) {
+    const css = this.createCss(config);
+    return states => {
+      const orderedStates = Object.keys(states);
+      const stateFns = {};
+      orderedStates.forEach(key => {
+        const stateKey = key;
+        const cssProps = states[stateKey];
+        stateFns[stateKey] = css(cssProps);
+      });
+      return props => {
+        const styles = {};
+        orderedStates.forEach(state => {
+          merge(styles, props[state] && stateFns[state](props));
+        });
+        return styles;
+      };
+    };
+  },
+  create(config) {
+    const transforms = {};
+
+    // Create a transform function for each of the props
+    for (const prop in config) {
+      if (typeof prop === 'string') {
+        transforms[prop] = this.createTransform(prop, config[prop]);
+      }
+    }
+
+    // Create a parser that handles all the props within the config
+    return this.createParser(transforms);
+  }
+};

package/dist/createTheme/createTheme.d.ts

@@ -0,0 +1,55 @@
+import { CSSObject } from '../types/props';
+import { AbstractTheme } from '../types/theme';
+import { LiteralPaths } from '../utils/flattenScale';
+import { KeyAsVariable } from '../utils/serializeTokens';
+import { ColorModeConfig, Merge, MergeTheme, PrivateThemeKeys } from './types';
+declare class ThemeBuilder<T extends AbstractTheme> {
+    #private;
+    constructor(baseTheme: T);
+    /**
+     *
+     * @param key A key of the current theme to transform into CSS Variables and Variable References
+     * @example .createScaleVariables('fontSize')
+     */
+    createScaleVariables<Key extends keyof Omit<T, 'breakpoints'> & string>(key: Key): ThemeBuilder<MergeTheme<T, PrivateThemeKeys, Record<Key, Record<Key, KeyAsVariable<T[Key], Key>>>>>;
+    /**
+     *
+     * @param colors A map of color tokens to add to the theme. These tokens are immediately converted to CSS Variables `--color-${key}`.
+     * @example .addColors({ navy: 'navy', hyper: 'purple' })
+     */
+    addColors<Colors extends Record<string, string | number | CSSObject>, NextColors extends LiteralPaths<Colors, '-'>>(colors: Colors): ThemeBuilder<MergeTheme<T & PrivateThemeKeys, Record<'colors', KeyAsVariable<NextColors, 'color'>>>>;
+    /**
+     *
+     * @param initialMode A key of the object passed for modes.  This sets the default state for the theme and transforms the correct variables.
+     * @param modes A map of color modes with keys of each possible mode with a value of alias to color keys.  This must be called after `addColors`
+     * @example .addColorModes('light', { light: { primary: 'hyper' }, { dark: { primary: 'navy' } } })
+     */
+    addColorModes<Modes extends string, InitialMode extends keyof Config, Colors extends keyof T['colors'], ModeColors extends ColorModeConfig<Colors>, Config extends Record<Modes, ModeColors>, ColorAliases extends {
+        [K in keyof Config]: LiteralPaths<Config[K], '-', '_'>;
+    }>(initialMode: InitialMode, modeConfig: Config): ThemeBuilder<MergeTheme<T & PrivateThemeKeys, {
+        colors: KeyAsVariable<LiteralPaths<Config[keyof Config], '-', '_'>, 'colors'> & T['colors'];
+        modes: Merge<T['modes'], ColorAliases>;
+        mode: keyof Config;
+        _getColorValue: (color: keyof T['colors']) => string;
+    }>>;
+    /**
+     *
+     * @param key A new key of theme
+     * @param createScale A function that accepts the current theme and returns a new object of scale values.
+     * @example .addScale('fonts', () => ({ basic: 'Gotham', cool: 'Wingdings' }))
+     */
+    addScale<Key extends string, Fn extends (theme: T) => Record<string | number, string | number | Record<string, string | number>>, NewScale extends LiteralPaths<ReturnType<Fn>, '-'>>(key: Key, createScale: Fn): ThemeBuilder<MergeTheme<T, Record<Key, NewScale>>>;
+    /**
+     *
+     * @param key A current key of theme to be updated with new or computed values
+     * @param updateFn A function that accepts an argument of the current values at the specified keys an returns a map of new values to merge.
+     * @example .updateScale('fonts', ({ basic }) => ({ basicFallback: `{basic}, Montserrat` }))
+     */
+    updateScale<Key extends keyof T, Fn extends (tokens: T[Key]) => Record<string | number, unknown>>(key: Key, updateFn: Fn): ThemeBuilder<T & Record<Key, T[Key] & ReturnType<Fn>>>;
+    /**
+     * This finalizes the theme build and returns the final theme and variables to be provided.
+     */
+    build(): T & PrivateThemeKeys;
+}
+export declare function createTheme<T extends AbstractTheme>(base: T): ThemeBuilder<T>;
+export {};

package/dist/createTheme/createTheme.js

@@ -0,0 +1,121 @@
+import mapValues from 'lodash/mapValues';
+import merge from 'lodash/merge';
+import { flattenScale } from '../utils/flattenScale';
+import { serializeTokens } from '../utils/serializeTokens';
+class ThemeBuilder {
+  #theme = {};
+  constructor(baseTheme) {
+    this.#theme = baseTheme;
+  }
+  /**
+   *
+   * @param key A key of the current theme to transform into CSS Variables and Variable References
+   * @example .createScaleVariables('fontSize')
+   */
+  createScaleVariables(key) {
+    const {
+      variables,
+      tokens
+    } = serializeTokens(this.#theme[key], key, this.#theme);
+    this.#theme = merge({}, this.#theme, {
+      [key]: tokens,
+      _variables: {
+        root: variables
+      },
+      _tokens: {
+        [key]: this.#theme[key]
+      }
+    });
+    return this;
+  }
+
+  /**
+   *
+   * @param colors A map of color tokens to add to the theme. These tokens are immediately converted to CSS Variables `--color-${key}`.
+   * @example .addColors({ navy: 'navy', hyper: 'purple' })
+   */
+  addColors(colors) {
+    const flatColors = flattenScale(colors);
+    const {
+      variables,
+      tokens
+    } = serializeTokens(flatColors, 'color', this.#theme);
+    this.#theme = merge({}, this.#theme, {
+      colors: tokens,
+      _variables: {
+        root: variables
+      },
+      _tokens: {
+        colors: flatColors
+      }
+    });
+    return this;
+  }
+
+  /**
+   *
+   * @param initialMode A key of the object passed for modes.  This sets the default state for the theme and transforms the correct variables.
+   * @param modes A map of color modes with keys of each possible mode with a value of alias to color keys.  This must be called after `addColors`
+   * @example .addColorModes('light', { light: { primary: 'hyper' }, { dark: { primary: 'navy' } } })
+   */
+  addColorModes(initialMode, modeConfig) {
+    const modes = mapValues(modeConfig, mode => flattenScale(mode));
+    const {
+      tokens: colors,
+      variables
+    } = serializeTokens(mapValues(merge({}, this.#theme.modes?.[initialMode], modes[initialMode]), color => this.#theme.colors[color]), 'color', this.#theme);
+    const getColorValue = color => this.#theme._tokens?.colors?.[color];
+    this.#theme = merge({}, this.#theme, {
+      colors,
+      modes,
+      mode: initialMode,
+      _getColorValue: getColorValue,
+      _variables: {
+        mode: variables
+      },
+      _tokens: {
+        modes: mapValues(modes, mode => mapValues(mode, getColorValue))
+      }
+    });
+    return this;
+  }
+
+  /**
+   *
+   * @param key A new key of theme
+   * @param createScale A function that accepts the current theme and returns a new object of scale values.
+   * @example .addScale('fonts', () => ({ basic: 'Gotham', cool: 'Wingdings' }))
+   */
+  addScale(key, createScale) {
+    this.#theme = merge({}, this.#theme, {
+      [key]: flattenScale(createScale(this.#theme))
+    });
+    return this;
+  }
+
+  /**
+   *
+   * @param key A current key of theme to be updated with new or computed values
+   * @param updateFn A function that accepts an argument of the current values at the specified keys an returns a map of new values to merge.
+   * @example .updateScale('fonts', ({ basic }) => ({ basicFallback: `{basic}, Montserrat` }))
+   */
+  updateScale(key, updateFn) {
+    this.#theme = merge({}, this.#theme, {
+      [key]: updateFn(this.#theme[key])
+    });
+    return this;
+  }
+
+  /**
+   * This finalizes the theme build and returns the final theme and variables to be provided.
+   */
+  build() {
+    return merge({}, this.#theme, {
+      _variables: {},
+      _tokens: {}
+    });
+  }
+}
+export function createTheme(base) {
+  return new ThemeBuilder(base);
+}

package/dist/createTheme/createTheme.test.js

@@ -0,0 +1,176 @@
+import mapValues from 'lodash/mapValues';
+import { createTheme } from './createTheme';
+describe('createTheme', () => {
+  const base = {
+    breakpoints: {
+      xs: '1',
+      sm: '2',
+      md: '3',
+      lg: '4',
+      xl: '5'
+    }
+  };
+  it('works', () => {
+    expect(createTheme(base).build()).toEqual({
+      ...base,
+      _variables: {},
+      _tokens: {}
+    });
+  });
+  it('adds a scale', () => {
+    const theme = createTheme(base).addScale('test', () => ({
+      test: 1,
+      test2: 2
+    })).build();
+    expect(theme.test).toEqual({
+      test: 1,
+      test2: 2
+    });
+  });
+  it('updates a scale', () => {
+    const builder = createTheme(base).addScale('test', () => ({
+      test: 1,
+      test2: 2
+    }));
+    expect(builder.build().test).toEqual({
+      test: 1,
+      test2: 2
+    });
+    builder.updateScale('test', () => ({
+      test3: 3
+    }));
+    expect(builder.build().test).toEqual({
+      test: 1,
+      test2: 2,
+      test3: 3
+    });
+  });
+  it('serializes variables', () => {
+    const theme = createTheme(base).addScale('test', () => ({
+      test: 1,
+      test2: 2
+    })).createScaleVariables('test').build();
+    expect(theme.test).toEqual({
+      test: 'var(--test-test)',
+      test2: 'var(--test-test2)'
+    });
+    expect(theme._variables.root).toEqual({
+      '--test-test': 1,
+      '--test-test2': 2
+    });
+  });
+  describe('colors', () => {
+    const staticColors = {
+      white: 'white',
+      black: 'black',
+      blue: 'blue',
+      green: 'green',
+      red: 'red'
+    };
+    const cssVariableReferences = mapValues(staticColors, val => `var(--color-${val})`);
+    const builder = createTheme(base);
+    it('creates color variables', () => {
+      const theme = builder.addColors(staticColors).build();
+      expect(theme.colors).toEqual(cssVariableReferences);
+    });
+    it('adds colorModes', () => {
+      const theme = builder.addColors(staticColors).addColorModes('light', {
+        light: {
+          primary: 'red'
+        },
+        dark: {
+          primary: 'blue'
+        }
+      }).build();
+      expect(theme.colors).toEqual({
+        ...mapValues(staticColors, val => `var(--color-${val})`),
+        primary: 'var(--color-primary)'
+      });
+      expect(theme._variables.mode).toEqual({
+        '--color-primary': 'var(--color-red)'
+      });
+    });
+    it('returns value checker for colors', () => {
+      const theme = builder.addColors({
+        black: '#000000',
+        white: '#FFFFFF'
+      }).addColorModes('light', {
+        light: {
+          primary: 'black'
+        },
+        dark: {
+          primary: 'white'
+        }
+      }).build();
+      expect(theme._getColorValue('white')).toEqual('#FFFFFF');
+      expect(theme._getColorValue(theme.modes.light.primary)).toEqual('#000000');
+    });
+    it('returns value checker for colors with deep values', () => {
+      const theme = builder.addColors({
+        black: '#000000',
+        white: '#FFFFFF',
+        gray: {
+          200: '#eeeeee',
+          300: '#666666'
+        }
+      }).addColorModes('light', {
+        light: {
+          primary: {
+            default: 'gray-200',
+            cool: {
+              _: 'gray-300',
+              town: 'black'
+            }
+          }
+        }
+      }).build();
+      expect(theme._getColorValue('gray-300')).toEqual('#666666');
+      expect(theme._getColorValue(theme.modes.light['primary-default'])).toEqual('#eeeeee');
+    });
+    it('merges color mode configurations when overriden', () => {
+      const theme = builder.addColors({
+        black: '#000000',
+        white: '#FFFFFF'
+      }).addColorModes('light', {
+        light: {
+          primary: {
+            _: 'black',
+            hover: 'white'
+          }
+        }
+      }).build();
+      const override = createTheme(theme).addColorModes('light', {
+        light: {
+          primary: {
+            _: 'white',
+            hover: 'black'
+          }
+        }
+      }).build();
+      expect(override.modes.light.primary).toEqual('white');
+    });
+    it('returns the raw values of color mode colors on the tokens object', () => {
+      const theme = createTheme(base).addColors({
+        black: '#000000',
+        gray: {
+          300: '#666666'
+        }
+      }).addColorModes('light', {
+        light: {
+          primary: {
+            cool: {
+              _: 'gray-300',
+              town: 'black'
+            }
+          }
+        }
+      }).build();
+      expect(theme._tokens.modes).toEqual({
+        light: {
+          'primary-cool': '#666666',
+          'primary-cool-town': '#000000'
+        }
+      });
+    });
+  });
+});

package/dist/createTheme/index.d.ts

@@ -0,0 +1,3 @@
+export * from './createTheme';
+export * from '../utils/serializeTokens';
+export * from '../utils/flattenScale';

package/dist/createTheme/index.js

@@ -0,0 +1,3 @@
+export * from './createTheme';
+export * from '../utils/serializeTokens';
+export * from '../utils/flattenScale';

package/dist/createTheme/types.d.ts

@@ -0,0 +1,42 @@
+import { CSSObject } from '../types/props';
+import { AbstractTheme } from '../types/theme';
+/**
+ * This is a custom generic that ensures the safety of adding additional values to a theme object without accidentally wiping out
+ * required keys like `breakpoints`.  It works by creating a new mapped type and merging the values of the union of Base & Next:
+ * 1. If the key exists on both Base and Next return the intersection of both values
+ * 2. If the key exists on next use the value on next.
+ * 3. If the key exists on base but nothing else use the value on base.
+ *
+ * The resulting type is then rejoined with keys that cannot be mutated (breakpoints) as the next version of Theme
+ */
+export type MergeTheme<Base extends AbstractTheme, Next, Unmergable = Record<'breakpoints', Base['breakpoints']>> = Unmergable & Merge<Base, Next>;
+/** This merges at 2 levels of depth */
+export type Merge<A, B> = {
+    [K in keyof (A & B)]: K extends keyof B ? K extends keyof A ? AssignValueIfUnmergable<A[K], B[K]> : B[K] : K extends keyof A ? A[K] : never;
+};
+/** Extract mergable objects */
+export type Mergable<T> = Exclude<T, ((...args: any) => any) | string | boolean | symbol | number | any[]>;
+/** Return B if either A or B is unmergable */
+export type AssignValueIfUnmergable<A, B> = Mergable<A> extends never ? B : Mergable<B> extends never ? B : Assign<A, B>;
+/** Prefer all values from B */
+export type Assign<A, B> = {
+    [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never;
+};
+/** These are keys that are consistent for all theme builds - they are loosely typed as they are not meant to be accessed directly */
+export type PrivateThemeKeys = {
+    _variables: Record<string, CSSObject>;
+    _tokens: Record<string | number, any>;
+};
+/** This allows 3 layers of color aliases to be constructed when adding colorModes
+ * @example
+ * {
+ *   button: {
+ *     bg: {
+ *       hover: 'someAlias'
+ *     }
+ *   }
+ * }
+ *
+ * `button-bg-hover`
+ * */
+export type ColorModeConfig<Colors> = Record<string, Colors | Record<string, Colors> | Record<string, Colors | Record<string, Colors>>>;

package/dist/createTheme/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { variance } from './core';
+export * from './createTheme';
+export * from './types/props';
+export * from './transforms';
+export * from './scales/createScale';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { variance } from './core';
+export * from './createTheme';
+export * from './types/props';
+export * from './transforms';
+export * from './scales/createScale';

package/dist/scales/createScale.d.ts

@@ -0,0 +1,3 @@
+export declare const createScale: <T extends string | number>() => readonly T[] & {
+    length: 0;
+};

package/dist/scales/createScale.js

@@ -0,0 +1 @@
+export const createScale = () => [];

package/dist/scales/createScaleLookup.d.ts

@@ -0,0 +1,5 @@
+import { Prop } from '../types/config';
+import { ThemeProps } from '../types/props';
+type GetScaleValue = (val: string | number, props: ThemeProps) => string | number | undefined;
+export declare const createScaleLookup: (scale: Prop['scale']) => GetScaleValue;
+export {};