feat: allow negative character positions for denoting end of line offsets (#1051)

Co-authored-by: Anthony Fu <[email protected]>

Author: sealer3

docs/guide/decorations.md

@@ -63,6 +63,26 @@ const x = 10
 console.log(x)
 ```
 
+Negative character positions denote characters from the end of a line, starting with the line end:
+
+```ts twoslash
+import { DecorationItem } from 'shiki'
+// ---cut---
+const item: DecorationItem = {
+  start: { line: 0, character: 0 },
+  end: { line: 0, character: -1 },
+  properties: { class: 'highlighted-word' }
+}
+```
+
+This highlights the entire first line:
+
+```ts
+// @decorations:[{"start":{"line":0,"character":0},"end":{"line":0,"character":-1},"properties":{"class":"highlighted-word"}}]
+const x = 10
+console.log(x)
+```
+
 ## Use Decorations in Transformers
 
 For advanced use cases, you can use the [Transformers API](./transformers.md) to have full access to the tokens and the HAST tree.

packages/core/src/transformer-decorations.ts

@@ -42,12 +42,19 @@ export function transformerDecorations(): ShikiTransformer {
           const line = converter.lines[p.line]
           if (line === undefined)
             throw new ShikiError(`Invalid decoration position ${JSON.stringify(p)}. Lines length: ${converter.lines.length}`)
-          if (p.character < 0 || p.character > line.length)
+
+          let character = p.character
+          // Negative numbers are positions from the end of the line
+          if (character < 0)
+            character = line.length + character
+
+          if (character < 0 || character > line.length)
             throw new ShikiError(`Invalid decoration position ${JSON.stringify(p)}. Line ${p.line} length: ${line.length}`)
 
           return {
             ...p,
-            offset: converter.posToIndex(p.line, p.character),
+            character,
+            offset: converter.posToIndex(p.line, character),
           }
         }
       }

packages/core/test/decorations.test.ts

@@ -102,6 +102,13 @@ describe('decorations', () => {
           end: code.length,
           properties: { class: 'highlighted' },
         },
+        // "ult" from "return result"
+        // Testing negative character positions
+        {
+          start: { line: 9, character: -4 },
+          end: { line: 9, character: -1 },
+          properties: { class: 'highlighted' },
+        },
       ],
     })