deja-vue 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# Déjà Vue
+
+Declarative GSAP Animations for Vue 3.
+
+## Development
+
+- Install dependencies:
+
+```bash
+npm install
+```
+
+- Run the playground:
+
+```bash
+npm run playground
+```
+
+- Run the unit tests:
+
+```bash
+npm run test
+```
+
+- Build the library:
+
+```bash
+npm run build
+```

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+import * as _$vue from "vue";
+import { InjectionKey, MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/constants.d.ts
+declare const ANIMATION_EVENTS: readonly ["complete", "interrupt", "repeat", "reverseComplete", "start", "update"];
+declare const parentAnimationInjectionKey: InjectionKey<Animation>;
+//#endregion
+//#region src/utils/EventBus.d.ts
+declare class EventBus<E extends string> {
+  private bus;
+  constructor(events?: E[]);
+  on(event: E | E[], callback: CallableFunction): void;
+  once(event: E | E[], callback: CallableFunction): void;
+  off(event: E | E[], callback: CallableFunction): void;
+  dispatch(event: E, ...args: any[]): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/utils/Animation.d.ts
+declare class Animation extends EventBus<typeof ANIMATION_EVENTS[number]> {
+  timeline: gsap.core.Timeline;
+  constructor(options?: gsap.TimelineVars);
+  add(child: Animation | gsap.Callback | string, position?: gsap.Position): void;
+  remove(child: Animation | gsap.Callback | string): void;
+  compose(target: HTMLElement | HTMLCollection, definition: TweenAnimationDefinition | TweenAnimationDefinition[]): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/types.d.ts
+interface ControllableAnimation {
+  progress?: number;
+  toggle?: boolean | undefined;
+}
+interface NestableAnimation {
+  parent?: Animation | null;
+  position?: gsap.Position;
+}
+interface WrappableAnimation {
+  group?: boolean;
+  initiallyHidden?: boolean;
+  tag?: string;
+}
+type BaseAnimation = ControllableAnimation & NestableAnimation & WrappableAnimation;
+type TimelineAnimation = BaseAnimation & {
+  duration?: number;
+  options?: gsap.TimelineVars;
+  tweens?: TweenAnimationDefinition[];
+};
+type TweenAnimationDefinition = ({
+  method: 'from' | 'to';
+  vars: gsap.TweenVars;
+} | {
+  method: 'fromTo';
+  vars: [gsap.TweenVars, gsap.TweenVars];
+} | {
+  method: `effect:${string}`;
+  vars?: object;
+}) & Pick<NestableAnimation, 'position'>;
+type TweenAnimation = BaseAnimation & TweenAnimationDefinition;
+//#endregion
+//#region src/components/Callback.vue.d.ts
+type __VLS_Props$1 = NestableAnimation & {
+  fn: () => void;
+};
+declare const __VLS_export$3: _$vue.DefineComponent<__VLS_Props$1, {}, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<__VLS_Props$1> & Readonly<{}>, {}, {}, {}, {}, string, _$vue.ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export$3;
+//#endregion
+//#region src/components/PositionMarker.vue.d.ts
+type __VLS_Props = NestableAnimation & {
+  label: string;
+};
+declare const __VLS_export$2: _$vue.DefineComponent<__VLS_Props, {}, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {
+  cross: (...args: any[]) => void;
+}, string, _$vue.PublicProps, Readonly<__VLS_Props> & Readonly<{
+  onCross?: ((...args: any[]) => any) | undefined;
+}>, {}, {}, {}, {}, string, _$vue.ComponentProvideOptions, false, {}, any>;
+declare const _default$1: typeof __VLS_export$2;
+//#endregion
+//#region src/components/Timeline.vue.d.ts
+declare var __VLS_9$1: {
+    animation: Animation;
+    controlled: boolean;
+    parent: Animation | null;
+    ready: boolean;
+  }, __VLS_11: {
+    animation: Animation;
+    controlled: boolean;
+    parent: Animation | null;
+    ready: boolean;
+  };
+type __VLS_Slots$1 = {} & {
+  default?: (props: typeof __VLS_9$1) => any;
+} & {
+  default?: (props: typeof __VLS_11) => any;
+};
+declare const __VLS_base$1: _$vue.DefineComponent<TimelineAnimation, {
+  animation: Animation;
+  controlled: _$vue.ComputedRef<boolean>;
+  parent: Animation | null;
+  ready: _$vue.ShallowRef<boolean, boolean>;
+}, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {
+  complete: (...args: any[]) => void;
+  interrupt: (...args: any[]) => void;
+  repeat: (...args: any[]) => void;
+  reverseComplete: (...args: any[]) => void;
+  start: (...args: any[]) => void;
+  update: (...args: any[]) => void;
+}, string, _$vue.PublicProps, Readonly<TimelineAnimation> & Readonly<{
+  onComplete?: ((...args: any[]) => any) | undefined;
+  onInterrupt?: ((...args: any[]) => any) | undefined;
+  onRepeat?: ((...args: any[]) => any) | undefined;
+  onReverseComplete?: ((...args: any[]) => any) | undefined;
+  onStart?: ((...args: any[]) => any) | undefined;
+  onUpdate?: ((...args: any[]) => any) | undefined;
+}>, {
+  toggle: boolean;
+  initiallyHidden: boolean;
+  tag: string;
+}, {}, {}, {}, string, _$vue.ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$1: __VLS_WithSlots$1<typeof __VLS_base$1, __VLS_Slots$1>;
+declare const _default$2: typeof __VLS_export$1;
+type __VLS_WithSlots$1<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+//#endregion
+//#region src/components/Tween.vue.d.ts
+declare var __VLS_9: {
+  animation: Animation;
+  controlled: boolean;
+  parent: Animation | null;
+  ready: boolean;
+};
+type __VLS_Slots = {} & {
+  default?: (props: typeof __VLS_9) => any;
+};
+declare const __VLS_base: _$vue.DefineSetupFnComponent<Record<string, any>, {}, {}, Record<string, any> & {}, _$vue.PublicProps>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default$3: typeof __VLS_export;
+type __VLS_WithSlots<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+//#endregion
+//#region src/composables/useAnimation.d.ts
+declare function useAnimation(wrapper: Readonly<ShallowRef<HTMLElement | null>>, props: TimelineAnimation | TweenAnimation, emit: (event: typeof ANIMATION_EVENTS[number], timeline: gsap.core.Timeline) => void, options?: gsap.TimelineVars): {
+  animation: Animation;
+  controlled: _$vue.ComputedRef<boolean>;
+  parent: Animation | null;
+  ready: ShallowRef<boolean, boolean>;
+};
+//#endregion
+//#region src/composables/useAnimationControls.d.ts
+type AnimationControls<C = ControllableAnimation> = { [K in keyof C]?: MaybeRefOrGetter<C[K]> };
+declare function useAnimationControls(animation: Animation, controls: AnimationControls): {
+  controlled: _$vue.ComputedRef<boolean>;
+};
+//#endregion
+//#region src/composables/useAnimationNesting.d.ts
+declare function useAnimationNesting(child?: Animation | gsap.Callback | string, options?: NestableAnimation): {
+  parent: Animation | null;
+};
+//#endregion
+export { ANIMATION_EVENTS, type Animation, BaseAnimation, _default as Callback, ControllableAnimation, NestableAnimation, _default$1 as PositionMarker, _default$2 as Timeline, TimelineAnimation, _default$3 as Tween, TweenAnimation, TweenAnimationDefinition, WrappableAnimation, parentAnimationInjectionKey, useAnimation, useAnimationControls, useAnimationNesting };

package/dist/index.js

@@ -0,0 +1,393 @@
+import { Fragment, computed, createBlock, defineComponent, inject, nextTick, normalizeStyle, onMounted, onUnmounted, openBlock, provide, renderSlot, resolveDynamicComponent, shallowRef, toValue, unref, useTemplateRef, watch, withCtx } from "vue";
+import { gsap } from "gsap";
+//#region src/constants.ts
+const ANIMATION_EVENTS = [
+	"complete",
+	"interrupt",
+	"repeat",
+	"reverseComplete",
+	"start",
+	"update"
+];
+const parentAnimationInjectionKey = Symbol("parent-animation");
+//#endregion
+//#region src/utils/EventBus.ts
+var EventBus = class {
+	bus;
+	constructor(events) {
+		this.bus = /* @__PURE__ */ new Map();
+		events?.forEach((event) => this.bus.set(event, /* @__PURE__ */ new Set()));
+	}
+	on(event, callback) {
+		if (Array.isArray(event)) event.forEach((e) => this.on(e, callback));
+		else {
+			if (!this.bus.has(event)) this.bus.set(event, /* @__PURE__ */ new Set());
+			this.bus.get(event).add(callback);
+		}
+	}
+	once(event, callback) {
+		const fn = (...args) => {
+			this.off(event, fn);
+			callback(...args);
+		};
+		this.on(event, fn);
+	}
+	off(event, callback) {
+		if (Array.isArray(event)) event.forEach((e) => this.off(e, callback));
+		else if (this.bus.has(event) && this.bus.get(event).has(callback)) this.bus.get(event).delete(callback);
+	}
+	dispatch(event, ...args) {
+		if (!this.bus.has(event)) return;
+		this.bus.get(event).forEach((callback) => callback(...args));
+	}
+	dispose() {
+		this.bus.clear();
+		this.bus = null;
+	}
+};
+//#endregion
+//#region src/utils/Animation.ts
+var Animation = class extends EventBus {
+	timeline;
+	constructor(options) {
+		super([...ANIMATION_EVENTS]);
+		this.timeline = gsap.timeline({
+			...options,
+			onComplete: () => this.dispatch("complete"),
+			onRepeat: () => this.dispatch("repeat"),
+			onReverseComplete: () => this.dispatch("reverseComplete"),
+			onStart: () => this.dispatch("start"),
+			onUpdate: () => this.dispatch("update")
+		});
+		(options ? Object.entries(options).filter(([key]) => key.startsWith("on")) : []).forEach(([key, fn]) => {
+			const [firstChar, ...rest] = key.replace(/^on/, "");
+			const event = `${firstChar.toLowerCase()}${rest.join()}`;
+			this.on(event, fn);
+		});
+	}
+	add(child, position) {
+		if (typeof child === "string") this.timeline.addLabel(child, position);
+		else if (typeof child === "function") this.timeline.add(child, position);
+		else {
+			this.timeline.add(child.timeline, position);
+			const totalDuration = "totalDuration" in (this.timeline.data || {}) ? this.timeline.data.totalDuration : void 0;
+			if (totalDuration) this.timeline.duration(totalDuration);
+		}
+	}
+	remove(child) {
+		if (typeof child === "string") this.timeline.removeLabel(child);
+		else if (typeof child === "function") this.timeline.remove(child);
+		else this.once(["complete", "reverseComplete"], () => {
+			const startTime = child.timeline.startTime();
+			const duration = child.timeline.duration();
+			this.timeline.remove(child.timeline);
+			this.timeline.getChildren(false, true, true).forEach((child) => child.startTime() > startTime && child.startTime(child.startTime() - duration));
+			this.timeline.invalidate();
+		});
+	}
+	compose(target, definition) {
+		if (Array.isArray(definition)) definition.forEach((tween) => this.compose(target, tween));
+		else if (definition.method.startsWith("effect")) try {
+			const [_, effect] = definition.method.split(":");
+			this.timeline[effect](target, structuredClone(definition.vars));
+		} catch {
+			console.warn("Missing or unknown effect");
+		}
+		else if (definition.method === "fromTo") this.timeline.fromTo(target, ...structuredClone(definition.vars));
+		else this.timeline[definition.method](target, structuredClone(definition.vars));
+	}
+	dispose() {
+		super.dispose();
+		this.timeline.kill();
+		this.timeline = null;
+	}
+};
+//#endregion
+//#region src/composables/useAnimationNesting.ts
+function useAnimationNesting(child, options) {
+	const parent = options?.parent === null ? null : options?.parent || inject(parentAnimationInjectionKey, null);
+	onMounted(async () => {
+		if (!parent || !child) return;
+		await nextTick();
+		parent.add(child, options?.position);
+	});
+	onUnmounted(() => {
+		if (!child) return;
+		if (parent) parent.remove(child);
+		else if (child instanceof Animation) child.dispose();
+	});
+	return { parent };
+}
+//#endregion
+//#region src/components/Callback.vue
+var Callback_default = /* @__PURE__ */ defineComponent({
+	__name: "Callback",
+	props: {
+		parent: {
+			type: [Object, null],
+			required: false
+		},
+		position: {
+			type: null,
+			required: false
+		},
+		fn: {
+			type: Function,
+			required: true
+		}
+	},
+	setup(__props) {
+		const props = __props;
+		useAnimationNesting(props.fn, props);
+		return (_ctx, _cache) => {
+			return openBlock(), createBlock(Fragment);
+		};
+	}
+});
+//#endregion
+//#region src/components/PositionMarker.vue
+var PositionMarker_default = /* @__PURE__ */ defineComponent({
+	__name: "PositionMarker",
+	props: {
+		parent: {
+			type: [Object, null],
+			required: false
+		},
+		position: {
+			type: null,
+			required: false
+		},
+		label: {
+			type: String,
+			required: true
+		}
+	},
+	emits: ["cross"],
+	setup(__props, { emit: __emit }) {
+		const props = __props;
+		const emit = __emit;
+		const { parent } = useAnimationNesting(props.label, props);
+		useAnimationNesting(() => emit("cross"), {
+			parent,
+			position: props.label
+		});
+		return (_ctx, _cache) => {
+			return openBlock(), createBlock(Fragment);
+		};
+	}
+});
+//#endregion
+//#region src/composables/useAnimationControls.ts
+function useAnimationControls(animation, controls) {
+	const progress = computed(() => toValue(controls.progress));
+	const toggle = computed(() => toValue(controls.toggle));
+	const controlled = computed(() => typeof progress.value === "number" || typeof toggle.value === "boolean");
+	if (controlled.value && toggle.value !== true) animation.timeline.pause();
+	watch(progress, (value) => {
+		if (typeof value !== "number") return;
+		animation.timeline.progress(value);
+	}, { immediate: true });
+	watch(toggle, (value) => {
+		if (typeof value !== "boolean") return;
+		animation.timeline[value ? "play" : "reverse"]();
+	});
+	return { controlled };
+}
+//#endregion
+//#region src/composables/useAnimation.ts
+function useAnimation(wrapper, props, emit, options) {
+	const animation = new Animation(options);
+	const ready = shallowRef(false);
+	const { controlled } = useAnimationControls(animation, {
+		progress: () => props.progress,
+		toggle: () => props.toggle
+	});
+	const { parent } = useAnimationNesting(animation, props);
+	ANIMATION_EVENTS.forEach((event) => animation.on(event, () => emit(event, animation.timeline)));
+	onMounted(() => {
+		if (wrapper.value) {
+			const target = props.group ? wrapper.value.children : wrapper.value;
+			const definition = "tweens" in props ? props.tweens || [] : props;
+			animation.compose(target, definition);
+		}
+		ready.value = true;
+	});
+	onUnmounted(() => animation.dispose());
+	return {
+		animation,
+		controlled,
+		parent,
+		ready
+	};
+}
+//#endregion
+//#region src/components/Timeline.vue
+var Timeline_default = /* @__PURE__ */ defineComponent({
+	__name: "Timeline",
+	props: {
+		progress: {
+			type: Number,
+			required: false
+		},
+		toggle: {
+			type: Boolean,
+			required: false,
+			skipCheck: true,
+			default: void 0
+		},
+		parent: {
+			type: [Object, null],
+			required: false
+		},
+		position: {
+			type: null,
+			required: false
+		},
+		group: {
+			type: Boolean,
+			required: false
+		},
+		initiallyHidden: {
+			type: Boolean,
+			required: false,
+			default: true
+		},
+		tag: {
+			type: String,
+			required: false,
+			default: "div"
+		},
+		duration: {
+			type: Number,
+			required: false
+		},
+		options: {
+			type: null,
+			required: false
+		},
+		tweens: {
+			type: Array,
+			required: false
+		}
+	},
+	emits: [...ANIMATION_EVENTS],
+	setup(__props, { expose: __expose, emit: __emit }) {
+		const props = __props;
+		const emit = __emit;
+		const wrapper = useTemplateRef("wrapper");
+		const { animation, controlled, parent, ready } = useAnimation(wrapper, props, emit, {
+			...props.options,
+			data: {
+				...props.options?.data,
+				totalDuration: Number(props.duration)
+			}
+		});
+		watch(() => props.duration, (duration) => animation.timeline.data.totalDuration = Number(duration));
+		__expose({
+			animation,
+			controlled,
+			parent,
+			ready
+		});
+		provide(parentAnimationInjectionKey, animation);
+		return (_ctx, _cache) => {
+			return __props.tweens ? (openBlock(), createBlock(resolveDynamicComponent(__props.tag), {
+				key: 0,
+				ref_key: "wrapper",
+				ref: wrapper,
+				style: normalizeStyle(__props.initiallyHidden && !unref(ready) ? { visibility: "hidden" } : void 0)
+			}, {
+				default: withCtx(() => [renderSlot(_ctx.$slots, "default", {
+					animation: unref(animation),
+					controlled: unref(controlled),
+					parent: unref(parent),
+					ready: unref(ready)
+				})]),
+				_: 3
+			}, 8, ["style"])) : renderSlot(_ctx.$slots, "default", {
+				key: 1,
+				animation: unref(animation),
+				controlled: unref(controlled),
+				parent: unref(parent),
+				ready: unref(ready)
+			});
+		};
+	}
+});
+//#endregion
+//#region src/components/Tween.vue
+var Tween_default = /* @__PURE__ */ defineComponent({
+	__name: "Tween",
+	props: {
+		progress: {
+			type: Number,
+			required: false
+		},
+		toggle: {
+			type: Boolean,
+			required: false,
+			skipCheck: true,
+			default: void 0
+		},
+		parent: {
+			type: [Object, null],
+			required: false
+		},
+		position: {
+			type: void 0,
+			required: false
+		},
+		group: {
+			type: Boolean,
+			required: false
+		},
+		initiallyHidden: {
+			type: Boolean,
+			required: false,
+			default: true
+		},
+		tag: {
+			type: String,
+			required: false,
+			default: "div"
+		},
+		method: {
+			type: null,
+			required: true
+		},
+		vars: {
+			type: null,
+			required: false
+		}
+	},
+	emits: [...ANIMATION_EVENTS],
+	setup(__props, { expose: __expose, emit: __emit }) {
+		const props = __props;
+		const emit = __emit;
+		const wrapper = useTemplateRef("wrapper");
+		const { animation, controlled, parent, ready } = useAnimation(wrapper, props, emit);
+		__expose({
+			animation,
+			controlled,
+			parent,
+			ready
+		});
+		return (_ctx, _cache) => {
+			return openBlock(), createBlock(resolveDynamicComponent(__props.tag), {
+				ref_key: "wrapper",
+				ref: wrapper,
+				style: normalizeStyle(__props.initiallyHidden && !unref(ready) ? { visibility: "hidden" } : void 0)
+			}, {
+				default: withCtx(() => [renderSlot(_ctx.$slots, "default", {
+					animation: unref(animation),
+					controlled: unref(controlled),
+					parent: unref(parent),
+					ready: unref(ready)
+				})]),
+				_: 3
+			}, 8, ["style"]);
+		};
+	}
+});
+//#endregion
+export { ANIMATION_EVENTS, Callback_default as Callback, PositionMarker_default as PositionMarker, Timeline_default as Timeline, Tween_default as Tween, parentAnimationInjectionKey, useAnimation, useAnimationControls, useAnimationNesting };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "deja-vue",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Declarative GSAP Animations for Vue 3",
+  "author": "Andrea 'Fiad' Fiadone <hello@fiad.one>",
+  "license": "MIT",
+  "homepage": "https://github.com/fiadone/deja-vue#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fiadone/deja-vue.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fiadone/deja-vue/issues"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch && npm run play",
+    "play": "vite",
+    "test": "vitest",
+    "typecheck": "vue-tsc --noEmit",
+    "release": "bumpp",
+    "prepublishOnly": "pnpm run build",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "peerDependencies": {
+    "gsap": "^3.0.0",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@tsdown/css": "^0.21.7",
+    "@types/node": "^25.5.0",
+    "@vitejs/plugin-vue": "^6.0.5",
+    "@vitest/browser-playwright": "^4.1.2",
+    "bumpp": "^11.0.1",
+    "gsap": "^3.15.0",
+    "playwright": "^1.58.2",
+    "semantic-release": "^24.2.9",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "unocss": "^66.6.8",
+    "vite": "^8.0.3",
+    "vitepress": "^1.6.4",
+    "vitest": "^4.1.2",
+    "vitest-browser-vue": "^2.1.0",
+    "vue": "^3.5.31",
+    "vue-tsc": "^3.2.6"
+  }
+}