Visualize Your Ideas With Code
feat(docs): added CodeBlock documentation (#302)
Ross Esmond73f7221536e0
diff --git a/packages/docs/docs/advanced/_category_.yml b/packages/docs/docs/advanced/_category_.ymlindex b03b99cc..7e6ff471 100644--- a/packages/docs/docs/advanced/_category_.yml+++ b/packages/docs/docs/advanced/_category_.yml@@ -1,4 +1,4 @@label: Advanced-position: 3+position: 4link:type: generated-indexdiff --git a/packages/docs/docs/advanced/custom-font.mdx b/packages/docs/docs/advanced/custom-font.mdxindex 5c252e96..aa4cb934 100644--- a/packages/docs/docs/advanced/custom-font.mdx+++ b/packages/docs/docs/advanced/custom-font.mdx@@ -1,3 +1,8 @@+---+sidebar_position: 1+slug: /custom-font+---+# Custom font## Loading fonts from the webdiff --git a/packages/docs/docs/advanced/project-variables.mdx b/packages/docs/docs/advanced/project-variables.mdxindex 1812b9e9..7c8f4b12 100644--- a/packages/docs/docs/advanced/project-variables.mdx+++ b/packages/docs/docs/advanced/project-variables.mdx@@ -1,4 +1,5 @@---+sidebar_position: 2slug: /project-variables---diff --git a/packages/docs/docs/advanced/random.mdx b/packages/docs/docs/advanced/random.mdxindex b74f7e22..e8632323 100644--- a/packages/docs/docs/advanced/random.mdx+++ b/packages/docs/docs/advanced/random.mdx@@ -1,4 +1,5 @@---+sidebar_position: 3slug: /random-values---diff --git a/packages/docs/docs/advanced/spawners.mdx b/packages/docs/docs/advanced/spawners.mdxindex c65c743e..d122fff6 100644--- a/packages/docs/docs/advanced/spawners.mdx+++ b/packages/docs/docs/advanced/spawners.mdx@@ -1,4 +1,5 @@---+sidebar_position: 4slug: /spawners---diff --git a/packages/docs/docs/components/_category_.yml b/packages/docs/docs/components/_category_.ymlnew file mode 100644index 00000000..9cd9fc91--- /dev/null+++ b/packages/docs/docs/components/_category_.yml@@ -0,0 +1,4 @@+label: Components+position: 3+link:+ type: generated-indexdiff --git a/packages/docs/docs/components/code-block.mdx b/packages/docs/docs/components/code-block.mdxnew file mode 100644index 00000000..d9bbe36b--- /dev/null+++ b/packages/docs/docs/components/code-block.mdx@@ -0,0 +1,264 @@+---+sidebar_position: 1+slug: /code-block+---++import AnimationPlayer from '@site/src/components/AnimationPlayer';+import signalSource from '!!raw-loader!@motion-canvas/examples/src/scenes/node-signal';++# CodeBlock++<AnimationPlayer banner name="code-block" />++The `CodeBlock` component is used to present syntax highlighted code. It can+automatically highlight many common languages. That code can then be modified in+place to present changes to the viewer. Modified code will animate from the+prior code to the new code by removing old code, translating the remaining code,+and inserting new code. You may also "select" code in order to call attention to+important snippets.++## Using the component++To display code, set the `code` and `language` property.++```ts+import {CodeBlock} from '@motion-canvas/2d/lib/components/CodeBlock';++yield view.add(+ <CodeBlock language="c#" code={`Console.WriteLine("Hello World!")`} />,+);+```++You can find a list of available languages in the [Starry Night][languages]+repository—the library used for syntax highlighting. The default language is+`tsx`, the language of Motion Canvas, which we will use for the rest of this+guide.++Note that unlike most components, you must `yield` any call to `add` which+includes a `CodeBlock`. This prompts Motion Canvas to prepare the syntax+highlighter.++```tsx+yield view.add(<CodeBlock />);+```++### Indentation++For convenience, the indentation of code will be automatically adjust whenever+the code starts with a new line.++```tsx+import {CodeBlock} from '@motion-canvas/2d/lib/components/CodeBlock';++yield view.add(+ // note that the ` bracket is followed by a new line+ <CodeBlock+ code={`+ console.log('Hello World!')+ // more indented+ // less indented`}+ />,+);+```++<!-- prettier-ignore -->+```tsx+console.log('Hello World!');+ // more indented+// less indented+```++The indentation is then set by the least indented code.++```tsx+import {CodeBlock} from '@motion-canvas/2d/lib/components/CodeBlock';++yield view.add(+ // note that the ` bracket is followed by a new line+ <CodeBlock+ code={`+ console.log('Hello World!')+ // less indented+ // more indented`}+ />,+);+```++<!-- prettier-ignore -->+```tsx+ console.log('Hello World!');+// less indented+ // more indented+```++### Selection++Code may be "selected" to call attention to it. The default behavior is to+desaturate any unselected text.++A selection can be made using the `selection` property when the `CodeBlock` is+first created. Selections are specified using two `[line, position]` arrays,+where `line` and `position` are zero indexed, and `position` is an insert+position between characters. So `[[0, 5], [1, 2]]` will select the sixth+character on the first line through to the second character on the second line.++The following code will select `myBool` out of the code snippet.++```tsx+yield view.add(+ <CodeBlock+ code={`var myBool;`}+ selection={[+ [0, 4],+ [0, 10],+ ]}+ />,+);+```++It is often better, however, to use one of the three provided utility functions+for selection. Though they all return a two by two array of numbers, they can be+more descriptive than an array literal.++The first and most commonly used is the `range` function. `range(0, 4, 0, 10)`+is equivalent to `[[0, 4], [0, 10]]`, making `range` a direct substitute for an+array literal.++The second is the `word` function, which creates a range on a single line using+a position and a length. So `word(2, 4, 6)` will make a selection on the third+line, starting at the fifth character, and selecting a total of six characters.++Finally, you can use the `lines` function to select whole lines of code.++```tsx+import {CodeBlock, lines} from '@motion-canvas/2d/lib/components/CodeBlock';++const codeRef = createRef();+yield view.add(+ <CodeBlock+ ref={codeRef}+ code={`+ // first line+ // second line+ // third line`}+ />,+);++// second line only+yield * codeRef().selection(line(1));+// second and third line (line 1 to line 2)+yield * codeRef().selection(line(1, 2));+```++To remove a selection, you must set the selected range from `[0, 0]` to+`[Infinity, Infinity]` to select all text. This is most easily performed by+setting the selection to `lines(0, Infinity)`.++### Animating code++You may insert, remove, or edit the displayed code, any of which will animate+the code to its new state. All of these changes are performed with the `edit`+method on a `CodeBlock` instance.++To insert code, start by using `createRef` to store your `CodeBlock` instance+for future edits. Then call `edit` with an embedded `insert` call to add the new+code.++```tsx+import {CodeBlock, insert} from '@motion-canvas/2d/lib/components/CodeBlock';+import {createRef} from '@motion-canvas/core/lib/utils';++const codeRef = createRef<CodeBlock>();++yield view.add(<CodeBlock ref={codeRef} code={`var myBool;`} />);++// duration of 1.2 seconds+yield * codeRef().edit(1.2)`var myBool${insert(' = true')};`;+```++```tsx+var myBool;+// will animate to+var myBool = true;+```++Removing code is similar, only with the provided code being removed during the+animation.++```tsx+import {CodeBlock, remove} from '@motion-canvas/2d/lib/components/CodeBlock';++yield view.add(<CodeBlock ref={codeRef} code={`var myBool = true;`} />);++yield * codeRef().edit(1.2)`var myBool${remove(' = true')};`;+```++```tsx+var myBool = true;+// will animate to+var myBool;+```++Finally, replacing code combines removal and insertion into one call.++```tsx+yield view.add(<CodeBlock ref={codeRef} code={`var myBool = true;`} />);++yield * codeRef().edit(1.2)`var myBool = ${edit('true', 'false')};`;+```++```tsx+var myBool = true;+// will animate to+var myBool = false;+```++Editing code will update your selection to highlight the changes. If you would+like to retain your selection through an animation, use `edit(duration, false)`.++```tsx+yield view.add(<CodeBlock ref={codeRef} code={`var myBool;`} />);++// note the second argument to edit+yield * codeRef().edit(1.2, false)`var myBool${insert(' = true')};`;+```++You may apply multiple edits to a code block over the course of a video, each+modifying the prior code to a new state.++```tsx+yield view.add(<CodeBlock ref={codeRef} code={`var myBool;`} />);++yield * codeRef().edit(1.2)`var myBool${insert(' = true')};`;+yield * waitFor(1);+yield * codeRef().edit(1.2)`var myBool = ${edit('true', 'false')};`;+yield * waitFor(1);+yield * codeRef().edit(1.2)`var myBool${remove(' = false')};`;+```++The proceeding code will animate through++```tsx+var myBool;+var myBool = true;+var myBool = false;+var myBool;+```++You can also apply multiple changes to a code block in one `edit`, such that all+changes are applied simultaneously.++```tsx+yield view.add(<CodeBlock ref={codeRef} code={`var myBool;`} />);++yield *+ codeRef().edit(1.2)`${edit('var', 'const')} myBool${insert(' = true')};`;+```++```tsx+var myBool;+// will animate to+const myBool = true;+```++[languages]: https://github.com/wooorm/starry-night#languagesdiff --git a/packages/docs/docs/advanced/custom-components.mdx b/packages/docs/docs/components/custom-components.mdxsimilarity index 99%rename from packages/docs/docs/advanced/custom-components.mdxrename to packages/docs/docs/components/custom-components.mdxindex 721bb90f..a39d420b 100644--- a/packages/docs/docs/advanced/custom-components.mdx+++ b/packages/docs/docs/components/custom-components.mdx@@ -1,4 +1,5 @@---+sidebar_position: 3slug: /custom-components---@@ -6,7 +7,7 @@ import AnimationPlayer from '@site/src/components/AnimationPlayer';import CodeBlock from '@theme/CodeBlock';import source from '!!raw-loader!@motion-canvas/examples/src/components/Switch';-# Components+# Custom Components<AnimationPlayer name="components" banner />diff --git a/packages/docs/docs/getting-started/nodes.mdx b/packages/docs/docs/components/nodes.mdxsimilarity index 91%rename from packages/docs/docs/getting-started/nodes.mdxrename to packages/docs/docs/components/nodes.mdxindex f2343ca1..2ac140cc 100644--- a/packages/docs/docs/getting-started/nodes.mdx+++ b/packages/docs/docs/components/nodes.mdx@@ -1,5 +1,5 @@----sidebar_position: 10+sidebar_position: 2slug: /nodes---@@ -7,15 +7,13 @@ import AnimationPlayer from '@site/src/components/AnimationPlayer';import CodeBlock from '@theme/CodeBlock';import texSource from '!!raw-loader!@motion-canvas/examples/src/scenes/tex';-# Nodes--## LaTeX+# LaTeX<CodeBlock language="tsx">{texSource}</CodeBlock><AnimationPlayer small name="tex" />-### A note on tweening LaTeX+## A note on tweening LaTeXBecause we use a canvas renderer, we're rendering the LaTeX to an image insteadusing a full graphics backend to render the TeX. This means that for all intentsdiff --git a/packages/docs/docs/getting-started/configuration.mdx b/packages/docs/docs/getting-started/configuration.mdxindex d5cde42c..cb632740 100644--- a/packages/docs/docs/getting-started/configuration.mdx+++ b/packages/docs/docs/getting-started/configuration.mdx@@ -1,5 +1,5 @@----sidebar_position: 10+sidebar_position: 11slug: /configuration---diff --git a/packages/docs/docs/getting-started/rendering.mdx b/packages/docs/docs/getting-started/rendering.mdxindex 3206e6fb..0b7f9aa5 100644--- a/packages/docs/docs/getting-started/rendering.mdx+++ b/packages/docs/docs/getting-started/rendering.mdx@@ -1,5 +1,6 @@----sidebar_position: 11+sidebar_position: 12+slug: /rendering---import {VideoSettings} from '@site/src/Icon/VideoSettings';diff --git a/packages/docs/docs/getting-started/signals.mdx b/packages/docs/docs/getting-started/signals.mdxindex d40a862f..eca27327 100644--- a/packages/docs/docs/getting-started/signals.mdx+++ b/packages/docs/docs/getting-started/signals.mdx@@ -1,5 +1,5 @@----sidebar_position: 5+sidebar_position: 6slug: /signals---diff --git a/packages/docs/docs/getting-started/time-events.mdx b/packages/docs/docs/getting-started/time-events.mdxindex e53cf3f7..b4f35a9a 100644--- a/packages/docs/docs/getting-started/time-events.mdx+++ b/packages/docs/docs/getting-started/time-events.mdx@@ -1,5 +1,5 @@----sidebar_position: 8+sidebar_position: 9slug: /time-events---diff --git a/packages/docs/docs/getting-started/transitions.mdx b/packages/docs/docs/getting-started/transitions.mdxindex 92669caa..23c01eb1 100644--- a/packages/docs/docs/getting-started/transitions.mdx+++ b/packages/docs/docs/getting-started/transitions.mdx@@ -1,5 +1,5 @@----sidebar_position: 9+sidebar_position: 10slug: /transitions---diff --git a/packages/docs/docs/getting-started/tweening.mdx b/packages/docs/docs/getting-started/tweening.mdxindex c8843174..674bb861 100644--- a/packages/docs/docs/getting-started/tweening.mdx+++ b/packages/docs/docs/getting-started/tweening.mdx@@ -1,5 +1,5 @@----sidebar_position: 6+sidebar_position: 7slug: /tweening---diff --git a/packages/examples/src/code-block.meta b/packages/examples/src/code-block.metanew file mode 100644index 00000000..5dfe44db--- /dev/null+++ b/packages/examples/src/code-block.meta@@ -0,0 +1,3 @@+{+ "version": 0+}diff --git a/packages/examples/src/code-block.ts b/packages/examples/src/code-block.tsnew file mode 100644index 00000000..36020f02--- /dev/null+++ b/packages/examples/src/code-block.ts@@ -0,0 +1,7 @@+import {makeProject} from '@motion-canvas/core';++import scene from './scenes/code-block?scene';++export default makeProject({+ scenes: [scene],+});diff --git a/packages/examples/src/scenes/code-block.meta b/packages/examples/src/scenes/code-block.metanew file mode 100644index 00000000..61a2092b--- /dev/null+++ b/packages/examples/src/scenes/code-block.meta@@ -0,0 +1,3 @@+{+ "version": 1+}diff --git a/packages/examples/src/scenes/code-block.tsx b/packages/examples/src/scenes/code-block.tsxnew file mode 100644index 00000000..d6bf5b42--- /dev/null+++ b/packages/examples/src/scenes/code-block.tsx@@ -0,0 +1,33 @@+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';+import {createRef} from '@motion-canvas/core/lib/utils';+import {+ CodeBlock,+ edit,+ insert,+ lines,+ remove,+} from '@motion-canvas/2d/lib/components/CodeBlock';+import {all, waitFor} from '@motion-canvas/core/lib/flow';++export default makeScene2D(function* (view) {+ const codeRef = createRef<CodeBlock>();++ yield view.add(<CodeBlock ref={codeRef} code={`var myBool;`} />);++ yield* codeRef().edit(1.2, false)`var myBool${insert(' = true')};`;+ yield* waitFor(0.6);+ yield* codeRef().edit(1.2)`var myBool = ${edit('true', 'false')};`;+ yield* waitFor(0.6);+ yield* all(+ codeRef().selection(lines(0, Infinity), 1.2),+ codeRef().edit(1.2, false)`var my${edit('Bool', 'Number')} = ${edit(+ 'false',+ '42',+ )};`,+ );+ yield* waitFor(0.6);+ yield* codeRef().edit(1.2, false)`var myNumber${remove(' = 42')};`;+ yield* waitFor(0.6);+ yield* codeRef().edit(1.2, false)`var my${edit('Number', 'Bool')};`;+ yield* waitFor(0.6);+});diff --git a/packages/examples/vite.config.ts b/packages/examples/vite.config.tsindex 21cdde4b..3948aceb 100644--- a/packages/examples/vite.config.ts+++ b/packages/examples/vite.config.ts@@ -13,6 +13,7 @@ export default defineConfig({'./src/tweening-vector.ts','./src/tweening-visualiser.ts','./src/node-signal.ts',+ './src/code-block.ts','./src/random.ts','./src/layout.ts','./src/layout-group.ts',