Visualize Your Ideas With Code
docs: add references section (#139)
Jacob9c49cf562c78
diff --git a/packages/docs/docs/guides/getting-started/configuration.mdx b/packages/docs/docs/guides/getting-started/configuration.mdxindex 3ca300fd..16c79848 100644--- a/packages/docs/docs/guides/getting-started/configuration.mdx+++ b/packages/docs/docs/guides/getting-started/configuration.mdx@@ -1,5 +1,5 @@----sidebar_position: 9+sidebar_position: 10---# Configurationdiff --git a/packages/docs/docs/guides/getting-started/references.mdx b/packages/docs/docs/guides/getting-started/references.mdxnew file mode 100644index 00000000..151ede26--- /dev/null+++ b/packages/docs/docs/guides/getting-started/references.mdx@@ -0,0 +1,267 @@+---+sidebar_position: 5+---++# References++Usually, when creating a node, we want to store a reference to it, so we can+animate it later. One way to do that is by assigning it to a variable first, and+then adding it to the scene:++```tsx+const circle = <Circle />;+view.add(circle);++// we can now animate our circle:+yield * circle.scale(2, 0.3);+```++:::info++If you're used to libraries such as React, the above example may seem strange.+In Motion Canvas, the JSX components immediately create and return an instance+of the given class. It's completely valid to store it as a reference and use it+throughout the animation.++:::++But this approach doesn't scale well. The more nodes we add, the harder it gets+to see the overall structure of our scene. Consider the following example:++```tsx+const rectA = <Rect />;+const rectB = <Rect />;+const circle = <Circle>{rectA}</Circle>;+view.add(+ <Layout>+ {circle}+ {rectB}+ </Layout>,+);+```++And now compare it to a version that doesn't store any references:++```tsx+view.add(+ <Layout>+ <Circle>+ <Rect />+ </Circle>+ <Rect />+ </Layout>,+);+```++If you find the latter example more readable, this guide is for you.++## `ref` property++Each node in Motion Canvas has a property called `ref` that allows you to create+a reference to said node. It excepts a callback that will be invoked right after+the node has benn created, with the first argument being the newly created+instance.++With this in mind, we can rewrite the initial example as:++```tsx+let circle: Circle;+view.add(+ <Circle+ ref={instance => {+ circle = instance;+ }}+ />,+);++yield * circle.scale(2, 0.3);+```++Using the `ref` property in this way is not really practical, and we wouldn't+recommend it. But it's crucial to understand how it works because all the+upcoming methods use this property as a base.++## `createRef()` function++The preferred way of using the `ref` property is in conjunction with the+[`createRef()`](/api/core/utils#createRef) function. Continuing with our+example, we can rewrite it as:++```tsx+import {createRef} from '@motion-canvas/core/lib/utils';++// ...++const circle = createRef<Circle>();+view.add(<Circle ref={circle} />);++yield * circle().scale(2, 0.3);+```++Notice that `circle` is no longer just a variable that points to our circle.+Instead, it's a [signal-like](/guides/getting-started/signals) function that can+be used to access it. Invoking it without any arguments (`circle()`) returns our+instance.++Going back to the example with the more complex scene, we can now rewrite it as:++```tsx+const rectA = createRef<Rect>();+const rectB = createRef<Rect>();+const circle = createRef<Circle>();+view.add(+ <Layout>+ <Circle ref={circle}>+ <Rect ref={rectA} />+ </Circle>+ <Rect ref={rectB} />+ </Layout>,+);+```++## `makeRef()` function++Another common use case of the `ref` property is to assign the newly created+instance to a property of some object. In the following example, we assign our+circle to `circle.instance` (We'll talk about why this may be useful in a bit):++```tsx+const circle = {instance: null as Circle};+view.add(+ <Circle+ // highlight-start+ ref={instance => {+ circle.instance = instance;+ }}+ // highlight-end+ />,+);+```++We can use the [`makeRef()`](/api/core/utils#makeRef) function to simplify this+process:++```tsx+import {makeRef} from '@motion-canvas/core/lib/utils';++// ...++const circle = {instance: null as Circle};+view.add(+ // highlight-next-line+ <Circle ref={makeRef(circle, 'instance')} />,+);+```++### Array of references++`makeRef()` can be particularly useful when we create an array of nodes and want+to grab references to all of them:++```tsx+const circles: Circle[] = [];+view.add(+ <Layout>+ {range(10).map(index => (+ // highlight-next-line+ <Circle ref={makeRef(circles, index)} />+ ))}+ </Layout>,+);+```++In JavaScript, arrays are objects whose properties are their indices. So+`makeRef(circles, index)` will set the nth element of our array to the created+circle. As a result, we end up with an array of size `10` filled with circles+that we can use to animate all of them.++### Custom functions++`makeRef()` can also be used to return more than one reference from a custom+function component:++```tsx+function Label({+ refs,+ children,+}: {+ refs: {rect: Rect; text: Text};+ children: string;+}) {+ return (+ // highlight-next-line+ <Rect ref={makeRef(refs, 'rect')}>+ // highlight-next-line+ <Text ref={makeRef(refs, 'text')}>{children}</Text>+ </Rect>+ );+}++const label = {rect: null as Rect, text: null as Text};+view.add(<Label refs={label}>HELLO</Label>);++// we can now animate both the Rect and the Text of our label:+yield * label.rect.opacity(2, 0.3);+yield * label.text.fontSize(24, 0.3);+```++In this example, we define a function component called `Label` consisting of a+rectangle with some text inside. When using the component, we use the `refs`+property to pass the `label` object created by us. `makeRef()` is then used to+fill this object with all the necessary references.++## `makeRefs()` function++Looking at the previous example, you may notice that we had to define the `refs`+type twice. First in the `Label` declaration and then again when creating the+`label` object:++```tsx+function Label({+ refs,+ children,+}: {+ // highlight-next-line+ refs: {rect: Rect; text: Text};+ children: string;+}) {+ return (+ <Rect ref={makeRef(refs, 'rect')}>+ <Text ref={makeRef(refs, 'text')}>{children}</Text>+ </Rect>+ );+}++// highlight-next-line+const label = {rect: null as Rect, text: null as Text};+view.add(<Label refs={label}>HELLO</Label>);+```++We can use [`makeRefs()`](/api/core/utils#makeRefs) to eliminate this+redundancy. It can extract the type from the `Label` declaration and create an+empty object matching it:++```tsx+import {makeRef, makeRefs} from '@motion-canvas/core/lib/utils';++// ...++function Label({+ refs,+ children,+}: {+ // highlight-next-line+ refs: {rect: Rect; text: Text};+ children: string;+}) {+ return (+ <Rect ref={makeRef(refs, 'rect')}>+ <Text ref={makeRef(refs, 'text')}>{children}</Text>+ </Rect>+ );+}++// highlight-next-line+const label = makeRefs<typeof Label>();+view.add(<Label refs={label}>HELLO</Label>);+```diff --git a/packages/docs/docs/guides/getting-started/rendering.md b/packages/docs/docs/guides/getting-started/rendering.mdindex a153db9a..d3b0cb04 100644--- a/packages/docs/docs/guides/getting-started/rendering.md+++ b/packages/docs/docs/guides/getting-started/rendering.md@@ -1,5 +1,5 @@----sidebar_position: 8+sidebar_position: 9---# Renderingdiff --git a/packages/docs/docs/guides/getting-started/time-events.mdx b/packages/docs/docs/guides/getting-started/time-events.mdxindex 19b5aacd..fb38bccc 100644--- a/packages/docs/docs/guides/getting-started/time-events.mdx+++ b/packages/docs/docs/guides/getting-started/time-events.mdx@@ -1,5 +1,5 @@----sidebar_position: 5+sidebar_position: 6---# Time Eventsdiff --git a/packages/docs/docs/guides/getting-started/transitions.mdx b/packages/docs/docs/guides/getting-started/transitions.mdxindex d759d213..6ea92509 100644--- a/packages/docs/docs/guides/getting-started/transitions.mdx+++ b/packages/docs/docs/guides/getting-started/transitions.mdx@@ -1,5 +1,5 @@----sidebar_position: 6+sidebar_position: 7---# Transitionsdiff --git a/packages/docs/docs/guides/getting-started/utils/_category_.yml b/packages/docs/docs/guides/getting-started/utils/_category_.ymlindex 69b3fc36..71e7c039 100644--- a/packages/docs/docs/guides/getting-started/utils/_category_.yml+++ b/packages/docs/docs/guides/getting-started/utils/_category_.yml@@ -1,3 +1,3 @@label: Utilities-position: 7+position: 8collapsed: false\ No newline at end of file