Skip to content

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_.yml
index 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: 4
link:
type: generated-index
diff --git a/packages/docs/docs/advanced/custom-font.mdx b/packages/docs/docs/advanced/custom-font.mdx
index 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 web
diff --git a/packages/docs/docs/advanced/project-variables.mdx b/packages/docs/docs/advanced/project-variables.mdx
index 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: 2
slug: /project-variables
---
diff --git a/packages/docs/docs/advanced/random.mdx b/packages/docs/docs/advanced/random.mdx
index b74f7e22..e8632323 100644
--- a/packages/docs/docs/advanced/random.mdx
+++ b/packages/docs/docs/advanced/random.mdx
@@ -1,4 +1,5 @@
---
+sidebar_position: 3
slug: /random-values
---
diff --git a/packages/docs/docs/advanced/spawners.mdx b/packages/docs/docs/advanced/spawners.mdx
index c65c743e..d122fff6 100644
--- a/packages/docs/docs/advanced/spawners.mdx
+++ b/packages/docs/docs/advanced/spawners.mdx
@@ -1,4 +1,5 @@
---
+sidebar_position: 4
slug: /spawners
---
diff --git a/packages/docs/docs/components/_category_.yml b/packages/docs/docs/components/_category_.yml
new file mode 100644
index 00000000..9cd9fc91
--- /dev/null
+++ b/packages/docs/docs/components/_category_.yml
@@ -0,0 +1,4 @@
+label: Components
+position: 3
+link:
+ type: generated-index
diff --git a/packages/docs/docs/components/code-block.mdx b/packages/docs/docs/components/code-block.mdx
new file mode 100644
index 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#languages
diff --git a/packages/docs/docs/advanced/custom-components.mdx b/packages/docs/docs/components/custom-components.mdx
similarity index 99%
rename from packages/docs/docs/advanced/custom-components.mdx
rename to packages/docs/docs/components/custom-components.mdx
index 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: 3
slug: /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.mdx
similarity index 91%
rename from packages/docs/docs/getting-started/nodes.mdx
rename to packages/docs/docs/components/nodes.mdx
index 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: 2
slug: /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 LaTeX
Because we use a canvas renderer, we're rendering the LaTeX to an image instead
using a full graphics backend to render the TeX. This means that for all intents
diff --git a/packages/docs/docs/getting-started/configuration.mdx b/packages/docs/docs/getting-started/configuration.mdx
index 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: 11
slug: /configuration
---
diff --git a/packages/docs/docs/getting-started/rendering.mdx b/packages/docs/docs/getting-started/rendering.mdx
index 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.mdx
index 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: 6
slug: /signals
---
diff --git a/packages/docs/docs/getting-started/time-events.mdx b/packages/docs/docs/getting-started/time-events.mdx
index 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: 9
slug: /time-events
---
diff --git a/packages/docs/docs/getting-started/transitions.mdx b/packages/docs/docs/getting-started/transitions.mdx
index 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: 10
slug: /transitions
---
diff --git a/packages/docs/docs/getting-started/tweening.mdx b/packages/docs/docs/getting-started/tweening.mdx
index 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: 7
slug: /tweening
---
diff --git a/packages/examples/src/code-block.meta b/packages/examples/src/code-block.meta
new file mode 100644
index 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.ts
new file mode 100644
index 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.meta
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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',