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.mdxindex 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: 1slug: /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+```tsximport {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 todesaturate 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:```tsimport {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 codediff --git a/packages/examples/src/code-block.meta b/packages/examples/src/code-block.metaindex 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}