Visualize Your Ideas With Code
docs: document Code node (#999)
Jacobc6db8ce828ea
diff --git a/package-lock.json b/package-lock.jsonindex 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.tsindex 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.jsindex 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.mdxindex 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ézierimport {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.mdxindex 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: 100slug: /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 candiff --git a/packages/docs/docs/components/code/grammars.json b/packages/docs/docs/components/code/grammars.jsonnew file mode 100644index 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.mdxnew file mode 100644index 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.jsondiff --git a/packages/docs/docs/components/code/index.mdx b/packages/docs/docs/components/code/index.mdxnew file mode 100644index 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_templatesdiff --git a/packages/docs/docs/components/path.mdx b/packages/docs/docs/components/path.mdxindex 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=previewimport {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.mdxindex 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=previewimport {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.jsindex 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.jsonindex 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.tsindex 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;