@elyndra/vue-animated 1.2.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@elyndra/vue-animated",
+  "version": "1.2.0",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Elyndra animated components for Vue",
+  "keywords": [
+    "elyndra",
+    "ui",
+    "front-end",
+    "framework",
+    "scifi",
+    "sci-fi",
+    "science-fiction",
+    "vue"
+  ],
+  "homepage": "https://elyndra.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gabox301/elyndra.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Gabox301/elyndra/issues"
+  },
+  "funding": "https://github.com/sponsors/romelperez",
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "types": "./src/index.ts",
+  "module": "./src/index.ts",
+  "main": "./src/index.ts",
+  "peerDependencies": {
+    "vue": "3"
+  },
+  "dependencies": {
+    "@elyndra/animated": "^1.2.0",
+    "@elyndra/animator": "^1.2.0",
+    "@elyndra/tools": "^1.2.0",
+    "@elyndra/vue-animator": "^1.2.0",
+    "@elyndra/vue-tools": "^1.2.0",
+    "tslib": "2.8.1"
+  },
+  "scripts": {
+    "build": "tsc --noEmit -p tsconfig.json && vue-tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/Animated/Animated.test.ts

@@ -0,0 +1,24 @@
+import { mount } from '@vue/test-utils';
+import { expect, test } from 'vitest';
+import { Animated } from './index.js';
+
+test('Should render element with children and default "div" element', () => {
+  const wrapper = mount(Animated, {
+    props: { animated: ['fade'] },
+    slots: { default: () => 'hello' },
+  });
+  const element = wrapper.element as HTMLElement;
+  expect(element.tagName).toBe('DIV');
+  expect(element.textContent).toBe('hello');
+  wrapper.unmount();
+});
+
+test('Should allow to set custom element', () => {
+  const wrapper = mount(Animated, {
+    props: { as: 'section', animated: ['fade'] },
+    slots: { default: () => 'hello' },
+  });
+  const element = wrapper.element as HTMLElement;
+  expect(element.tagName).toBe('SECTION');
+  wrapper.unmount();
+});

package/src/Animated/Animated.vue

@@ -0,0 +1,87 @@
+<script setup lang="ts" generic="E extends HTMLElement | SVGElement = HTMLDivElement">
+import { formatAnimatedCSSProps } from '@elyndra/animated';
+import { useAnimator } from '@elyndra/vue-animator';
+import { mergeRefs } from '@elyndra/vue-tools';
+import { computed, type CSSProperties } from 'vue';
+import { useAnimated } from '../useAnimated/index.js';
+import type { AnimatedProps } from '../types.js';
+
+const props = withDefaults(defineProps<AnimatedProps<E>>(), {
+  // Vue boolean-casts absent props with a Boolean type to `false`.
+  // `hideOnExited` defaults to `true`, so it gets an `undefined` default
+  // which skips the cast. (`hideOnEntered` absent also means falsy, but an
+  // explicit default keeps both intentions readable.)
+  hideOnExited: undefined,
+  hideOnEntered: undefined,
+});
+
+const getAnimator = useAnimator();
+// Snapshot visibility like React/Preact/Solid render: the node state is
+// vanilla (not reactive), live show/hide during transitions is owned by the
+// animation above.
+const animator = getAnimator?.();
+const as = computed(() => props.as ?? 'div');
+const elementBox: { current: E | null } = { current: null };
+
+useAnimated(elementBox, () => props.animated, {
+  renderInitials: false,
+  hideOnExited: props.hideOnExited ?? true,
+  hideOnEntered: props.hideOnEntered,
+  onTransition: props.onTransition,
+});
+
+const animatedSettingsList = computed(() => {
+  const animatedSettingsListReceived = Array.isArray(props.animated) ? props.animated : [props.animated];
+  return animatedSettingsListReceived
+    .map((item) => (typeof item === 'string' || Array.isArray(item) ? undefined : item))
+    .filter(Boolean);
+});
+
+const initialAttributes = computed<Record<string, string> | undefined>(() => {
+  if (!animator) {
+    return undefined;
+  }
+  return animatedSettingsList.value
+    .map((item) => (item ? item.initialAttributes : undefined))
+    .reduce<Record<string, string>>((total, item) => ({ ...total, ...item }), {});
+});
+
+const dynamicStyles = computed<CSSProperties | undefined>(() => {
+  if (!animator) {
+    return undefined;
+  }
+  return animatedSettingsList.value
+    .map((item) => (item ? item.initialStyle : undefined))
+    .filter((style): style is NonNullable<typeof style> => Boolean(style))
+    .map((styles) => formatAnimatedCSSProps(styles) as CSSProperties)
+    .reduce((total, item) => ({ ...total, ...item }), {});
+});
+
+const hideOnExited = computed(() => props.hideOnExited ?? true);
+
+const setElementRef = (value: E | null): void => {
+  elementBox.current = value;
+  mergeRefs(props.elementRef)(value);
+};
+</script>
+
+<template>
+  <component
+    :is="as"
+    v-bind="initialAttributes"
+    :ref="setElementRef"
+    :class="props.className"
+    :style="{
+      ...props.style,
+      visibility:
+        animator &&
+        ((hideOnExited && animator.node.state === 'exited') ||
+          (props.hideOnEntered && animator.node.state === 'entered'))
+          ? 'hidden'
+          : '',
+      ...dynamicStyles,
+    }"
+  >
+    <slot />
+  </component>
+</template>

package/src/Animated/index.ts

@@ -0,0 +1 @@
+export { default as Animated } from './Animated.vue';

package/src/AnimatedX/AnimatedX.test.ts

@@ -0,0 +1,24 @@
+import { mount } from '@vue/test-utils';
+import { expect, test } from 'vitest';
+import { AnimatedX } from './index.js';
+
+test('Should render element with children and default "div" element', () => {
+  const wrapper = mount(AnimatedX, {
+    props: { state: null },
+    slots: { default: () => 'hello' },
+  });
+  const element = wrapper.element as HTMLElement;
+  expect(element.tagName).toBe('DIV');
+  expect(element.textContent).toBe('hello');
+  wrapper.unmount();
+});
+
+test('Should allow to set custom element', () => {
+  const wrapper = mount(AnimatedX, {
+    props: { as: 'section', state: 'on' },
+    slots: { default: () => 'hello' },
+  });
+  const element = wrapper.element as HTMLElement;
+  expect(element.tagName).toBe('SECTION');
+  wrapper.unmount();
+});

package/src/AnimatedX/AnimatedX.vue

@@ -0,0 +1,66 @@
+<script setup lang="ts" generic="S extends string, E extends HTMLElement | SVGElement = HTMLDivElement">
+import { type AnimatedSettings, formatAnimatedCSSProps } from '@elyndra/animated';
+import { mergeRefs } from '@elyndra/vue-tools';
+import { computed, type CSSProperties } from 'vue';
+import { useAnimatedX } from '../useAnimatedX/index.js';
+import type { AnimatedXProps } from '../types.js';
+
+const props = withDefaults(defineProps<AnimatedXProps<S, E>>(), {
+  hideOnStates: undefined,
+});
+
+const hasState = computed(() => props.state !== undefined && props.state !== null);
+const as = computed(() => props.as ?? 'div');
+const elementBox: { current: E | null } = { current: null };
+
+useAnimatedX<S, E>(() => props.state, elementBox, () => props.animated, {
+  renderInitials: false,
+  hideOnStates: props.hideOnStates ?? [],
+});
+
+const animatedSettingsList = computed(() => {
+  const animatedSettingsListReceived = Array.isArray(props.animated) ? props.animated : [props.animated];
+  return animatedSettingsListReceived.filter(Boolean) as AnimatedSettings[];
+});
+
+const initialAttributes = computed<Record<string, string> | undefined>(() => {
+  if (!hasState.value) {
+    return undefined;
+  }
+  return animatedSettingsList.value
+    .map((item) => item?.initialAttributes)
+    .reduce<Record<string, string>>((total, item) => ({ ...total, ...item }), {});
+});
+
+const dynamicStyles = computed<CSSProperties | undefined>(() => {
+  if (!hasState.value) {
+    return undefined;
+  }
+  return animatedSettingsList.value
+    .map((item) => item.initialStyle)
+    .filter((style): style is NonNullable<typeof style> => Boolean(style))
+    .map((styles) => formatAnimatedCSSProps(styles) as CSSProperties)
+    .reduce((total, item) => ({ ...total, ...item }), {});
+});
+
+const setElementRef = (value: E | null): void => {
+  elementBox.current = value;
+  mergeRefs(props.elementRef)(value);
+};
+</script>
+
+<template>
+  <component
+    :is="as"
+    v-bind="initialAttributes"
+    :ref="setElementRef"
+    :class="props.className"
+    :style="{
+      ...props.style,
+      visibility: hasState && (props.hideOnStates ?? []).includes(props.state as S) ? 'hidden' : '',
+      ...dynamicStyles,
+    }"
+  >
+    <slot />
+  </component>
+</template>

package/src/AnimatedX/index.ts

@@ -0,0 +1 @@
+export { default as AnimatedX } from './AnimatedX.vue';

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './Animated/index.js';
+export * from './AnimatedX/index.js';
+export * from './useAnimated/index.js';
+export * from './useAnimatedX/index.js';
+export type * from './types.js';

package/src/types.ts

@@ -0,0 +1,27 @@
+import type { CSSProperties } from 'vue';
+import type { AnimatedProp, AnimatedXProp } from '@elyndra/animated';
+import type { AnimatorNode } from '@elyndra/animator';
+import type { ElementRef } from '@elyndra/vue-tools';
+
+interface AnimatedProps<E extends HTMLElement | SVGElement = HTMLDivElement> {
+  elementRef?: ElementRef<E>;
+  className?: string;
+  style?: CSSProperties;
+  animated?: AnimatedProp;
+  hideOnExited?: boolean;
+  hideOnEntered?: boolean;
+  onTransition?: (element: E, node: AnimatorNode) => void;
+  as?: keyof HTMLElementTagNameMap | keyof SVGElementTagNameMap;
+}
+
+interface AnimatedXProps<S extends string, E extends HTMLElement | SVGElement = HTMLDivElement> {
+  elementRef?: ElementRef<E>;
+  className?: string;
+  style?: CSSProperties;
+  state: S | undefined | null;
+  hideOnStates?: S[];
+  animated?: AnimatedXProp<S>;
+  as?: keyof HTMLElementTagNameMap | keyof SVGElementTagNameMap;
+}
+
+export type { AnimatedProps, AnimatedXProps, ElementRef };

package/src/useAnimated/index.ts

@@ -0,0 +1 @@
+export * from './useAnimated.js';

package/src/useAnimated/useAnimated.test.ts

@@ -0,0 +1,50 @@
+import { flushPromises, mount } from '@vue/test-utils';
+import { defineComponent, h } from 'vue';
+import { expect, test } from 'vitest';
+import { Animator } from '@elyndra/vue-animator';
+import { useAnimated } from './index.js';
+
+const flush = async (): Promise<void> => {
+  await flushPromises();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await flushPromises();
+};
+
+test('Should apply initial attributes through the live settings ref', async () => {
+  const element = document.createElement('div');
+  const elementRef = { current: element as HTMLDivElement | null };
+
+  const Harness = defineComponent({
+    setup() {
+      useAnimated(elementRef, () => [{ initialAttributes: { 'data-animated': 'ready' } }]);
+      return () => h('div');
+    },
+  });
+
+  const wrapper = mount(Animator, {
+    props: { reducedMotion: true },
+    slots: { default: () => h(Harness) },
+  });
+  await flush();
+
+  expect(element.getAttribute('data-animated')).toBe('ready');
+  wrapper.unmount();
+});
+
+test('Should do nothing without an animator or element', async () => {
+  const elementRef = { current: null as HTMLDivElement | null };
+
+  const Harness = defineComponent({
+    setup() {
+      useAnimated(elementRef, () => ['fade']);
+      return () => h('div');
+    },
+  });
+
+  // No animator above: the animated element is never created, no throw.
+  const wrapper = mount(Harness);
+  await flush();
+
+  expect(elementRef.current).toBeNull();
+  wrapper.unmount();
+});

package/src/useAnimated/useAnimated.ts

@@ -0,0 +1,56 @@
+import { type AnimatedElementPropsSettings, type AnimatedProp, createAnimatedElement } from '@elyndra/animated';
+import { useAnimator } from '@elyndra/vue-animator';
+import { watch, watchEffect } from 'vue';
+
+interface ElementSource<Element> {
+  current: Element | null;
+}
+
+/**
+ * Mechanical Vue port of the React/Preact/Solid `useAnimated` hook.
+ * Differences are Vue idiom only: `watch` + `watch` cleanup replace
+ * `useEffect`/`createEffect` + `onCleanup`, the animator is read through the
+ * `useAnimator` accessor, and `animated` is a source function so updates
+ * stay tracked (same convention as `Animator`'s `refreshOn`). Must be called
+ * inside `setup`.
+ */
+const useAnimated = <Element extends HTMLElement | SVGElement = HTMLElement>(
+  elementRef: ElementSource<Element | null>,
+  animated: () => undefined | AnimatedProp,
+  settings?: undefined | Omit<AnimatedElementPropsSettings<Element>, 'animated'>,
+): void => {
+  const getAnimator = useAnimator();
+  const settingsRef: { current: AnimatedElementPropsSettings<Element> } = {
+    current: { animated: undefined } as AnimatedElementPropsSettings<Element>,
+  };
+
+  // The settings ref stays live so the vanilla animated element always reads
+  // the latest settings.
+  watchEffect(() => {
+    settingsRef.current = {
+      ...settings,
+      animated: animated(),
+    } as AnimatedElementPropsSettings<Element>;
+  });
+
+  watch(
+    // oxlint-disable-next-line react/refs -- L4 arquitectura intencional: latest-ref en watch source; mover a efecto cambia timing/identidad (mismo patron que Solid)
+    () => [elementRef.current, getAnimator?.()] as const,
+    ([element, animator], _previous, onCleanup) => {
+      if (!element || !animator) {
+        return;
+      }
+
+      const animatedElement = createAnimatedElement({
+        element,
+        animator: animator.node,
+        settingsRef,
+      });
+
+      onCleanup(() => animatedElement.cancel());
+    },
+    { immediate: true, flush: 'post' },
+  );
+};
+
+export { useAnimated };

package/src/useAnimatedX/index.ts

@@ -0,0 +1 @@
+export * from './useAnimatedX.js';

package/src/useAnimatedX/useAnimatedX.ts

@@ -0,0 +1,54 @@
+import { type AnimatedXElementPropsSettings, type AnimatedXProp, createAnimatedXElement } from '@elyndra/animated';
+import { watch, watchEffect } from 'vue';
+
+interface ElementSource<Element> {
+  current: Element | null;
+}
+
+/**
+ * Mechanical Vue port of the React/Preact/Solid `useAnimatedX` hook.
+ * `state` is a source function so state transitions stay tracked (same
+ * convention as `Animator`'s `refreshOn`); `watch` + `watch` cleanup replace
+ * `useEffect`/`createEffect` + `onCleanup`. Must be called inside `setup`.
+ */
+const useAnimatedX = <States extends string, Element extends HTMLElement | SVGElement = HTMLDivElement>(
+  state: () => undefined | null | States,
+  elementRef: ElementSource<Element | null>,
+  animated: () => undefined | AnimatedXProp<States>,
+  settings?: Omit<AnimatedXElementPropsSettings<States>, 'state' | 'animated'>,
+): void => {
+  const settingsRef: { current: AnimatedXElementPropsSettings<States> } = {
+    current: {} as unknown as AnimatedXElementPropsSettings<States>,
+  };
+
+  watchEffect(() => {
+    const currentState = state();
+
+    // NOTE: `currentState as States` is load-bearing, not debt. The hook legitimately
+    // accepts null/undefined state, and the stored value is only consumed
+    // inside the creation watcher after an explicit null/undefined guard.
+    // Widening the settings type instead would weaken the contract for all
+    // consumers.
+    settingsRef.current = {
+      ...settings,
+      state: currentState as States,
+      animated: animated(),
+    };
+  });
+
+  watch(
+    () => [state(), elementRef.current] as const,
+    ([currentState, element], _previous, onCleanup) => {
+      if (currentState === undefined || currentState === null || !element) {
+        return;
+      }
+
+      const animatedXElement = createAnimatedXElement({ element, settingsRef });
+
+      onCleanup(() => animatedXElement.cancel());
+    },
+    { immediate: true, flush: 'post' },
+  );
+};
+
+export { useAnimatedX };

package/src/vue.d.ts

@@ -0,0 +1,8 @@
+// In-repo ambient types for `.vue` imports (tests only). The published
+// package ships the `.vue` sources and consumers get full prop inference
+// from their own Vue setup.
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue';
+  const Component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>;
+  export default Component;
+}