[Site] CodeBlock with gutter and line pre-slice

ux.symfony.com/assets/styles/components/_Terminal.scss

@@ -8,6 +8,10 @@
     font-size: 12px;
 }
 
+.Terminal_light {
+    --header-opacity: .25;
+}
+
 .Terminal_header {
     display: flex;
     background-color: var(--bg-header, #0D0D0DBA);
@@ -21,6 +25,7 @@
 
     .Terminal:hover & {
         opacity: 1;
+         transition: all 350ms ease-out;
     }
 
     .nav-tabs {
@@ -58,6 +63,11 @@
     code {
         font-size: inherit;
         opacity: .8;
+
+        em {
+            font-style: normal;
+            color: #77d1e0 !important;
+        }
     }
 }
 
@@ -197,3 +207,17 @@
     color: #fff !important;
     opacity: 1;
 }
+
+.Terminal .hl-gutter  {
+    display: inline-flex;
+  font-size: 0.8em;
+  color: #474747;
+  padding: 0 1ch 0 0;
+  user-select: none;
+  margin-inline-start: -1ch;
+    opacity: 0;
+    transition: all 250ms;
+}
+.Terminal:hover .hl-gutter  {
+    opacity: 1;
+}

ux.symfony.com/src/Twig/Components/Code/CodeBlock.php

@@ -38,11 +38,39 @@ class CodeBlock
      */
     public bool $stripExcessHtml = false;
 
+    public ?int $lineStart = null;
+    public ?int $lineEnd = null;
+
     public function __construct(
         #[Autowire('%kernel.project_dir%')] private string $rootDir,
     ) {
     }
 
+    public function mount(string $filename): void
+    {
+        if (str_contains($filename, '#')) {
+            [$filename, $lines] = explode('#', $filename, 2);
+            if (str_contains($lines, '#')) {
+                throw new \InvalidArgumentException(sprintf('Invalid filename "%s": only one "#" is allowed.', $filename));
+            }
+
+            if (!preg_match('/^L(\d+)(?:-L(\d+))?$/', $lines, $matches)) {
+                throw new \InvalidArgumentException(sprintf('Invalid filename "%s": the line range is not valid.', $filename));
+            }
+
+            $lineStart = (int) $matches[1];
+            $lineEnd = (int) ($matches[2] ?? $matches[1]);
+            if ($lineStart > $lineEnd) {
+                throw new \InvalidArgumentException(sprintf('Invalid filename "%s": the line range is not valid.', $filename));
+            }
+
+            $this->lineStart = $lineStart;
+            $this->lineEnd = $lineEnd;
+        }
+
+        $this->filename = $filename;
+    }
+
     /**
      * Returns a list of source code pieces, extracted from the filename
      * argument, ready to be renderer in the template.
@@ -74,6 +102,8 @@ public function getRawSource(): string
 
         if ($this->targetTwigBlock) {
             $content = SourceCleaner::extractTwigBlock($content, $this->targetTwigBlock, $this->showTwigExtends);
+        } elseif (null !== $this->getLineAnchor()) {
+            $content = $this->extractLines($content, $this->lineStart, $this->lineEnd);
         }
 
         if ($this->stripExcessHtml) {
@@ -83,9 +113,35 @@ public function getRawSource(): string
         return $content;
     }
 
+    private function extractLines(string $content, int $lineStart, int $lineEnd): string
+    {
+        $lines = explode("\n", $content);
+        $lines = \array_slice($lines, $lineStart - 1, $lineEnd - $lineStart + 1);
+
+        return implode("\n", $lines);
+    }
+
+    public function getLineAnchor(): ?string
+    {
+        if (null === $this->lineStart) {
+            return null;
+        }
+
+        $anchor = sprintf('L%d', $this->lineStart);
+        if (null === $this->lineEnd) {
+            return $anchor;
+        }
+
+        if ($this->lineStart !== $this->lineEnd) {
+            $anchor .= sprintf('-L%d', $this->lineEnd);
+        }
+
+        return $anchor;
+    }
+
     public function getClassString(): string
     {
-        return 'terminal-code'.($this->showFilename ? '' : ' terminal-code-no-filename');
+        return 'terminal-code';
     }
 
     public function getGithubLink(): string

ux.symfony.com/src/Twig/Extension/HighlightExtension.php

@@ -20,10 +20,24 @@
  */
 final class HighlightExtension extends AbstractExtension
 {
+    public function __construct(
+        private readonly Highlighter $highlighter,
+    ) {
+    }
+
     public function getFilters(): array
     {
         return [
-            new TwigFilter('highlight', [Highlighter::class, 'parse'], ['is_safe' => ['html']]),
+            new TwigFilter('highlight', $this->highlight(...), ['is_safe' => ['html']]),
         ];
     }
+
+    public function highlight(string $code, string $language, ?int $startAt = null): string
+    {
+        if (null !== $startAt) {
+            return $this->highlighter->withGutter($startAt)->parse($code, $language);
+        }
+
+        return $this->highlighter->parse($code, $language);
+    }
 }

ux.symfony.com/templates/components/Code/CodeBlock.html.twig

@@ -4,7 +4,9 @@
 
     {% if showFilename %}
         <div class="Terminal_header py-2 px-3 mb-0 d-flex justify-content-between align-items-center">
-            <a id="{{ this.elementId }}" href="#{{ this.elementId }}" class="Terminal_title"><code>{{ filename }}</code></a>
+            <a id="{{ this.elementId }}" href="#{{ this.elementId }}" class="Terminal_title">
+                <code>{{ filename }}{% if this.lineStart %}<em>{{ '#%s'|format(this.lineAnchor) }}</em>{% endif %}</code>
+            </a>
             <div class="Terminal_actions">
                 <twig:Code:CodeBlockButtons source="{{ this.rawSource }}" link="{{ this.githubLink }}"/>
             </div>
@@ -23,7 +25,7 @@
             {% for piece in this.prepareSource %}
                 {% if piece.highlight ?? true %}
                     <pre><code class="language-{{ this.language }}">
-                        {{- piece.content|highlight(this.language) -}}
+                        {{- piece.content|highlight(this.language, this.lineStart) -}}
                     </code></pre>
                 {% else %}
                     {{- piece.content|raw -}}