[ENG-3892]Shiki codeblock support decorations (#4234)

* Shiki codeblock support decorations

* add decorations to useEffect

* fix pyright

* validate decorations dict

* Fix exception message plus unit tests

* possible test fix

* fix pyright

* possible tests fix

* cast decorations before creating codeblock

* `plain` is not a valid theme

* pyi fix

* address PR comment

Author: ElijahAhianyo

reflex/.templates/web/components/shiki/code.js

@@ -1,26 +1,31 @@
 import { useEffect, useState } from "react"
 import { codeToHtml} from "shiki"
 
-export function Code ({code, theme, language, transformers, ...divProps}) {
+/**
+ * Code component that uses Shiki to convert code to HTML and render it.
+ *
+ * @param code - The code to be highlighted.
+ * @param theme - The theme to be used for highlighting.
+ * @param language - The language of the code.
+ * @param transformers - The transformers to be applied to the code.
+ * @param decorations - The decorations to be applied to the code.
+ * @param divProps - Additional properties to be passed to the div element.
+ * @returns The rendered code block.
+ */
+export function Code ({code, theme, language, transformers, decorations, ...divProps}) {
     const [codeResult, setCodeResult] = useState("")
     useEffect(() => {
         async function fetchCode() {
-          let final_code;
-
-          if (Array.isArray(code)) {
-            final_code = code[0];
-          } else {
-            final_code = code;
-          }
-          const result = await codeToHtml(final_code, {
+          const result = await codeToHtml(code, {
             lang: language,
             theme,
-            transformers
+            transformers,
+            decorations
           });
           setCodeResult(result);
         }
         fetchCode();
-      }, [code, language, theme, transformers]
+      }, [code, language, theme, transformers, decorations]
 
     )
     return (

reflex/components/datadisplay/shiki_code_block.py

@@ -12,6 +12,7 @@
 from reflex.components.core.cond import color_mode_cond
 from reflex.components.el.elements.forms import Button
 from reflex.components.lucide.icon import Icon
+from reflex.components.props import NoExtrasAllowedProps
 from reflex.components.radix.themes.layout.box import Box
 from reflex.event import call_script, set_clipboard
 from reflex.style import Style
@@ -253,6 +254,7 @@ def copy_script() -> Any:
     "pascal",
     "perl",
     "php",
+    "plain",
     "plsql",
     "po",
     "postcss",
@@ -369,10 +371,11 @@ def copy_script() -> Any:
     "nord",
     "one-dark-pro",
     "one-light",
-    "plain",
     "plastic",
     "poimandres",
     "red",
+    # rose-pine themes dont work with the current version of shikijs transformers
+    # https://github.com/shikijs/shiki/issues/730
     "rose-pine",
     "rose-pine-dawn",
     "rose-pine-moon",
@@ -390,6 +393,23 @@ def copy_script() -> Any:
 ]
 
 
+class Position(NoExtrasAllowedProps):
+    """Position of the decoration."""
+
+    line: int
+    character: int
+
+
+class ShikiDecorations(NoExtrasAllowedProps):
+    """Decorations for the code block."""
+
+    start: Union[int, Position]
+    end: Union[int, Position]
+    tag_name: str = "span"
+    properties: dict[str, Any] = {}
+    always_wrap: bool = False
+
+
 class ShikiBaseTransformers(Base):
     """Base for creating transformers."""
 
@@ -537,6 +557,9 @@ class ShikiCodeBlock(Component):
         []
     )
 
+    # The decorations to use for the syntax highlighter.
+    decorations: Var[list[ShikiDecorations]] = Var.create([])
+
     @classmethod
     def create(
         cls,
@@ -555,6 +578,7 @@ def create(
         # Separate props for the code block and the wrapper
         code_block_props = {}
         code_wrapper_props = {}
+        decorations = props.pop("decorations", [])
 
         class_props = cls.get_props()
 
@@ -564,6 +588,15 @@ def create(
                 value
             )
 
+        # cast decorations into ShikiDecorations.
+        decorations = [
+            ShikiDecorations(**decoration)
+            if not isinstance(decoration, ShikiDecorations)
+            else decoration
+            for decoration in decorations
+        ]
+        code_block_props["decorations"] = decorations
+
         code_block_props["code"] = children[0]
         code_block = super().create(**code_block_props)
 
@@ -676,10 +709,10 @@ class ShikiHighLevelCodeBlock(ShikiCodeBlock):
     show_line_numbers: Var[bool]
 
     # Whether a copy button should appear.
-    can_copy: Var[bool] = Var.create(False)
+    can_copy: bool = False
 
     # copy_button: A custom copy button to override the default one.
-    copy_button: Var[Optional[Union[Component, bool]]] = Var.create(None)
+    copy_button: Optional[Union[Component, bool]] = None
 
     @classmethod
     def create(

reflex/components/datadisplay/shiki_code_block.pyi

@@ -7,6 +7,7 @@ from typing import Any, Dict, Literal, Optional, Union, overload
 
 from reflex.base import Base
 from reflex.components.component import Component, ComponentNamespace
+from reflex.components.props import NoExtrasAllowedProps
 from reflex.event import EventType
 from reflex.style import Style
 from reflex.vars.base import Var
@@ -192,6 +193,7 @@ LiteralCodeLanguage = Literal[
     "pascal",
     "perl",
     "php",
+    "plain",
     "plsql",
     "po",
     "postcss",
@@ -308,7 +310,6 @@ LiteralCodeTheme = Literal[
     "nord",
     "one-dark-pro",
     "one-light",
-    "plain",
     "plastic",
     "poimandres",
     "red",
@@ -328,6 +329,17 @@ LiteralCodeTheme = Literal[
     "vitesse-light",
 ]
 
+class Position(NoExtrasAllowedProps):
+    line: int
+    character: int
+
+class ShikiDecorations(NoExtrasAllowedProps):
+    start: Union[int, Position]
+    end: Union[int, Position]
+    tag_name: str
+    properties: dict[str, Any]
+    always_wrap: bool
+
 class ShikiBaseTransformers(Base):
     library: str
     fns: list[FunctionStringVar]
@@ -479,6 +491,7 @@ class ShikiCodeBlock(Component):
                     "pascal",
                     "perl",
                     "php",
+                    "plain",
                     "plsql",
                     "po",
                     "postcss",
@@ -694,6 +707,7 @@ class ShikiCodeBlock(Component):
                         "pascal",
                         "perl",
                         "php",
+                        "plain",
                         "plsql",
                         "po",
                         "postcss",
@@ -815,7 +829,6 @@ class ShikiCodeBlock(Component):
                     "nord",
                     "one-dark-pro",
                     "one-light",
-                    "plain",
                     "plastic",
                     "poimandres",
                     "red",
@@ -870,7 +883,6 @@ class ShikiCodeBlock(Component):
                         "nord",
                         "one-dark-pro",
                         "one-light",
-                        "plain",
                         "plastic",
                         "poimandres",
                         "red",
@@ -906,6 +918,9 @@ class ShikiCodeBlock(Component):
                 list[Union[ShikiBaseTransformers, dict[str, Any]]],
             ]
         ] = None,
+        decorations: Optional[
+            Union[Var[list[ShikiDecorations]], list[ShikiDecorations]]
+        ] = None,
         style: Optional[Style] = None,
         key: Optional[Any] = None,
         id: Optional[Any] = None,
@@ -938,6 +953,7 @@ class ShikiCodeBlock(Component):
             themes: The set of themes to use for different modes.
             code: The code to display.
             transformers: The transformers to use for the syntax highlighter.
+            decorations: The decorations to use for the syntax highlighter.
             style: The style of the component.
             key: A unique key for the component.
             id: The id for the component.
@@ -965,10 +981,8 @@ class ShikiHighLevelCodeBlock(ShikiCodeBlock):
         *children,
         use_transformers: Optional[Union[Var[bool], bool]] = None,
         show_line_numbers: Optional[Union[Var[bool], bool]] = None,
-        can_copy: Optional[Union[Var[bool], bool]] = None,
-        copy_button: Optional[
-            Union[Component, Var[Optional[Union[Component, bool]]], bool]
-        ] = None,
+        can_copy: Optional[bool] = None,
+        copy_button: Optional[Union[Component, bool]] = None,
         language: Optional[
             Union[
                 Literal[
@@ -1104,6 +1118,7 @@ class ShikiHighLevelCodeBlock(ShikiCodeBlock):
                     "pascal",
                     "perl",
                     "php",
+                    "plain",
                     "plsql",
                     "po",
                     "postcss",
@@ -1319,6 +1334,7 @@ class ShikiHighLevelCodeBlock(ShikiCodeBlock):
                         "pascal",
                         "perl",
                         "php",
+                        "plain",
                         "plsql",
                         "po",
                         "postcss",
@@ -1440,7 +1456,6 @@ class ShikiHighLevelCodeBlock(ShikiCodeBlock):
                     "nord",
                     "one-dark-pro",
                     "one-light",
-                    "plain",
                     "plastic",
                     "poimandres",
                     "red",
@@ -1495,7 +1510,6 @@ class ShikiHighLevelCodeBlock(ShikiCodeBlock):
                         "nord",
                         "one-dark-pro",
                         "one-light",
-                        "plain",
                         "plastic",
                         "poimandres",
                         "red",
@@ -1531,6 +1545,9 @@ class ShikiHighLevelCodeBlock(ShikiCodeBlock):
                 list[Union[ShikiBaseTransformers, dict[str, Any]]],
             ]
         ] = None,
+        decorations: Optional[
+            Union[Var[list[ShikiDecorations]], list[ShikiDecorations]]
+        ] = None,
         style: Optional[Style] = None,
         key: Optional[Any] = None,
         id: Optional[Any] = None,
@@ -1567,6 +1584,7 @@ class ShikiHighLevelCodeBlock(ShikiCodeBlock):
             themes: The set of themes to use for different modes.
             code: The code to display.
             transformers: The transformers to use for the syntax highlighter.
+            decorations: The decorations to use for the syntax highlighter.
             style: The style of the component.
             key: A unique key for the component.
             id: The id for the component.
@@ -1593,10 +1611,8 @@ class CodeblockNamespace(ComponentNamespace):
         *children,
         use_transformers: Optional[Union[Var[bool], bool]] = None,
         show_line_numbers: Optional[Union[Var[bool], bool]] = None,
-        can_copy: Optional[Union[Var[bool], bool]] = None,
-        copy_button: Optional[
-            Union[Component, Var[Optional[Union[Component, bool]]], bool]
-        ] = None,
+        can_copy: Optional[bool] = None,
+        copy_button: Optional[Union[Component, bool]] = None,
         language: Optional[
             Union[
                 Literal[
@@ -1732,6 +1748,7 @@ class CodeblockNamespace(ComponentNamespace):
                     "pascal",
                     "perl",
                     "php",
+                    "plain",
                     "plsql",
                     "po",
                     "postcss",
@@ -1947,6 +1964,7 @@ class CodeblockNamespace(ComponentNamespace):
                         "pascal",
                         "perl",
                         "php",
+                        "plain",
                         "plsql",
                         "po",
                         "postcss",
@@ -2068,7 +2086,6 @@ class CodeblockNamespace(ComponentNamespace):
                     "nord",
                     "one-dark-pro",
                     "one-light",
-                    "plain",
                     "plastic",
                     "poimandres",
                     "red",
@@ -2123,7 +2140,6 @@ class CodeblockNamespace(ComponentNamespace):
                         "nord",
                         "one-dark-pro",
                         "one-light",
-                        "plain",
                         "plastic",
                         "poimandres",
                         "red",
@@ -2159,6 +2175,9 @@ class CodeblockNamespace(ComponentNamespace):
                 list[Union[ShikiBaseTransformers, dict[str, Any]]],
             ]
         ] = None,
+        decorations: Optional[
+            Union[Var[list[ShikiDecorations]], list[ShikiDecorations]]
+        ] = None,
         style: Optional[Style] = None,
         key: Optional[Any] = None,
         id: Optional[Any] = None,
@@ -2195,6 +2214,7 @@ class CodeblockNamespace(ComponentNamespace):
             themes: The set of themes to use for different modes.
             code: The code to display.
             transformers: The transformers to use for the syntax highlighter.
+            decorations: The decorations to use for the syntax highlighter.
             style: The style of the component.
             key: A unique key for the component.
             id: The id for the component.