sass-site/source/helpers/codeExample.ts

import sass from 'sass';

import { liquidEngine } from './engines';

/**
 * Renders a code example.
 *
 * This takes a block of SCSS and/or indented syntax code, and emits HTML that
 * (combined with JS) will allow users to choose which to display.
 *
 * The SCSS should be separated from the Sass with `===`. For example, in
 * LiquidJS:
 *
 *     {% codeExample 'unique-id-string' %}
 *     .foo {
 *       color: blue;
 *     }
 *     ===
 *     .foo
 *       color: blue
 *     {% endcodeExample %}
 *
 * Different sections can be separated within one syntax (for example, to
 * indicate different files) with `---`. For example, in LiquidJS:
 *
 *     {% codeExample 'unique-id-string' %}
 *     // _reset.scss
 *     * {margin: 0}
 *     ---
 *     // base.scss
 *     @import 'reset';
 *     ===
 *     // _reset.sass
 *     *
 *       margin: 0;
 *     ---
 *     // base.sass
 *     @import reset
 *     {% endcodeExample %}
 *
 * A third section may optionally be provided to represent compiled CSS. If it's
 * not passed and `autogenCSS` is `true`, it's generated from the SCSS source.
 * If the autogenerated CSS is empty, it's omitted entirely.
 *
 * If `syntax` is either `sass` or `scss`, the first section will be
 * interpreted as that syntax and the second will be interpreted (or
 * auto-generated) as the CSS output.
 */
export default async function codeExample(
  contents: string,
  exampleName: string,
  autogenCSS = true,
  syntax: 'sass' | 'scss' | null = null,
) {
  const code = generateCodeExample(contents, autogenCSS, syntax);
  return liquidEngine.renderFile('code_examples/code_example', {
    code,
    exampleName,
  });
}

const generateCodeExample = (
  contents: string,
  autogenCSS: boolean,
  syntax: 'sass' | 'scss' | null,
) => {
  const splitContents = contents.split('\n===\n');

  let scssContents, sassContents, cssContents;
  switch (syntax) {
    case 'scss':
      scssContents = splitContents[0];
      cssContents = splitContents[1];
      break;
    case 'sass':
      sassContents = splitContents[0];
      cssContents = splitContents[1];
      break;
    default:
      scssContents = splitContents[0];
      sassContents = splitContents[1];
      cssContents = splitContents[2];
      if (!sassContents) {
        throw new Error(`Couldn't find === in:\n${contents}`);
      }
      break;
  }

  const scssExamples =
    scssContents?.split('\n---\n').map((str) => str.trim()) ?? [];
  const sassExamples =
    sassContents?.split('\n---\n').map((str) => str.trim()) ?? [];

  if (!cssContents && autogenCSS) {
    const sections = scssContents ? scssExamples : sassExamples;
    if (sections.length !== 1) {
      throw new Error("Can't auto-generate CSS from more than one SCSS block.");
    }
    cssContents = sass.compileString(sections[0], {
      syntax: syntax === 'sass' ? 'indented' : 'scss',
    }).css;
  }

  const cssExamples =
    cssContents?.split('\n---\n').map((str) => str.trim()) ?? [];

  const { canSplit, maxSourceWidth, maxCSSWidth } = getCanSplit(
    scssExamples,
    sassExamples,
    cssExamples,
  );
  let splitLocation: number | null = null;
  if (canSplit) {
    if (maxSourceWidth < 55 && maxCSSWidth < 55) {
      splitLocation = 0.5 * 100;
    } else {
      // Put the split exactly in between the two longest lines.
      splitLocation = 0.5 + ((maxSourceWidth - maxCSSWidth) / 110.0 / 2) * 100;
    }
  }

  return {
    scss: scssExamples,
    sass: sassExamples,
    css: cssExamples,
    canSplit,
    splitLocation,
  };
};

const getCanSplit = (
  scssExamples: string[],
  sassExamples: string[],
  cssExamples: string[],
) => {
  const exampleSourceLengths = [...scssExamples, ...sassExamples].flatMap(
    (source) => source.split('\n').map((line) => line.length),
  );
  const cssSourceLengths = cssExamples.flatMap((source) =>
    source.split('\n').map((line) => line.length),
  );

  const maxSourceWidth = Math.max(...exampleSourceLengths);
  const maxCSSWidth = Math.max(...cssSourceLengths);

  const canSplit = Boolean(maxCSSWidth && maxSourceWidth + maxCSSWidth < 110);

  return {
    canSplit,
    maxSourceWidth,
    maxCSSWidth,
  };
};