@workday/canvas-kit-styling-transform 13.2.1 → 13.2.2

package/lib/styleTransform.ts

@@ -0,0 +1,169 @@
+/// <reference types="node" />
+import path from 'node:path';
+import ts from 'typescript';
+
+import {getVariablesFromFiles} from './utils/getCssVariables';
+import {handleCalc} from './utils/handleCalc';
+import {handleCreateStencil} from './utils/handleCreateStencil';
+import {handleCreateStyles} from './utils/handleCreateStyles';
+import {handleCreateVars} from './utils/handleCreateVars';
+import {handleCssVar} from './utils/handleCssVar';
+import {handleInjectGlobal} from './utils/handleInjectGlobal';
+import {handleKeyframes} from './utils/handleKeyframes';
+import {handleParentModifier} from './utils/handleParentModifier';
+import {handlePx2Rem} from './utils/handlePx2Rem';
+import {NodeTransformer, ObjectTransform, TransformerContext} from './utils/types';
+
+export type NestedStyleObject = {[key: string]: string | NestedStyleObject};
+
+export interface StyleTransformerOptions extends TransformerContext {
+  fallbackFiles?: string[];
+  transformers?: NodeTransformer[];
+}
+
+let vars: TransformerContext['names'] = {};
+let extractedNames: TransformerContext['extractedNames'] = {};
+let styles: TransformerContext['styles'] = {};
+let cache: TransformerContext['cache'] = {};
+let loadedFallbacks = false;
+
+/**
+ * The reset is used in tests and should not be called normally.
+ */
+export function _reset() {
+  vars = {};
+  extractedNames = {};
+  styles = {};
+  cache = {};
+  loadedFallbacks = false;
+}
+
+/**
+ * Optional list of transformers. Useful to override for tests
+ */
+const defaultTransformers = [
+  handleKeyframes,
+  handleCreateVars,
+  handleCreateStyles,
+  handleCreateStencil,
+  handleInjectGlobal,
+];
+export default styleTransformer;
+export function styleTransformer(
+  program: ts.Program,
+  {fallbackFiles = [], ...options}: Partial<StyleTransformerOptions> = {}
+): ts.TransformerFactory<ts.SourceFile> {
+  const {names, ...transformContext} = withDefaultContext(program.getTypeChecker(), options);
+
+  if (!loadedFallbacks) {
+    const files: string[] = fallbackFiles
+      .filter(file => file) // don't process empty files
+      .map(file => {
+        // Find the fully-qualified path name. This could error which should give "module not found" errors
+        return file.startsWith('.') ? path.resolve(process.cwd(), file) : require.resolve(file);
+      })
+      .map(file => {
+        console.log(`Loading CSS variable fallback file: ${file}`);
+        return ts.sys.readFile(file) || '';
+      });
+
+    const fallbackVars = getVariablesFromFiles(files);
+    console.log(`Found ${Object.keys(fallbackVars).length} variables.`);
+
+    // eslint-disable-next-line guard-for-in
+    for (const key in fallbackVars) {
+      names[key] = fallbackVars[key];
+    }
+    loadedFallbacks = true;
+  }
+
+  return context => {
+    const visit: ts.Visitor = node => {
+      if (!transformContext.fileName) {
+        transformContext.fileName = node.getSourceFile()?.fileName;
+        transformContext.prefix = transformContext.getPrefix(transformContext.fileName);
+      }
+
+      if (
+        ts.isSourceFile(node) &&
+        node.fileName !== 'test.ts' &&
+        transformContext.styles[transformContext.getFileName(node.fileName)] &&
+        transformContext.extractCSS
+      ) {
+        ts.sys.writeFile(
+          transformContext.getFileName(transformContext.getFileName(node.fileName)),
+          (transformContext.styles[transformContext.getFileName(node.fileName)] || []).join('\n')
+        );
+      }
+
+      const newNode = transformContext.transform(node, {
+        names,
+        ...transformContext,
+      });
+
+      return newNode || ts.visitEachChild(node, visit, context);
+    };
+
+    return (node => ts.visitNode(node, visit)) as ts.Transformer<ts.SourceFile>;
+  };
+}
+
+export function withDefaultContext(
+  checker: ts.TypeChecker,
+  {transformers, ...input}: Partial<StyleTransformerOptions> = {}
+): TransformerContext {
+  return {
+    prefix: 'css',
+    getPrefix: path => input.prefix || 'css',
+    names: vars,
+    extractedNames,
+    styles,
+    cache,
+    checker,
+    seed: '',
+    extractCSS: false,
+    getFileName: path => path.replace(/\.tsx?/, '.css'),
+    objectTransforms: [] as ObjectTransform[],
+    transform: handleTransformers(transformers || defaultTransformers),
+    ...input,
+    propertyTransforms: [handleCalc, handlePx2Rem, handleCssVar, handleParentModifier].concat(
+      input.propertyTransforms || []
+    ),
+  } as TransformerContext;
+}
+
+/**
+ * This function is useful for tests or a custom build. The `styleTransformer` function is used by
+ * the https://www.npmjs.com/package/ts-patch package.
+ */
+export function transform(
+  program: ts.Program,
+  fileName = 'test.ts',
+  options?: Partial<StyleTransformerOptions>
+) {
+  const source =
+    program.getSourceFile(fileName) || ts.createSourceFile(fileName, '', ts.ScriptTarget.ES2019);
+
+  const printer = ts.createPrinter();
+
+  const transformers = [styleTransformer(program, options)];
+
+  return printer.printFile(
+    ts.transform(source, transformers).transformed.find(s => s.fileName === source.fileName) ||
+      source
+  );
+}
+
+const handleTransformers =
+  (transformers: ((node: ts.Node, context: TransformerContext) => ts.Node | void)[]) =>
+  (node: ts.Node, context: TransformerContext) => {
+    return transformers.reduce((result, transformer) => {
+      return result || transformer(node, context);
+    }, undefined as ts.Node | void);
+  };
+
+export function getConfig(basePath = '.') {
+  const tsconfigPath = ts.findConfigFile(basePath, ts.sys.fileExists, 'styling.config.ts');
+
+  return tsconfigPath;
+}

package/lib/utils/createStyleObjectNode.ts

@@ -0,0 +1,105 @@
+import {serializeStyles as serializedStylesEmotion} from '@emotion/serialize';
+import crypto from 'node:crypto';
+import {compile, serialize} from 'stylis';
+import ts from 'typescript';
+
+import {generateUniqueId} from '@workday/canvas-kit-styling';
+
+import {prettyStringify} from './stylisFns';
+import {NestedStyleObject, TransformerContext} from './types';
+
+/**
+ * Creates an AST node representation of the passed in `styleObj`, but in the format of `{name:
+ * string, styles: serializedStyles}`. The `name` is hard-coded here to work with both server-side
+ * and client-side style injection. This results in a stable style key for Emotion while also
+ * optimizing style serialization.
+ *
+ * If `name` is provided, the name will be whatever `name` is, replacing "{hash}" with the hash
+ * created via `serializeStyles`. For example: 'animation-{hash}' will be converted into
+ * 'animation-abc123'
+ */
+export function createStyleObjectNode(styles: string, name?: string) {
+  const styleExpression = ts.factory.createStringLiteral(styles);
+
+  // create an emotion-optimized object: https://github.com/emotion-js/emotion/blob/f3b268f7c52103979402da919c9c0dd3f9e0e189/packages/serialize/src/index.js#L315-L322
+  // Looks like: `{name: $hash, styles: $styleText }`
+  return ts.factory.createObjectLiteralExpression(
+    [
+      ts.factory.createPropertyAssignment(
+        ts.factory.createIdentifier('name'),
+        ts.factory.createStringLiteral(name || generateUniqueId()) // We might be using values that are resolved at runtime, but should still be static. We're only supporting the `cs` function running once per file, so a stable id based on a hash is not necessary
+      ),
+      ts.factory.createPropertyAssignment(
+        ts.factory.createIdentifier('styles'),
+        styleExpression // In the future we can extract CSS from here by running the `stylis` compiler directly. Emotion does this here: https://github.com/emotion-js/emotion/blob/f3b268f7c52103979402da919c9c0dd3f9e0e189/packages/cache/src/index.js#L188-L245
+      ),
+    ],
+    false
+  );
+}
+
+/**
+ * Compiles CSS using stylis. Emotion's `serializeStyles` creates an unwrapped string for cache
+ * storage and it often needs to be wrapped by a CSS selector or `@keyframes`. This function does
+ * this the same way Emotion does it internally.
+ */
+export function compileCSS(input: string): string {
+  return serialize(compile(input), prettyStringify);
+}
+
+/**
+ * Serialize styles and put them to style output. The styles will be serialized via Emotion. Returns
+ * the serialized styles.
+ * @param node
+ * @param input
+ * @param template The template for creating styles for static CSS. There are two placeholders: `%n`
+ * represents the hash name while `%s` represents the string styles.
+ * @param context
+ * @returns
+ */
+export function serializeStyles(
+  node: ts.Node,
+  input: NestedStyleObject | string,
+  template: string,
+  context: TransformerContext
+) {
+  const {getFileName, styles, cache, names, extractedNames} = context;
+  const fileName = getFileName(node.getSourceFile().fileName);
+  const serialized = serializedStylesEmotion([input]);
+  const hash = getHash(node, context);
+  serialized.name = hash;
+
+  if (!cache[hash]) {
+    const styleOutput = compileCSS(
+      template.replace('%s', serialized.styles).replace('%n', serialized.name)
+    );
+
+    let extractedStyleOutput = styleOutput;
+
+    for (const key in names) {
+      if (extractedNames[names[key]]) {
+        // @ts-ignore replaceAll was added in es2021, but our lib versions don't go past es2019. replaceAll is available in node 15+
+        extractedStyleOutput = extractedStyleOutput.replaceAll(
+          names[key],
+          extractedNames[names[key]]
+        );
+      }
+    }
+    styles[fileName] = styles[fileName] || [];
+    styles[fileName].push(extractedStyleOutput);
+    cache[hash] = styleOutput;
+  }
+
+  return serialized;
+}
+
+/**
+ * Generate a deterministic hash that is unique to the seed +
+ */
+export function getHash(node: ts.Node, context: TransformerContext) {
+  const content = context.seed + node.getStart() + node.getEnd();
+  // Convert content to a sha256 hash and then convert to a base36 number for better compression
+  return Number(
+    `0x${crypto.createHash('sha256').update(content).digest('hex').slice(0, 7)}`
+  ).toString(36);
+}

package/lib/utils/getCssVariables.ts

@@ -0,0 +1,36 @@
+import {compile, Element} from 'stylis';
+
+export function getVariablesFromFiles(files: string[]): Record<string, string> {
+  return files.reduce((result, file) => {
+    extractVariables(compile(file));
+    return {...result, ...extractVariables(compile(file))};
+  }, {} as Record<string, string>);
+}
+
+export function extractVariables(
+  blocks: Element[] | string,
+  variables: Record<string, string> = {}
+): Record<string, string> {
+  if (typeof blocks === 'string') {
+    return variables;
+  }
+  return blocks
+    .filter(block => block.type === 'rule')
+    .reduce(
+      (result, rule) => {
+        if (Array.isArray(rule.children)) {
+          rule.children.forEach(child => {
+            if (
+              typeof child.props === 'string' &&
+              child.props.startsWith('--') &&
+              typeof child.children === 'string'
+            ) {
+              result[child.props] = child.children;
+            }
+          });
+        }
+        return result;
+      },
+      {...variables}
+    );
+}

package/lib/utils/getErrorMessage.ts

@@ -0,0 +1,57 @@
+import ts from 'typescript';
+import {TransformerContext} from './types';
+
+/**
+ * Creates an error message around a node. It will look something like:
+ *
+ * ```
+ * Unknown type at: "fontSize".
+ * File: test.ts, Line: 6, Character: 17.
+ * const styles = createStyles({
+ *   fontSize: fontSize
+ *             ========
+ * })
+ * ```
+ */
+export function getErrorMessage(node: ts.Node, context: TransformerContext) {
+  const sourceFile = node.getSourceFile();
+
+  const {line} = node.getSourceFile().getLineAndCharacterOfPosition(node.pos);
+  const lineStarts = sourceFile.getLineStarts();
+
+  const lineStartIndex = lineStarts.findIndex(s => s >= node.pos) - 1;
+
+  // get a whole line's text given a lineStarts index
+  function getLine(sourceFile: ts.SourceFile, startIndex: number) {
+    const lineStarts = sourceFile.getLineStarts();
+
+    return sourceFile.text.substring(
+      lineStarts[Math.max(0, startIndex)],
+      startIndex + 1 >= lineStarts.length ? undefined : lineStarts[startIndex + 1]
+    );
+  }
+
+  // Create a full context message with source code and highlighting
+  const lineBefore = getLine(sourceFile, lineStartIndex - 1);
+  const lineCurrent = getLine(sourceFile, lineStartIndex);
+  const lineAfter = getLine(sourceFile, lineStartIndex + 1);
+  const highlightedLine =
+    ''
+      .padStart(node.getStart() - lineStarts[lineStartIndex], ' ')
+      .padEnd(node.getStart() - lineStarts[lineStartIndex] + node.getWidth(), '=') + '\n';
+
+  /** This should look something like:
+   * ```
+   * const styles = createStyles({
+   *   fontSize: fontSize
+   *             ========
+   * })
+   * ```
+   */
+  const fullContext = lineBefore + lineCurrent + highlightedLine + lineAfter;
+
+  const character = node.getStart() - lineStarts[lineStartIndex];
+  return `File: ${sourceFile.fileName}:${line + 1}:${character}.\n${fullContext}\nOriginal File: ${
+    context.fileName
+  }`;
+}

package/lib/utils/getFallbackVariable.ts

@@ -0,0 +1,34 @@
+/**
+ * Looks for a variable value that doesn't include a fallback and automatically adds one if found in
+ * the current cache of names. This allows fallbacks to be automatically included in environments
+ * without the names defined. This is most useful for Storybook or other sandboxes that may not have
+ * CSS Variables defined. The fallbacks will allow the UI to look correct without additional setup.
+ * Fallbacks come from the `fallbackFiles` transform configuration.
+ */
+export function getFallbackVariable(
+  variableName: string,
+  names: Record<string, string>
+): string | undefined {
+  const variable = variableName.includes('var(') ? variableName : names[variableName];
+  if (variable && variable.includes('var(')) {
+    return variable.replace(
+      /(var\(([A-Za-z0-9\-_]+)\))/,
+      (
+        /** matched substring "var(--var-name)" */ _,
+        /** the full match of the first group "var(--var-name)" */ varMatch,
+        /** the variable name  - match of the second group "--var-name" */ cssVarName
+      ) => {
+        const value = names[cssVarName];
+        if (value && value.startsWith('var')) {
+          return getFallbackVariable(value, names);
+        }
+        return value || varMatch;
+      }
+    );
+  }
+  if (variable) {
+    return variable;
+  }
+
+  return;
+}

package/lib/utils/getHash.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+import crypto from 'node:crypto';
+
+import {TransformerContext} from './types';
+
+export function getHash(node: ts.Node, context: TransformerContext) {
+  const fileName = context.getFileName(node.getSourceFile().fileName);
+  return crypto
+    .createHash('md5')
+    .update(fileName + node.pos) // file name + position should be unique and repeatable
+    .digest('hex')
+    .substring(0, 6);
+}

package/lib/utils/getVarName.ts

@@ -0,0 +1,32 @@
+import ts from 'typescript';
+
+/**
+ * This function returns a calculated name of a node by walking up the AST and looking for nodes
+ * with a `name` property that has an `Identifier` node type. The result is dash-case. This is
+ * useful for automatically generating variable names based on a TS file.
+ *
+ * In the following example, the `baz` node would have a name of `foo-bar-baz`.
+ * ```ts
+ * const foo = {
+ *   bar: {
+ *     baz: ''
+ *   }
+ * }
+ * ```
+ */
+export function getVarName(node: ts.Node, parts: string[] = []): string {
+  // base case. Join all the parts
+  if (!node.parent || node.kind === ts.SyntaxKind.VariableStatement) {
+    return parts.join('.');
+  }
+
+  // Any node with a `name` property that is an identifier can add to the var name
+  if (
+    (node as any).name &&
+    (ts.isIdentifier((node as any).name) || ts.isStringLiteral((node as any).name))
+  ) {
+    return getVarName(node.parent, [(node as any).name.text, ...parts]);
+  }
+
+  return getVarName(node.parent, parts);
+}

package/lib/utils/handleCalc.ts

@@ -0,0 +1,33 @@
+import ts from 'typescript';
+
+import {calc} from '@workday/canvas-kit-styling';
+import {createPropertyTransform} from '../createPropertyTransform';
+import {parseNodeToStaticValue} from './parseNodeToStaticValue';
+
+export const handleCalc = createPropertyTransform((node, context) => {
+  if (
+    ts.isCallExpression(node) &&
+    ts.isPropertyAccessExpression(node.expression) &&
+    ts.isIdentifier(node.expression.expression) &&
+    node.expression.expression.text === 'calc' &&
+    ts.isIdentifier(node.expression.name)
+  ) {
+    function toStaticValue(node: ts.Node) {
+      return parseNodeToStaticValue(node, context);
+    }
+    const args = node.arguments;
+    const method = node.expression.name.text;
+
+    if (method === 'add' || method === 'subtract') {
+      return calc[method](toStaticValue(args[0]).toString(), toStaticValue(args[1]).toString());
+    }
+    if (method === 'multiply' || method === 'divide') {
+      return calc[method](toStaticValue(args[0]).toString(), toStaticValue(args[1]));
+    }
+    if (method === 'negate') {
+      return calc.negate(toStaticValue(args[0]).toString());
+    }
+  }
+
+  return;
+});