@efxlab/motion-canvas-responsive 4.0.0

package/src/context/ResponsiveContext.test.ts

@@ -0,0 +1,112 @@
+import {describe, expect, it} from 'vitest';
+import {
+  detectRatioClass,
+  endResponsive,
+  getGlobalRatio,
+  parseRatioString,
+  setGlobalRatio,
+  startResponsive,
+  useResponsiveContext,
+} from '../context/ResponsiveContext';
+import type {RatioClass} from '../types';
+
+describe('ResponsiveContext', () => {
+  describe('detectRatioClass', () => {
+    it('should detect landscape ratios (ar > 1)', () => {
+      expect(detectRatioClass(16 / 9)).toBe('landscape');
+      expect(detectRatioClass(4 / 3)).toBe('landscape');
+      expect(detectRatioClass(2)).toBe('landscape');
+    });
+
+    it('should detect portrait ratios (ar < 1)', () => {
+      expect(detectRatioClass(9 / 16)).toBe('portrait');
+      expect(detectRatioClass(3 / 4)).toBe('portrait');
+      expect(detectRatioClass(0.5)).toBe('portrait');
+    });
+
+    it('should detect square ratios (ar === 1)', () => {
+      expect(detectRatioClass(1)).toBe('square');
+    });
+
+    it('should detect ultrawide ratios (ar > 2)', () => {
+      expect(detectRatioClass(21 / 9)).toBe('ultrawide');
+      expect(detectRatioClass(3)).toBe('ultrawide');
+    });
+  });
+
+  describe('parseRatioString', () => {
+    it('should parse colon-separated ratios', () => {
+      expect(parseRatioString('16:9')).toBe(16 / 9);
+      expect(parseRatioString('9:16')).toBe(9 / 16);
+      expect(parseRatioString('4:3')).toBe(4 / 3);
+    });
+
+    it('should parse x-separated ratios', () => {
+      expect(parseRatioString('16x9')).toBe(16 / 9);
+      expect(parseRatioString('9x16')).toBe(9 / 16);
+    });
+
+    it('should default to 16:9 for invalid input', () => {
+      expect(parseRatioString('invalid')).toBe(16 / 9);
+    });
+  });
+
+  describe('global state', () => {
+    it('should set and get global ratio', () => {
+      setGlobalRatio('9x16', 1080, 1920);
+      const state = getGlobalRatio();
+
+      expect(state.ratio).toBe('9x16');
+      expect(state.width).toBe(1080);
+      expect(state.height).toBe(1920);
+      expect(state.ratioClass).toBe('portrait');
+    });
+
+    it('should update ratio class when width/height changes', () => {
+      setGlobalRatio('16x9', 1920, 1080);
+      let state = getGlobalRatio();
+      expect(state.ratioClass).toBe('landscape');
+
+      setGlobalRatio('9x16', 1080, 1920);
+      state = getGlobalRatio();
+      expect(state.ratioClass).toBe('portrait');
+    });
+  });
+
+  describe('stack operations', () => {
+    it('should push and pop responsive state', () => {
+      const state = {
+        ratio: '16x9',
+        ratioClass: 'landscape' as RatioClass,
+        width: 1920,
+        height: 1080,
+      };
+
+      startResponsive(state);
+      const result = useResponsiveContext();
+      expect(result.ratio).toBe('16x9');
+
+      endResponsive(state);
+      const afterPop = useResponsiveContext();
+      expect(afterPop.ratio).toBe('9x16'); // falls back to global
+    });
+
+    it('should throw on mismatched endResponsive', () => {
+      const state1 = {
+        ratio: '16x9',
+        ratioClass: 'landscape' as RatioClass,
+        width: 1920,
+        height: 1080,
+      };
+      const state2 = {
+        ratio: '9x16',
+        ratioClass: 'portrait' as RatioClass,
+        width: 1080,
+        height: 1920,
+      };
+
+      startResponsive(state1);
+      expect(() => endResponsive(state2)).toThrow();
+    });
+  });
+});

package/src/context/ResponsiveContext.ts

@@ -0,0 +1,146 @@
+import type {Vector2} from '@efxlab/motion-canvas-core';
+import type {
+  RatioClass,
+  RatioId,
+  ResponsiveRatioConfig,
+  ResponsiveRatiosConfig,
+  ResponsiveState,
+} from '../types';
+
+const ResponsiveStack: ResponsiveState[] = [];
+
+// Custom ratio registry
+const CustomRatios: ResponsiveRatiosConfig = {};
+
+// Default built-in ratios
+const RATIO_16X9 = '16x9';
+const RATIO_9X16 = '9x16';
+const RATIO_4X3 = '4x3';
+const RATIO_1X1 = '1x1';
+
+const DefaultRatios: ResponsiveRatiosConfig = {
+  [RATIO_16X9]: {aspect: '16:9'},
+  [RATIO_9X16]: {aspect: '9:16'},
+  [RATIO_4X3]: {aspect: '4:3'},
+  [RATIO_1X1]: {aspect: '1:1'},
+  fullwindow: {aspect: 'auto'},
+};
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+let globalResponsiveState: ResponsiveState = {
+  ratio: '16x9',
+  ratioClass: 'landscape',
+  width: 1920,
+  height: 1080,
+};
+
+export function startResponsive(state: ResponsiveState) {
+  ResponsiveStack.push(state);
+}
+
+export function endResponsive(state: ResponsiveState) {
+  if (ResponsiveStack.pop() !== state) {
+    throw new Error('startResponsive/endResponsive called out of order.');
+  }
+}
+
+export function useResponsiveContext(): ResponsiveState {
+  const state = ResponsiveStack.at(-1);
+  if (!state) {
+    return globalResponsiveState;
+  }
+  return state;
+}
+
+export function getResponsiveState(): ResponsiveState | undefined {
+  return ResponsiveStack.at(-1) ?? globalResponsiveState;
+}
+
+export function setGlobalRatio(ratio: RatioId, width: number, height: number) {
+  const aspectRatio = width / height;
+  const ratioClass = detectRatioClass(aspectRatio);
+  globalResponsiveState = {ratio, ratioClass, width, height};
+}
+
+export function getGlobalRatio(): ResponsiveState {
+  return globalResponsiveState;
+}
+
+export function initResponsiveFromSize(size: Vector2, ratio: RatioId = '16x9') {
+  setGlobalRatio(ratio, size.x, size.y);
+}
+
+export function detectRatioClass(aspectRatio: number): RatioClass {
+  if (aspectRatio > 2) {
+    return 'ultrawide';
+  }
+  if (aspectRatio > 1) {
+    return 'landscape';
+  }
+  if (aspectRatio === 1) {
+    return 'square';
+  }
+  return 'portrait';
+}
+
+export function parseRatioString(ratio: string): number {
+  const [w, h] = ratio.split(':').map(Number);
+  if (w && h) {
+    return w / h;
+  }
+  const parts = ratio.split('x').map(Number);
+  if (parts.length === 2 && parts[0] && parts[1]) {
+    return parts[0] / parts[1];
+  }
+  return 16 / 9;
+}
+
+/**
+ * Register custom ratios for the responsive system.
+ * This allows templates to define custom aspect ratios beyond the defaults.
+ *
+ * @param ratios - Object mapping ratio IDs to their configuration
+ *
+ * @example
+ * ```typescript
+ * registerCustomRatios({
+ *   'cinema': { aspect: '21:9' },
+ *   'story': { aspect: '9:18' },
+ *   'portrait2': { aspect: '3:4' },
+ * });
+ * ```
+ */
+export function registerCustomRatios(ratios: ResponsiveRatiosConfig): void {
+  Object.assign(CustomRatios, ratios);
+}
+
+/**
+ * Get all registered custom ratios.
+ */
+export function getCustomRatios(): ResponsiveRatiosConfig {
+  return {...CustomRatios};
+}
+
+/**
+ * Get ratio configuration for a specific ratio ID.
+ * Checks custom ratios first, then falls back to defaults.
+ */
+export function getRatioConfig(
+  ratioId: string,
+): ResponsiveRatioConfig | undefined {
+  return CustomRatios[ratioId] ?? DefaultRatios[ratioId];
+}
+
+/**
+ * Get all available ratio configurations (custom + default).
+ */
+export function getAllRatioConfigs(): ResponsiveRatiosConfig {
+  return {...DefaultRatios, ...CustomRatios};
+}
+
+/**
+ * Clear all custom ratios.
+ */
+export function clearCustomRatios(): void {
+  Object.keys(CustomRatios).forEach(key => delete CustomRatios[key]);
+}

package/src/helpers/color.ts

@@ -0,0 +1,21 @@
+export interface ColorHelpers {
+  tint: (from: string, to: string) => {from: string; to: string};
+  highlight: (color: string) => {color: string; duration: number};
+  gradient: (colors: string[]) => {colors: string[]; duration: number};
+}
+
+export interface StrokeHelpers {
+  draw: (duration: number) => {duration: number};
+  dash: (length: number, gap: number) => {length: number; gap: number};
+}
+
+export const color: ColorHelpers = {
+  tint: (from: string, to: string) => ({from, to}),
+  highlight: (color: string) => ({color, duration: 0.3}),
+  gradient: (colors: string[]) => ({colors, duration: colors.length * 0.5}),
+};
+
+export const stroke: StrokeHelpers = {
+  draw: (duration: number) => ({duration}),
+  dash: (length: number, gap: number) => ({length, gap}),
+};

package/src/helpers/filter.ts

@@ -0,0 +1,18 @@
+export interface FilterHelpers {
+  blur: (
+    from: number,
+    to: number,
+  ) => {from: number; to: number; duration: number};
+  brightness: (value: number) => {value: number; duration: number};
+  contrast: (value: number) => {value: number; duration: number};
+  saturate: (value: number) => {value: number; duration: number};
+  grayscale: (value: number) => {value: number; duration: number};
+}
+
+export const filter: FilterHelpers = {
+  blur: (from: number, to: number) => ({from, to, duration: 1}),
+  brightness: (value: number) => ({value, duration: 0.5}),
+  contrast: (value: number) => ({value, duration: 0.5}),
+  saturate: (value: number) => ({value, duration: 0.5}),
+  grayscale: (value: number) => ({value, duration: 0.5}),
+};

package/src/helpers/helpers.test.ts

@@ -0,0 +1,252 @@
+import {describe, expect, it} from 'vitest';
+import {color, stroke} from './color';
+import {filter} from './filter';
+import {path} from './path';
+import {rotate} from './rotation';
+import {scale, transform} from './scale';
+import {opacity} from './visibility';
+
+describe('Rotation Helpers', () => {
+  describe('rotate.spin', () => {
+    it('should convert turns to degrees', () => {
+      expect(rotate.spin(1)).toBe(360);
+      expect(rotate.spin(2)).toBe(720);
+      expect(rotate.spin(0.5)).toBe(180);
+    });
+  });
+
+  describe('rotate.spinCW', () => {
+    it('should return positive degrees', () => {
+      expect(rotate.spinCW(1)).toBe(360);
+    });
+  });
+
+  describe('rotate.spinCCW', () => {
+    it('should return negative degrees', () => {
+      expect(rotate.spinCCW(1)).toBe(-360);
+    });
+  });
+
+  describe('rotate.pivot', () => {
+    it('should return center pivot', () => {
+      expect(rotate.pivot.center()).toEqual({x: 0, y: 0});
+    });
+
+    it('should return corner pivots', () => {
+      expect(rotate.pivot.topLeft()).toEqual({x: -0.5, y: -0.5});
+      expect(rotate.pivot.topRight()).toEqual({x: 0.5, y: -0.5});
+      expect(rotate.pivot.bottomLeft()).toEqual({x: -0.5, y: 0.5});
+      expect(rotate.pivot.bottomRight()).toEqual({x: 0.5, y: 0.5});
+    });
+
+    it('should return custom pivot', () => {
+      expect(rotate.pivot.custom(100, 50)).toEqual({x: 100, y: 50});
+    });
+  });
+});
+
+describe('Scale Helpers', () => {
+  describe('scale.from', () => {
+    it('should create from-to config', () => {
+      const result = scale.from(0);
+      expect(result.from).toBe(0);
+      expect(result.to).toBe(1);
+    });
+  });
+
+  describe('scale.to', () => {
+    it('should create from-to config', () => {
+      const result = scale.to(2);
+      expect(result.from).toBe(1);
+      expect(result.to).toBe(2);
+    });
+  });
+
+  describe('scale.pop', () => {
+    it('should create bounce keyframes', () => {
+      const result = scale.pop();
+      expect(result.from).toBe(1);
+      expect(result.to).toBe(1);
+      expect(result.keyframes).toHaveLength(3);
+      expect(result.keyframes[1].scale).toBe(1.1);
+    });
+  });
+
+  describe('scale.pulse', () => {
+    it('should create pulse range', () => {
+      const result = scale.pulse(5);
+      expect(result.from).toBe(0.5);
+      expect(result.to).toBe(1.5);
+    });
+  });
+
+  describe('transform', () => {
+    it('should return transform values', () => {
+      expect(transform.scaleX(2)).toBe(2);
+      expect(transform.scaleY(2)).toBe(2);
+      expect(transform.skewX(30)).toBe(30);
+      expect(transform.skewY(30)).toBe(30);
+    });
+  });
+});
+
+describe('Visibility Helpers', () => {
+  describe('opacity.fadeIn', () => {
+    it('should create fade in config', () => {
+      const result = opacity.fadeIn(1);
+      expect(result.from).toBe(0);
+      expect(result.to).toBe(1);
+      expect(result.duration).toBe(1);
+    });
+  });
+
+  describe('opacity.fadeOut', () => {
+    it('should create fade out config', () => {
+      const result = opacity.fadeOut(1);
+      expect(result.from).toBe(1);
+      expect(result.to).toBe(0);
+    });
+  });
+
+  describe('opacity.flash', () => {
+    it('should create flash config', () => {
+      const result = opacity.flash(3);
+      expect(result.times).toBe(3);
+      expect(result.duration).toBeCloseTo(0.6);
+    });
+  });
+
+  describe('opacity.blink', () => {
+    it('should create blink config', () => {
+      const result = opacity.blink(0.5);
+      expect(result.interval).toBe(0.5);
+    });
+  });
+});
+
+describe('Color Helpers', () => {
+  describe('color.tint', () => {
+    it('should create tint config', () => {
+      const result = color.tint('red', 'blue');
+      expect(result.from).toBe('red');
+      expect(result.to).toBe('blue');
+    });
+  });
+
+  describe('color.highlight', () => {
+    it('should create highlight config', () => {
+      const result = color.highlight('yellow');
+      expect(result.color).toBe('yellow');
+      expect(result.duration).toBe(0.3);
+    });
+  });
+
+  describe('color.gradient', () => {
+    it('should create gradient config', () => {
+      const result = color.gradient(['red', 'green', 'blue']);
+      expect(result.colors).toEqual(['red', 'green', 'blue']);
+      expect(result.duration).toBe(1.5);
+    });
+  });
+
+  describe('stroke.draw', () => {
+    it('should create draw config', () => {
+      const result = stroke.draw(2);
+      expect(result.duration).toBe(2);
+    });
+  });
+
+  describe('stroke.dash', () => {
+    it('should create dash config', () => {
+      const result = stroke.dash(10, 5);
+      expect(result.length).toBe(10);
+      expect(result.gap).toBe(5);
+    });
+  });
+});
+
+describe('Path Helpers', () => {
+  describe('path.arc', () => {
+    it('should create arc config', () => {
+      const result = path.arc(0, 180, 100);
+      expect(result.startAngle).toBe(0);
+      expect(result.endAngle).toBe(180);
+      expect(result.radius).toBe(100);
+    });
+  });
+
+  describe('path.orbit', () => {
+    it('should create orbit config', () => {
+      const result = path.orbit(0, 0, 200);
+      expect(result.centerX).toBe(0);
+      expect(result.centerY).toBe(0);
+      expect(result.radius).toBe(200);
+      expect(result.duration).toBe(2);
+    });
+  });
+
+  describe('path.wave', () => {
+    it('should create wave config', () => {
+      const result = path.wave(50, 2);
+      expect(result.amplitude).toBe(50);
+      expect(result.frequency).toBe(2);
+      expect(result.duration).toBe(1);
+    });
+  });
+
+  describe('path.shake', () => {
+    it('should create shake config', () => {
+      const result = path.shake(10);
+      expect(result.intensity).toBe(10);
+      expect(result.duration).toBe(0.5);
+    });
+  });
+
+  describe('path.wobble', () => {
+    it('should create wobble config', () => {
+      const result = path.wobble(5);
+      expect(result.intensity).toBe(5);
+      expect(result.duration).toBe(1);
+    });
+  });
+});
+
+describe('Filter Helpers', () => {
+  describe('filter.blur', () => {
+    it('should create blur config', () => {
+      const result = filter.blur(0, 10);
+      expect(result.from).toBe(0);
+      expect(result.to).toBe(10);
+      expect(result.duration).toBe(1);
+    });
+  });
+
+  describe('filter.brightness', () => {
+    it('should create brightness config', () => {
+      const result = filter.brightness(1.5);
+      expect(result.value).toBe(1.5);
+      expect(result.duration).toBe(0.5);
+    });
+  });
+
+  describe('filter.contrast', () => {
+    it('should create contrast config', () => {
+      const result = filter.contrast(1.2);
+      expect(result.value).toBe(1.2);
+    });
+  });
+
+  describe('filter.saturate', () => {
+    it('should create saturate config', () => {
+      const result = filter.saturate(2);
+      expect(result.value).toBe(2);
+    });
+  });
+
+  describe('filter.grayscale', () => {
+    it('should create grayscale config', () => {
+      const result = filter.grayscale(1);
+      expect(result.value).toBe(1);
+    });
+  });
+});

package/src/helpers/index.ts

@@ -0,0 +1,7 @@
+export * from './color';
+export * from './filter';
+export * from './path';
+export * from './position';
+export * from './rotation';
+export * from './scale';
+export * from './visibility';

package/src/helpers/path.ts

@@ -0,0 +1,49 @@
+import {Vector2} from '@efxlab/motion-canvas-core';
+
+export interface PathHelpers {
+  arc: (
+    startAngle: number,
+    endAngle: number,
+    radius: number,
+  ) => {startAngle: number; endAngle: number; radius: number};
+  bezier: (controlPoints: Vector2[]) => {controlPoints: Vector2[]};
+  orbit: (
+    centerX: number,
+    centerY: number,
+    radius: number,
+  ) => {centerX: number; centerY: number; radius: number; duration: number};
+  wave: (
+    amplitude: number,
+    frequency: number,
+  ) => {amplitude: number; frequency: number; duration: number};
+  shake: (intensity: number) => {intensity: number; duration: number};
+  wobble: (intensity: number) => {intensity: number; duration: number};
+}
+
+export const path: PathHelpers = {
+  arc: (startAngle: number, endAngle: number, radius: number) => ({
+    startAngle,
+    endAngle,
+    radius,
+  }),
+  bezier: (controlPoints: Vector2[]) => ({controlPoints}),
+  orbit: (centerX: number, centerY: number, radius: number) => ({
+    centerX,
+    centerY,
+    radius,
+    duration: 2,
+  }),
+  wave: (amplitude: number, frequency: number) => ({
+    amplitude,
+    frequency,
+    duration: 1,
+  }),
+  shake: (intensity: number) => ({
+    intensity,
+    duration: 0.5,
+  }),
+  wobble: (intensity: number) => ({
+    intensity,
+    duration: 1,
+  }),
+};

package/src/helpers/position.ts

@@ -0,0 +1,75 @@
+import {useResponsiveContext} from '../context/ResponsiveContext';
+
+export interface PositionHelpers {
+  offLeft: (margin?: number) => number;
+  offRight: (margin?: number) => number;
+  offTop: (margin?: number) => number;
+  offBottom: (margin?: number) => number;
+  fromLeft: (margin?: number) => number;
+  fromRight: (margin?: number) => number;
+  fromTop: (margin?: number) => number;
+  fromBottom: (margin?: number) => number;
+}
+
+export function createPositionHelpers(
+  elementWidth: number = 0,
+  elementHeight: number = 0,
+): PositionHelpers {
+  const state = useResponsiveContext();
+  const {width, height} = state;
+  const hw = width / 2;
+  const hh = height / 2;
+  const elHalfW = elementWidth / 2;
+  const elHalfH = elementHeight / 2;
+
+  return {
+    offLeft: (margin = 0) => -hw - elHalfW - margin,
+    offRight: (margin = 0) => hw + elHalfW + margin,
+    offTop: (margin = 0) => -hh - elHalfH - margin,
+    offBottom: (margin = 0) => hh + elHalfH + margin,
+    fromLeft: (margin = 0) => -hw + elHalfW + margin,
+    fromRight: (margin = 0) => hw - elHalfW - margin,
+    fromTop: (margin = 0) => -hh + elHalfH + margin,
+    fromBottom: (margin = 0) => hh - elHalfH - margin,
+  };
+}
+
+export const offLeft = (margin = 0, elementWidth = 0): number => {
+  const state = useResponsiveContext();
+  return -state.width / 2 - elementWidth / 2 - margin;
+};
+
+export const offRight = (margin = 0, elementWidth = 0): number => {
+  const state = useResponsiveContext();
+  return state.width / 2 + elementWidth / 2 + margin;
+};
+
+export const offTop = (margin = 0, elementHeight = 0): number => {
+  const state = useResponsiveContext();
+  return -state.height / 2 - elementHeight / 2 - margin;
+};
+
+export const offBottom = (margin = 0, elementHeight = 0): number => {
+  const state = useResponsiveContext();
+  return state.height / 2 + elementHeight / 2 + margin;
+};
+
+export const fromLeft = (margin = 0, elementWidth = 0): number => {
+  const state = useResponsiveContext();
+  return -state.width / 2 + elementWidth / 2 + margin;
+};
+
+export const fromRight = (margin = 0, elementWidth = 0): number => {
+  const state = useResponsiveContext();
+  return state.width / 2 - elementWidth / 2 - margin;
+};
+
+export const fromTop = (margin = 0, elementHeight = 0): number => {
+  const state = useResponsiveContext();
+  return -state.height / 2 + elementHeight / 2 + margin;
+};
+
+export const fromBottom = (margin = 0, elementHeight = 0): number => {
+  const state = useResponsiveContext();
+  return state.height / 2 - elementHeight / 2 - margin;
+};