@efxlab/motion-canvas-responsive 4.0.0

package/src/helpers/rotation.ts

@@ -0,0 +1,27 @@
+export interface RotationHelpers {
+  spin: (turns: number) => number;
+  spinCW: (turns: number) => number;
+  spinCCW: (turns: number) => number;
+  pivot: {
+    center: () => {x: number; y: number};
+    topLeft: () => {x: number; y: number};
+    topRight: () => {x: number; y: number};
+    bottomLeft: () => {x: number; y: number};
+    bottomRight: () => {x: number; y: number};
+    custom: (x: number, y: number) => {x: number; y: number};
+  };
+}
+
+export const rotate: RotationHelpers = {
+  spin: (turns: number) => turns * 360,
+  spinCW: (turns: number) => turns * 360,
+  spinCCW: (turns: number) => -turns * 360,
+  pivot: {
+    center: () => ({x: 0, y: 0}),
+    topLeft: () => ({x: -0.5, y: -0.5}),
+    topRight: () => ({x: 0.5, y: -0.5}),
+    bottomLeft: () => ({x: -0.5, y: 0.5}),
+    bottomRight: () => ({x: 0.5, y: 0.5}),
+    custom: (x: number, y: number) => ({x, y}),
+  },
+};

package/src/helpers/scale.ts

@@ -0,0 +1,42 @@
+export interface ScaleHelpers {
+  from: (value: number) => {from: number; to: number};
+  to: (value: number) => {from: number; to: number};
+  pop: () => {
+    from: number;
+    to: number;
+    keyframes: Array<{progress: number; scale: number}>;
+  };
+  pulse: (intensity: number) => {from: number; to: number};
+}
+
+export interface TransformHelpers {
+  scaleX: (value: number) => number;
+  scaleY: (value: number) => number;
+  skewX: (degrees: number) => number;
+  skewY: (degrees: number) => number;
+}
+
+export const scale: ScaleHelpers = {
+  from: (value: number) => ({from: value, to: 1}),
+  to: (value: number) => ({from: 1, to: value}),
+  pop: () => ({
+    from: 1,
+    to: 1,
+    keyframes: [
+      {progress: 0, scale: 1},
+      {progress: 0.5, scale: 1.1},
+      {progress: 1, scale: 1},
+    ],
+  }),
+  pulse: (intensity: number) => ({
+    from: 1 - intensity * 0.1,
+    to: 1 + intensity * 0.1,
+  }),
+};
+
+export const transform: TransformHelpers = {
+  scaleX: (value: number) => value,
+  scaleY: (value: number) => value,
+  skewX: (degrees: number) => degrees,
+  skewY: (degrees: number) => degrees,
+};

package/src/helpers/visibility.ts

@@ -0,0 +1,13 @@
+export interface VisibilityHelpers {
+  fadeIn: (duration: number) => {from: number; to: number; duration: number};
+  fadeOut: (duration: number) => {from: number; to: number; duration: number};
+  flash: (times: number) => {times: number; duration: number};
+  blink: (interval: number) => {interval: number};
+}
+
+export const opacity: VisibilityHelpers = {
+  fadeIn: (duration: number) => ({from: 0, to: 1, duration}),
+  fadeOut: (duration: number) => ({from: 1, to: 0, duration}),
+  flash: (times: number) => ({times, duration: times * 0.2}),
+  blink: (interval: number) => ({interval}),
+};

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export * from './useRatioEffect';
+export * from './useRatioElement';
+export * from './useResponsive';
+export * from './useResponsiveAnimation';

package/src/hooks/useRatio.ts

@@ -0,0 +1 @@
+export {useRatio} from '../layout/ResponsiveLayout';

package/src/hooks/useRatioEffect.ts

@@ -0,0 +1,42 @@
+import {useEffect} from 'react';
+import {
+  detectRatioClass,
+  useResponsiveContext,
+} from '../context/ResponsiveContext';
+import type {RatioClass, RatioId} from '../types';
+
+type RatioCondition =
+  | RatioId
+  | RatioClass
+  | 'portrait'
+  | 'landscape'
+  | 'square'
+  | 'ultrawide';
+
+export function useRatioEffect(
+  condition: RatioCondition | RatioCondition[],
+  callback: () => void | (() => void),
+  deps: any[] = [],
+) {
+  const state = useResponsiveContext();
+  const aspectRatio = state.width / state.height;
+  const ratioClass = detectRatioClass(aspectRatio);
+
+  const conditions = Array.isArray(condition) ? condition : [condition];
+
+  const matches = conditions.some(cond => {
+    if (cond === state.ratio) return true;
+    if (cond === ratioClass) return true;
+    if (cond === 'portrait' && ratioClass === 'portrait') return true;
+    if (cond === 'landscape' && ratioClass === 'landscape') return true;
+    if (cond === 'square' && ratioClass === 'square') return true;
+    if (cond === 'ultrawide' && ratioClass === 'ultrawide') return true;
+    return false;
+  });
+
+  useEffect(() => {
+    if (matches) {
+      return callback();
+    }
+  }, [matches, ...deps]);
+}

package/src/hooks/useRatioElement.ts

@@ -0,0 +1,61 @@
+import React, {useMemo} from 'react';
+import {
+  detectRatioClass,
+  useResponsiveContext,
+} from '../context/ResponsiveContext';
+import type {RatioClass, RatioId} from '../types';
+
+type RatioCondition =
+  | RatioId
+  | RatioClass
+  | 'portrait'
+  | 'landscape'
+  | 'square'
+  | 'ultrawide';
+
+export interface UseRatioElementOptions {
+  only?: RatioCondition[];
+  except?: RatioCondition[];
+  element: () => React.ReactElement | null;
+}
+
+export function useRatioElement(
+  options: UseRatioElementOptions,
+): React.ReactElement | null {
+  const state = useResponsiveContext();
+  const aspectRatio = state.width / state.height;
+  const ratioClass = detectRatioClass(aspectRatio);
+
+  return useMemo(() => {
+    const conditions = options.only ?? [];
+    const exceptions = options.except ?? [];
+
+    const matchesConditions =
+      conditions.length === 0 ||
+      conditions.some(cond => {
+        if (cond === state.ratio) return true;
+        if (cond === ratioClass) return true;
+        if (cond === 'portrait' && ratioClass === 'portrait') return true;
+        if (cond === 'landscape' && ratioClass === 'landscape') return true;
+        if (cond === 'square' && ratioClass === 'square') return true;
+        if (cond === 'ultrawide' && ratioClass === 'ultrawide') return true;
+        return false;
+      });
+
+    const matchesExceptions = exceptions.some(cond => {
+      if (cond === state.ratio) return true;
+      if (cond === ratioClass) return true;
+      if (cond === 'portrait' && ratioClass === 'portrait') return true;
+      if (cond === 'landscape' && ratioClass === 'landscape') return true;
+      if (cond === 'square' && ratioClass === 'square') return true;
+      if (cond === 'ultrawide' && ratioClass === 'ultrawide') return true;
+      return false;
+    });
+
+    if (matchesConditions && !matchesExceptions) {
+      return options.element();
+    }
+
+    return null;
+  }, [state.ratio, ratioClass, options]);
+}

package/src/hooks/useResponsive.ts

@@ -0,0 +1,36 @@
+import {
+  detectRatioClass,
+  useResponsiveContext,
+} from '../context/ResponsiveContext';
+import type {ResponsiveConfig} from '../types';
+
+export function useResponsive<T>(config: ResponsiveConfig<T>): T {
+  const state = useResponsiveContext();
+  const aspectRatio = state.width / state.height;
+  const ratioClass = detectRatioClass(aspectRatio);
+
+  let result: any = {...config.base};
+
+  const classOverrides: Partial<T>[] = [];
+
+  if (config.portrait && ratioClass === 'portrait') {
+    classOverrides.push(config.portrait);
+  } else if (config.landscape && ratioClass === 'landscape') {
+    classOverrides.push(config.landscape);
+  } else if (config.square && ratioClass === 'square') {
+    classOverrides.push(config.square);
+  } else if (config.ultrawide && ratioClass === 'ultrawide') {
+    classOverrides.push(config.ultrawide);
+  }
+
+  const specificOverride = config[state.ratio];
+  if (specificOverride) {
+    classOverrides.push(specificOverride);
+  }
+
+  for (const override of classOverrides) {
+    result = {...result, ...override};
+  }
+
+  return result as T;
+}

package/src/hooks/useResponsiveAnimation.ts

@@ -0,0 +1,8 @@
+import type {AnimationConfig, ResponsiveConfig} from '../types';
+import {useResponsive} from './useResponsive';
+
+export function useResponsiveAnimation(
+  config: ResponsiveConfig<AnimationConfig>,
+): AnimationConfig {
+  return useResponsive(config);
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from './components';
+export * from './context/ResponsiveContext';
+export * from './helpers';
+export * from './hooks/useRatio';
+export * from './hooks/useRatioEffect';
+export * from './hooks/useRatioElement';
+export * from './hooks/useResponsive';
+export * from './hooks/useResponsiveAnimation';
+export * from './layout/ResponsiveLayout';
+export * from './scene';
+export * from './types';
+
+declare module '@efxlab/motion-canvas-core' {
+  interface Scene {
+    setResponsiveSetup(callback: (size: {x: number; y: number}) => void): void;
+  }
+}

package/src/layout/ResponsiveLayout.test.ts

@@ -0,0 +1,82 @@
+import {describe, expect, it} from 'vitest';
+import {createResponsiveLayout} from '../layout/ResponsiveLayout';
+
+describe('ResponsiveLayout', () => {
+  describe('createResponsiveLayout', () => {
+    it('should create layout for 16:9 landscape', () => {
+      const layout = createResponsiveLayout(1920, 1080, '16x9');
+
+      expect(layout.ratio).toBe('16x9');
+      expect(layout.ratioClass).toBe('landscape');
+      expect(layout.width).toBe(1920);
+      expect(layout.height).toBe(1080);
+      expect(layout.ar).toBeCloseTo(1.778, 2);
+      expect(layout.isLandscape).toBe(true);
+      expect(layout.isPortrait).toBe(false);
+    });
+
+    it('should create layout for 9:16 portrait', () => {
+      const layout = createResponsiveLayout(1080, 1920, '9x16');
+
+      expect(layout.ratio).toBe('9x16');
+      expect(layout.ratioClass).toBe('portrait');
+      expect(layout.isPortrait).toBe(true);
+      expect(layout.isLandscape).toBe(false);
+    });
+
+    it('should create layout for 1:1 square', () => {
+      const layout = createResponsiveLayout(1080, 1080, '1x1');
+
+      expect(layout.ratioClass).toBe('square');
+      expect(layout.isSquare).toBe(true);
+    });
+
+    it('should create layout for 21:9 ultrawide', () => {
+      const layout = createResponsiveLayout(2520, 1080, '21x9');
+
+      expect(layout.ratioClass).toBe('ultrawide');
+      expect(layout.isUltrawide).toBe(true);
+    });
+
+    it('should calculate px correctly', () => {
+      const layout = createResponsiveLayout(1920, 1080, '16x9');
+
+      expect(layout.px(0)).toBe(0);
+      expect(layout.px(-0.5)).toBe(-960);
+      expect(layout.px(0.5)).toBe(960);
+    });
+
+    it('should calculate py correctly', () => {
+      const layout = createResponsiveLayout(1920, 1080, '16x9');
+
+      expect(layout.py(0)).toBe(0);
+      expect(layout.py(-0.5)).toBe(-540);
+      expect(layout.py(0.5)).toBe(540);
+    });
+
+    it('should calculate sz correctly', () => {
+      const layout = createResponsiveLayout(1920, 1080, '16x9');
+
+      expect(layout.sz(1080)).toBe(1080); // base 1080 at 1080 min dimension
+      expect(layout.sz(64)).toBeCloseTo(64);
+    });
+
+    it('should calculate half dimensions', () => {
+      const layout = createResponsiveLayout(1920, 1080, '16x9');
+
+      expect(layout.hw).toBe(960);
+      expect(layout.hh).toBe(540);
+    });
+
+    it('should calculate padding correctly', () => {
+      const layout = createResponsiveLayout(1920, 1080, '16x9');
+
+      // topPad: -h/2 + sz(padding)
+      // -540 + (100 * scale) where scale = 1080/1080 = 1
+      expect(layout.topPad(100)).toBe(-440);
+
+      // bottomPad: h/2 - sz(padding)
+      expect(layout.bottomPad(100)).toBe(440);
+    });
+  });
+});

package/src/layout/ResponsiveLayout.ts

@@ -0,0 +1,89 @@
+import {
+  detectRatioClass,
+  useResponsiveContext,
+} from '../context/ResponsiveContext';
+import type {RatioClass, RatioId} from '../types';
+
+export interface ResponsiveLayout {
+  ratio: RatioId;
+  ratioClass: RatioClass;
+  width: number;
+  height: number;
+  w: number;
+  h: number;
+  hw: number;
+  hh: number;
+  ar: number;
+  isPortrait: boolean;
+  isLandscape: boolean;
+  isSquare: boolean;
+  isUltrawide: boolean;
+  px: (frac: number) => number;
+  py: (frac: number) => number;
+  sz: (base: number) => number;
+  sx: (frac: number) => number;
+  sy: (frac: number) => number;
+  pad: (frac: number) => number;
+  topPad: (basePadding: number) => number;
+  bottomPad: (basePadding: number) => number;
+  leftPad: (basePadding: number) => number;
+  rightPad: (basePadding: number) => number;
+}
+
+export function createResponsiveLayout(
+  width: number,
+  height: number,
+  ratio: RatioId = '16x9',
+): ResponsiveLayout {
+  const aspectRatio = width / height;
+  const ratioClass = detectRatioClass(aspectRatio);
+  const scale = Math.min(width, height) / 1080;
+
+  return {
+    ratio,
+    ratioClass,
+    width,
+    height,
+    w: width,
+    h: height,
+    hw: width / 2,
+    hh: height / 2,
+    ar: aspectRatio,
+    isPortrait: ratioClass === 'portrait',
+    isLandscape: ratioClass === 'landscape',
+    isSquare: ratioClass === 'square',
+    isUltrawide: ratioClass === 'ultrawide',
+    px: (frac: number) => frac * width,
+    py: (frac: number) => frac * height,
+    sz: (base: number) => base * scale,
+    sx: (frac: number) => frac * width,
+    sy: (frac: number) => frac * height,
+    pad: (frac: number) => frac * Math.min(width, height),
+    topPad: (basePadding: number) => -(height / 2) + basePadding * scale,
+    bottomPad: (basePadding: number) => height / 2 - basePadding * scale,
+    leftPad: (basePadding: number) => -(width / 2) + basePadding * scale,
+    rightPad: (basePadding: number) => width / 2 - basePadding * scale,
+  };
+}
+
+export function useRatio(): ResponsiveLayout {
+  const state = useResponsiveContext();
+  return createResponsiveLayout(state.width, state.height, state.ratio);
+}
+
+/**
+ * Create a responsive layout from width and height values.
+ * This is a standalone version that doesn't require the responsive context,
+ * useful for creating layouts from raw values.
+ *
+ * @param width - The width of the view
+ * @param height - The height of the view
+ * @param ratio - Optional ratio ID (default: '16x9')
+ */
+export function viewLayout(
+  width: number,
+  height: number,
+  ratio: RatioId = '16x9',
+): ResponsiveLayout {
+  return createResponsiveLayout(width, height, ratio);
+}

package/src/scene/index.ts

@@ -0,0 +1,2 @@
+export * from './integration';
+export * from './makeResponsiveScene';

package/src/scene/integration.ts

@@ -0,0 +1,13 @@
+import type {Vector2} from '@efxlab/motion-canvas-core';
+import {initResponsiveFromSize} from '../context/ResponsiveContext';
+import type {RatioId} from '../types';
+
+export interface ResponsiveSetupOptions {
+  ratio?: RatioId;
+}
+
+export function createResponsiveSetup(options: ResponsiveSetupOptions = {}) {
+  return (size: Vector2) => {
+    initResponsiveFromSize(size, options.ratio ?? '16x9');
+  };
+}

package/src/scene/makeResponsiveScene.ts

@@ -0,0 +1,49 @@
+import type {Scene2D} from '@efxlab/motion-canvas-2d';
+import type {
+  ThreadGenerator,
+  ThreadGeneratorFactory,
+} from '@efxlab/motion-canvas-core';
+import {useResponsiveContext} from '../context/ResponsiveContext';
+
+type SceneFactory = () => ThreadGenerator;
+
+export interface ResponsiveSceneConfig {
+  base: SceneFactory;
+  portrait?: SceneFactory;
+  landscape?: SceneFactory;
+  square?: SceneFactory;
+  ultrawide?: SceneFactory;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  '16x9'?: SceneFactory;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  '9x16'?: SceneFactory;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  '4x3'?: SceneFactory;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  '1x1'?: SceneFactory;
+  fullwindow?: SceneFactory;
+  [key: string]: SceneFactory | undefined;
+}
+
+export function makeResponsiveScene(
+  config: ResponsiveSceneConfig,
+): ThreadGeneratorFactory<Scene2D> {
+  return function* (): ThreadGenerator {
+    // Note: _view parameter is required by ThreadGeneratorFactory but scene is selected via config
+    const state = useResponsiveContext();
+
+    const specificFactory = config[state.ratio];
+    if (specificFactory) {
+      yield* specificFactory();
+      return;
+    }
+
+    const classFactory = config[state.ratioClass];
+    if (classFactory) {
+      yield* classFactory();
+      return;
+    }
+
+    yield* config.base();
+  };
+}

package/src/types.ts

@@ -0,0 +1,44 @@
+export type RatioId = '16x9' | '9x16' | '4x3' | '1x1' | 'fullwindow' | string;
+
+export type RatioClass = 'landscape' | 'portrait' | 'square' | 'ultrawide';
+
+export interface ResponsiveRatioConfig {
+  aspect: string;
+  ratioClass?: RatioClass;
+}
+
+export interface ResponsiveRatiosConfig {
+  [ratioId: string]: ResponsiveRatioConfig;
+}
+
+export interface ResponsiveConfig<T> {
+  base: T;
+  portrait?: Partial<T>;
+  landscape?: Partial<T>;
+  square?: Partial<T>;
+  ultrawide?: Partial<T>;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  '16x9'?: Partial<T>;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  '9x16'?: Partial<T>;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  '4x3'?: Partial<T>;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  '1x1'?: Partial<T>;
+  fullwindow?: Partial<T>;
+  [key: string]: Partial<T> | undefined;
+}
+
+export interface ResponsiveState {
+  ratio: RatioId;
+  ratioClass: RatioClass;
+  width: number;
+  height: number;
+}
+
+export interface AnimationConfig {
+  duration?: number;
+  easing?: any;
+  delay?: number;
+  [key: string]: any;
+}