scss - include SCSS variables as CSS variables in themes

Author: cscheid

src/command/render/pandoc-html.ts

@@ -53,7 +53,7 @@ export async function resolveSassBundles(
   extras: FormatExtras,
   format: Format,
   temp: TempContext,
-  project?: ProjectContext,
+  project: ProjectContext,
 ) {
   extras = cloneDeep(extras);
 
@@ -286,6 +286,29 @@ async function resolveQuartoSyntaxHighlighting(
   if (themeDescriptor) {
     // Other variables that need to be injected (if any)
     const extraVariables = extras.html?.[kQuartoCssVariables] || [];
+    for (let i = 0; i < extraVariables.length; ++i) {
+      // For the same reason as outlined in https://github.com/rstudio/bslib/issues/1104,
+      // we need to patch the text to include a semicolon inside the declaration
+      // if it doesn't have one.
+      // This happens because scss-parser is brittle, and will fail to parse a declaration
+      // if it doesn't end with a semicolon.
+      //
+      // In addition, we know that some our variables come from the output
+      // of sassCompile which
+      // - misses the last semicolon
+      // - emits a :root declaration
+      // - triggers the scss-parser bug
+      // So we'll attempt to target the last declaration in the :root
+      // block specifically and add a semicolon if it doesn't have one.
+      let variable = extraVariables[i].trim();
+      if (
+        variable.endsWith("}") && variable.startsWith(":root") &&
+        !variable.match(/.*;\s?}$/)
+      ) {
+        variable = variable.slice(0, -1) + ";}";
+        extraVariables[i] = variable;
+      }
+    }
 
     // The text highlighting CSS variables
     const highlightCss = generateThemeCssVars(themeDescriptor.json);
@@ -308,7 +331,7 @@ async function resolveQuartoSyntaxHighlighting(
       // Add this string literal to the rule set, which prevents pandoc
       // from inlining this style sheet
       // See https://github.com/jgm/pandoc/commit/7c0a80c323f81e6262848bfcfc922301e3f406e0
-      rules.push(".prevent-inlining { content: '</' }");
+      rules.push(".prevent-inlining { content: '</'; }");
 
       // Compile the scss
       const highlightCssPath = await compileSass(

src/core/sass.ts

@@ -16,6 +16,7 @@ import { dartCompile } from "./dart-sass.ts";
 import * as ld from "./lodash.ts";
 import { lines } from "./text.ts";
 import { sassCache } from "./sass/cache.ts";
+import { cssVarsBlock } from "./sass/add-css-vars.ts";
 import { md5HashBytes } from "./hash.ts";
 import { kSourceMappingRegexes } from "../config/constants.ts";
 import { writeTextFileSyncPreserveMode } from "./write.ts";
@@ -44,6 +45,7 @@ export function outputVariable(
   return `$${variable.name}: ${variable.value}${isDefault ? " !default" : ""};`;
 }
 
+let counter: number = 1;
 export async function compileSass(
   bundles: SassBundleLayers[],
   temp: TempContext,
@@ -104,39 +106,83 @@ export async function compileSass(
   // * Mixins are available to rules as well
   // * Rules may use functions, variables, and mixins
   //   (theme follows framework so it can override the framework rules)
-  const scssInput = [
+  let scssInput = [
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...frameWorkUses,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...quartoUses,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...userUses,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...frameworkFunctions,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...quartoFunctions,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...userFunctions,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...userDefaults.reverse(),
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...quartoDefaults.reverse(),
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...frameworkDefaults.reverse(),
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...frameworkMixins,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...quartoMixins,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...userMixins,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...frameworkRules,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...quartoRules,
+    '// quarto-scss-analysis-annotation { "origin": null }',
     ...userRules,
+    '// quarto-scss-analysis-annotation { "origin": null }',
   ].join("\n\n");
-
-  const hash = md5HashBytes(new TextEncoder().encode(scssInput));
+  try {
+    scssInput += "\n" + cssVarsBlock(scssInput);
+  } catch (e) {
+    console.error("Error adding css vars block", e);
+    Deno.writeTextFileSync("scss-error.scss", scssInput);
+    console.error(
+      "This is a Quarto bug.\nPlease consider reporting it at https://github.com/quarto-dev/quarto-cli,\nalong with the scss-error.scss file that can be found in the current working directory.",
+    );
+    throw e;
+  }
 
   // Compile the scss
-  // Note that you can set this to undefined to bypass the cache entirely
-  const cacheKey = hash;
-  // bundles.map((bundle) => bundle.key).join("|") + "-" +
-  //   (minified ? "min" : "nomin");
-
-  return await compileWithCache(
+  const result = await compileWithCache(
     scssInput,
     loadPaths,
     temp,
     minified,
-    cacheKey,
+    md5HashBytes(new TextEncoder().encode(scssInput)),
+  );
+  if (!Deno.env.get("QUARTO_SAVE_SCSS")) {
+    return result;
+  }
+  const partialOutput = Deno.readTextFileSync(result);
+  // now we attempt to find the SCSS variables in the output
+  // and inject them back in the SCSS file so that our debug tooling can use them.
+  const scssToWrite = [scssInput];
+  const internalVars = Array.from(
+    partialOutput.matchAll(/(--quarto-scss-export-[^;}]+;?)/g),
+  ).map((m) => m[0]);
+  const annotation = {
+    "css-vars": internalVars,
+  };
+  scssToWrite.push(
+    `// quarto-scss-analysis-annotation ${JSON.stringify(annotation)}`,
   );
+  scssInput = scssToWrite.join("\n");
+  const prefix = Deno.env.get("QUARTO_SAVE_SCSS");
+  const counterValue = counter++;
+  Deno.writeTextFileSync(
+    `${prefix}-${counterValue}.scss`,
+    scssInput,
+  );
+
+  return result;
 }
 
 /*-- scss:uses --*/

src/core/sass/analyzer/ast-utils.ts

@@ -0,0 +1,69 @@
+export const walk = (node: any, cb: (node: any) => unknown) => {
+  if (!node || typeof node !== "object") return;
+  if (!cb(node)) {
+    return;
+  };
+  for (const key of Object.keys(node)) {
+    walk(node[key], cb);
+  }
+}
+
+export const withType = (node: any, func: (ast: any) => any) => {
+  if (!node?.type) {
+    return node;
+  }
+  return func(node);
+}
+
+export const withTypeAndArray = (node: any, func: (ast: any) => any) => {
+  if (!node?.type) {
+    return node;
+  }
+  if (!node?.children || !Array.isArray(node.children)) {
+    return node;
+  }
+  return func(node);
+}
+
+export const filterDeep = (outer: any, cb: (v: any) => boolean): any =>
+  withType(outer, (ast: any) => {
+    return Object.fromEntries(Object.entries(ast).map(([k, v]) => {
+      if (Array.isArray(v)) {
+        return [k, v.filter(cb).map((v: any) => filterDeep(v, cb))];
+      } else if (v && typeof v === "object") {
+        return [k, filterDeep(v, cb)];
+      } else {
+        return [k, v];
+      }
+    }));
+  });
+
+  export const mapDeep = (outer: any, cb: (mapped: any) => any): any =>
+  withType(outer, (ast: any) => {
+    if (Array.isArray(ast.children)) {
+      ast.children = ast.children.map((v: any) => mapDeep(v, cb));
+    }
+    if (Array.isArray(ast.value)) {
+      ast.value = ast.value.map((v: any) => mapDeep(v, cb));
+    }
+    return cb(ast);
+  });
+
+export const collect = (outer: any, cb: (v: any) => boolean): any[] => {
+  const results: any = [];
+  walk(outer, (node: any) => {
+    if (cb(node)) {
+      results.push(node);
+    }
+    return true;
+  });
+  return results;
+}
+
+export const annotateNode = (node: any, annotation: Record<string, unknown>) => {
+  if (!node.annotation) {
+    node.annotation = {};
+  }
+  Object.assign(node.annotation, annotation);
+  return node;
+}

src/core/sass/analyzer/clean-ast.ts

@@ -0,0 +1,56 @@
+import { withTypeAndArray, filterDeep, mapDeep } from "./ast-utils.ts";
+import { isRealContent, isNotPunctuation } from "./remove-nonsemantic-entries.ts";
+import { simplifyLineInfo } from "./line-info.ts";
+import { explicitlyTagDefaultValues } from "./default-declarations.ts";
+import { fixImmediateTypes, tagNamedColors, tagColorConstructors, findDimensionValues } from "./value-types.ts";
+import { groupArguments } from "./group-arguments.ts";
+import { forwardAnnotations } from "./forward-annotations.ts";
+
+const valueArrayToObjectKeys = (outer: any) => 
+  withTypeAndArray(outer, (node: any) => {
+    const keys = node.children.map((v: any) => v.type);
+    if (keys.length !== new Set(keys).size) {
+      return node;
+    }
+    return {
+      ...node,
+      ...Object.fromEntries(node.children
+        .map((v: any) => {
+          const key = v.type;
+          let children = v.children;
+          return [key, {...v, children}];
+        })),
+    };
+  });
+
+export const cleanSassAst = (ast: any) => {
+  // we now attempt to turn this glorified lexer into a real AST
+
+  // before everything else, we associate declarations with the
+  // annotations that tell us which part of the theming system
+  // they belong to
+  ast = forwardAnnotations(ast);
+
+  // before clearing out the punctuation, group arguments
+  ast = filterDeep(ast, isRealContent);
+  ast = mapDeep(ast, groupArguments);
+
+  // clear out all the gunk from the AST
+  ast = filterDeep(ast, isNotPunctuation);
+
+  ast = mapDeep(ast, simplifyLineInfo);
+  ast = mapDeep(ast, explicitlyTagDefaultValues);
+  ast = mapDeep(ast, findDimensionValues);
+  ast = mapDeep(ast, fixImmediateTypes);
+  ast = mapDeep(ast, tagColorConstructors);
+  ast = mapDeep(ast, tagNamedColors);
+
+  // if the value array looks like an array of keys and values,
+  // insert those values into the parent object
+  // additionally, in these properties, if the value is an array
+  // with a single element, remove the array and just use the
+  // element.
+  ast = mapDeep(ast, valueArrayToObjectKeys);
+
+  return ast;
+}