Visualize Your Ideas With Code
docs: added intro, installation, and quickstart guide to docs (#46)
Ross Esmonddb50531f12db
diff --git a/README.md b/README.mdindex eb1eb869..c2a6b7ed 100644--- a/README.md+++ b/README.md@@ -40,7 +40,7 @@ node -v`Username` is your GitHub username,`Password` is the token you just generated.`Email` is your GitHub email address.- For instace:+ For instance:```text> Username: Jacob> Password: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxdiff --git a/package-lock.json b/package-lock.jsonindex 59fc65ac..b9b3b1c9 100644--- a/package-lock.json+++ b/package-lock.json@@ -14681,6 +14681,11 @@"node": ">=8"}},+ "node_modules/load-script": {+ "version": "1.0.0",+ "resolved": "https://registry.npmjs.org/load-script/-/load-script-1.0.0.tgz",+ "integrity": "sha512-kPEjMFtZvwL9TaZo0uZ2ml+Ye9HUMmPwbYRJ324qF9tqMejwykJ5ggTyvzmrbBeapCAbk98BSbTeovHEEP1uCA=="+ },"node_modules/loader-runner": {"version": "4.3.0","resolved": "https://registry.npmjs.org/loader-runner/-/loader-runner-4.3.0.tgz",@@ -15043,6 +15048,11 @@"node": ">= 4.0.0"}},+ "node_modules/memoize-one": {+ "version": "5.2.1",+ "resolved": "https://registry.npmjs.org/memoize-one/-/memoize-one-5.2.1.tgz",+ "integrity": "sha512-zYiwtZUcYyXKo/np96AGZAckk+FWWsUdJ3cHGGmld7+AhvcWmQyGCYUh1hc4Q/pkOhb65dQR/pqCyK0cOaHz4Q=="+ },"node_modules/meow": {"version": "8.1.2","resolved": "https://registry.npmjs.org/meow/-/meow-8.1.2.tgz",@@ -18160,6 +18170,21 @@"webpack": ">=4.41.1 || 5.x"}},+ "node_modules/react-player": {+ "version": "2.10.1",+ "resolved": "https://registry.npmjs.org/react-player/-/react-player-2.10.1.tgz",+ "integrity": "sha512-ova0jY1Y1lqLYxOehkzbNEju4rFXYVkr5rdGD71nsiG4UKPzRXQPTd3xjoDssheoMNjZ51mjT5ysTrdQ2tEvsg==",+ "dependencies": {+ "deepmerge": "^4.0.0",+ "load-script": "^1.0.0",+ "memoize-one": "^5.1.1",+ "prop-types": "^15.7.2",+ "react-fast-compare": "^3.0.1"+ },+ "peerDependencies": {+ "react": ">=16.6.0"+ }+ },"node_modules/react-router": {"version": "5.3.3","resolved": "https://registry.npmjs.org/react-router/-/react-router-5.3.3.tgz",@@ -22394,7 +22419,7 @@},"packages/core": {"name": "@motion-canvas/core",- "version": "10.0.0",+ "version": "10.1.0","license": "MIT","dependencies": {"@types/prismjs": "^1.26.0",@@ -22423,7 +22448,7 @@},"packages/create": {"name": "@motion-canvas/create",- "version": "10.0.1",+ "version": "10.1.0","license": "MIT","dependencies": {"prompts": "^2.4.2"@@ -22432,9 +22457,9 @@"create-motion-canvas": "index.js"},"devDependencies": {- "@motion-canvas/core": "^10.0.0",- "@motion-canvas/ui": "^10.0.0",- "@motion-canvas/vite-plugin": "^10.0.0"+ "@motion-canvas/core": "^10.1.0",+ "@motion-canvas/ui": "^10.1.0",+ "@motion-canvas/vite-plugin": "^10.1.0"}},"packages/docs": {@@ -22447,7 +22472,8 @@"clsx": "^1.2.0","prism-react-renderer": "^1.3.5","react": "^17.0.2",- "react-dom": "^17.0.2"+ "react-dom": "^17.0.2",+ "react-player": "^2.10.1"},"devDependencies": {"@docusaurus/module-type-aliases": "^2.0.0",@@ -22476,10 +22502,10 @@},"packages/ui": {"name": "@motion-canvas/ui",- "version": "10.0.0",+ "version": "10.1.0","license": "MIT","devDependencies": {- "@motion-canvas/core": "^10.0.0",+ "@motion-canvas/core": "^10.1.0","@preact/preset-vite": "^2.3.0","preact": "10.7.3","typescript": "^4.6.4",@@ -22501,7 +22527,7 @@},"packages/vite-plugin": {"name": "@motion-canvas/vite-plugin",- "version": "10.0.0",+ "version": "10.1.0","license": "MIT","dependencies": {"mime-types": "^2.1.35"@@ -26265,9 +26291,9 @@"@motion-canvas/create": {"version": "file:packages/create","requires": {- "@motion-canvas/core": "^10.0.0",- "@motion-canvas/ui": "^10.0.0",- "@motion-canvas/vite-plugin": "^10.0.0",+ "@motion-canvas/core": "^10.1.0",+ "@motion-canvas/ui": "^10.1.0",+ "@motion-canvas/vite-plugin": "^10.1.0","prompts": "^2.4.2"}},@@ -26284,6 +26310,7 @@"prism-react-renderer": "^1.3.5","react": "^17.0.2","react-dom": "^17.0.2",+ "react-player": "^2.10.1","typedoc": "^0.23.7","typedoc-plugin-markdown": "^3.13.3","typescript": "^4.7.4"@@ -26301,7 +26328,7 @@"@motion-canvas/ui": {"version": "file:packages/ui","requires": {- "@motion-canvas/core": "^10.0.0",+ "@motion-canvas/core": "^10.1.0","@preact/preset-vite": "^2.3.0","preact": "10.7.3","typescript": "^4.6.4",@@ -26319,7 +26346,7 @@"@motion-canvas/vite-plugin": {"version": "file:packages/vite-plugin","requires": {- "@types/mime-types": "*",+ "@types/mime-types": "^2.1.1","mime-types": "^2.1.35","typescript": "^4.7.4","vite": "^3.0.5"@@ -33533,6 +33560,11 @@}}},+ "load-script": {+ "version": "1.0.0",+ "resolved": "https://registry.npmjs.org/load-script/-/load-script-1.0.0.tgz",+ "integrity": "sha512-kPEjMFtZvwL9TaZo0uZ2ml+Ye9HUMmPwbYRJ324qF9tqMejwykJ5ggTyvzmrbBeapCAbk98BSbTeovHEEP1uCA=="+ },"loader-runner": {"version": "4.3.0","resolved": "https://registry.npmjs.org/loader-runner/-/loader-runner-4.3.0.tgz",@@ -33807,6 +33839,11 @@"fs-monkey": "^1.0.3"}},+ "memoize-one": {+ "version": "5.2.1",+ "resolved": "https://registry.npmjs.org/memoize-one/-/memoize-one-5.2.1.tgz",+ "integrity": "sha512-zYiwtZUcYyXKo/np96AGZAckk+FWWsUdJ3cHGGmld7+AhvcWmQyGCYUh1hc4Q/pkOhb65dQR/pqCyK0cOaHz4Q=="+ },"meow": {"version": "8.1.2","resolved": "https://registry.npmjs.org/meow/-/meow-8.1.2.tgz",@@ -36052,6 +36089,18 @@"@babel/runtime": "^7.10.3"}},+ "react-player": {+ "version": "2.10.1",+ "resolved": "https://registry.npmjs.org/react-player/-/react-player-2.10.1.tgz",+ "integrity": "sha512-ova0jY1Y1lqLYxOehkzbNEju4rFXYVkr5rdGD71nsiG4UKPzRXQPTd3xjoDssheoMNjZ51mjT5ysTrdQ2tEvsg==",+ "requires": {+ "deepmerge": "^4.0.0",+ "load-script": "^1.0.0",+ "memoize-one": "^5.1.1",+ "prop-types": "^15.7.2",+ "react-fast-compare": "^3.0.1"+ }+ },"react-router": {"version": "5.3.3","resolved": "https://registry.npmjs.org/react-router/-/react-router-5.3.3.tgz",diff --git a/packages/docs/docs/guides/getting-started/installation.md b/packages/docs/docs/guides/getting-started/installation.mddeleted file mode 100644index 8e8f69e8..00000000--- a/packages/docs/docs/guides/getting-started/installation.md+++ /dev/null@@ -1,7 +0,0 @@-----sidebar_position: 1------# Installation--TODOdiff --git a/packages/docs/docs/guides/getting-started/quickstart.mdx b/packages/docs/docs/guides/getting-started/quickstart.mdxnew file mode 100644index 00000000..ea5fc1da--- /dev/null+++ b/packages/docs/docs/guides/getting-started/quickstart.mdx@@ -0,0 +1,240 @@+---+sidebar_position: 2+---++import ReactPlayer from 'react-player'++# Creating an Animation++In this guide, we will start a new Motion Canvas project and create an animation+in it.++### Prerequisites++Make sure that [Node.js](https://nodejs.org/) version 16 or greater is+installed on your machine.++If you're using Motion Canvas as part of the Patreon early access, make sure to+[authenticate to GitHub Packages][autheticate] first.++### Creating a new project++Run the following command in order to scaffold a new Motion Canvas project:++```bash+npm init @motion-canvas+```++Answer the prompts to name your project and select which language you would like+to use, either TypeScript or plain JavaScript.++:::caution++We recommend using TypeScript in your first project, as our Guides use+TypeScript.++:::++### Starting the Motion Canvas App++From your new Motion Canvas project directory, run++```shell+npm run serve+```++This will start the Motion Canvas editor, which you may open by visiting+[http://localhost:9000/](http://localhost:9000/). We will use the editor to+preview our animation, but for now there is nothing to see. To do that, we+must add an element to our scene.++### Programming an animation++The scaffolding command will create several files for you, but for now we're+going to focus on `src/scenes/example.scene.tsx`, which is where we can add our+animations. Open `example.scene.tsx` in a text editor, and replace all code in+the file with the following snippet.++```tsx+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';+import {Circle} from 'konva/lib/shapes/Circle';+import {useRef} from '@motion-canvas/core/lib/utils';++export default makeKonvaScene(function* example(view) {+ const myCircle = useRef();++ view.add(+ <Circle+ position={{x: -300, y: 0}}+ ref={myCircle}+ width={240}+ height={240}+ fill="#ccc"+ />+ );++ yield* myCircle.value.position({x: 300, y: 0}, 1);+});+```++Now save the file. Any changes you make are automatically picked up and+reflected in the preview. You should see a gray circle in the preview pane at+the top right of the web application. Press the play button to see the circle+animate across the screen.++<ReactPlayer loop controls url='/video/animation.mp4' />++Depending on the size of your browser, you may want to zoom the preview out by+scrolling down on your mouse wheel while hovering over the preview panel.++### Explanation++Motion Canvas is designed to work with different HTML canvas libraries, though+it currently only ships with [Konva](https://konvajs.org/) integration. To+create a new konva scene, we need to call `makeKonvaScene` with a generator+function.++```tsx+// highlight-next-line+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';++// highlight-next-line+export default makeKonvaScene(function* example(view) {+ // animation code+});+```++The generator function is passed a `view` argument, which we will use to add+components to the scene.++:::tip+If you aren't familiar with generator functions from JavaScript, declared with+`function*`, you can read the MDN documentation on them [here][generators],+though a thorough understanding of them is not necessary to start using Motion+Canvas.+:::++In order to create an animation, we needed something to animate. For that, we+used the Konva Circle component.++```tsx+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';+// highlight-next-line+import {Circle} from 'konva/lib/shapes/Circle';++export default makeKonvaScene(function* example(view) {+ // highlight-start+ view.add(+ <Circle+ width={240}+ height={240}+ fill="#ccc"+ />+ );+ // highlight-end+});+```++Here we create a new circle instance with `<Circle />` and add it to the scene+using `view.add()`. This code alone will show a gray circle in the middle of the+screen, though it won't move.++To animate the circle, we needed to store a reference to it. This is the purpose+of the `useRef` call.++```tsx+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';+import {Circle} from 'konva/lib/shapes/Circle';+// highlight-next-line+import {useRef} from '@motion-canvas/core/lib/utils';++export default makeKonvaScene(function* example(view) {+ // highlight-next-line+ const myCircle = useRef();++ view.add(+ <Circle+ // highlight-next-line+ ref={myCircle}+ width={240}+ height={240}+ fill="#ccc"+ />+ );++ // myCircle.value available here+});+```++Once the `Circle` is created with `ref={myCircle}`, it may be accessed from+`myCircle.value`, which we can use to edit the circle's properties. In Konva,+properties are read using `property()`, and written using `property(value)`. To+update the circle's position, for instance, we use++```tsx+myCircle.value.position({x: 300, y: 0});+```++When we edit the properties of a component, however, the changes are immediate.+In order to _transition_ to a new value over time, we must change our call in+two ways. We must specify the duration of the transition in seconds to create an+animation, `position(value, duration)`, and we must `yield*` to the animation.++```tsx+yield* myCircle.value.position({x: 300, y: 0}, 1);+```++The `yield*` is important. Calling `position({...}, 1)` alone will not run the+animation; it simply returns a value called a task, which represents the+animation.++```tsx+const task = myCircle.value.position({x: 300, y: 0}, 1);+```++Yielding a task prompts Motion Canvas to run it. Using `yield*` waits for the+animation to complete before continuing the scene function, while using `yield`+plays the animation but continues the scene function immediately.++```tsx+yield* myCircle.value.position({x: 300, y: 0}, 1);+// this line will run after the animation has ended+```+```tsx+yield myCircle.value.position({x: 300, y: 0}, 1);+// this line will run immediately while the animation plays+```++In our example, we used `yield*` so that the scene wouldn't end until the+animation was completed.++```tsx+import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';+import {Circle} from 'konva/lib/shapes/Circle';+import {useRef} from '@motion-canvas/core/lib/utils';++// make a new konva scene and pass it the scene function+export default makeKonvaScene(function* example(view) {+ // create a reference to store the circle+ const myCircle = useRef();++ // create a circle and add it to the scene's view+ view.add(+ <Circle+ position={{x: -300, y: 0}} // set an initial position+ ref={myCircle} // assign the circle instance to the myCircle ref+ width={240}+ height={240}+ fill="#ccc"+ />+ );++ // animate to a new position over 1 second and+ // wait for it to finish before continuing+ yield* myCircle.value.position({x: 300, y: 0}, 1);+});+```++[installation]: /guides/getting-started/installation+[generators]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*+[autheticate]: https://github.com/motion-canvas/motion-canvas#authenticate-to-github-packagesdiff --git a/packages/docs/docs/guides/intro.md b/packages/docs/docs/guides/intro.mdindex 8e953810..cd201e71 100644--- a/packages/docs/docs/guides/intro.md+++ b/packages/docs/docs/guides/intro.md@@ -4,4 +4,33 @@ sidebar_position: 1# Introduction-TODO+Motion Canvas is a TypeScript library and web application for creating+animations programmatically. It was invented to accelerate the process of+combining informative voice overs with supporting animation, but can satisfy a+variety of use cases. Animations are programmed in either TypeScript or+JavaScript using the Motion Canvas core library. The Motion Canvas web app then+displays a preview of the animations with an audio file of your choice.++Though most details of the animation are driven by code, your program may+selectively defer the timing of some events to be edited in the web app using a+function called `waitUntil`. From the web app, you may then drag and drop this+timing event to fine tune your animations. This is most useful for synchronizing+the timing of animations with your voice over. This way, you may program the+precise details of your animation in code, but adjust them manually to match the+imprecise timing of a recorded voice over.++Motion Canvas is not intended to be a full-sale replacement for a video editor+like Adobe Premiere Pro or DaVinci Resolve, but it may improve your workflow+when combined with these other tools.++Motion Canvas is Open Source, and relies on your feedback to inform its+development. If you would like to report a bug or request a feature, you may+visit [the GitHub repository][repo] to do so. We cannot satisfy every request,+but we do read every request, and are dedicated to making Motion Canvas work for+as wide a user base as possible.++If you would like to contribute pull requests, please read [the contribution+guide][contributing] to learn about our process.++[contributing]: https://github.com/motion-canvas/motion-canvas/blob/main/CONTRIBUTING.md+[repo]: https://github.com/motion-canvas/motion-canvasdiff --git a/packages/docs/package.json b/packages/docs/package.jsonindex fff7e376..1d75ee87 100644--- a/packages/docs/package.json+++ b/packages/docs/package.json@@ -21,7 +21,8 @@"clsx": "^1.2.0","prism-react-renderer": "^1.3.5","react": "^17.0.2",- "react-dom": "^17.0.2"+ "react-dom": "^17.0.2",+ "react-player": "^2.10.1"},"devDependencies": {"@docusaurus/module-type-aliases": "^2.0.0",diff --git a/packages/docs/static/video/animation.mp4 b/packages/docs/static/video/animation.mp4new file mode 100644index 00000000..24ca1816Binary files /dev/null and b/packages/docs/static/video/animation.mp4 differ