[2.x] Add basic support for inline annotations (#109)

* Add a way of asking for the parsed grammar in Transformer

* Implement highlight and focus, start writing some tests

* wip

* Add tests for focusing

* Shuffle documentation and add inline annotations stuff

* add tests for keywords

* Add interface for getting themes inside of transformers

Author: ryangjchandler

docs/commonmark.mdx

@@ -60,24 +60,34 @@ $environment
     ])); // [!code ++]
 ```
 
-### Highlighting and focusing lines
+### Meta information
 
-You can highlight and focus lines in your code blocks using special annotations in the code block's info string.
+You can add additional meta information to your Markdown code blocks to highlight and focus a specified set of lines.
+
+#### Highlighting lines
+
+You can highlight lines in your code blocks using special annotations in the code block's info string.
 
 ```md
-```php {2,4-8}{3}
+```php {2,4-8}
 ```
 
-The first set of braces represents the lines to highlight, while the second set represents the lines to focus on.
+The braces represent the lines to highlight. In this example, line 2 will be highlighted, as well as lines 4 through 8.
 
-In this example, line 2 will be highlighted, as well as lines 4 through 8. Line 3 will then be focused.
+#### Focusing lines
 
-If you only want to focus lines, you can use an empty set of braces for the highlighted lines:
+You can focus lines in your code blocks using special annotations in the code block's info string.
 
 ```md
-```php {}{3}
+```php {}{2,4-8}
 ```
 
+The first set of braces represents the lines to highlight (none in this case), while the second set of braces represents the lines to focus. In this example, line 2 will be focused, as well as lines 4 through 8.
+
+<Tip>
+    When you have focused lines inside of a code block, Phiki will add a `focus` class to the `<pre>` element.
+</Tip>
+
 #### Sample CSS
 
 Phiki does not style the highlighted or focused lines by default, so you will need to add your own CSS.
@@ -99,3 +109,105 @@ pre.phiki.focus:hover .line {
     filter: blur(0);
 }
 ```
+
+### Inline annotations
+
+The meta information for highlighting and focusing lines can be difficult to use when you have a large code block or if you change the code frequently since it uses line numbers.
+
+That's why Phiki also supports inline annotations using special comments in your code.
+
+#### Ranges
+
+Inline annotations accept an optional range parameter to specify which lines should be highlighted or focused. 
+
+```
+// [code! highlight]      → Only this line.
+// [code! highlight:2]    → This line and the 2 lines after it.
+// [code! highlight:-2]   → This line and the 2 lines before it.
+// [code! highlight:1,3]  → From the next line, 3 lines in total.
+// [code! highlight:-1,2] → From the previous line, 2 lines in total.
+```
+
+It's also possible to create an "open ended" range by using `start` and `end` to mark the beginning and end of a range.
+
+```
+// [code! highlight:start] → Start highlighting from this line.
+// ...
+// [code! highlight:end]   → Stop highlighting after this line.
+```
+
+#### Highlighting lines
+
+To highlight a line, you can add a trailing comment to the line you want to highlight.
+
+```php
+echo "Hello, world!"; // [code! highlight]
+```
+
+This comment tells Phiki to highlight this line by adding a `highlight` class to the corresponding line element.
+
+If you don't want to write out `highlight` every time, you can use the `hl` or `~~` shorthands instead.
+
+```php
+echo "Hello, world!"; // [code! hl]
+echo "Hello, world!"; // [code! ~~]
+```
+
+#### Focusing lines
+
+To focus a line, you can add a trailing comment to the line you want to focus.
+
+```php
+echo "Hello, world!"; // [code! focus]
+```
+
+This comment tells Phiki to focus this line by adding a `focus` class to the corresponding line element.
+
+<Tip>
+    When you have focused lines inside of a code block, Phiki will add a `focus` class to the `<pre>` element.
+</Tip>
+
+If you don't want to write out `focus` every time, you can use the `f` or `**` shorthands instead.
+
+```php
+echo "Hello, world!"; // [code! f]
+echo "Hello, world!"; // [code! **]
+```
+
+#### Sample CSS
+
+##### **Highlighted lines**
+
+When you use an inline highlight annotation, Phiki will try to find an `editor.lineHighlightBackground` or `editor.selectionHighlightBackground` color inside of your chosen theme(s) and add a CSS variable to the `<pre>` element.
+
+If it can't find one, it will fallback to the default background color of the theme.
+
+Those CSS variables are then applied to the line element the same as other styled elements.
+
+<Note>
+If you're using multiple themes, Phiki will also add CSS variables for each theme so you can style them differently in dark mode, for example.
+</Note>
+
+```css
+@media (prefers-color-scheme: dark) {
+    .phiki .line.highlight {
+        background-color: var(--phiki-dark-line-highlight) !important;
+    }
+}
+```
+
+##### **Focused lines**
+
+Phiki does not apply any styles to focused lines by default, so you will need to add your own CSS.
+
+```css
+pre.phiki.focus .line:not(.focus) {
+    transition: all 250ms;
+    filter: blur(2px);
+}
+
+pre.phiki.focus:hover .line {
+    transition: all 250ms;
+    filter: blur(0);
+}
+```

meta/commonmark.php

@@ -0,0 +1,26 @@
+<?php
+
+use League\CommonMark\Environment\Environment;
+use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
+use League\CommonMark\MarkdownConverter;
+use Phiki\Adapters\CommonMark\PhikiExtension;
+use Phiki\Theme\Theme;
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+$environment = new Environment();
+$environment->addExtension(new CommonMarkCoreExtension)->addExtension(new PhikiExtension(Theme::GithubLight));
+$converter = new MarkdownConverter($environment);
+
+$markdown = <<<'MARKDOWN'
+```blade
+{{-- [code! highlight:start] --}}
+@if(true) {{-- [code! focus:start] --}}
+    Hello, world!
+@endif {{-- [code! highlight:end] --}}
+
+{{ $variable }} {{-- [code! focus:end] --}}
+```
+MARKDOWN;
+
+echo $converter->convert($markdown);

src/Adapters/CommonMark/CodeBlockRenderer.php

@@ -7,6 +7,7 @@
 use League\CommonMark\Node\Node;
 use League\CommonMark\Renderer\ChildNodeRendererInterface;
 use League\CommonMark\Renderer\NodeRendererInterface;
+use Phiki\Adapters\CommonMark\Transformers\AnnotationsTransformer;
 use Phiki\Adapters\CommonMark\Transformers\MetaTransformer;
 use Phiki\Grammar\Grammar;
 use Phiki\Phiki;
@@ -35,6 +36,7 @@ public function render(Node $node, ChildNodeRendererInterface $childRenderer)
             ->withGutter($this->withGutter)
             ->withMeta($meta)
             ->transformer(new MetaTransformer)
+            ->transformer(new AnnotationsTransformer)
             ->toString();
     }
 

src/Adapters/CommonMark/Transformers/Annotations/Annotation.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Phiki\Adapters\CommonMark\Transformers\Annotations;
+
+use Phiki\Phast\Element;
+
+class Annotation
+{
+    public function __construct(
+        public AnnotationType $type,
+        public int $start,
+        public int $end,
+    ) {}
+
+    public function applyToLine(Element $line): void
+    {
+        $line->properties->get('class')->add(...$this->type->getLineClasses());
+    }
+
+    public function applyToPre(Element $pre): void
+    {
+        $pre->properties->get('class')->add(...$this->type->getPreClasses());
+    }
+}

src/Adapters/CommonMark/Transformers/Annotations/AnnotationRange.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Phiki\Adapters\CommonMark\Transformers\Annotations;
+
+class AnnotationRange
+{
+    public function __construct(
+        public AnnotationRangeKind $kind,
+        public int $start,
+        public int $end,
+    ) {}
+
+    public static function parse(string $range, int $index): ?self
+    {
+        $range = trim($range);
+
+        // Highlight the current line plus the next N lines.
+        if (preg_match('/^\d+$/', $range) === 1) {
+            return new AnnotationRange(AnnotationRangeKind::Fixed, $index, (int) $range + $index);
+        }
+
+        // Highlight the current line plus the previous N lines.
+        if (preg_match('/^-\d+$/', $range) === 1) {
+            return new AnnotationRange(AnnotationRangeKind::Fixed, $index + (int) $range, $index);
+        }
+
+        // Start highlighting from OFFSET for a total of AND lines.
+        if (preg_match('/^(?<offset>\d+),(?<and>\d+)$/', $range, $matches) === 1) {
+            return new AnnotationRange(AnnotationRangeKind::Fixed, $index + (int) $matches['offset'], $index + (int) $matches['offset'] + (int) $matches['and'] - 1);
+        }
+
+        // Start highlighting from $index - OFFSET for a total of AND lines.
+        if (preg_match('/^(?<offset>-\d+),(?<and>\d+)$/', $range, $matches) === 1) {
+            return new AnnotationRange(AnnotationRangeKind::Fixed, $index + (int) $matches['offset'], $index + (int) $matches['offset'] + (int) $matches['and'] - 1);
+        }
+
+        // Start highlighting in an open-ended manner from the current line.
+        if (preg_match('/^start$/i', $range) === 1) {
+            return new AnnotationRange(AnnotationRangeKind::OpenEnded, $index, $index);
+        }
+
+        // Stop highlighting in an open-ended manner at the current line.
+        if (preg_match('/^end$/i', $range) === 1) {
+            return new AnnotationRange(AnnotationRangeKind::End, $index, $index);
+        }
+
+        return null;
+    }
+}

src/Adapters/CommonMark/Transformers/Annotations/AnnotationRangeKind.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Phiki\Adapters\CommonMark\Transformers\Annotations;
+
+enum AnnotationRangeKind
+{
+    case Fixed;
+    case OpenEnded;
+    case End;
+}

src/Adapters/CommonMark/Transformers/Annotations/AnnotationType.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Phiki\Adapters\CommonMark\Transformers\Annotations;
+
+enum AnnotationType
+{
+    case Highlight;
+    case Focus;
+
+    /**
+     * Get the keywords used to denote this annotation type.
+     * 
+     * e.g. highlight can be denoted by `[code! highlight]`.
+     */
+    public function keywords(): array
+    {
+        return match ($this) {
+            self::Highlight => ['highlight', 'hl', '~~'],
+            self::Focus => ['focus', 'f', '**'],
+        };
+    }
+
+    /**
+     * Get the CSS classes to apply to lines with this annotation.
+     */
+    public function getLineClasses(): array
+    {
+        return match ($this) {
+            self::Highlight => ['highlight'],
+            self::Focus => ['focus'],
+        };
+    }
+
+    /**
+     * Get the CSS classes to apply to the pre element.
+     */
+    public function getPreClasses(): array
+    {
+        return match ($this) {
+            self::Focus => ['focus'],
+            default => [],
+        };
+    }
+
+    /**
+     * Get the type from the given keyword.
+     */
+    public static function fromKeyword(string $keyword): self
+    {
+        return match ($keyword) {
+            'highlight', 'hl', '~~' => self::Highlight,
+            'focus', 'f', '**' => self::Focus,
+            default => throw new \InvalidArgumentException("Unknown annotation keyword: {$keyword}"),
+        };
+    }
+}