Skip to content

Visualize Your Ideas With Code

docs: fix selection interface in Code Block Docs (#790)

Waldemar Lehner18055fe6fe4f
diff --git a/packages/docs/docs/components/code-block.mdx b/packages/docs/docs/components/code-block.mdx
index 8c4a103f..9ff6e549 100644
--- a/packages/docs/docs/components/code-block.mdx
+++ b/packages/docs/docs/components/code-block.mdx
@@ -3,11 +3,10 @@ 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
+import AnimationPlayer from '@site/src/components/AnimationPlayer';
+
<AnimationPlayer banner name="code-block" />
The `CodeBlock` component is used to present syntax highlighted code. It can
@@ -21,7 +20,7 @@ important snippets.
To display code, set the `code` and `language` property.
-```ts
+```tsx
import {CodeBlock} from '@motion-canvas/2d/lib/components/CodeBlock';
yield view.add(
@@ -96,62 +95,79 @@ yield view.add(
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.
+#### Using Helpers
-The following code will select `myBool` out of the code snippet.
+You can define the selection with the help of three helper functions — `range`,
+`word` and `lines`.
```tsx
+import {CodeBlock} from '@motion-canvas/2d/lib/components/CodeBlock';
+import {createRef} from '@motion-canvas/core';
+
+const codeBlockRef = createRef<CodeBlock>();
yield view.add(
- <CodeBlock
- code={`var myBool;`}
- selection={[
- [0, 4],
- [0, 10],
- ]}
- />,
+ <CodeBlock ref={codeBlockRef} code={`...`} selection={range(0, 2, 0, 4)} />,
);
+// or
+yield codeBlockRef.selection(range(0, 2, 0, 4));
```
-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.
+`range` expects 4 parameters: the starting line, starting character offset,
+ending line and ending character offset. Do note however that all values are
+**zero-indexed**. So if you want to select a 5 character long word on the first
+line that has another 4 characters before it, you would use the following call:
-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.
+```ts
+range(
+ 0, // starting on the first line
+ 4, // starting with the 5th character
+ 0, // ending on the first line
+ 8, // ending with the 9th character
+);
+```
-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.
+For this specific use case there is however another helper, `word`. It expects
+2-3 parameters - the starting line and character offset, aswell as an optional
+word length.
-Finally, you can use the `lines` function to select whole lines of code.
+The aforementioned `range`-Example could be rewritten as follows using the
+`word`-Helper:
-```tsx
-import {CodeBlock, lines} from '@motion-canvas/2d/lib/components/CodeBlock';
+```ts
+word(
+ 0, // starting on the first line
+ 4, // starting with the 5th character,
+ 5, // the selection will have a total of 5 chars, can be ommited, which will select the remainder of this line
+);
+```
-const codeRef = createRef();
-yield view.add(
- <CodeBlock
- ref={codeRef}
- code={`
- // first line
- // second line
- // third line`}
- />,
+Do note that the `word`-Helper can only be applied on a per-line basis.
+
+Finally, you can use the `lines` function to select whole lines of code. The
+following will select the 5th up to the 10th line:
+
+```ts
+lines(
+ 4, // starting line
+ 9, // ending line, can be ommited, which will only select the starting line
);
+```
-// second line only
-yield * codeRef().selection(lines(1), 1);
-// second and third line (line 1 to line 2)
-yield * codeRef().selection(lines(1, 2), 1);
+:::tip
+
+You can also mix and match helpers by using the spread operator!
+
+You could select the 3rd line and a 10 character long word on the 5th line
+starting at the 6th character using the following expression:
+
+```tsx
+yield * codeRef().selection([...lines(2), ...word(4, 5, 10)], 1);
```
-To remove a selection, the value of `.selection()` signal can be set to its
-[`DEFAULT`][signal-default], i.e. "all selected". For example:
+:::
+
+If you wish to undo a selection, you can either select all lines from `0` to
+`Infinity`, or simply pass `DEFAULT` as a selection, as shown below:
```ts
import {DEFAULT} from '@motion-canvas/core';
@@ -163,9 +179,42 @@ yield * codeRef().selection(lines(1, 2), 1);
yield * codeRef().selection(DEFAULT, 1);
```
-Alternatively, the selected range can be set from `[0, 0]` to
-`[Infinity, Infinity]` to select all text. This is most easily performed by
-setting the selection to `lines(0, Infinity)`.
+#### Raw Usage
+
+Under the hood the helpers return a nested array which defines multiple
+selections using two tuples, each defining a line and character offset per
+selection.
+
+```tsx
+<CodeBlock
+ selection={[
+ [
+ // First selection
+ [lineFrom, characterFrom],
+ [lineTo, characterTo],
+ ],
+ [
+ // Second selection
+ [lineFrom, characterFrom],
+ [lineTo, characterTo],
+ ],
+ [
+ //... etc
+ ],
+ ]}
+/>
+```
+
+`lines(4,7)` will for example return the following structure:
+
+```ts
+[
+ [
+ [4, 0],
+ [7, Infinity],
+ ],
+];
+```
### Animating code
diff --git a/packages/examples/src/code-block.meta b/packages/examples/src/code-block.meta
index af6756e0..719f97bf 100644
--- a/packages/examples/src/code-block.meta
+++ b/packages/examples/src/code-block.meta
@@ -20,6 +20,14 @@
"fps": 60,
"resolutionScale": 2,
"colorSpace": "srgb",
+ "exporter": {
+ "name": "@motion-canvas/core/image-sequence",
+ "options": {
+ "fileType": "image/png",
+ "quality": 100,
+ "groupByScene": false
+ }
+ },
"fileType": "image/png",
"quality": 1
}