feat: files decorators (#365)

docs/getting-started/authoring.mdx

@@ -469,6 +469,79 @@ It will render the [`SandpackCodeViewer`](https://sandpack.codesandbox.io/docs/a
 
 You can also pass [any `codeViewer={options: ComponentProps<SandpackCodeViewer>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#code-viewer:~:text=Preview-,Options,-CodeMirror%20decorations).
 
+##### `Sandpack[codeViewer][filesDecorators]`
+
+You can define per-file [decorators](https://sandpack.codesandbox.io/docs/advanced-usage/components#codemirror-decorations) through `filesDecorators` prop:
+
+```tsx
+<Sandpack
+  template="react-ts"
+  folder="authoring-sandpack-cloud"
+  codeViewer={{
+    filesDecorators: {
+      '/App.tsx': [
+        { className: "highlight", line: 1 },
+        { className: "highlight", line: 7 },
+        {
+          className: "widget",
+          elementAttributes: { "data-id": "1" },
+          line: 7,
+          startColumn: 13,
+          endColumn: 24,
+        },
+        {
+          className: "widget",
+          elementAttributes: { "data-id": "2" },
+          line: 7,
+          startColumn: 25,
+          endColumn: 35,
+        },
+
+      ],
+      '/styles.css': [
+        { className: "highlight", line: 4 },
+      ]
+    }
+  }}
+/>
+```
+
+<details>
+  <summary>Result</summary>
+
+<Sandpack
+  template="react-ts"
+  folder="authoring-sandpack-cloud"
+  codeViewer={{
+    filesDecorators: {
+      '/App.tsx': [
+        { className: "highlight", line: 1 },
+        { className: "highlight", line: 7 },
+        {
+          className: "widget",
+          elementAttributes: { "data-id": "1" },
+          line: 7,
+          startColumn: 13,
+          endColumn: 24,
+        },
+        {
+          className: "widget",
+          elementAttributes: { "data-id": "2" },
+          line: 7,
+          startColumn: 25,
+          endColumn: 35,
+        },
+
+      ],
+      '/styles.css': [
+        { className: "highlight", line: 4 },
+      ]
+    }
+  }}
+/>
+
+</details>
+
 #### `Sandpack[preview]`
 
 You can pass [any `preview={options: ComponentProps<SandpackPreview>}`](https://sandpack.codesandbox.io/docs/advanced-usage/components#preview:~:text=Preview-,Options,-Additional%20buttons).

src/components/mdx/Sandpack/Sandpack.css

@@ -0,0 +1,28 @@
+.highlight {
+  background: #1ea7fd2b;
+  border-radius: 4px;
+}
+.widget {
+  border: 1px solid #1ea7fd;
+  border-radius: 2px;
+  padding: 2px 4px 2px 12px;
+  margin-left: 6px;
+  position: relative;
+  cursor: pointer;
+}
+
+.widget:before {
+  content: attr(data-id);
+  background: #1ea7fd;
+  border-radius: 100%;
+  position: absolute;
+  width: 16px;
+  display: block;
+  height: 16px;
+  left: -8px;
+  top: 2px;
+  font-size: 11px;
+  text-align: center;
+  color: white;
+  line-height: 17px;
+}

src/components/mdx/Sandpack/Sandpack.tsx

@@ -2,7 +2,6 @@ import cn from '@/lib/cn'
 import { crawl } from '@/utils/docs'
 import {
   SandpackCodeEditor,
-  SandpackCodeViewer,
   SandpackFileExplorer,
   SandpackLayout,
   SandpackPreview,
@@ -13,6 +12,8 @@ import {
 import fs from 'node:fs'
 import path from 'node:path'
 
+import { SandpackCodeViewer } from './SandpackCodeViewer'
+
 // https://tailwindcss.com/docs/configuration#referencing-in-java-script
 import { ComponentProps } from 'react'
 import resolveConfig from 'tailwindcss/resolveConfig'

src/components/mdx/Sandpack/SandpackCodeViewer.tsx

@@ -0,0 +1,31 @@
+'use client'
+
+import {
+  CodeViewerProps,
+  SandpackFiles,
+  SandpackCodeViewer as SPCodeViewer,
+  useSandpack,
+} from '@codesandbox/sandpack-react'
+
+import { useEffect, useState } from 'react'
+import './Sandpack.css'
+
+type Decorators = CodeViewerProps['decorators']
+
+export function SandpackCodeViewer(
+  props: CodeViewerProps & { filesDecorators?: Record<keyof SandpackFiles, Decorators> },
+) {
+  const { sandpack } = useSandpack()
+  const { activeFile } = sandpack
+
+  const { filesDecorators, ...restCodeViewerProps } = props ?? {}
+
+  const [decorators, setDecorators] = useState<Decorators>(undefined)
+  useEffect(() => {
+    if (!filesDecorators) return
+
+    setDecorators(filesDecorators[activeFile])
+  }, [activeFile, filesDecorators])
+
+  return <SPCodeViewer {...restCodeViewerProps} decorators={decorators} />
+}