Skip to content

The VS Code of video editing, built for agents.

TypeScript

Introduce animatable properties and keyframe support in JSX and rendering systems. Update documentation to reflect new animation capabilities for properties like `x`, `y`, `width`, `height`, `rotation`, `opacity`, and `cornerRadius`. Implement keyframe management functions and enhance easing options for smoother animations. Ensure compatibility with existing rendering logic and improve type definitions for better clarity.

konstantin-paulus310ee8eb3658
diff --git a/apps/cli/jsx-spec.md b/apps/cli/jsx-spec.md
index a859d7d3..52bf351c 100644
--- a/apps/cli/jsx-spec.md
+++ b/apps/cli/jsx-spec.md
@@ -154,13 +154,15 @@ All visual elements accept:
| ---- | ---- | ------- | ------- |
| `key` | `string` | — | Stable identity across mounts; **required** on document roots (see [Roots](#roots)). |
| `name` | `string` | — | Human-readable node name. |
-| `x`, `y` | `number` | `0` | Position relative to the parent, px. |
-| `width`, `height` | `number` | parent size | Box size, px. |
-| `rotation` | `number` | `0` | Rotation in degrees. |
-| `opacity` | `number` | `1` | `0`–`1`. |
-| `cornerRadius` | `number` | `0` | Uniform corner radius, px. |
+| `x`, `y` | `Animatable<number>` | `0` | Position relative to the parent, px. |
+| `width`, `height` | `Animatable<number>` | parent size | Box size, px. |
+| `rotation` | `Animatable<number>` | `0` | Rotation in degrees. |
+| `opacity` | `Animatable<number>` | `1` | `0`–`1`. |
+| `cornerRadius` | `Animatable<number>` | `0` | Uniform corner radius, px. |
| `inPoint`, `outPoint`, `startTime` | `Time` | see [Timing](#timing) | Temporal placement. |
+`Animatable` props also take a keyframe list — see [Animation](#animation).
+
Common and per-element props share one property table, exported as
`PatchProps`. `dapi node patch` accepts exactly these keys with the same value
requirements as patch entries on existing nodes (see
@@ -185,7 +187,7 @@ alpha is ignored — use `opacity`). Takes only [paint children](#paints); use
| ---- | ---- | ------- | ------- |
| `src` | `string \| AssetRef` | **required** | See [Media source resolution](#media-source-resolution). |
| `objectFit` | `"cover" \| "contain" \| "fill"` | `"cover"` | How the source maps into the box. |
-| `volume` | `number` | `1` | `0`–`1`; `1` = unity gain. |
+| `volume` | `Animatable<number>` | `1` | `0`–`1`; `1` = unity gain. |
| `muted` | `boolean` | `false` | Excludes the node's audio from the mix; independent of `volume`. |
| `syncTo` | `string` | — | Key of another element carrying audio; derives `startTime` by audio alignment (see [Audio sync](#audio-sync)). Mutually exclusive with `startTime`. |
@@ -307,6 +309,59 @@ import. All values may be negative.
| `"MM:SS"` | `"02:30"` | Minutes and seconds. |
| `"HH:MM:SS"` | `"01:02:30"` | Hours, minutes, seconds. |
+## Animation
+
+Animatable props accept a keyframe list in place of a static value:
+
+```tsx
+<image
+ src="/photo.jpg"
+ inPoint={0} outPoint={5}
+ x={[
+ { time: 0, value: -400 },
+ { time: 1, value: 200, easing: "easeOut" },
+ ]}
+ opacity={[{ time: 0, value: 0 }, { time: "15f", value: 1 }]}
+/>
+```
+
+```ts
+type Keyframe<T> = { time: Time; value: T; easing?: Easing };
+type Animatable<T> = T | Keyframe<T>[];
+```
+
+Animatable props: `x`, `y`, `width`, `height`, `rotation`, `opacity`,
+`cornerRadius`, `volume`, `color`, `offset`. As part of the shared property
+table this applies to `dapi node patch` identically, and to paints and color
+stops (`color`, `opacity`, `offset` animate gradients).
+
+### Semantics
+
+- `time` is **node-local**: `0` is the node's in point, in any
+ [time format](#time-formats). Timing props are composition-relative;
+ keyframe times are not, so animation moves with the clip.
+- Outside the keyframed range the value holds at the first/last keyframe.
+- `easing` shapes the segment from its keyframe to the next; the last
+ keyframe's easing is ignored. Default `"linear"`.
+- A **static value replaces any existing keyframes** on that property — mount
+ and `dapi node patch` own what they set. Keyframes land as regular editor
+ keyframes, editable in the timeline and inspector, and props the render
+ doesn't set keep their hand-made tracks across re-mounts.
+
+### Easing
+
+| Easing | Use for |
+| ------ | ------- |
+| `"linear"` (default) | Constant-rate change. |
+| `"easeIn"`, `"easeOut"`, `"easeInOut"` | Standard acceleration curves (CSS equivalents). |
+| `"gentle"`, `"snappy"`, `"bouncy"`, `"strong"` | Spring presets, from soft settle to hard overshoot. |
+| `"cubicBezier(x1,y1,x2,y2)"` | Custom curve, CSS control points. |
+| `"spring(bounce,duration)"` | Custom spring: bounce `0`–`1`, duration in ms. |
+| `"steps(n)"` | Discrete hold: n equal steps, no interpolation. |
+
+Named presets expand to the same descriptors the editor's interpolation
+inspector writes, so they round-trip cleanly.
+
## Sequences
`<sequence>` enforces **sequential, non-overlapping** placement of its children —
diff --git a/apps/web/src/components/engine/api/keyframe.ts b/apps/web/src/components/engine/api/keyframe.ts
index 9e10bd03..c00937f9 100644
--- a/apps/web/src/components/engine/api/keyframe.ts
+++ b/apps/web/src/components/engine/api/keyframe.ts
@@ -150,6 +150,45 @@ export function toggleKeyframeTrack(world: EngineWorld, eid: number, property: P
});
}
+/**
+ * Declaratively replace all keyframes for (target, property): creates the
+ * track on first use, deletes it when `keyframes` is empty. Times are local
+ * frames; values are in the property's authored unit. Runs without a history
+ * transaction — callers (mount, patch) provide their own.
+ */
+export function setKeyframeTrack(
+ world: EngineWorld,
+ target: number,
+ property: PropertyPath,
+ keyframes: ReadonlyArray<{ time: number; value: number; easing?: string }>,
+): void {
+ const c = world.components;
+ const existing = findKeyframeTrackEntity(world, target, property);
+
+ if (existing !== null) {
+ for (const kid of query(world, [c.Keyframe, ChildOf(existing), Not(c.Deleted)])) {
+ deleteEntity(world, kid);
+ }
+ if (keyframes.length === 0) {
+ deleteEntity(world, existing);
+ return;
+ }
+ }
+ if (keyframes.length === 0) return;
+
+ const tid = existing ?? ensureKeyframeTrackEntity(world, target, property);
+ const sorted = [...keyframes].sort((a, b) => a.time - b.time);
+ for (const kf of sorted) {
+ const kid = createEntity(world);
+ setComponent(world, kid, c.Keyframe, {
+ time: kf.time,
+ value: kf.value,
+ easing: kf.easing ?? '',
+ });
+ appendChild(world, kid, tid);
+ }
+}
+
export function removeKeyframeTrack(world: EngineWorld, eid: number, property: PropertyPath) {
const c = world.components;
const trackEid = findKeyframeTrackEntity(world, eid, property);
diff --git a/apps/web/src/components/engine/systems/motion.ts b/apps/web/src/components/engine/systems/motion.ts
index 96d1e5db..a65a29aa 100644
--- a/apps/web/src/components/engine/systems/motion.ts
+++ b/apps/web/src/components/engine/systems/motion.ts
@@ -339,7 +339,7 @@ function resolveEasing(descriptor: string | undefined): EasingFunction | null {
fn = steps(n, fromStart);
}
- const bezierMatch = descriptor.match(/^cubicBezier\(([\d.]+),([\d.]+),([\d.]+),([\d.]+)\)$/);
+ const bezierMatch = descriptor.match(/^cubicBezier\((-?[\d.]+),(-?[\d.]+),(-?[\d.]+),(-?[\d.]+)\)$/);
if (bezierMatch) {
const [, x1, y1, x2, y2] = bezierMatch;
fn = cubicBezier(Number(x1), Number(y1), Number(x2), Number(y2));
diff --git a/apps/web/src/utils/jsx.ts b/apps/web/src/utils/jsx.ts
index 62e461f0..2cf851e0 100644
--- a/apps/web/src/utils/jsx.ts
+++ b/apps/web/src/utils/jsx.ts
@@ -32,6 +32,7 @@ import {
removeComponent,
resizeEntity,
setComponent,
+ setKeyframeTrack,
transcribeScene,
} from "@/components/engine";
import { ChildOf } from "@/components/engine/components";
@@ -92,6 +93,67 @@ const TEXT_BASELINE_MAP = {
bottom: TextBaseline.BOTTOM,
} as const;
+// Named easing presets, expanded to the descriptors the interpolation
+// inspector writes so JSX-authored keyframes match hand-edited ones.
+const EASING_PRESET_MAP: Record<string, string> = {
+ linear: "",
+ easeIn: "cubicBezier(0.42,0,1,1)",
+ easeOut: "cubicBezier(0,0,0.58,1)",
+ easeInOut: "cubicBezier(0.42,0,0.58,1)",
+ gentle: "spring(0.5,628)",
+ snappy: "spring(0.15,300)",
+ bouncy: "spring(0.4,500)",
+ strong: "spring(0.65,400)",
+};
+
+function parseEasing(value: unknown): string {
+ assert(typeof value === "string", "keyframe `easing` must be a string" + `, value: ${value}`);
+ const preset = EASING_PRESET_MAP[value];
+ if (preset !== undefined) return preset;
+
+ const valid =
+ /^cubicBezier\(-?[\d.]+,-?[\d.]+,-?[\d.]+,-?[\d.]+\)$/.test(value) ||
+ /^spring\(-?[\d.]+,-?[\d.]+\)$/.test(value) ||
+ /^steps\(\d+(,(true|false))?\)$/.test(value);
+ assert(valid, `invalid keyframe easing: "${value}"`);
+ return value;
+}
+
+/**
+ * Parses a keyframe-list prop value: times to local frames (0 = the node's
+ * in point), values through `convert` into the property's authored unit,
+ * easings through the preset map. Returns the list sorted by time — callers
+ * land `[0].value` as the authored value and hand the list to
+ * `setKeyframeTrack`.
+ */
+function parseKeyframes(
+ name: string,
+ entries: unknown[],
+ convert: (value: unknown) => number,
+): { time: number; value: number; easing: string }[] {
+ assert(entries.length > 0, `\`${name}\` keyframe list must not be empty`);
+
+ const frames = new Set<number>();
+ const keyframes = entries.map((entry) => {
+ assert(
+ typeof entry === "object" && entry !== null && !Array.isArray(entry),
+ `\`${name}\` keyframes must be { time, value, easing? } objects`,
+ );
+ const { time, value, easing } = entry as Record<string, unknown>;
+ const frame = parseFrames(String(time), 30);
+ assert(typeof frame === "number", `\`${name}\` keyframe \`time\` must be a time value` + `, value: ${time}`);
+ assert(!frames.has(frame), `\`${name}\` has two keyframes at frame ${frame}`);
+ frames.add(frame);
+ return {
+ time: frame,
+ value: convert(value),
+ easing: easing === undefined ? "" : parseEasing(easing),
+ };
+ });
+
+ return keyframes.sort((a, b) => a.time - b.time);
+}
+
const CAPTION_PRESET_MAP = {
classic: CaptionType.CLASSIC,
cascade: CaptionType.CASCADE,
@@ -333,37 +395,113 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
setComponent(world, eid, c.Name, value);
break;
} case "x": {
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "number", "`x` must be a number" + `, value: ${v}`);
+ return Math.round(v);
+ });
+ setComponent(world, eid, c.Position, { x: keyframes[0].value });
+ setKeyframeTrack(world, eid, "position.x", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, "position.x", []);
assert(typeof value === "number", "`x` must be a number" + `, value: ${value}`);
setComponent(world, eid, c.Position, { x: Math.round(value) });
break;
} case "y": {
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "number", "`y` must be a number" + `, value: ${v}`);
+ return Math.round(v);
+ });
+ setComponent(world, eid, c.Position, { y: keyframes[0].value });
+ setKeyframeTrack(world, eid, "position.y", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, "position.y", []);
assert(typeof value === "number", "`y` must be a number" + `, value: ${value}`);
setComponent(world, eid, c.Position, { y: Math.round(value) });
break;
} case "width": {
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "number", "`width` must be a number" + `, value: ${v}`);
+ assert(v >= 0, "`width` must be >= 0");
+ return Math.round(v);
+ });
+ resizeEntity(world, eid, { width: keyframes[0].value });
+ setKeyframeTrack(world, eid, "width", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, "width", []);
assert(typeof value === "number", "`width` must be a number" + `, value: ${value}`);
assert(value >= 0, "`width` must be >= 0");
resizeEntity(world, eid, { width: Math.round(value) });
break;
- } case "height":
+ } case "height": {
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "number", "`height` must be a number" + `, value: ${v}`);
+ assert(v >= 0, "`height` must be >= 0");
+ return Math.round(v);
+ });
+ resizeEntity(world, eid, { height: keyframes[0].value });
+ setKeyframeTrack(world, eid, "height", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, "height", []);
assert(typeof value === "number", "`height` must be a number" + `, value: ${value}`);
assert(value >= 0, "`height` must be >= 0");
resizeEntity(world, eid, { height: Math.round(value) });
break;
- case "rotation": {
+ } case "rotation": {
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "number", "`rotation` must be a number" + `, value: ${v}`);
+ return v;
+ });
+ setComponent(world, eid, c.Rotation, keyframes[0].value);
+ setKeyframeTrack(world, eid, "rotation", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, "rotation", []);
assert(typeof value === "number", "`rotation` must be a number" + `, value: ${value}`);
setComponent(world, eid, c.Rotation, value);
break;
} case "opacity": {
+ const isStop = hasComponent(world, eid, c.ColorStop);
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "number", "`opacity` must be a number" + `, value: ${v}`);
+ assert(v >= 0 && v <= 1, "`opacity` must be between 0 and 1");
+ return v;
+ });
+ if (isStop) setComponent(world, eid, c.ColorStop, { opacity: keyframes[0].value });
+ else setComponent(world, eid, c.Appearance, { opacity: keyframes[0].value });
+ setKeyframeTrack(world, eid, isStop ? "stop.opacity" : "opacity", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, isStop ? "stop.opacity" : "opacity", []);
assert(typeof value === "number", "`opacity` must be a number" + `, value: ${value}`);
assert(value >= 0 && value <= 1, "`opacity` must be between 0 and 1");
- if (hasComponent(world, eid, c.ColorStop)) {
+ if (isStop) {
setComponent(world, eid, c.ColorStop, { opacity: value });
} else {
setComponent(world, eid, c.Appearance, { opacity: value });
}
break;
} case "cornerRadius": {
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "number", "`cornerRadius` must be a number" + `, value: ${v}`);
+ assert(v >= 0, "`cornerRadius` must be >= 0");
+ return Math.round(v);
+ });
+ setComponent(world, eid, c.CornerRadius, keyframes[0].value);
+ setKeyframeTrack(world, eid, "vertexRadius", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, "vertexRadius", []);
assert(typeof value === "number", "`cornerRadius` must be a number" + `, value: ${value}`);
assert(value >= 0, "`cornerRadius` must be >= 0");
setComponent(world, eid, c.CornerRadius, Math.round(value));
@@ -417,6 +555,19 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
break;
}
case "volume": {
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "number", "`volume` must be a number" + `, value: ${v}`);
+ assert(v >= 0, "`volume` must be >= 0");
+ // Keyframed silence floors at -60 dB so segments toward it
+ // interpolate over finite values.
+ return Math.max(v <= 0 ? -Infinity : 20 * Math.log10(v), -60);
+ });
+ setComponent(world, eid, c.Volume, keyframes[0].value);
+ setKeyframeTrack(world, eid, "volume", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, "volume", []);
assert(typeof value === "number", "`volume` must be a number" + `, value: ${value}`);
assert(value >= 0, "`volume` must be >= 0");
// Convert linear volume to decibels
@@ -499,19 +650,43 @@ export class WorldDocument implements ProjectDocument<DocumentNode> {
setComponent(world, eid, c.TextStyle, { textBaseline: TEXT_BASELINE_MAP[value as keyof typeof TEXT_BASELINE_MAP] });
break;
case "color": {
+ const isStop = hasComponent(world, eid, c.ColorStop);
+ assert(isStop || hasComponent(world, eid, c.Paint), "`color` only applies to paints or color stops");
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "string", "`color` must be a string" + `, value: ${v}`);
+ const color = parseColor(v);
+ assert(color !== null, `color is not a valid CSS color: "${v}"`);
+ return color;
+ });
+ if (isStop) setComponent(world, eid, c.ColorStop, { color: keyframes[0].value });
+ else setComponent(world, eid, c.Color, keyframes[0].value);
+ setKeyframeTrack(world, eid, isStop ? "stop.color" : "color", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, isStop ? "stop.color" : "color", []);
assert(typeof value === "string", "`color` must be a string" + `, value: ${value}`);
const color = parseColor(value);
assert(color !== null, `color is not a valid CSS color: "${value}"`);
- if (hasComponent(world, eid, c.ColorStop)) {
+ if (isStop) {
setComponent(world, eid, c.ColorStop, { color });
- } else if (hasComponent(world, eid, c.Paint)) {
- setComponent(world, eid, c.Color, color);
} else {
- assert(false, "`color` only applies to paints or color stops");
+ setComponent(world, eid, c.Color, color);
}
break;
} case "offset": {
assert(hasComponent(world, eid, c.ColorStop), "`offset` only applies to <colorStop>");
+ if (Array.isArray(value)) {
+ const keyframes = parseKeyframes(name, value, (v) => {
+ assert(typeof v === "number", "`offset` must be a number" + `, value: ${v}`);
+ assert(v >= 0 && v <= 1, "`offset` must be between 0 and 1");
+ return v;
+ });
+ setComponent(world, eid, c.ColorStop, { offset: keyframes[0].value });
+ setKeyframeTrack(world, eid, "stop.offset", keyframes);
+ break;
+ }
+ setKeyframeTrack(world, eid, "stop.offset", []);
assert(typeof value === "number", "`offset` must be a number" + `, value: ${value}`);
assert(value >= 0 && value <= 1, "`offset` must be between 0 and 1");
setComponent(world, eid, c.ColorStop, { offset: value });
diff --git a/docs/composition.md b/docs/composition.md
index 5389127b..072620e1 100644
--- a/docs/composition.md
+++ b/docs/composition.md
@@ -48,13 +48,15 @@ User-defined components are ordinary Solid components; only intrinsic elements p
| --- | --- | --- |
| `key` | none | Stable identity; required on document roots. |
| `name` | none | Node name in the editor. |
-| `x`, `y` | `0` | Position in px, relative to the parent, origin top-left. |
-| `width`, `height` | parent size | Box size in px. |
-| `rotation` | `0` | Degrees. |
-| `opacity` | `1` | `0`–`1`. |
-| `cornerRadius` | `0` | Px. |
+| `x`, `y` | `0` | Position in px, relative to the parent, origin top-left. Animatable. |
+| `width`, `height` | parent size | Box size in px. Animatable. |
+| `rotation` | `0` | Degrees. Animatable. |
+| `opacity` | `1` | `0`–`1`. Animatable. |
+| `cornerRadius` | `0` | Px. Animatable. |
| `inPoint`, `outPoint`, `startTime` | see [Timing](#timing) | Temporal placement. |
+Animatable props also take a keyframe list — see [Animation](#animation).
+
**Every box defaults to its parent's box**, the JSX analog of `position: absolute; inset: 0`. So a centered full-frame title is just:
```tsx
@@ -108,6 +110,36 @@ Composition-relative, Lottie-inspired. Values take any [time format](cli.md#time
`syncTo` and `startTime` are mutually exclusive; `inPoint`/`outPoint` stay yours, and when omitted the window defaults to the overlap with the target's window. Alignment runs after generated assets land (either side may be generated), locally and cached, and blocks the mount; an alignment too weak to trust fails the mount and the node keeps its default placement.
+## Animation
+
+Animatable props (`x`, `y`, `width`, `height`, `rotation`, `opacity`, `cornerRadius`, `volume`, `color`, `offset`) accept a keyframe list in place of a static value:
+
+```tsx
+<image
+ src="/photo.jpg"
+ inPoint={0} outPoint={5}
+ x={[
+ { time: 0, value: -400 },
+ { time: 1, value: 200, easing: "easeOut" },
+ ]}
+ opacity={[{ time: 0, value: 0 }, { time: "15f", value: 1 }]}
+/>
+```
+
+- `time` is **node-local** (0 = the node's in point), in any [time format](cli.md#time-values); animation moves with the clip. Outside the keyframed range the value holds at the first/last keyframe.
+- `easing` shapes the segment from its keyframe to the next (ignored on the last). Default `"linear"`.
+- A static value replaces any existing keyframes on the property; mounted keyframes are regular editor keyframes, editable in the timeline and inspector. Props the render doesn't set keep their hand-made tracks.
+- `color`, `opacity`, and `offset` also animate on paints and color stops, so gradients can move.
+
+| Easing | Use for |
+| --- | --- |
+| `"linear"` (default) | Constant-rate change. |
+| `"easeIn"`, `"easeOut"`, `"easeInOut"` | Standard acceleration curves (CSS equivalents). |
+| `"gentle"`, `"snappy"`, `"bouncy"`, `"strong"` | Spring presets, from soft settle to hard overshoot. |
+| `"cubicBezier(x1,y1,x2,y2)"` | Custom curve, CSS control points. |
+| `"spring(bounce,duration)"` | Custom spring: bounce `0`–`1`, duration in ms. |
+| `"steps(n)"` | Discrete hold: n equal steps, no interpolation. |
+
## Paints
A node's fill is a **paint child**; the `fill` prop is shorthand for a solid paint. Declaring paints as children unlocks gradients and stacking (later paints render on top, including over the media paint of a `<video>` or `<image>`):
diff --git a/packages/solid/src/index.ts b/packages/solid/src/index.ts
index 428bcb06..b0d2669a 100644
--- a/packages/solid/src/index.ts
+++ b/packages/solid/src/index.ts
@@ -6,14 +6,17 @@
export { PATCH_PROP_KEYS } from "./types";
export { parseTime, TIME_FPS } from "./time";
export type {
+ Animatable,
AudioProps,
CaptionPreset,
CaptionsProps,
ColorStopProps,
+ Easing,
Fit,
GradientPaintProps,
GroupProps,
ImageProps,
+ Keyframe,
PatchProps,
RectProps,
SceneProps,
diff --git a/packages/solid/src/types.ts b/packages/solid/src/types.ts
index d3ff0487..185d4c73 100644
--- a/packages/solid/src/types.ts
+++ b/packages/solid/src/types.ts
@@ -14,6 +14,39 @@ export type Time = number | `${number}f` | `${string}:${string}`;
export type Fit = "cover" | "contain" | "fill";
+/**
+ * Easing for the segment from a keyframe to the next one: a named preset or
+ * an explicit descriptor. `cubicBezier(x1,y1,x2,y2)` takes CSS-style control
+ * points, `spring(bounce,duration)` a 0–1 bounce and a duration in ms,
+ * `steps(n)` holds n discrete values.
+ */
+export type Easing =
+ | "linear"
+ | "easeIn"
+ | "easeOut"
+ | "easeInOut"
+ | "gentle"
+ | "snappy"
+ | "bouncy"
+ | "strong"
+ | `cubicBezier(${string})`
+ | `spring(${string})`
+ | `steps(${string})`;
+
+export type Keyframe<T> = {
+ /** Node-local time: 0 is the node's in point. Any `Time` format. */
+ time: Time;
+ value: T;
+ /** Shapes the segment to the next keyframe; ignored on the last. Default "linear". */
+ easing?: Easing;
+};
+
+/**
+ * A static value, or keyframes animating it over the node's local time.
+ * Setting a static value removes any existing keyframe track on the property.
+ */
+export type Animatable<T> = T | Keyframe<T>[];
+
/** Caption style presets — the editor's caption inspector presets. */
export type CaptionPreset =
| "classic"
@@ -39,18 +72,18 @@ export type PatchProps = {
key?: string;
/** Human-readable node name. */
name?: string;
- /** Position relative to the parent, px. Defaults to 0. */
- x?: number;
- y?: number;
- /** Box size, px. Defaults to the parent's size. */
- width?: number;
- height?: number;
- /** Rotation in degrees. */
- rotation?: number;
- /** Opacity, 0–1. */
- opacity?: number;
- /** Uniform corner radius, px. */
- cornerRadius?: number;
+ /** Position relative to the parent, px. Defaults to 0. Animatable. */
+ x?: Animatable<number>;
+ y?: Animatable<number>;
+ /** Box size, px. Defaults to the parent's size. Animatable. */
+ width?: Animatable<number>;
+ height?: Animatable<number>;
+ /** Rotation in degrees. Animatable. */
+ rotation?: Animatable<number>;
+ /** Opacity, 0–1. Animatable. */
+ opacity?: Animatable<number>;
+ /** Uniform corner radius, px. Animatable. */
+ cornerRadius?: Animatable<number>;
/** Composition time at which the node becomes visible/audible. */
inPoint?: Time;
/** Composition time at which the node stops. */
@@ -69,8 +102,8 @@ export type PatchProps = {
src?: string | AssetRef;
/** How the source maps into the box. Default "cover" on `<video>`, "contain" on `<image>`. */
objectFit?: Fit;
- /** 0–1; 1 = unity gain. */
- volume?: number;
+ /** 0–1; 1 = unity gain. Animatable. */
+ volume?: Animatable<number>;
/** Excludes the node's audio from the mix; independent of `volume`. */
muted?: boolean;
/** A family available on the machine (`dapi fonts`). */
@@ -80,14 +113,14 @@ export type PatchProps = {
/** CSS weights 100–900, or "normal" / "bold". */
fontWeight?: number | "normal" | "bold";
fontStyle?: "normal" | "italic";
- /** Any CSS color: the glyph color on `<text>`, the paint color on paints and color stops. */
- color?: string;
+ /** Any CSS color: the glyph color on `<text>`, the paint color on paints and color stops. Animatable. */
+ color?: Animatable<string>;
/** Horizontal alignment of glyphs within the box. Default "left". */
textAlign?: "left" | "center" | "right";
/** Vertical alignment within the box. Default "top". */
textBaseline?: "top" | "middle" | "bottom";
- /** Position along the gradient, 0–1. */
- offset?: number;
+ /** Position along the gradient, 0–1. Animatable. */
+ offset?: Animatable<number>;
/** Caption style preset — `<captions>` only. Default "classic". */
preset?: CaptionPreset;
/** Fills the caption preset's color slots in order; any CSS color, alpha is ignored. */