Add folding support to code blocks (#12680)

This adds support for defining **folding ranges** in any code block.

Folding ranges can be defined by specifying `foldable` on the code block
and using `[*` and `*]` lines in the code, and will be transformed to
collapsible sections with a toggle marker and indicator line. Folding
ranges can be nested. By default folding ranges are open, but can be set
to initially closed using `[* -`.

When using line numbers, the folding range markers and lines will be
shifted to the right of the line numbers.

Author: schultek

site/lib/_sass/components/_code.scss

@@ -142,13 +142,111 @@ pre {
     span.line {
       padding-left: 0.5rem;
 
-      &[data-line]::before {
-        display: inline-block;
-        content: attr(data-line) "";
-        width: 2em;
-        margin-right: 0.5rem;
-        text-align: right;
-        color: var(--site-base-fgColor-alt);
+      &[data-line] {
+        padding-left: 0;
+
+        &::before {
+          display: inline-block;
+          content: attr(data-line) "";
+          width: 2em;
+          margin-right: 1rem;
+          text-align: right;
+          color: var(--site-base-fgColor-alt);
+        }
+      }
+    }
+  }
+
+  &.show-folding-ranges code {
+
+    --folding-inset: 0px;
+
+    // A folding range.
+    details {
+      margin: 0;
+      position: relative;
+
+      --level: 0;
+      --inset: calc(var(--folding-inset) + 2px + (var(--level) * 1em));
+
+      // Vertical line drawn along a folding range.
+      &::before {
+        content: "";
+        display: none;
+        position: absolute;
+        // inset + caret width/2 - line width/2
+        left: calc(var(--inset) + .5em - .5px);
+        width: 1px;
+        background: var(--site-inset-borderColor);
+        height: calc(100% - 1lh);
+        top: .8lh;
+      }
+
+      summary {
+        margin: 0;
+        font-weight: initial;
+        user-select: initial;
+        list-style: none;
+        position: relative;
+
+        // Caret at the beginning of the folding range. 
+        span.material-symbols {
+          position: absolute;
+          cursor: pointer;
+          z-index: var(--site-z-base);
+          left: var(--inset);
+          top: 50%;
+          font-size: 1em;
+          user-select: none;
+          translate: 0 -50%;
+          transition: transform 300ms ease;
+          transform: rotate(0);
+          transform-origin: center;
+        }
+
+        &:hover>span {
+          color: initial;
+        }
+      }
+
+      &:not([open])>summary .line {
+        >span {
+          opacity: 0.5;
+        }
+
+        >span::after {
+          content: ' …';
+        }
+      }
+
+      &[open] {
+        &::before {
+          display: block;
+        }
+
+        >summary {
+          cursor: auto;
+
+          span.material-symbols {
+            transform: rotate(90deg);
+          }
+        }
+      }
+
+      >* {
+        margin: 0;
+      }
+    }
+  }
+
+  &.show-line-numbers.show-folding-ranges code {
+    --folding-inset: 2.5em;
+
+    span.line {
+      &[data-line] {
+        &::before {
+          margin-right: 3rem;
+        }
       }
     }
   }

site/lib/src/components/common/wrapped_code_block.dart

@@ -6,6 +6,7 @@ import 'package:jaspr/jaspr.dart';
 
 import '../../util.dart';
 import 'client/copy_button.dart';
+import 'material_icon.dart';
 
 /// A rendered code block with support for syntax highlighting,
 /// line highlighting, filenames, language specifying,
@@ -19,6 +20,7 @@ final class WrappedCodeBlock extends StatelessComponent {
     this.highlightLines = const {},
     this.addedLines = const {},
     this.removedLines = const {},
+    this.foldingRanges = const [],
     this.languagesToHide = const {'plaintext', 'console'},
     this.tag,
     this.initialLineNumber = 1,
@@ -35,6 +37,7 @@ final class WrappedCodeBlock extends StatelessComponent {
   final Set<int> highlightLines;
   final Set<int> addedLines;
   final Set<int> removedLines;
+  final List<FoldingRange> foldingRanges;
   final Set<String> languagesToHide;
   final CodeBlockTag? tag;
   final int initialLineNumber;
@@ -43,14 +46,67 @@ final class WrappedCodeBlock extends StatelessComponent {
 
   @override
   Component build(BuildContext context) {
+    final children = <int, Component>{
+      for (var lineIndex = 0; lineIndex < content.length; lineIndex += 1)
+        lineIndex: span(
+          classes: [
+            'line',
+            if (highlightLines.contains(lineIndex + 1)) 'highlighted-line',
+            if (removedLines.contains(lineIndex + 1)) 'removed-line',
+            if (addedLines.contains(lineIndex + 1)) 'added-line',
+          ].toClasses,
+          attributes: {
+            if (showLineNumbers)
+              'data-line': '${initialLineNumber + lineIndex}',
+          },
+          [
+            switch (content[lineIndex]) {
+              // Add a zero-width space when empty
+              // so that the line isn't collapsed to 0 height.
+              final line when line.isEmpty => span(
+                styles: const Styles(
+                  userSelect: UserSelect.none,
+                ),
+                [text('\u200b')],
+              ),
+              final lineSpans => span(lineSpans),
+            },
+            text('\n'),
+          ],
+        ),
+    };
+
+    if (foldingRanges.isNotEmpty) {
+      for (final (:start, :end, :level, :open) in foldingRanges) {
+        final foldingSummary = children.remove(start - 1);
+        final foldedChildren = [
+          for (var i = start + 1; i <= end; i += 1) ?children.remove(i - 1),
+        ];
+
+        children[start - 1] = details(
+          open: open,
+          styles: Styles(raw: {'--level': '$level'}),
+          [
+            summary(
+              classes: 'fold-summary',
+              [
+                const MaterialIcon('keyboard_arrow_right'),
+                foldingSummary ?? text('...'),
+              ],
+            ),
+            ...foldedChildren,
+          ],
+        );
+      }
+    }
+
     return div(
       classes: 'code-block-wrapper language-$language',
       [
         if (title case final title?)
-          div(
-            classes: 'code-block-header',
-            [text(title)],
-          ),
+          div(classes: 'code-block-header', [
+            text(title),
+          ]),
         div(
           classes: [
             'code-block-body',
@@ -71,47 +127,14 @@ final class WrappedCodeBlock extends StatelessComponent {
             pre(
               classes: [
                 if (showLineNumbers) 'show-line-numbers',
+                if (foldingRanges.isNotEmpty) 'show-folding-ranges',
                 'opal',
               ].toClasses,
               attributes: {'tabindex': '0'},
               [
-                code(
-                  [
-                    for (
-                      var lineIndex = 0;
-                      lineIndex < content.length;
-                      lineIndex += 1
-                    )
-                      span(
-                        classes: [
-                          'line',
-                          if (highlightLines.contains(lineIndex + 1))
-                            'highlighted-line',
-                          if (removedLines.contains(lineIndex + 1))
-                            'removed-line',
-                          if (addedLines.contains(lineIndex + 1)) 'added-line',
-                        ].toClasses,
-                        attributes: {
-                          if (showLineNumbers)
-                            'data-line': '${initialLineNumber + lineIndex}',
-                        },
-                        [
-                          switch (content[lineIndex]) {
-                            // Add a zero-width space when empty
-                            // so that the line isn't collapsed to 0 height.
-                            final line when line.isEmpty => span(
-                              styles: const Styles(
-                                userSelect: UserSelect.none,
-                              ),
-                              [text('\u200b')],
-                            ),
-                            final lineSpans => span(lineSpans),
-                          },
-                          text('\n'),
-                        ],
-                      ),
-                  ],
-                ),
+                code([
+                  for (var i = 0; i < content.length; i += 1) ?children[i],
+                ]),
               ],
             ),
             if (textToCopy case final textToCopy?)
@@ -151,3 +174,5 @@ enum CodeBlockTag {
     _ => throw ArgumentError('Unknown tag for code blocks: $tag'),
   };
 }
+
+typedef FoldingRange = ({int start, int end, int level, bool open});

site/lib/src/extensions/code_block_processor.dart

@@ -88,13 +88,17 @@ final class CodeBlockProcessor implements PageExtension {
             );
           }
 
-          final diffResult = isDiff ? _processDiffLines(lines) : null;
-          final linesWithDiffRemoved = diffResult?.lines ?? lines;
-          final addedLines = diffResult?.addedLines ?? const <int>{};
-          final removedLines = diffResult?.removedLines ?? const <int>{};
+          final isFolding = metadata.containsKey('foldable');
+
+          final diffResult = isDiff
+              ? _processDiffLines(lines)
+              : (lines: lines, addedLines: <int>{}, removedLines: <int>{});
+          final foldingResult = isFolding
+              ? _processFoldingLines(diffResult.lines)
+              : (lines: diffResult.lines, foldingRanges: <FoldingRange>[]);
 
           final codeLines = _removeHighlights(
-            linesWithDiffRemoved,
+            foldingResult.lines,
             skipHighlighting,
           );
           final processedContent = _highlightCode(
@@ -117,8 +121,9 @@ final class CodeBlockProcessor implements PageExtension {
               },
               title: title,
               highlightLines: _parseNumbersAndRanges(rawHighlightLines),
-              addedLines: addedLines,
-              removedLines: removedLines,
+              addedLines: diffResult.addedLines,
+              removedLines: diffResult.removedLines,
+              foldingRanges: foldingResult.foldingRanges,
               tag: tag != null ? CodeBlockTag.parse(tag) : null,
               initialLineNumber: initialLineNumber ?? 1,
               showLineNumbers: showLineNumbers,
@@ -441,6 +446,65 @@ final class CodeBlockProcessor implements PageExtension {
       removedLines: removedLines,
     );
   }
+
+  /// Processes lines for folding mode, extracting folding range line markers.
+  ///
+  /// Lines equal to '[*' are marked as the start of an open folding range.
+  /// Lines equal to '[* -' are marked as the start of a closed folding range.
+  /// Lines equal to '*]' are marked as the end of a folding range.
+  /// The folding markers are removed from the lines.
+  ({
+    List<String> lines,
+    List<FoldingRange> foldingRanges,
+  })
+  _processFoldingLines(List<String> lines) {
+    final foldingRanges = <FoldingRange>[];
+    final processedLines = <String>[];
+    final foldingStack = <({int start, bool open})>[];
+
+    for (var lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+      final line = lines[lineIndex];
+
+      // To account for removal of the folding marker lines.
+      final lineIndexCorrection =
+          (foldingRanges.length * 2) + foldingStack.length;
+
+      if (line.trim() == '[*') {
+        foldingStack.add((
+          start: lineIndex + 1 - lineIndexCorrection,
+          open: true,
+        ));
+        // Skip adding this line to processed lines.
+        continue;
+      } else if (line.trim() == '[* -') {
+        foldingStack.add((
+          start: lineIndex + 1 - lineIndexCorrection,
+          open: false,
+        ));
+        // Skip adding this line to processed lines.
+        continue;
+      } else if (line.trim() == '*]') {
+        if (foldingStack.isNotEmpty) {
+          final (:start, :open) = foldingStack.removeLast();
+          foldingRanges.add((
+            start: start,
+            end: lineIndex - lineIndexCorrection,
+            level: foldingStack.length,
+            open: open,
+          ));
+        }
+        // Skip adding this line to processed lines.
+        continue;
+      }
+
+      processedLines.add(line);
+    }
+
+    return (
+      lines: processedLines,
+      foldingRanges: foldingRanges,
+    );
+  }
 }
 
 @immutable