variablelab/theatre
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

README: add theatre logo. Add/fix social links (#113)

Browse source 
* add theatre logo. Add/fix social links

* remove styles that don't work in github md

* Add more detailed getting started links to README

* change github links to use theatre-js org and autoformat
This commit is contained in:
Elliot 2022-04-05 13:29:40 -04:00 committed by GitHub
parent f1a1f48c0f
commit 0cc4f795a1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 203 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

131
CONTRIBUTING.md
View file

@ -5,6 +5,7 @@
### Setting up the environment ### Setting up the environment
Make sure you have [`node 14+`](https://nodejs.org/) installed: Make sure you have [`node 14+`](https://nodejs.org/) installed:
```sh ```sh
$ node -v $ node -v
> v14.0.0 > v14.0.0
@ -20,7 +21,11 @@ $ yarn -v
Then clone the repo: Then clone the repo:
```sh ```sh
$ git clone git@github.com:AriaMinaei/theatre.git # for SSH:
$ git clone git@github.com:<github-username>/theatre.git
# for HTTPS:
$ git clone https://github.com/<github-username>/theatre.git
$ cd theatre $ cd theatre
``` ```
@ -30,9 +35,13 @@ And fetch the dependencies with yarn:
$ yarn $ yarn
``` ```
* Notes about Yarn: - Notes about Yarn:
* This project uses [yarn workspaces](https://yarnpkg.com/features/workspaces) so `npm install` will not work. - This project uses [yarn workspaces](https://yarnpkg.com/features/workspaces)
* This repo uses Yarn v2. You don't have to install yarn v2 globally. If you do have yarn 1.22.10+ on your machine, yarn will automatically switch to v2 when you `cd` into theatre. Read more about Yarn v2 [here](https://yarnpkg.com/). so `npm install` will not work.
- This repo uses Yarn v2. You don't have to install yarn v2 globally. If you
do have yarn 1.22.10+ on your machine, yarn will automatically switch to v2
when you `cd` into theatre. Read more about Yarn v2
[here](https://yarnpkg.com/).
### Hacking with `playground` ### Hacking with `playground`
@ -46,13 +55,19 @@ $ cd root
$ yarn playground $ yarn playground
``` ```
The playground is a bunch of ready-made projects that you can run to experiment with Theatre.js. It also contains the project's end-to-end tests. The playground is a bunch of ready-made projects that you can run to experiment
with Theatre.js. It also contains the project's end-to-end tests.
Read more at [`./packages/playground/README.md`](./packages/playground/README.md). Read more at
[`./packages/playground/README.md`](./packages/playground/README.md).
### Hacking with `examples/` ### Hacking with `examples/`
Other than `playground`, the [`examples/`](./examples) folder contains a few small projects that use Theatre with [parcel](https://parceljs.org), [Create react app](create-react-app.dev), and other build tools. This means that unlike `playground`, you have to build all the packages before running the examples. Other than `playground`, the [`examples/`](./examples) folder contains a few
small projects that use Theatre with [parcel](https://parceljs.org),
[Create react app](create-react-app.dev), and other build tools. This means that
unlike `playground`, you have to build all the packages before running the
examples.
You can do that by running the `build` command at the root of the repo: You can do that by running the `build` command at the root of the repo:
@ -61,6 +76,7 @@ $ yarn build
``` ```
Then build any of the examples: Then build any of the examples:
``` ```
$ cd examples/dom-cra $ cd examples/dom-cra
$ yarn start $ yarn start
@ -68,7 +84,8 @@ $ yarn start
### Running unit/integration tests ### Running unit/integration tests
We use a single [jest](https://jestjs.io/) setup for the repo. The tests files have the `.test.ts` or `.test.tsx` extension. We use a single [jest](https://jestjs.io/) setup for the repo. The tests files
have the `.test.ts` or `.test.tsx` extension.
You can run the tests at the root of the repo: You can run the tests at the root of the repo:
@ -81,11 +98,13 @@ $ yarn test --watch
### Running end-to-end tests ### Running end-to-end tests
End-to-end tests are hosted in the playground package. More details [there](./packages/playground/README.md). End-to-end tests are hosted in the playground package. More details
[there](./packages/playground/README.md).
### Type checking ### Type checking
The packages in this repo have full typescript coverage, so you should be able to get diagnostics and intellisense if your editor supports typescript. The packages in this repo have full typescript coverage, so you should be able
to get diagnostics and intellisense if your editor supports typescript.
You can also run a typecheck of the whole repo from the root: You can also run a typecheck of the whole repo from the root:
@ -96,18 +115,26 @@ $ yarn typecheck
$ yarn typecheck --watch $ yarn typecheck --watch
``` ```
* If you're using VSCode, we have a ["Typescript watch"](./.vscode/tasks.json) task for VSCode that you can use by [running](https://code.visualstudio.com/Docs/editor/tasks) "Run Task -> Typescript watch". - If you're using VSCode, we have a ["Typescript watch"](./.vscode/tasks.json)
* If you wish to contribute code without typescript annotations, that's totally fine. We're happy to add the annotations to your PR. task for VSCode that you can use by
[running](https://code.visualstudio.com/Docs/editor/tasks) "Run Task ->
Typescript watch".
- If you wish to contribute code without typescript annotations, that's totally
fine. We're happy to add the annotations to your PR.
### Linting ### Linting
We're using a minimal [ESLint](https://code.visualstudio.com/Docs/editor/tasks) setup for linting. If your editor supports ESLint, you should get diagnostics as you code. You can also run the lint command from the root of the repo: We're using a minimal [ESLint](https://code.visualstudio.com/Docs/editor/tasks)
setup for linting. If your editor supports ESLint, you should get diagnostics as
you code. You can also run the lint command from the root of the repo:
```sh ```sh
$ yarn lint:all $ yarn lint:all
``` ```
Some lint rules have [autofix](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems), so you can run: Some lint rules have
[autofix](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems),
so you can run:
```sh ```sh
$ yarn lint:all --fix $ yarn lint:all --fix
@ -115,7 +142,9 @@ $ yarn lint:all --fix
### Publishing to npm ### Publishing to npm
Currently all packages (except for [`@theatre/r3f`](./packages/r3f/)) share the same version number. In order to publish to npm, you can run the `release` script from the root of the repo: Currently all packages (except for [`@theatre/r3f`](./packages/r3f/)) share the
same version number. In order to publish to npm, you can run the `release`
script from the root of the repo:
```sh ```sh
$ yarn release x.y.z # npm publish version x.y.z $ yarn release x.y.z # npm publish version x.y.z
@ -125,7 +154,10 @@ $ yarn release x.y.z-rc.w # npm publish version x.y.z-rc.w and tag it as "rc"
### Generating API docs ### Generating API docs
We use [API extractor](https://api-extractor.com/pages/setup/generating_docs/) to generate API docs in markdown. We put the markdown files in the [theatre-docs](https://github.com/ariaminaei/theatre-docs/) repo, which also contains the tutorials and guides. We use [API extractor](https://api-extractor.com/pages/setup/generating_docs/)
to generate API docs in markdown. We put the markdown files in the
[theatre-docs](https://github.com/theatre-js/theatre-docs) repo, which also
contains the tutorials and guides.
To generate the API docs, run the `build:api-docs` from the root of the repo: To generate the API docs, run the `build:api-docs` from the root of the repo:
@ -139,15 +171,23 @@ Learn more about api documentation [here](./contributing/api-docs.md).
The [monorepo](https://en.wikipedia.org/wiki/Monorepo) consists of: The [monorepo](https://en.wikipedia.org/wiki/Monorepo) consists of:
* `@theatre/core` – The core animation library at [`./theatre/core`](./theatre/core). - `@theatre/core` – The core animation library at
* `@theatre/studio` – The visual editor at [`./theatre/studio`](./theatre/studio). [`./theatre/core`](./theatre/core).
* `@theatre/dataverse` – The reactive dataflow library at [`./packages/dataverse`](./packages/dataverse). - `@theatre/studio` – The visual editor at
* `@theatre/react` – Utilities for using Theatre with React at [`./packages/react`](./packages/react). [`./theatre/studio`](./theatre/studio).
* `@theatre/r3f` – The react-three-fiber extension at [`./packages/r3f`](./packages/r3f). - `@theatre/dataverse` – The reactive dataflow library at
* `playground` – The playground explained [above](#hacking-with-playground), located at [`./packages/playground`](./packages/playground) [`./packages/dataverse`](./packages/dataverse).
* `examples/` * A bunch of [examples](#hacking-with-examples) at [./examples](./examples). - `@theatre/react` – Utilities for using Theatre with React at
[`./packages/react`](./packages/react).
- `@theatre/r3f` – The react-three-fiber extension at
[`./packages/r3f`](./packages/r3f).
- `playground` – The playground explained [above](#hacking-with-playground),
located at [`./packages/playground`](./packages/playground)
- `examples/` \* A bunch of [examples](#hacking-with-examples) at
[./examples](./examples).
In addition, each package may contain a `dotEnv/` folder that holds some dev-related files, like bundle configuration, lint setup, etc. In addition, each package may contain a `dotEnv/` folder that holds some
dev-related files, like bundle configuration, lint setup, etc.
## Commands ## Commands
@ -182,11 +222,13 @@ $ yarn build
$ yarn build:api-docs /path/to/theatre-docs/docs/api/ $ yarn build:api-docs /path/to/theatre-docs/docs/api/
``` ```
> Yarn passes all extra parameters to the internal scripts. So, for example, if you wish to run the tests in watch mode, you can run `yarn test --watch`. > Yarn passes all extra parameters to the internal scripts. So, for example, if
> you wish to run the tests in watch mode, you can run `yarn test --watch`.
## Documentation ## Documentation
The libraries come bundled with typescript definitions with TSDoc comments. You can explore the API if your editor is configured to display TSDoc comments. The libraries come bundled with typescript definitions with TSDoc comments. You
can explore the API if your editor is configured to display TSDoc comments.
Other references Other references
@ -198,25 +240,36 @@ Other references
You can contribute with: You can contribute with:
* Bug fixes - Bug fixes
* Feature suggestions - Feature suggestions
* Features implementations - Features implementations
* [Documentation](https://github.com/ariaminaei/theatre-docs/) (or write/record tutorials of your own which we'll showcase) - [Documentation](https://github.com/theatre-js/theatre-docs/) (or write/record
* Create examples projects for your own particular dev stack (eg. using Pixie/Vue/THREE.js/Babylon/etc) tutorials of your own which we'll showcase)
- Create examples projects for your own particular dev stack (eg. using
Pixie/Vue/THREE.js/Babylon/etc)
Another great way to help is to join our [community](https://discord.gg/bm9f8F9Y9N) and chime in on questions and share ideas. Another great way to help is to join our
[community](https://discord.gg/bm9f8F9Y9N) and chime in on questions and share
ideas.
### Helping with outstanding issues ### Helping with outstanding issues
Feel free to chime in on any [issue](https://github.com/AriaMinaei/theatre/issues). We have labeled some with ["Help wanted"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ["Good first issue"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22) if you're just getting started with the codebase. Feel free to chime in on any
[issue](https://github.com/theatre-js/theatre/issues). We have labeled some with
["Help wanted"](https://github.com/theatre-js/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22)
or
["Good first issue"](https://github.com/theatre-js/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22)
if you're just getting started with the codebase.
## Sending pull requests ## Sending pull requests
We use Github's regular PR workflow. Basically fork the repo, push your commits, and send a pull request. We use Github's regular PR workflow. Basically fork the repo, push your commits,
and send a pull request.
If you're a core contributor and have write access to the repo, you should submit your pull requests from a branch If you're a core contributor and have write access to the repo, you should
rather than a personal fork. The naming convention for these branches should be: submit your pull requests from a branch rather than a personal fork. The naming
convention for these branches should be:
* `(feature|hotfix|docs)/[identifier]` - `(feature|hotfix|docs)/[identifier]` or
or - an autogenerated branch name from a Github issue (On an issue without a PR,
* an autogenerated branch name from a Github issue (On an issue without a PR, look under the "Development" sidebar heading for a "create a branch link") look under the "Development" sidebar heading for a "create a branch link")

96
README.md
View file

@ -1,35 +1,54 @@
# Theatre.js <h1 align="center">
<img src="https://docs.theatrejs.com/public/theatrejs-logo-black.svg" alt="Theatre.js" width="200">
</h1>
<p align="center">Motion Design, for the web</p>
<p align="center">
<a href="https://discord.gg/Tku4CJKf4B">
<img src="https://img.shields.io/discord/870988717190426644?label=Discord" alt="Join us on Discord">
</a> ⎯◈⎯
<a href="https://twitter.com/theatre_js">
<img src="https://img.shields.io/twitter/follow/theatre_js?style=social" alt="Follow us on Twitter">
</a> ⎯◈⎯
<a href="https://www.youtube.com/channel/UCsp9XOCs8v2twyq5kMLzS2Q">
<img src="https://img.shields.io/youtube/channel/views/UCsp9XOCs8v2twyq5kMLzS2Q?label=TheatreJS&style=social" alt="Watch on YouTube">
</a> ⎯◈⎯
<a href="https://theatrejs.com">
<img src="https://docs.theatrejs.com/public/theatrejs-logo-black.svg" alt="TheatreJS" width="70">.com
</a>
</p>
> ✨ Update: [We're hiring – join the core team!](https://join.theatrejs.com/) > ✨ Update: [We're hiring – join the core team!](https://join.theatrejs.com/)
Theatre.js is an animation library for high-fidelity motion graphics. It is
![Join us on Discord](https://img.shields.io/discord/870988717190426644?label=Discord) designed to help you express detailed animation, enabling you to create
intricate movement, and convey nuance.
Theatre.js is an animation library for high-fidelity motion graphics. It is designed to help you express detailed animation, enabling you to create intricate movement, and convey nuance.
Theatre can be used both programmatically _and_ visually. Theatre can be used both programmatically _and_ visually.
---
You can use Theatre.js to: You can use Theatre.js to:
* Animate 3D objects made with THREE.js or other 3D libraries - Animate 3D objects made with THREE.js or other 3D libraries
![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-3d-short.gif) ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-3d-short.gif)
<sub>Art by [drei.lu](https://sketchfab.com/models/91964c1ce1a34c3985b6257441efa500)</sub> <sub>Art by
[drei.lu](https://sketchfab.com/models/91964c1ce1a34c3985b6257441efa500)</sub>
* Animate HTML/SVG via React or other libraries - Animate HTML/SVG via React or other libraries
![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-dom.gif) ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-dom.gif)
* Design micro-interactions - Design micro-interactions
![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-micro-interaction.gif) ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-micro-interaction.gif)
* Choreograph generative interactive art - Choreograph generative interactive art
![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-generative.gif) ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-generative.gif)
* Or animate any other JS variable - Or animate any other JS variable
![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-console.gif) ![s](https://raw.githubusercontent.com/AriaMinaei/theatre-docs/main/docs/.vuepress/public/preview-console.gif)
@ -37,43 +56,64 @@ You can use Theatre.js to:
The docs are at [docs.theatrejs.com](https://docs.theatrejs.com): The docs are at [docs.theatrejs.com](https://docs.theatrejs.com):
* [Getting started](https://docs.theatrejs.com/getting-started/) - [Getting started guide](https://docs.theatrejs.com/getting-started/)
* [In depth guide](https://docs.theatrejs.com/in-depth/) - [Install Theatre.js](https://docs.theatrejs.com/getting-started/install/)
* [API docs](https://docs.theatrejs.com/api/) - [Quickly try Theatre.js out](https://docs.theatrejs.com/getting-started/try-it-out/)
* [Extensions](https://docs.theatrejs.com/extensions/) - [Learn the basics](https://docs.theatrejs.com/getting-started/basics/)
* [Video tutorials](https://www.youtube.com/channel/UCsp9XOCs8v2twyq5kMLzS2Q) - [In depth guide](https://docs.theatrejs.com/in-depth/)
* [Crash course](https://www.youtube.com/watch?v=icR9EIS1q34) - [API docs](https://docs.theatrejs.com/api/)
* [Animating with music](https://www.youtube.com/watch?v=QoS4gMxwq_4) - [Extensions](https://docs.theatrejs.com/extensions/)
* [Yuri Artiukh](https://twitter.com/akella)'s [stream](https://youtu.be/qmRqgFbNprM?t=3462) with a section on using Theatre with THREE.js - [Video tutorials](https://www.youtube.com/channel/UCsp9XOCs8v2twyq5kMLzS2Q)
* \<Add your own tutorials here\> - [Crash course](https://www.youtube.com/watch?v=icR9EIS1q34)
- [Animating with music](https://www.youtube.com/watch?v=QoS4gMxwq_4)
- [Yuri Artiukh](https://twitter.com/akella)'s
[stream](https://youtu.be/qmRqgFbNprM?t=3462) with a section on using
Theatre with THREE.js
- \<Add your own tutorials here\>
## Community and support ## Community and support
Join our friendly community on [Discord](https://discord.gg/bm9f8F9Y9N), follow the updates on [twitter](https://twitter.com/AriaMinaei) or write us an [email](mailto:hello@theatrejs.com). Join our friendly community on [Discord](https://discord.gg/bm9f8F9Y9N), follow
the updates on [twitter](https://twitter.com/AriaMinaei) or write us an
[email](mailto:hello@theatrejs.com).
## Development and contributing ## Development and contributing
If you want to change the source of Theatre, have a look at the guide [here](./CONTRIBUTING.md). If you want to change the source of Theatre, have a look at the guide
[here](./CONTRIBUTING.md).
### Proposing fixes and changes ### Proposing fixes and changes
You can always get help with bugfixes or discuss changes with our community on [Discord](https://discord.gg/bm9f8F9Y9N), or directly open an issue on Github. You can always get help with bugfixes or discuss changes with our community on
[Discord](https://discord.gg/bm9f8F9Y9N), or directly open an issue on Github.
### Helping with outstanding issues ### Helping with outstanding issues
Feel free to chime in on any [issue](https://github.com/AriaMinaei/theatre/issues). We have also labeled some issues with ["Help wanted"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ["Good first issue"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22) if you're just getting started with the codebase. Feel free to chime in on any
[issue](https://github.com/AriaMinaei/theatre/issues). We have also labeled some
issues with
["Help wanted"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22)
or
["Good first issue"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22)
if you're just getting started with the codebase.
### Helping with documentation ### Helping with documentation
The documentation website's repo is [here](https://github.com/ariaminaei/theatre-docs/). The documentation website's repo is
[here](https://github.com/theatre-js/theatre-docs/).
### Writing/recording tutorials ### Writing/recording tutorials
If you make tutorials or video content about Theatre, tell us to showcase it here :) If you make tutorials or video content about Theatre, tell us to showcase it
here :)
## License ## License
Your use of Theatre.js is governed under the Apache License Version 2.0: Your use of Theatre.js is governed under the Apache License Version 2.0:
* Theatre's core (`@theatre/core`) is released under the Apache License. Same goes for most packages in this repository. - Theatre's core (`@theatre/core`) is released under the Apache License. Same
* The studio (`@theatre/studio`) is released under the AGPL 3.0 License. This is the package that you use to edit your animations, setup your scenes, etc. You only use the studio during design/development. Your project's final bundle only includes `@theatre/core`, so only the Apache License applies. goes for most packages in this repository.
- The studio (`@theatre/studio`) is released under the AGPL 3.0 License. This is
the package that you use to edit your animations, setup your scenes, etc. You
only use the studio during design/development. Your project's final bundle
only includes `@theatre/core`, so only the Apache License applies.

57
contributing/api-docs.md
View file

@ -1,6 +1,9 @@
# Writing API docs # Writing API docs
We use [API extractor](https://api-extractor.com/pages/setup/generating_docs/) to generate API docs in markdown. We put the markdown files in the [theatre-docs](https://github.com/ariaminaei/theatre-docs/) repo, which also contains the tutorials and guides. We use [API extractor](https://api-extractor.com/pages/setup/generating_docs/)
to generate API docs in markdown. We put the markdown files in the
[theatre-docs](https://github.com/theatre-js/theatre-docs/) repo, which also
contains the tutorials and guides.
To generate the API docs, run the `build:api-docs` from the root of the repo: To generate the API docs, run the `build:api-docs` from the root of the repo:
@ -10,16 +13,20 @@ $ yarn build:api-docs /path/to/theatre-docs/docs/api/ # this will empty the /api
## JSDoc/TSDoc gotchas ## JSDoc/TSDoc gotchas
We are using TSDoc for documentation generation, IDEs use JSDoc for tooltips. TSDoc and JSDoc have subtle differences. We need to optimize for both. We are using TSDoc for documentation generation, IDEs use JSDoc for tooltips.
TSDoc and JSDoc have subtle differences. We need to optimize for both.
Most users will read our documentation inside their IDEs. Most users will read our documentation inside their IDEs.
### `@example` ### `@example`
IDEs automatically wrap example sections in `` ``` `` if they aren't already wrapped by you. This means you can't use non-code explanations in example sections, like TSDoc examples do. IDEs automatically wrap example sections in ` ``` ` if they aren't already
wrapped by you. This means you can't use non-code explanations in example
sections, like TSDoc examples do.
This will be formatted incorrectly: This will be formatted incorrectly:
```ts
````ts
/** /**
* Adds two numbers together. * Adds two numbers together.
* @example * @example
@ -35,42 +42,54 @@ This will be formatted incorrectly:
* console.log(add(1,-1)); * console.log(add(1,-1));
* ``` * ```
*/ */
export function add(x: number, y: number): number { export function add(x: number, y: number): number {}
} ````
```
Some IDEs have problems with having multiple example sections in the same JSDoc comment. Some IDEs have problems with having multiple example sections in the same JSDoc
comment.
WebStorm doesn’t highlight examples if you wrap them in `` ``` ``. WebStorm doesn’t highlight examples if you wrap them in ` ``` `.
api-documenter doesn’t highlight examples if you don't wrap them in `` ``` ``. api-documenter doesn’t highlight examples if you don't wrap them in ` ``` `.
### Guidelines ### Guidelines
- Only use one `@example` section - Only use one `@example` section
- Use a single code block in it, no explanations - Use a single code block in it, no explanations
- Wrap the code block in `` ```ts ... ``` `` (the `ts` modifier is important, api-documenter copies the `@example` section verbatim, and our documentation page might not highlight the vanilla `` ``` `` sections) - Wrap the code block in ` ```ts ... ``` ` (the `ts` modifier is important,
api-documenter copies the `@example` section verbatim, and our documentation
page might not highlight the vanilla ` ``` ` sections)
- If you need to explain the code, use code comments - If you need to explain the code, use code comments
#### `@typeParam` #### `@typeParam`
api-documenter doesn’t generate documentation for it, but IDEs might display it even if they don't have bespoke support for it. api-documenter doesn’t generate documentation for it, but IDEs might display it
even if they don't have bespoke support for it.
#### `@link` #### `@link`
While in JSDoc you can specify paths relative to the current declaration, TSDoc requires everything to be specified relative to the entry point. That is, if `bar` is a member of `Foo`, and `Foo` is exported in the entry, you need to refer to `bar` as `Foo.bar`, even inside `Foo`. While in JSDoc you can specify paths relative to the current declaration, TSDoc
requires everything to be specified relative to the entry point. That is, if
`bar` is a member of `Foo`, and `Foo` is exported in the entry, you need to
refer to `bar` as `Foo.bar`, even inside `Foo`.
JSDoc allows separating the link text from the link either with a space or using `|`. TSDoc only supports `|`, *and* you mustn’t have spaces around it. So for example `{@link MyClass | go here}` would be rendered incorrectly, whereas `{@link MyClass|go here}` would be correct. JSDoc allows separating the link text from the link either with a space or using
`|`. TSDoc only supports `|`, _and_ you mustn’t have spaces around it. So for
example `{@link MyClass | go here}` would be rendered incorrectly, whereas
`{@link MyClass|go here}` would be correct.
#### `@param` #### `@param`
api-documenter won’t render the documentation for object properties, but document them anyway, IDEs do. api-documenter won’t render the documentation for object properties, but
document them anyway, IDEs do.
Since documentation is only rendered for the object and not for its properties, make sure to include examples for these properties. Since documentation is only rendered for the object and not for its properties,
make sure to include examples for these properties.
#### `@see` #### `@see`
While JSDoc attempts to hyperlink to anything after the `@see` tag, TSDoc requires an explicit `{@link}` tag tag to make hyperlinks. While JSDoc attempts to hyperlink to anything after the `@see` tag, TSDoc
requires an explicit `{@link}` tag tag to make hyperlinks.
**Incorrect ❌** **Incorrect ❌**
@ -83,7 +102,7 @@ While JSDoc attempts to hyperlink to anything after the `@see` tag, TSDoc requir
* @param url - the string to be parsed * @param url - the string to be parsed
* @returns the parsed result * @returns the parsed result
*/ */
function parseURL(url: string): ParsedUrl; function parseURL(url: string): ParsedUrl
``` ```
**Correct ✅** **Correct ✅**
@ -97,5 +116,5 @@ function parseURL(url: string): ParsedUrl;
* @param url - The string to be parsed * @param url - The string to be parsed
* @returns The parsed result * @returns The parsed result
*/ */
function parseURL(url: string): ParsedUrl; function parseURL(url: string): ParsedUrl
``` ```

2
packages/browser-bundles/LICENSE
View file

@ -1,3 +1,3 @@
This is a bundle of @theatre/core and @theatre/studio packages. This is a bundle of @theatre/core and @theatre/studio packages.
See their licenses in their repo: https://github.com/ariaminaei/theatre See their licenses in their repo: https://github.com/theatre-js/theatre

2
theatre/core/src/propTypes/index.ts
View file

@ -63,7 +63,7 @@ const validateCommonOpts = (fnCallSignature: string, opts?: CommonOpts) => {
* *
* // nesting * // nesting
* const foo = {bar: {baz: {quo: 0}}} * const foo = {bar: {baz: {quo: 0}}}
* assert(sheet.object('some object', foo).bar.baz.quo === 0) * assert(sheet.object('some object', foo).value.bar.baz.quo === 0)
* *
* // With additional options: * // With additional options:
* const position = t.compound( * const position = t.compound(