Add concept of gutter cells

Author: andrewbranch

src/factory/html.js

@@ -30,7 +30,26 @@ function createLineElement(line, meta, index, language, getLineClassName, tokens
   const lineClassName = joinClassNames(getLineClassName(lineData), 'grvsc-line');
   const attrs = mergeAttributes({ class: lineClassName }, line.attrs);
   const children = typeof tokens === 'string' ? [tokens] : mergeSimilarTokens(tokens);
-  return span(attrs, children, { whitespace: TriviaRenderFlags.NoWhitespace });
+  const gutterCells = line.gutterCells.map((cell, i) =>
+    createGutterCellElement(cell, i === line.gutterCells.length - 1)
+  );
+  return span(
+    attrs,
+    [...gutterCells, span({ class: 'grvsc-source' }, children, { whitespace: TriviaRenderFlags.NoWhitespace })],
+    { whitespace: TriviaRenderFlags.NoWhitespace }
+  );
+}
+
+/**
+ * @param {GutterCell} cell
+ * @param {boolean} isLast
+ */
+function createGutterCellElement(cell, isLast) {
+  return span(
+    { class: joinClassNames('grvsc-gutter', cell.className, isLast && 'grvsc-gutter-last') },
+    [escapeHTML(cell.text || '')],
+    { whitespace: TriviaRenderFlags.NoWhitespace }
+  );
 }
 
 /**

src/registerCodeNode.js

@@ -82,7 +82,7 @@ async function registerCodeSpan(
   const [registry, unlockRegistry] = await getTextMateRegistry();
   try {
     /** @type {Line[]} */
-    const lines = [{ text, data: {}, attrs: {} }];
+    const lines = [{ text, data: {}, attrs: {}, gutterCells: [] }];
     const { tokenTypes, languageId } = getGrammar(scope, grammarCache);
     const grammar = await registry.loadGrammarWithConfiguration(scope, languageId, { tokenTypes });
     codeBlockRegistry.register(registryKey, {

src/transformers/getTransformedLines.js

@@ -9,13 +9,18 @@
  * @returns {Promise<Line[]>}
  */
 async function getTransformedLines(transformers, text, languageName, meta) {
-  /** @type {Line[]} */
+  /** @type {Omit<Line, 'gutterCells'>[]} */
   const result = [];
   const rawLines = text.split(/\r?\n/);
   const prevTransformerStates = [];
+  const gutterCellsPerTransformer = [];
+  /** @type {GutterCell[][][]} */
+  const gutterCells = [];
 
   linesLoop: for (let lineIndex = 0; lineIndex < rawLines.length; lineIndex++) {
     let line = rawLines[lineIndex];
+    /** @type {GutterCell[][]} */
+    const lineGutterCells = [];
     const attrs = {};
     const graphQLData = {};
     for (let i = 0; i < transformers.length; i++) {
@@ -33,14 +38,76 @@ async function getTransformedLines(transformers, text, languageName, meta) {
       if (!txResult.line) {
         continue linesLoop;
       }
+      if (txResult.gutterCells) {
+        gutterCellsPerTransformer[i] = Math.max(txResult.gutterCells.length, gutterCellsPerTransformer[i] || 0);
+        lineGutterCells[i] = txResult.gutterCells;
+      }
       line = txResult.line.text;
       Object.assign(attrs, txResult.line.attrs);
       Object.assign(graphQLData, txResult.data);
     }
+    gutterCells.push(lineGutterCells);
     result.push({ text: line, attrs, data: graphQLData });
   }
 
-  return result;
+  const flattenedGutterCells = flattenGutterCells(gutterCells, gutterCellsPerTransformer);
+  return result.map((line, i) => ({ ...line, gutterCells: flattenedGutterCells[i] }));
+}
+
+/**
+ * Transforms a 3D array of gutter cells into a 2D array of gutter cells.
+ * The input is in the form of gutter cells per line transformer per line,
+ * whereas the output is is gutter cells per line. Each line transformer can
+ * return more than one gutter cell, and need not return the same number of
+ * cells for each line, so the flattening must be done in a way that ensures
+ * that each line transformer has its gutter cells aligned to the same index
+ * in every line. For example, for the input
+ *
+ * ```
+ * [
+ *   [[t0],       [t1a, t1b], [t2]],       // Line 1
+ *   [undefined,  [t1],       [t2]],       // Line 2
+ *   [[t0a, t0b], undefined,  [t2a, t2b]]  // Line 3
+ * ]
+ * ```
+ *
+ * we would flatten to
+ *
+ * ```
+ * [
+ *   [t0,        undefined, t1a,       t1b,       t2,  undefined], // Line 1
+ *   [undefined, undefined, t1,        undefined, t2,  undefined], // Line 2
+ *   [t0a,       t0b,       undefined, undefined, t2a, t2b]        // Line 3
+ * ]
+ * ```
+ *
+ * such that each of the three transformers (t0, t1, t2) reserve two gutter
+ * cells for itself, padding empty spaces in the final array with `undefined`
+ * to ensure correct vertical alignment.
+ *
+ * The parameter `gutterCellsPerTransformer` can be derived from `gutterCells`,
+ * but as an optimization, we already know it from previously iterating through
+ * line transformer results.
+ *
+ * @param {GutterCell[][][]} gutterCells
+ * @param {number[]} gutterCellsPerTransformer
+ * @returns {GutterCell[][]}
+ */
+function flattenGutterCells(gutterCells, gutterCellsPerTransformer) {
+  return gutterCells.map(transformerResults => {
+    /** @type {GutterCell[]} */
+    const result = [];
+    for (let i = 0; i < transformerResults.length; i++) {
+      const currentTransformerCells = transformerResults[i];
+      const length = currentTransformerCells ? currentTransformerCells.length : 0;
+      const padding = gutterCellsPerTransformer[i] - length;
+      if (currentTransformerCells) {
+        result.push(...currentTransformerCells);
+      }
+      result.fill(undefined, result.length, result.length + padding);
+    }
+    return result;
+  });
 }
 
 module.exports = getTransformedLines;

src/types.d.ts

@@ -180,6 +180,7 @@ interface MarkdownNode extends grvsc.gql.Node {
 }
 
 type Line = {
+  gutterCells: (GutterCell | undefined)[];
   text: string;
   attrs: object;
   data: object;
@@ -213,8 +214,14 @@ interface LineTransformerInfo<T> {
   state: T | undefined;
 }
 
+interface GutterCell {
+  className?: string;
+  text?: string;
+}
+
 interface LineTransformerResult<T> extends LineTransformerInfo<T> {
   data?: object;
+  gutterCells?: (GutterCell | undefined)[];
 }
 
 interface LineTransformerArgs<T> extends LineTransformerInfo<T> {