diff options
Diffstat (limited to 'docs/keyframes.md')
| -rw-r--r-- | docs/keyframes.md | 408 |
1 files changed, 204 insertions, 204 deletions
diff --git a/docs/keyframes.md b/docs/keyframes.md index 97619626..afa85846 100644 --- a/docs/keyframes.md +++ b/docs/keyframes.md @@ -1,204 +1,204 @@ -# Keyframe System - -Keyframes allow element properties to change over time. The system is split into three layers: the **data model** (how keyframes are stored), the **registry** (which properties support keyframes and how to read/write them), and the **UI** (hooks and components that wire it all together). - -## How It Works - -### Data model - -Every `BaseTimelineElement` has an optional `animations?: ElementAnimations` field: - -```typescript -interface ElementAnimations { - channels: Record<string, AnimationChannel | undefined>; -} -``` - -A channel is a typed bucket of keyframes keyed by property path (e.g. `"opacity"`, `"background.color"`). Three channel types exist: `NumberAnimationChannel`, `ColorAnimationChannel`, and `DiscreteAnimationChannel`. - -### Registry - -`src/lib/animation/property-registry.ts` defines which property paths are animatable and how to read/write their values on an element. `src/types/animation.ts` holds the canonical list of valid paths in `ANIMATION_PROPERTY_PATHS`. - -### Resolver - -`src/lib/animation/resolve.ts` provides functions that return the effective value of a property at a given local time — falling back to the element's static value when no keyframes exist. - -### Renderer - -Nodes in `src/services/renderer/` call the resolve functions before drawing so that animated properties interpolate correctly during export and preview. - -### UI - -Two hooks in `src/components/editor/panels/properties/hooks/` handle the keyframe-aware field logic: - -- `useKeyframedNumberProperty` — for numeric fields (opacity, position, scale, etc.) -- `useKeyframedColorProperty` — for color pickers - -Both hooks handle the toggle/add/remove keyframe flow and automatically switch between writing to the static property and writing to the animation channel depending on whether keyframes are active. - ---- - -## Adding a New Animatable Property - -Using `"background.paddingX"` as an example. - -### 1. Register the path — `src/types/animation.ts` - -```typescript -export const ANIMATION_PROPERTY_PATHS = [ - // ...existing paths - "background.paddingX", -] as const; -``` - -### 2. Add a registry entry — `src/lib/animation/property-registry.ts` - -```typescript -"background.paddingX": { - valueKind: "number", // "number" | "color" | "discrete" - defaultInterpolation: "linear", - numericRange: { min: 0 }, // optional, only for number properties - supportsElement: ({ element }) => element.type === "text", - getValue: ({ element }) => - element.type === "text" - ? (element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX) - : null, - setValue: ({ element, value }) => - element.type === "text" - ? { ...element, background: { ...element.background, paddingX: value as number } } - : element, -}, -``` - -**Notes:** -- `getValue` must return the effective value including any defaults — this is what gets recorded when a keyframe is added. -- `setValue` receives `AnimationValue` (`number | string | boolean`). Cast to the correct type since `coerceAnimationValueForProperty` already validated it upstream. -- For color properties, use `valueKind: "color"` and cast `value as string`. - -### 3. Add a resolve function — `src/lib/animation/resolve.ts` - -For **numbers**, use the existing generic `resolveNumberAtTime`: - -```typescript -import { resolveNumberAtTime } from "@/lib/animation"; - -const resolvedPaddingX = resolveNumberAtTime({ - baseValue: element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX, - animations: element.animations, - propertyPath: "background.paddingX", - localTime, -}); -``` - -For **colors**, use `resolveColorAtTime`: - -```typescript -const resolvedColor = resolveColorAtTime({ - baseColor: element.color, - animations: element.animations, - propertyPath: "color", - localTime, -}); -``` - -If neither fits (new value kind), add a dedicated resolve function following the same pattern as `resolveOpacityAtTime` and export it from `src/lib/animation/index.ts`. - -### 4. Wire the renderer - -In the relevant node (`src/services/renderer/nodes/`), call the resolve function before drawing: - -```typescript -const resolvedPaddingX = resolveNumberAtTime({ - baseValue: this.params.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX, - animations: this.params.animations, - propertyPath: "background.paddingX", - localTime, -}); -``` - -Use the resolved value (not `this.params.*`) anywhere that value affects rendering. - -### 5. Wire the UI - -In the properties panel, replace `usePropertyDraft` with the appropriate keyframe hook and add a `KeyframeToggle` to the field. - -**For number fields:** - -```typescript -const { localTime, isPlayheadWithinElementRange } = useElementPlayhead({ - startTime: element.startTime, - duration: element.duration, -}); - -const resolvedPaddingX = resolveNumberAtTime({ - baseValue: element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX, - animations: element.animations, - propertyPath: "background.paddingX", - localTime, -}); - -const paddingX = useKeyframedNumberProperty({ - trackId, - elementId: element.id, - animations: element.animations, - propertyPath: "background.paddingX", - localTime, - isPlayheadWithinElementRange, - displayValue: Math.round(resolvedPaddingX).toString(), - parse: (input) => { - const parsed = parseFloat(input); - return Number.isNaN(parsed) ? null : Math.max(0, Math.round(parsed)); - }, - valueAtPlayhead: resolvedPaddingX, - buildBaseUpdates: ({ value }) => ({ - background: { ...element.background, paddingX: value }, - }), -}); -``` - -In JSX: - -```tsx -<SectionField - label="Width" - beforeLabel={ - <KeyframeToggle - isActive={paddingX.isKeyframedAtTime} - isDisabled={!isPlayheadWithinElementRange} - title="Toggle background width keyframe" - onToggle={paddingX.toggleKeyframe} - /> - } -> - <NumberField - value={paddingX.displayValue} - onFocus={paddingX.onFocus} - onChange={paddingX.onChange} - onBlur={paddingX.onBlur} - onScrub={paddingX.scrubTo} - onScrubEnd={paddingX.commitScrub} - onReset={() => paddingX.commitValue({ value: DEFAULT_TEXT_BACKGROUND.paddingX })} - isDefault={isPropertyAtDefault({ - hasAnimatedKeyframes: paddingX.hasAnimatedKeyframes, - isPlayheadWithinElementRange, - resolvedValue: resolvedPaddingX, - staticValue: element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX, - defaultValue: DEFAULT_TEXT_BACKGROUND.paddingX, - })} - /> -</SectionField> -``` - -**For color fields**, use `useKeyframedColorProperty` instead. It returns `{ onChange, onChangeEnd, toggleKeyframe, isKeyframedAtTime }` — wire `onChange({ color })` and `onChangeEnd` directly to the `ColorPicker`. - ---- - -## Checklist - -- [ ] Path added to `ANIMATION_PROPERTY_PATHS` -- [ ] Registry entry added with correct `valueKind`, `supportsElement`, `getValue`, `setValue` -- [ ] Resolve call added in the renderer node -- [ ] UI field uses `useKeyframedNumberProperty` or `useKeyframedColorProperty` (not `usePropertyDraft`) -- [ ] `KeyframeToggle` added to the `SectionField` -- [ ] `onReset` calls `commitValue` (not `editor.timeline.updateElements` directly) +# Keyframe System
+
+Keyframes allow element properties to change over time. The system is split into three layers: the **data model** (how keyframes are stored), the **registry** (which properties support keyframes and how to read/write them), and the **UI** (hooks and components that wire it all together).
+
+## How It Works
+
+### Data model
+
+Every `BaseTimelineElement` has an optional `animations?: ElementAnimations` field:
+
+```typescript
+interface ElementAnimations {
+ channels: Record<string, AnimationChannel | undefined>;
+}
+```
+
+A channel is a typed bucket of keyframes keyed by property path (e.g. `"opacity"`, `"background.color"`). Three channel types exist: `NumberAnimationChannel`, `ColorAnimationChannel`, and `DiscreteAnimationChannel`.
+
+### Registry
+
+`src/lib/animation/property-registry.ts` defines which property paths are animatable and how to read/write their values on an element. `src/types/animation.ts` holds the canonical list of valid paths in `ANIMATION_PROPERTY_PATHS`.
+
+### Resolver
+
+`src/lib/animation/resolve.ts` provides functions that return the effective value of a property at a given local time — falling back to the element's static value when no keyframes exist.
+
+### Renderer
+
+Nodes in `src/services/renderer/` call the resolve functions before drawing so that animated properties interpolate correctly during export and preview.
+
+### UI
+
+Two hooks in `src/components/editor/panels/properties/hooks/` handle the keyframe-aware field logic:
+
+- `useKeyframedNumberProperty` — for numeric fields (opacity, position, scale, etc.)
+- `useKeyframedColorProperty` — for color pickers
+
+Both hooks handle the toggle/add/remove keyframe flow and automatically switch between writing to the static property and writing to the animation channel depending on whether keyframes are active.
+
+---
+
+## Adding a New Animatable Property
+
+Using `"background.paddingX"` as an example.
+
+### 1. Register the path — `src/types/animation.ts`
+
+```typescript
+export const ANIMATION_PROPERTY_PATHS = [
+ // ...existing paths
+ "background.paddingX",
+] as const;
+```
+
+### 2. Add a registry entry — `src/lib/animation/property-registry.ts`
+
+```typescript
+"background.paddingX": {
+ valueKind: "number", // "number" | "color" | "discrete"
+ defaultInterpolation: "linear",
+ numericRange: { min: 0 }, // optional, only for number properties
+ supportsElement: ({ element }) => element.type === "text",
+ getValue: ({ element }) =>
+ element.type === "text"
+ ? (element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX)
+ : null,
+ setValue: ({ element, value }) =>
+ element.type === "text"
+ ? { ...element, background: { ...element.background, paddingX: value as number } }
+ : element,
+},
+```
+
+**Notes:**
+- `getValue` must return the effective value including any defaults — this is what gets recorded when a keyframe is added.
+- `setValue` receives `AnimationValue` (`number | string | boolean`). Cast to the correct type since `coerceAnimationValueForProperty` already validated it upstream.
+- For color properties, use `valueKind: "color"` and cast `value as string`.
+
+### 3. Add a resolve function — `src/lib/animation/resolve.ts`
+
+For **numbers**, use the existing generic `resolveNumberAtTime`:
+
+```typescript
+import { resolveNumberAtTime } from "@/lib/animation";
+
+const resolvedPaddingX = resolveNumberAtTime({
+ baseValue: element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX,
+ animations: element.animations,
+ propertyPath: "background.paddingX",
+ localTime,
+});
+```
+
+For **colors**, use `resolveColorAtTime`:
+
+```typescript
+const resolvedColor = resolveColorAtTime({
+ baseColor: element.color,
+ animations: element.animations,
+ propertyPath: "color",
+ localTime,
+});
+```
+
+If neither fits (new value kind), add a dedicated resolve function following the same pattern as `resolveOpacityAtTime` and export it from `src/lib/animation/index.ts`.
+
+### 4. Wire the renderer
+
+In the relevant node (`src/services/renderer/nodes/`), call the resolve function before drawing:
+
+```typescript
+const resolvedPaddingX = resolveNumberAtTime({
+ baseValue: this.params.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX,
+ animations: this.params.animations,
+ propertyPath: "background.paddingX",
+ localTime,
+});
+```
+
+Use the resolved value (not `this.params.*`) anywhere that value affects rendering.
+
+### 5. Wire the UI
+
+In the properties panel, replace `usePropertyDraft` with the appropriate keyframe hook and add a `KeyframeToggle` to the field.
+
+**For number fields:**
+
+```typescript
+const { localTime, isPlayheadWithinElementRange } = useElementPlayhead({
+ startTime: element.startTime,
+ duration: element.duration,
+});
+
+const resolvedPaddingX = resolveNumberAtTime({
+ baseValue: element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX,
+ animations: element.animations,
+ propertyPath: "background.paddingX",
+ localTime,
+});
+
+const paddingX = useKeyframedNumberProperty({
+ trackId,
+ elementId: element.id,
+ animations: element.animations,
+ propertyPath: "background.paddingX",
+ localTime,
+ isPlayheadWithinElementRange,
+ displayValue: Math.round(resolvedPaddingX).toString(),
+ parse: (input) => {
+ const parsed = parseFloat(input);
+ return Number.isNaN(parsed) ? null : Math.max(0, Math.round(parsed));
+ },
+ valueAtPlayhead: resolvedPaddingX,
+ buildBaseUpdates: ({ value }) => ({
+ background: { ...element.background, paddingX: value },
+ }),
+});
+```
+
+In JSX:
+
+```tsx
+<SectionField
+ label="Width"
+ beforeLabel={
+ <KeyframeToggle
+ isActive={paddingX.isKeyframedAtTime}
+ isDisabled={!isPlayheadWithinElementRange}
+ title="Toggle background width keyframe"
+ onToggle={paddingX.toggleKeyframe}
+ />
+ }
+>
+ <NumberField
+ value={paddingX.displayValue}
+ onFocus={paddingX.onFocus}
+ onChange={paddingX.onChange}
+ onBlur={paddingX.onBlur}
+ onScrub={paddingX.scrubTo}
+ onScrubEnd={paddingX.commitScrub}
+ onReset={() => paddingX.commitValue({ value: DEFAULT_TEXT_BACKGROUND.paddingX })}
+ isDefault={isPropertyAtDefault({
+ hasAnimatedKeyframes: paddingX.hasAnimatedKeyframes,
+ isPlayheadWithinElementRange,
+ resolvedValue: resolvedPaddingX,
+ staticValue: element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX,
+ defaultValue: DEFAULT_TEXT_BACKGROUND.paddingX,
+ })}
+ />
+</SectionField>
+```
+
+**For color fields**, use `useKeyframedColorProperty` instead. It returns `{ onChange, onChangeEnd, toggleKeyframe, isKeyframedAtTime }` — wire `onChange({ color })` and `onChangeEnd` directly to the `ColorPicker`.
+
+---
+
+## Checklist
+
+- [ ] Path added to `ANIMATION_PROPERTY_PATHS`
+- [ ] Registry entry added with correct `valueKind`, `supportsElement`, `getValue`, `setValue`
+- [ ] Resolve call added in the renderer node
+- [ ] UI field uses `useKeyframedNumberProperty` or `useKeyframedColorProperty` (not `usePropertyDraft`)
+- [ ] `KeyframeToggle` added to the `SectionField`
+- [ ] `onReset` calls `commitValue` (not `editor.timeline.updateElements` directly)
|
