Skip to content

Visualize Your Ideas With Code

feat: add experimental features (#876)

Jacob498d3871d05d
diff --git a/packages/core/src/app/Project.ts b/packages/core/src/app/Project.ts
index 51970a72..696e7274 100644
--- a/packages/core/src/app/Project.ts
+++ b/packages/core/src/app/Project.ts
@@ -15,6 +15,12 @@ export interface ProjectSettings {
*/
audioOffset?: number;
variables?: Record<string, unknown>;
+ /**
+ * Enable experimental features.
+ *
+ * @experimental
+ */
+ experimentalFeatures?: boolean;
}
export interface Versions {
@@ -34,6 +40,7 @@ export interface Project {
audio?: string;
variables?: Record<string, unknown>;
versions: Versions;
+ experimentalFeatures: boolean;
}
export function makeProject(settings: ProjectSettings) {
diff --git a/packages/core/src/app/bootstrap.ts b/packages/core/src/app/bootstrap.ts
index 8c5fe106..66075222 100644
--- a/packages/core/src/app/bootstrap.ts
+++ b/packages/core/src/app/bootstrap.ts
@@ -51,6 +51,7 @@ export function bootstrap(
project.settings = settings;
project.meta = new ProjectMetadata(project);
project.meta.shared.set(settings.defaults.get());
+ project.experimentalFeatures ??= false;
metaFile.attach(project.meta);
plugins.forEach(plugin => plugin.project?.(project));
diff --git a/packages/core/src/scenes/GeneratorScene.ts b/packages/core/src/scenes/GeneratorScene.ts
index 5b5faacc..05c1b25d 100644
--- a/packages/core/src/scenes/GeneratorScene.ts
+++ b/packages/core/src/scenes/GeneratorScene.ts
@@ -108,6 +108,8 @@ export abstract class GeneratorScene<T>
return this.previousScene;
}
+ public readonly experimentalFeatures: boolean;
+
protected resolutionScale: number;
private runnerFactory: ThreadGeneratorFactory<T>;
private previousScene: Scene | null = null;
@@ -128,6 +130,7 @@ export abstract class GeneratorScene<T>
this.meta = description.meta;
this.runnerFactory = description.config;
this.creationStack = description.stack;
+ this.experimentalFeatures = description.experimentalFeatures ?? false;
decorate(this.runnerFactory, threadable(this.name));
this.timeEvents = new description.timeEventsClass(this);
diff --git a/packages/core/src/scenes/Scene.ts b/packages/core/src/scenes/Scene.ts
index a7a4c8e4..9f42a688 100644
--- a/packages/core/src/scenes/Scene.ts
+++ b/packages/core/src/scenes/Scene.ts
@@ -63,6 +63,7 @@ export interface FullSceneDescription<T = unknown> extends SceneDescription<T> {
logger: Logger;
onReplaced: ValueDispatcher<FullSceneDescription<T>>;
timeEventsClass: new (scene: Scene) => TimeEvents;
+ experimentalFeatures?: boolean;
}
/**
@@ -209,6 +210,11 @@ export interface Scene<T = unknown> {
*/
get previous(): Scene | null;
+ /**
+ * Whether experimental features are enabled.
+ */
+ get experimentalFeatures(): boolean;
+
/**
* Render the scene onto a canvas.
*
diff --git a/packages/docs/docs/advanced/experimental.mdx b/packages/docs/docs/advanced/experimental.mdx
new file mode 100644
index 00000000..63f51476
--- /dev/null
+++ b/packages/docs/docs/advanced/experimental.mdx
@@ -0,0 +1,34 @@
+---
+sidebar_position: 6
+slug: /experimental
+---
+
+# Experimental features
+
+Motion Canvas follows the [semver](https://semver.org/) versioning scheme. Among
+other things, this means that any release with the same major version will be
+backwards compatible. For example, an animation made using `v3.2.0` (In this
+case the major version is `3`) will work just fine with `v3.2.1`, `v3.3.0`,
+`v3.4.0`, and so on.
+
+Experimental features don't follow this rule. They are subject to change at any
+time and may break your animations. They are meant to be used for testing and
+feedback purposes only.
+
+:::experimental
+
+Throughout the documentation, experimental features are marked with a warning
+like this one.
+
+:::
+
+In order to use experimental features, you need to enable them in your project
+configuration:
+
+```ts title="project.ts"
+export default makeProject({
+ // highlight-next-line
+ experimentalFeatures: true,
+ // ...
+});
+```
diff --git a/packages/docs/docusaurus.config.js b/packages/docs/docusaurus.config.js
index 620cf1b0..28644c24 100644
--- a/packages/docs/docusaurus.config.js
+++ b/packages/docs/docusaurus.config.js
@@ -131,6 +131,17 @@ const config = {
exclude: ['**/api/core/*.md', '**/api/2d/*.md'],
showLastUpdateAuthor: true,
docItemComponent: '@site/src/components/DocPage',
+ admonitions: {
+ tag: ':::',
+ keywords: [
+ 'note',
+ 'tip',
+ 'info',
+ 'caution',
+ 'danger',
+ 'experimental',
+ ],
+ },
editUrl: ({versionDocsDirPath, docPath}) =>
`https://github.com/motion-canvas/motion-canvas/blob/main/packages/docs/${versionDocsDirPath}/${docPath}`,
},
diff --git a/packages/docs/src/components/Api/Comment/index.tsx b/packages/docs/src/components/Api/Comment/index.tsx
index 55a255e0..e69e0d59 100644
--- a/packages/docs/src/components/Api/Comment/index.tsx
+++ b/packages/docs/src/components/Api/Comment/index.tsx
@@ -1,6 +1,6 @@
import {Collapsible} from '@docusaurus/theme-common';
import Summary from '@site/src/components/Api/Comment/Summary';
-import Admonition from '@theme/Admonition';
+import ExperimentalWarning from '@site/src/components/ExperimentalWarning';
import clsx from 'clsx';
import React, {useMemo, useState} from 'react';
import type {JSONOutput} from 'typedoc';
@@ -33,16 +33,7 @@ function Experimental({comment}: {comment: JSONOutput.Comment}) {
[comment],
);
- return (
- <>
- {experimental && (
- <Admonition type="experimental">
- This is an experimental feature. The behavior and API may change
- drastically between major releases.
- </Admonition>
- )}
- </>
- );
+ return experimental ? <ExperimentalWarning /> : null;
}
function FullComment({comment}: {comment: JSONOutput.Comment}) {
diff --git a/packages/docs/src/components/ExperimentalWarning/index.tsx b/packages/docs/src/components/ExperimentalWarning/index.tsx
new file mode 100644
index 00000000..bc20ce2e
--- /dev/null
+++ b/packages/docs/src/components/ExperimentalWarning/index.tsx
@@ -0,0 +1,12 @@
+import Link from '@docusaurus/Link';
+import Admonition from '@theme/Admonition';
+import React from 'react';
+
+export default function ExperimentalWarning() {
+ return (
+ <Admonition type="experimental">
+ This is an <Link to="/docs/experimental">experimental feature</Link>. The
+ behavior and API may change drastically between minor releases.
+ </Admonition>
+ );
+}
diff --git a/packages/docs/src/components/Release/Issue.tsx b/packages/docs/src/components/Release/Issue.tsx
index 5d045d80..16b93ba6 100644
--- a/packages/docs/src/components/Release/Issue.tsx
+++ b/packages/docs/src/components/Release/Issue.tsx
@@ -1,3 +1,4 @@
+import Link from '@docusaurus/Link';
import IconScience from '@site/src/Icon/Science';
import Contributor from '@site/src/components/Release/Contributor';
import PullRequest from '@site/src/components/Release/PullRequest';
@@ -16,9 +17,9 @@ export default function Issue({user, pr, experimental, children}: IssueProps) {
<li className={styles.element}>
<Contributor name={user} />
{experimental && (
- <span title="Experimental feature">
+ <Link to="/docs/experimental" title="Experimental feature">
<IconScience className="experimental" />
- </span>
+ </Link>
)}
{children}
{pr && <PullRequest id={pr} />}
diff --git a/packages/template/src/project.ts b/packages/template/src/project.ts
index ecfbbeb6..8b01617a 100644
--- a/packages/template/src/project.ts
+++ b/packages/template/src/project.ts
@@ -3,5 +3,6 @@ import {makeProject} from '@motion-canvas/core';
import example from './scenes/example?scene';
export default makeProject({
+ experimentalFeatures: true,
scenes: [example],
});
diff --git a/packages/ui/src/components/icons/Science.tsx b/packages/ui/src/components/icons/Science.tsx
new file mode 100644
index 00000000..18e8c754
--- /dev/null
+++ b/packages/ui/src/components/icons/Science.tsx
@@ -0,0 +1,7 @@
+export function Science() {
+ return (
+ <svg viewBox="0 0 24 24" fill="currentColor">
+ <path d="M13,11.33L18,18H6l5-6.67V6h2 M15.96,4H8.04C7.62,4,7.39,4.48,7.65,4.81L9,6.5v4.17L3.2,18.4C2.71,19.06,3.18,20,4,20h16 c0.82,0,1.29-0.94,0.8-1.6L15,10.67V6.5l1.35-1.69C16.61,4.48,16.38,4,15.96,4L15.96,4z" />
+ </svg>
+ );
+}
diff --git a/packages/ui/src/components/icons/index.ts b/packages/ui/src/components/icons/index.ts
index c4614233..b3f354a9 100644
--- a/packages/ui/src/components/icons/index.ts
+++ b/packages/ui/src/components/icons/index.ts
@@ -21,6 +21,7 @@ export * from './Recenter';
export * from './Repeat';
export * from './Schedule';
export * from './School';
+export * from './Science';
export * from './Settings';
export * from './SkipNext';
export * from './SkipPrevious';
diff --git a/packages/ui/src/components/layout/Navigation.tsx b/packages/ui/src/components/layout/Navigation.tsx
index 7cd0c963..3284f51b 100644
--- a/packages/ui/src/components/layout/Navigation.tsx
+++ b/packages/ui/src/components/layout/Navigation.tsx
@@ -1,5 +1,6 @@
+import {LogLevel} from '@motion-canvas/core';
import {useEffect, useRef, useState} from 'preact/hooks';
-import {useInspection, useLogger} from '../../contexts';
+import {useApplication, useInspection, useLogger} from '../../contexts';
import {useReducedMotion} from '../../hooks';
import {BottomPanel, EditorPanel, SidebarPanel} from '../../signals';
import {emphasize, shake} from '../animations';
@@ -10,6 +11,7 @@ import {
MotionCanvas,
Movie,
School,
+ Science,
Settings,
Videocam,
} from '../icons';
@@ -17,6 +19,7 @@ import {Badge, Space, Tab, TabGroup, TabLink, Tabs} from '../tabs';
import styles from './Navigation.module.scss';
export function Navigation() {
+ const {project} = useApplication();
const {inspectedElement} = useInspection();
const inspectorTab = useRef<HTMLButtonElement>();
const reducedMotion = useReducedMotion();
@@ -96,6 +99,17 @@ export function Navigation() {
</Tab>
</TabGroup>
<Space />
+ {project.experimentalFeatures && (
+ <TabLink
+ title="Experimental features enabled"
+ id="docs-experimental-link"
+ href="https://motioncanvas.io/docs/experimental/"
+ target="_blank"
+ >
+ <Science />
+ <Badge level={LogLevel.Warn}>!</Badge>
+ </TabLink>
+ )}
<TabLink
title="Docs"
id="docs-external-link"
diff --git a/packages/ui/src/components/tabs/Badge.tsx b/packages/ui/src/components/tabs/Badge.tsx
index eba9e10c..a519dd0c 100644
--- a/packages/ui/src/components/tabs/Badge.tsx
+++ b/packages/ui/src/components/tabs/Badge.tsx
@@ -1,15 +1,21 @@
-import styles from './Tabs.module.scss';
-
+import {LogLevel} from '@motion-canvas/core';
+import clsx from 'clsx';
import {ComponentChildren, Ref} from 'preact';
+import styles from './Tabs.module.scss';
export interface BadgeInterface {
+ level?: LogLevel;
children?: ComponentChildren;
badgeRef?: Ref<HTMLDivElement>;
}
-export function Badge({children, badgeRef}: BadgeInterface) {
+export function Badge({
+ children,
+ badgeRef,
+ level = LogLevel.Error,
+}: BadgeInterface) {
return (
- <div ref={badgeRef} className={styles.badge}>
+ <div ref={badgeRef} className={clsx(styles.badge, styles[level])}>
{children}
</div>
);
diff --git a/packages/ui/src/components/tabs/Tabs.module.scss b/packages/ui/src/components/tabs/Tabs.module.scss
index 43642cb8..d0fc0ec2 100644
--- a/packages/ui/src/components/tabs/Tabs.module.scss
+++ b/packages/ui/src/components/tabs/Tabs.module.scss
@@ -1,3 +1,13 @@
+$colors: (
+ 'error': var(--red),
+ 'warn': var(--yellow),
+ 'info': var(--blue),
+ 'http': #cccccc,
+ 'verbose': #cccccc,
+ 'debug': #cccccc,
+ 'silly': #cccccc,
+);
+
.root {
width: 100%;
height: 100%;
@@ -53,10 +63,15 @@
padding: 0 4px;
min-width: 16px;
height: 16px;
- background-color: var(--red);
border-radius: 8px;
text-align: center;
z-index: 1;
+
+ @each $level, $color in $colors {
+ &.#{$level} {
+ background-color: $color;
+ }
+ }
}
.space {