Skip to content

Visualize Your Ideas With Code

docs: document Code node (#999)

Jacobc6db8ce828ea
diff --git a/package-lock.json b/package-lock.json
index 73fa37de..a3c68e96 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -4779,22 +4779,33 @@
}
},
"node_modules/@lezer/javascript": {
- "version": "1.4.1",
- "resolved": "https://registry.npmjs.org/@lezer/javascript/-/javascript-1.4.1.tgz",
- "integrity": "sha512-Hqx36DJeYhKtdpc7wBYPR0XF56ZzIp0IkMO/zNNj80xcaFOV4Oj/P7TQc/8k2TxNhzl7tV5tXS8ZOCPbT4L3nA==",
+ "version": "1.4.13",
+ "resolved": "https://registry.npmjs.org/@lezer/javascript/-/javascript-1.4.13.tgz",
+ "integrity": "sha512-5IBr8LIO3xJdJH1e9aj/ZNLE4LSbdsx25wFmGRAZsj2zSmwAYjx26JyU/BYOCpRQlu1jcv1z3vy4NB9+UkfRow==",
"dependencies": {
+ "@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.1.3",
"@lezer/lr": "^1.3.0"
}
},
"node_modules/@lezer/lr": {
- "version": "1.3.3",
- "resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.3.3.tgz",
- "integrity": "sha512-JPQe3mwJlzEVqy67iQiiGozhcngbO8QBgpqZM6oL1Wj/dXckrEexpBLeFkq0edtW5IqnPRFxA24BHJni8Js69w==",
+ "version": "1.4.0",
+ "resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.4.0.tgz",
+ "integrity": "sha512-Wst46p51km8gH0ZUmeNrtpRYmdlRHUpN1DQd3GFAyKANi8WVz8c2jHYTf1CVScFaCjQw1iO3ZZdqGDxQPRErTg==",
"dependencies": {
"@lezer/common": "^1.0.0"
}
},
+ "node_modules/@lezer/rust": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/@lezer/rust/-/rust-1.0.2.tgz",
+ "integrity": "sha512-Lz5sIPBdF2FUXcWeCu1//ojFAZqzTQNRga0aYv6dYXqJqPfMdCAI0NzajWUd4Xijj1IKJLtjoXRPMvTKWBcqKg==",
+ "dependencies": {
+ "@lezer/common": "^1.2.0",
+ "@lezer/highlight": "^1.0.0",
+ "@lezer/lr": "^1.0.0"
+ }
+ },
"node_modules/@mdx-js/mdx": {
"version": "1.6.22",
"resolved": "https://registry.npmjs.org/@mdx-js/mdx/-/mdx-1.6.22.tgz",
@@ -25749,6 +25760,8 @@
"@docusaurus/preset-classic": "^2.4.0",
"@docusaurus/theme-mermaid": "^2.4.0",
"@docusaurus/theme-search-algolia": "^2.4.0",
+ "@lezer/javascript": "^1.4.13",
+ "@lezer/rust": "^1.0.2",
"@mdx-js/react": "^1.6.22",
"@motion-canvas/examples": "*",
"@motion-canvas/player": "*",
@@ -29273,22 +29286,33 @@
}
},
"@lezer/javascript": {
- "version": "1.4.1",
- "resolved": "https://registry.npmjs.org/@lezer/javascript/-/javascript-1.4.1.tgz",
- "integrity": "sha512-Hqx36DJeYhKtdpc7wBYPR0XF56ZzIp0IkMO/zNNj80xcaFOV4Oj/P7TQc/8k2TxNhzl7tV5tXS8ZOCPbT4L3nA==",
+ "version": "1.4.13",
+ "resolved": "https://registry.npmjs.org/@lezer/javascript/-/javascript-1.4.13.tgz",
+ "integrity": "sha512-5IBr8LIO3xJdJH1e9aj/ZNLE4LSbdsx25wFmGRAZsj2zSmwAYjx26JyU/BYOCpRQlu1jcv1z3vy4NB9+UkfRow==",
"requires": {
+ "@lezer/common": "^1.2.0",
"@lezer/highlight": "^1.1.3",
"@lezer/lr": "^1.3.0"
}
},
"@lezer/lr": {
- "version": "1.3.3",
- "resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.3.3.tgz",
- "integrity": "sha512-JPQe3mwJlzEVqy67iQiiGozhcngbO8QBgpqZM6oL1Wj/dXckrEexpBLeFkq0edtW5IqnPRFxA24BHJni8Js69w==",
+ "version": "1.4.0",
+ "resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.4.0.tgz",
+ "integrity": "sha512-Wst46p51km8gH0ZUmeNrtpRYmdlRHUpN1DQd3GFAyKANi8WVz8c2jHYTf1CVScFaCjQw1iO3ZZdqGDxQPRErTg==",
"requires": {
"@lezer/common": "^1.0.0"
}
},
+ "@lezer/rust": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/@lezer/rust/-/rust-1.0.2.tgz",
+ "integrity": "sha512-Lz5sIPBdF2FUXcWeCu1//ojFAZqzTQNRga0aYv6dYXqJqPfMdCAI0NzajWUd4Xijj1IKJLtjoXRPMvTKWBcqKg==",
+ "requires": {
+ "@lezer/common": "^1.2.0",
+ "@lezer/highlight": "^1.0.0",
+ "@lezer/lr": "^1.0.0"
+ }
+ },
"@mdx-js/mdx": {
"version": "1.6.22",
"resolved": "https://registry.npmjs.org/@mdx-js/mdx/-/mdx-1.6.22.tgz",
@@ -29538,6 +29562,8 @@
"@docusaurus/preset-classic": "^2.4.0",
"@docusaurus/theme-mermaid": "^2.4.0",
"@docusaurus/theme-search-algolia": "^2.4.0",
+ "@lezer/javascript": "^1.4.13",
+ "@lezer/rust": "^1.0.2",
"@mdx-js/react": "^1.6.22",
"@motion-canvas/examples": "*",
"@motion-canvas/player": "*",
diff --git a/packages/2d/src/lib/components/Code.ts b/packages/2d/src/lib/components/Code.ts
index 41a9d3db..8a6abe33 100644
--- a/packages/2d/src/lib/components/Code.ts
+++ b/packages/2d/src/lib/components/Code.ts
@@ -103,12 +103,10 @@ export interface CodeProps extends ShapeProps {
*
* @preview
* ```tsx editor
- * import {parser} from '@lezer/javascript';
- * import {Code, LezerHighlighter, makeScene2D} from '@motion-canvas/2d';
+ * import {Code, makeScene2D} from '@motion-canvas/2d';
* import {createRef} from '@motion-canvas/core';
*
* export default makeScene2D(function* (view) {
- * LezerHighlighter.registerParser(parser);
* const code = createRef<Code>();
*
* view.add(
diff --git a/packages/docs/bundle.js b/packages/docs/bundle.js
index 318b246b..c3114d53 100644
--- a/packages/docs/bundle.js
+++ b/packages/docs/bundle.js
@@ -26,7 +26,6 @@ module.exports = () => ({
'@motion-canvas/core': `${core}`,
'@motion-canvas/2d': `${two}`,
'@motion-canvas/2d/jsx-runtime': `${two}`,
- '@lezer/javascript': 'https://esm.sh/@lezer/javascript',
},
}),
},
diff --git a/packages/docs/docs/components/bezier.mdx b/packages/docs/docs/components/bezier.mdx
index 0ec524e8..c906e62b 100644
--- a/packages/docs/docs/components/bezier.mdx
+++ b/packages/docs/docs/components/bezier.mdx
@@ -5,7 +5,7 @@ slug: /bezier-curves
# Bézier Curves
-```tsx editor
+```tsx editor mode=preview
// snippet Cubic Bézier
import {makeScene2D, CubicBezier} from '@motion-canvas/2d';
import {createRef} from '@motion-canvas/core';
diff --git a/packages/docs/docs/components/code-block.mdx b/packages/docs/docs/components/code-block.mdx
index 9ff6e549..e10820e9 100644
--- a/packages/docs/docs/components/code-block.mdx
+++ b/packages/docs/docs/components/code-block.mdx
@@ -1,12 +1,19 @@
---
-sidebar_position: 1
+sidebar_position: 100
slug: /code-block
---
-# CodeBlock
+# CodeBlock (Deprecated)
import AnimationPlayer from '@site/src/components/AnimationPlayer';
+:::caution
+
+`CodeBlock` has been deprecated and will be removed in version 4. Please use the
+[new `Code` node](/docs/code) instead.
+
+:::
+
<AnimationPlayer banner name="code-block" />
The `CodeBlock` component is used to present syntax highlighted code. It can
diff --git a/packages/docs/docs/components/code/grammars.json b/packages/docs/docs/components/code/grammars.json
new file mode 100644
index 00000000..17d2e52c
--- /dev/null
+++ b/packages/docs/docs/components/code/grammars.json
@@ -0,0 +1,82 @@
+[
+ {
+ "name": "C++",
+ "url": "https://github.com/lezer-parser/cpp",
+ "package": "@lezer/cpp"
+ },
+ {
+ "name": "CSS",
+ "url": "https://github.com/lezer-parser/css",
+ "package": "@lezer/css"
+ },
+ {
+ "name": "Clojure",
+ "url": "https://github.com/lezer-parser/clojure",
+ "package": "@lezer/clojure"
+ },
+ {
+ "name": "Go",
+ "url": "https://github.com/lezer-parser/go",
+ "package": "@lezer/go"
+ },
+ {
+ "name": "HTML",
+ "url": "https://github.com/lezer-parser/html",
+ "package": "@lezer/html"
+ },
+ {
+ "name": "Java",
+ "url": "https://github.com/lezer-parser/java",
+ "package": "@lezer/java"
+ },
+ {
+ "name": "JavaScript",
+ "url": "https://github.com/lezer-parser/javascript",
+ "package": "@lezer/javascript"
+ },
+ {
+ "name": "Julia",
+ "url": "https://github.com/lezer-parser/julia",
+ "package": "@lezer/julia"
+ },
+ {
+ "name": "JSON",
+ "url": "https://github.com/lezer-parser/json",
+ "package": "@lezer/json"
+ },
+ {
+ "name": "Markdown",
+ "url": "https://github.com/lezer-parser/markdown",
+ "package": "@lezer/markdown"
+ },
+ {
+ "name": "PHP",
+ "url": "https://github.com/lezer-parser/php",
+ "package": "@lezer/php"
+ },
+ {
+ "name": "Python",
+ "url": "https://github.com/lezer-parser/python",
+ "package": "@lezer/python"
+ },
+ {
+ "name": "Rust",
+ "url": "https://github.com/lezer-parser/rust",
+ "package": "@lezer/rust"
+ },
+ {
+ "name": "Sass",
+ "url": "https://github.com/lezer-parser/sass",
+ "package": "@lezer/sass"
+ },
+ {
+ "name": "XML",
+ "url": "https://github.com/lezer-parser/xml",
+ "package": "@lezer/xml"
+ },
+ {
+ "name": "YAML",
+ "url": "https://github.com/lezer-parser/yaml",
+ "package": "@lezer/yaml"
+ }
+]
diff --git a/packages/docs/docs/components/code/grammars.mdx b/packages/docs/docs/components/code/grammars.mdx
new file mode 100644
index 00000000..3c2affe5
--- /dev/null
+++ b/packages/docs/docs/components/code/grammars.mdx
@@ -0,0 +1,29 @@
+---
+sidebar_position: 1
+slug: /grammars
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import GRAMMARS from './grammars.json';
+
+# Grammars
+
+Here are some of the available grammars for Lezer together with their
+corresponding npm packages. If you know of a grammar that is not listed here,
+feel free to submit a pull request that adds it [to this file][edit].
+
+Learn [how to configure a grammar](/docs/code#parsing-and-highlighting).
+
+<>
+ {GRAMMARS.map(g => (
+ <>
+ <h4>
+ <a href={g.url}>{g.name}</a>
+ </h4>
+ <CodeBlock language="bash">npm i {g.package}</CodeBlock>
+ </>
+ ))}
+</>
+
+[edit]:
+ https://github.com/motion-canvas/motion-canvas/blob/main/packages/docs/docs/components/code/grammars.json
diff --git a/packages/docs/docs/components/code/index.mdx b/packages/docs/docs/components/code/index.mdx
new file mode 100644
index 00000000..b351bdb6
--- /dev/null
+++ b/packages/docs/docs/components/code/index.mdx
@@ -0,0 +1,790 @@
+---
+sidebar_position: 1
+slug: /code
+---
+
+# Code
+
+```tsx editor mode=preview
+import {makeScene2D, Code} from '@motion-canvas/2d';
+import {all, createRef, DEFAULT, waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const code = createRef<Code>();
+
+ view.add(
+ <Code
+ ref={code}
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ code={'const number = 7;'}
+ />,
+ );
+
+ yield* waitFor(0.6);
+ yield* all(
+ code().code.replace(code().findFirstRange('number'), 'variable', 0.6),
+ code().code.prepend(0.6)`function example() {\n `,
+ code().code.append(0.6)`\n}`,
+ );
+
+ yield* waitFor(0.6);
+ yield* code().selection(code().findFirstRange('variable'), 0.6);
+
+ yield* waitFor(0.6);
+ yield* all(
+ code().code('const number = 7;', 0.6),
+ code().selection(DEFAULT, 0.6),
+ );
+});
+```
+
+The [`Code`](/api/2d/components/Code) node is used for displaying code snippets.
+It supports syntax highlighting and a handful of different methods for animating
+the code.
+
+## Parsing and Highlighting
+
+First things first, if you just copy any of the snippets in this tutorial you'll
+notice that the displayed code has a uniform color. The default highlighter uses
+[`Lezer`](https://lezer.codemirror.net/) to parse and highlighting the code but
+to do that it needs the grammar for the language you're using. You can set that
+up in your project configuration file.
+
+First, install the grammar for your language. You can check out this
+non-exhaustive [list of available grammars](/docs/grammars). For this tutorial,
+you should install the `javascript` grammar:
+
+```bash
+npm i @lezer/javascript
+```
+
+Then, in your project configuration, import the grammar and register it via
+`LezerHighlighter`:
+
+```ts title="src/project.ts"
+import {makeProject} from '@motion-canvas/core';
+import example from './scenes/example?scene';
+
+// highlight-start
+import {LezerHighlighter} from '@motion-canvas/2d';
+import {parser} from '@lezer/javascript';
+
+LezerHighlighter.registerParser(parser);
+// highlight-end
+
+export default makeProject({
+ scenes: [example],
+});
+```
+
+This sets `@lezer/javascript` up as the default parser for all your code
+snippets. If you want to use more than one language, check out the
+[Multiple Languages](#multiple-languages) section.
+
+## Defining Code
+
+The code to display is set via the [`code`](/api/2d/components/Code#code)
+property. In the simplest case, you can just use a string:
+
+```tsx editor
+import {makeScene2D, Code} from '@motion-canvas/2d';
+
+export default makeScene2D(function* (view) {
+ view.add(
+ <Code
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ code={'const number = 7;'}
+ />,
+ );
+});
+```
+
+However, usually code snippets contain multiple lines of code. It's much more
+convenient to use a template string for this (denoted using the backtick
+character `` ` ``):
+
+```tsx
+view.add(
+ <Code
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ // highlight-start
+ code={`\
+function example() {
+ const number = 7;
+}
+`}
+ // highlight-end
+ />,
+);
+```
+
+Notice two things here:
+
+- The code snippet ignores the indentation of the template string itself. The
+ template string preserves all whitespace characters, so any additional spaces
+ or tabs at the beginning of each line would be included in the snippet.
+
+- The backslash character (`\`) at the very beginning is used to escape the
+ first newline character. This lets us start the snippet on a new line without
+ actually including an empty line at the start of the snippet. Without the
+ slash, the equivalent code would have to be written as:
+ ```tsx
+ view.add(
+ <Code
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ // highlight-start
+ code={`function example() {
+ const number = 7;
+ }
+ `}
+ // highlight-end
+ />,
+ );
+ ```
+
+Template strings allow you to easily include variables in your code snippets
+with `${}` syntax. In the example below, `${name}` is replaced with the value of
+the `name` variable (which is `number` in this case):
+
+```tsx
+// highlight-next-line
+const name = 'number';
+
+view.add(
+ <Code
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ code={`\
+function example() {
+ // highlight-next-line
+ const ${name} = 7;
+}
+`}
+ />,
+);
+```
+
+Any valid JavaScript expression inside the `${}` syntax will be included in the
+code snippet:
+
+```tsx
+// highlight-next-line
+const isRed = true;
+
+view.add(
+ <Code
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ code={`\
+function example() {
+ // highlight-next-line
+ const color = '${isRed ? 'red' : 'blue'}';
+}
+`}
+ />,
+);
+```
+
+## Using Signals
+
+If you try to use signals inside the `${}` syntax, you'll notice that they don't
+work as expected. Invoking a signal inside a template string uses its current
+value and then never updates the snippet again, even if the signal changes:
+
+```tsx editor mode=code
+import {makeScene2D, Code} from '@motion-canvas/2d';
+import {waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const nameSignal = Code.createSignal('number');
+ view.add(
+ <Code
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ code={`const ${nameSignal()} = 7;`}
+ />,
+ );
+
+ yield* waitFor(1);
+ nameSignal('newValue');
+ // The code snippet still displays "number" instead of "newValue".
+ yield* waitFor(1);
+});
+```
+
+Trying to pass the signal without invoking it is even worse. Since each signal
+is a function, it will be stringified and included in the snippet:
+
+```tsx editor
+import {makeScene2D, Code} from '@motion-canvas/2d';
+import {waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const nameSignal = Code.createSignal('number');
+ view.add(
+ <Code
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ code={`const ${nameSignal} = 7;`}
+ />,
+ );
+
+ yield* waitFor(1);
+ nameSignal('newValue');
+ yield* waitFor(1);
+});
+```
+
+This happens because template strings are parsed immediately when our code is
+executed. To work around this, you can use a custom [tag function][tag-function]
+called [`CODE`](/api/2d/code#CODE). It allows the `Code` node to parse the
+template string in a custom way and correctly support signals. It's really easy
+to use, simply put the `CODE` tag function before your template string:
+
+```tsx editor
+import {makeScene2D, Code, CODE} from '@motion-canvas/2d';
+import {waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const nameSignal = Code.createSignal('number');
+ view.add(
+ <Code
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ // Note the CODE tag function here:
+ code={CODE`const ${nameSignal} = 7;`}
+ />,
+ );
+
+ yield* waitFor(1);
+ nameSignal('newValue');
+ // Now the code snippet is updated accordingly.
+ yield* waitFor(1);
+});
+```
+
+The value returned by `CODE` can itself be nested in other template strings:
+
+```tsx
+const implementation = CODE`\
+ console.log('Hello!');
+ return 7;`;
+
+const method = CODE`\
+ greet() {
+${implementation}
+ }`;
+
+const klass = CODE`\
+class Example {
+${method}
+}
+`;
+
+view.add(<Code code={klass} />);
+// class Example {
+// greet() {
+// console.log('Hello!');
+// return 7;
+// }
+// }
+```
+
+You might have noticed that these examples used a specialized type of signal
+created using [`Code.createSignal()`](/api/2d/components/Code#createSignal).
+While the generic [`createSignal()`](/api/core/signals#createSignal) would work
+fine in these simple examples, the specialized signal will shine once you start
+animating your code snippets.
+
+## Animating Code
+
+The `Code` node comes with a few different techniques for animating the code
+depending on the level of control you need.
+
+### Diffing
+
+The default method for animating code is diffing. It's used whenever you tween
+the `code` property:
+
+```tsx editor
+import {makeScene2D, Code} from '@motion-canvas/2d';
+import {createRef} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const code = createRef<Code>();
+
+ view.add(
+ <Code
+ ref={code}
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ code={`\
+function example() {
+ const number = 9;
+}`}
+ />,
+ );
+
+ yield* code().code('const nine = 9;', 0.6).wait(0.6).back(0.6).wait(0.6);
+});
+```
+
+This method uses the patience diff algorithm to determine the differences
+between the old and new code snippets. It then animates the changes accordingly.
+
+### `append` and `prepend`
+
+For cases where you want to add some code at the beginning or end of the
+snippet, you can use the [`append`](/api/2d/code/CodeSignalContext#append) and
+[`prepend`](/api/2d/code/CodeSignalContext#prepend) methods. They can either
+modify the code immediately or animate the changes over time:
+
+```tsx editor
+import {makeScene2D, Code} from '@motion-canvas/2d';
+import {createRef, waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const code = createRef<Code>();
+
+ view.add(
+ <Code
+ ref={code}
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ />,
+ );
+
+ // append immediately
+ code().code.append(`const one = 1;`);
+
+ // animate using the signal signature
+ yield* code().code.append('\nconst two = 2;', 0.6);
+
+ // animate using the template tag signature
+ yield* code().code.append(0.6)`
+const three = 3;`;
+
+ // prepend works analogically
+ yield* code().code.prepend('// example\n', 0.6);
+
+ yield* waitFor(0.6);
+});
+```
+
+### `insert`, `replace`, and `remove`
+
+For more granular control over the changes, you can use
+[`insert`](/api/2d/code/CodeSignalContext#insert),
+[`replace`](/api/2d/code/CodeSignalContext#replace), and
+[`remove`](/api/2d/code/CodeSignalContext#remove) to modify the code at specific
+points. Check out [Code Ranges](#code-ranges) for more information on how to
+specify points in your code snippets.
+
+```tsx editor
+import {makeScene2D, Code, word, lines} from '@motion-canvas/2d';
+import {all, createRef, waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const code = createRef<Code>();
+
+ view.add(
+ <Code
+ ref={code}
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ code={`\
+function example() {
+ console.log('Hello!');
+}`}
+ />,
+ );
+
+ // insert code at line 2, column 0
+ yield* code().code.insert([2, 0], ' return 7;\n', 0.6);
+
+ // replace the word "Hello!" with "Goodbye!"
+ yield* code().code.replace(word(1, 15, 6), 'Goodbye!', 0.6);
+
+ // remove line 2
+ yield* code().code.remove(lines(2), 0.6);
+
+ // animate multiple changes at the same time
+ yield* all(
+ code().code.replace(word(0, 9, 7), 'greet', 0.6),
+ code().code.replace(word(1, 15, 8), 'Hello!', 0.6),
+ );
+
+ yield* waitFor(0.6);
+});
+```
+
+### `edit`
+
+The [`edit`](/api/2d/code/CodeSignalContext#edit) method offers a different way
+of defining code transitions. It's used together with the
+[`replace`](/api/2d/code#insert), [`insert`](/api/2d/code#insert), and
+[`remove`](/api/2d/code#remove) helper functions that are inserted into the
+template string. They let you specify the changes in a more visual way, without
+having to know the exact positions in the code:
+
+```tsx editor
+import {makeScene2D, Code, replace, insert, remove} from '@motion-canvas/2d';
+import {createRef, waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const code = createRef<Code>();
+
+ view.add(
+ <Code
+ ref={code}
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ />,
+ );
+
+ yield* code().code.edit(0.6)`\
+function example() {
+ ${insert(`// This is a comment
+ `)}console.log("${replace('Hello!', 'Goodbye!')}");
+${remove(` return 7;
+`)}}`;
+
+ yield* waitFor(0.6);
+});
+```
+
+### Signals
+
+Notice that all the methods used above are not invoked on the `Code` node but
+rather on its `code` property. It may seem unnecessarily verbose but there's a
+good reason for it: the `code` property is a specialized code signal, just like
+the ones created by
+[`Code.createSignal()`](/api/2d/components/Code#createSignal). This means that
+all the animation methods are also available on your own signals:
+
+```tsx editor
+import {makeScene2D, Code, CODE} from '@motion-canvas/2d';
+import {all, waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const message = Code.createSignal(`Hello, world!`);
+ const body = Code.createSignal(CODE`console.log('${message}');`);
+
+ view.add(
+ <Code
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ code={CODE`\
+function hello() {
+ ${body}
+}`}
+ />,
+ );
+
+ yield* waitFor(0.3);
+ // prettier-ignore
+ yield* all(
+ message('Goodbye, world!', 0.6),
+ body.append(0.6)`\n return 7;`,
+ );
+ yield* waitFor(0.3);
+});
+```
+
+Code signals can also be nested in the template strings passed to the animation
+methods:
+
+```tsx editor mode=code
+import {makeScene2D, Code, CODE} from '@motion-canvas/2d';
+import {createRef, waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const code = createRef<Code>();
+
+ view.add(
+ <Code
+ ref={code}
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ code={'// example'}
+ />,
+ );
+
+ const body = Code.createSignal(CODE`console.log('Hello!');`);
+ yield* waitFor(0.3);
+ // Notice how the CODE tag is not used here because
+ // "append" already supports nested signals:
+ yield* code().code.append(0.6)`
+function hello() {
+ ${body}
+}`;
+
+ // The "body" signal remains reactive after the append animation:
+ yield* body(`console.log('Goodbye!');`, 0.6);
+ yield* waitFor(0.3);
+});
+```
+
+## Code Ranges
+
+A [`CodeRange`](/api/2d/code#CodeRange) is used to specify a continuous span of
+characters using line and column numbers. It can be used for editing the code,
+visually selecting a part of it, or querying the positions and sizes of
+characters.
+
+Code ranges have the following structure:
+
+```js
+// prettier-ignore
+[[startLine, startColumn], [endLine, endColumn]];
+```
+
+For example, to select the first three characters of the second line, you would
+use the following range:
+
+```js
+// prettier-ignore
+[[1, 0], [1, 3]];
+```
+
+Keep in mind that both lines and columns are zero-based. Additionally, you
+should think of columns as being located on the left side of the characters,
+meaning that if you want to include the character at column `n` you should use
+`n + 1` as the end column.
+
+For convenience, the [`word`](/api/2d/code#word) and
+[`lines`](/api/2d/code#lines) helper functions are provided to create some of
+the common types of ranges:
+
+```ts
+// a range starting at line 1, column 3,
+// spanning 3 characters:
+word(1, 3, 3);
+
+// a range starting at line 1, column 3,
+// spanning until the end of the line:
+word(1, 3);
+
+// a range containing lines from 1 to 3 (inclusive):
+lines(1, 3);
+
+// a range containing line 2
+lines(2);
+```
+
+Once you create a `Code` node, you can use its
+[`findFirstRange`](/api/2d/components/Code#findFirstRange),
+[`findAllRanges`](/api/2d/components/Code#findAllRanges), and
+[`findLastRange`](/api/2d/components/Code#findLastRange) methods to find the
+ranges that contain a specific string or match the given regular expression:
+
+```tsx editor mode=code
+import {makeScene2D, Code} from '@motion-canvas/2d';
+import {createRef, waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const code = createRef<Code>();
+
+ view.add(
+ <Code
+ ref={code}
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ code={`\
+function example() {
+ console.log('Hello!');
+}`}
+ />,
+ );
+
+ yield* code().code.replace(
+ // find the range of "example" and replace it with "greet"
+ code().findFirstRange('example'),
+ 'greet',
+ 0.6,
+ );
+
+ yield* waitFor(0.6);
+});
+```
+
+## Code Selection
+
+The [`selection`](/api/2d/code/CodeSignalContext#selection) property can be used
+to visually distinguish a part of the code snippet. The selection is specified
+using an individual [`code range`](#code-ranges) or an array of ranges:
+
+```tsx editor
+import {makeScene2D, Code, lines} from '@motion-canvas/2d';
+import {createRef, DEFAULT, waitFor} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const code = createRef<Code>();
+
+ view.add(
+ <Code
+ ref={code}
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ code={`\
+function hello() {
+ console.log('Hello');
+}`}
+ />,
+ );
+
+ // select all instances of "hello" (case-insensitive)
+ yield* code().selection(code().findAllRanges(/hello/gi), 0.6);
+ yield* waitFor(0.3);
+
+ // select line 1
+ yield* code().selection(lines(1), 0.6);
+ yield* waitFor(0.3);
+
+ // reset the selection
+ yield* code().selection(DEFAULT, 0.6);
+ yield* waitFor(0.3);
+});
+```
+
+## Querying Positions and Sizes
+
+[`getPointBBox`](/api/2d/components/Code#getPointBBox) and
+[`getSelectionBBox`](/api/2d/components/Code#getSelectionBBox) can be used to
+retrieve the position and size of a specific character or a range of characters,
+respectively. The returned value is a [`bounding box`](/api/core/types/BBox) in
+the local space of the `Code` node.
+
+The following example uses `getSelectionBBox` to draw a rectangle around the
+word `log`:
+
+```tsx editor
+import {Code, Rect, makeScene2D} from '@motion-canvas/2d';
+import {createRef, createSignal} from '@motion-canvas/core';
+
+export default makeScene2D(function* (view) {
+ const code = createRef<Code>();
+
+ view.add(
+ <Code
+ ref={code}
+ fontSize={28}
+ fontFamily={'JetBrains Mono'}
+ offsetX={-1}
+ x={-400}
+ code={`\
+function hello() {
+ console.log('Hello');
+}`}
+ />,
+ );
+
+ const range = createSignal(() => {
+ const range = code().findFirstRange('log');
+ const bboxes = code().getSelectionBBox(range);
+ // "getSelectionBBox" returns an array of bboxes,
+ // one for each line in the range. You can just
+ // use the first one for this example.
+ const first = bboxes[0];
+ return first.expand([4, 8]);
+ });
+
+ code().add(
+ <Rect
+ offset={-1}
+ position={range().position}
+ size={range().size}
+ lineWidth={4}
+ stroke={'white'}
+ radius={8}
+ />,
+ );
+});
+```
+
+## Multiple Languages
+
+You can register parsers for multiple different languages by giving them a
+unique name during registration:
+
+```ts
+import {LezerHighlighter} from '@motion-canvas/2d';
+import {parser as jsParser} from '@lezer/javascript';
+// highlight-next-line
+import {parser as rsParser} from '@lezer/rust';
+
+LezerHighlighter.registerParser(jsParser);
+// highlight-next-line
+LezerHighlighter.registerParser(rsParser, 'rs');
+```
+
+This name can then be passed to the [`dialect`](/api/2d/components/Code#dialect)
+property of a specific `Code` node to use a different parser:
+
+```tsx editor mode=code
+import {makeScene2D, Code} from '@motion-canvas/2d';
+
+export default makeScene2D(function* (view) {
+ // Font properties configured for the view are
+ // inherited by all text nodes, including Code:
+ view.fontSize(28).fontFamily('JetBrains Mono');
+
+ view.add(
+ <>
+ <Code
+ // this node uses the default parser (javascript)
+ offsetX={-1}
+ x={-400}
+ code={`
+function hello() {
+ console.log('Hello!');
+}
+`}
+ />
+ <Code
+ // this node uses the "rs" parser (rust)
+ dialect={'rs'}
+ offsetX={1}
+ x={400}
+ code={`
+fn hello() {
+ println!("Hello!");
+}
+`}
+ />
+ </>,
+ );
+});
+```
+
+## Rendering
+
+If you're using a Chromium-based browser, you might notice that the code
+animations jitter a bit. This happens because the canvas snaps the rendered text
+to the nearest pixel which prevents it from moving smoothly. Until we find a way
+to fix this, we recommend you use Firefox for rendering.
+
+[tag-function]:
+ https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates
diff --git a/packages/docs/docs/components/path.mdx b/packages/docs/docs/components/path.mdx
index c4fafec0..3d3427b9 100644
--- a/packages/docs/docs/components/path.mdx
+++ b/packages/docs/docs/components/path.mdx
@@ -5,7 +5,7 @@ slug: /path
# Path
-```tsx editor
+```tsx editor mode=preview
import {makeScene2D, Path} from '@motion-canvas/2d';
import {createRef} from '@motion-canvas/core';
diff --git a/packages/docs/docs/components/spline.mdx b/packages/docs/docs/components/spline.mdx
index 6903c670..139a24f4 100644
--- a/packages/docs/docs/components/spline.mdx
+++ b/packages/docs/docs/components/spline.mdx
@@ -5,7 +5,7 @@ slug: /spline
# Spline
-```tsx editor
+```tsx editor mode=preview
import {makeScene2D, Spline, Knot} from '@motion-canvas/2d';
import {createRef} from '@motion-canvas/core';
diff --git a/packages/docs/docusaurus.config.js b/packages/docs/docusaurus.config.js
index bb3d0206..40d397a3 100644
--- a/packages/docs/docusaurus.config.js
+++ b/packages/docs/docusaurus.config.js
@@ -109,6 +109,17 @@ const config = {
theme: require('./config/codeTheme'),
darkTheme: require('./config/codeTheme'),
additionalLanguages: ['glsl'],
+ magicComments: [
+ {
+ className: 'theme-code-block-highlighted-line',
+ line: 'highlight-next-line',
+ block: {start: 'highlight-start', end: 'highlight-end'},
+ },
+ {
+ className: 'prettier-ignore',
+ line: 'prettier-ignore',
+ },
+ ],
},
}),
themes: [
diff --git a/packages/docs/package.json b/packages/docs/package.json
index c7ddf7c3..0dae17e2 100644
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -23,6 +23,8 @@
"@docusaurus/preset-classic": "^2.4.0",
"@docusaurus/theme-mermaid": "^2.4.0",
"@docusaurus/theme-search-algolia": "^2.4.0",
+ "@lezer/javascript": "^1.4.13",
+ "@lezer/rust": "^1.0.2",
"@mdx-js/react": "^1.6.22",
"@motion-canvas/examples": "*",
"@motion-canvas/player": "*",
diff --git a/packages/docs/src/components/Fiddle/SharedPlayer.ts b/packages/docs/src/components/Fiddle/SharedPlayer.ts
index 08bd1d78..f7f1243a 100644
--- a/packages/docs/src/components/Fiddle/SharedPlayer.ts
+++ b/packages/docs/src/components/Fiddle/SharedPlayer.ts
@@ -1,3 +1,5 @@
+import {parser as javascript} from '@lezer/javascript';
+import {parser as rust} from '@lezer/rust';
import type {View2D} from '@motion-canvas/2d';
import type {
FullSceneDescription,
@@ -58,9 +60,11 @@ export async function borrowPlayer(
ValueDispatcher,
DefaultPlugin,
} = await import(/* webpackIgnore: true */ '@motion-canvas/core');
- const {makeScene2D} = await import(
+ const {makeScene2D, LezerHighlighter} = await import(
/* webpackIgnore: true */ '@motion-canvas/2d'
);
+ LezerHighlighter.registerParser(javascript);
+ LezerHighlighter.registerParser(rust, 'rs');
Description = makeScene2D(function* () {
yield;