@elyndra/svelte-animated 1.2.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@elyndra/svelte-animated",
+  "version": "1.2.0",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Elyndra animated components for Svelte",
+  "keywords": [
+    "elyndra",
+    "ui",
+    "front-end",
+    "framework",
+    "scifi",
+    "sci-fi",
+    "science-fiction",
+    "svelte"
+  ],
+  "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": {
+    "svelte": "5.57.0"
+  },
+  "dependencies": {
+    "@elyndra/animated": "^1.2.0",
+    "@elyndra/animator": "^1.2.0",
+    "@elyndra/svelte-animator": "^1.2.0",
+    "@elyndra/svelte-tools": "^1.2.0",
+    "@elyndra/tools": "^1.2.0",
+    "tslib": "2.8.1"
+  },
+  "scripts": {
+    "build": "tsc --noEmit -p tsconfig.json && svelte-check --tsconfig tsconfig.json --output machine"
+  }
+}

package/src/Animated/Animated.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+  import { formatAnimatedCSSProps } from '@elyndra/animated';
+  import { useAnimator } from '@elyndra/svelte-animator';
+  import { useAnimated } from '../useAnimated/index.js';
+  import { toStyleText } from '../internal/style.js';
+  import type { AnimatedProps } from './types.js';
+
+  // No destructured rest: only direct `props.*` reads stay reactive.
+  const props: AnimatedProps<HTMLElement | SVGElement> = $props();
+
+  const getAnimator = useAnimator();
+  const animator = $derived(getAnimator?.());
+
+  let el: HTMLElement | SVGElement | null = $state(null);
+  const elementRef: { current: HTMLElement | SVGElement | null } = $state({ current: null });
+
+  // Keep the vanilla ref object live: `$state` makes `.current` reads
+  // tracked, so the `useAnimated` creation effect re-runs once the element
+  // is bound after mount.
+  $effect(() => {
+    elementRef.current = el;
+  });
+
+  // Forward to the consumer ref (callback or object).
+  $effect(() => {
+    const target = el;
+    const ref = props.elementRef;
+
+    if (typeof ref === 'function') {
+      ref(target as HTMLElement & SVGElement);
+    } else if (ref) {
+      ref.current = target as HTMLElement & SVGElement;
+    }
+  });
+
+  // Settings below intentionally capture the initial render values, same as
+  // the Solid adapter (vanilla `settingsRef` only tracks `animated`
+  // afterwards; visibility stays reactive via the template deriveds).
+  // svelte-ignore state_referenced_locally
+  useAnimated<HTMLElement | SVGElement>(elementRef, () => props.animated, {
+    renderInitials: false,
+    // svelte-ignore state_referenced_locally
+    hideOnExited: props.hideOnExited ?? true,
+    // svelte-ignore state_referenced_locally
+    hideOnEntered: props.hideOnEntered,
+    // svelte-ignore state_referenced_locally
+    onTransition: props.onTransition as (
+      element: HTMLElement | SVGElement,
+      node: Parameters<NonNullable<AnimatedProps<HTMLElement | SVGElement>['onTransition']>>[1],
+    ) => void,
+  });
+
+  const animatedSettingsList = $derived.by(() => {
+    const received = Array.isArray(props.animated) ? props.animated : [props.animated];
+    return received
+      .map((item) => (typeof item === 'string' || Array.isArray(item) ? undefined : item))
+      .filter(Boolean);
+  });
+
+  const initialAttributes = $derived.by(() => {
+    if (!animator) {
+      return undefined;
+    }
+    return animatedSettingsList
+      .map((item) => (item ? item.initialAttributes : undefined))
+      .reduce<Record<string, string>>((total, item) => ({ ...total, ...item }), {});
+  });
+
+  const dynamicStyles = $derived.by(() => {
+    if (!animator) {
+      return undefined;
+    }
+    return animatedSettingsList
+      .map((item) => (item ? item.initialStyle : undefined))
+      .filter((style): style is NonNullable<typeof style> => Boolean(style))
+      .map((styles) => formatAnimatedCSSProps(styles) as Record<string, string>)
+      .reduce<Record<string, string>>((total, item) => ({ ...total, ...item }), {});
+  });
+
+  const hideOnExited = $derived(props.hideOnExited ?? true);
+  const visibility = $derived(
+    animator && ((hideOnExited && animator.node.state === 'exited') || (props.hideOnEntered && animator.node.state === 'entered'))
+      ? 'hidden'
+      : undefined,
+  );
+  const styleText = $derived(toStyleText(props.style, visibility ? { visibility } : undefined, dynamicStyles));
+</script>
+
+<svelte:element
+  this={props.as ?? 'div'}
+  bind:this={el}
+  {...initialAttributes ?? {}}
+  id={props.id}
+  class={props.className}
+  style={styleText}
+>
+  {@render props.children?.()}
+</svelte:element>

package/src/Animated/Animated.test.ts

@@ -0,0 +1,35 @@
+import { render } from '@testing-library/svelte';
+import type { Component } from 'svelte';
+import { createRawSnippet, type Snippet } from 'svelte';
+import { expect, test } from 'vitest';
+import Animated from './Animated.svelte';
+
+const text = (html: string): Snippet =>
+  createRawSnippet(() => ({
+    render: () => html,
+  }));
+
+// `.svelte` components are `unknown` in-repo (ambient decl, tests only).
+const animated = Animated as Component;
+
+test('Should render element with children and default "div" element', () => {
+  const { container } = render(animated, {
+    animated: 'fade',
+    children: text('<span>hello</span>'),
+  });
+  // Svelte renders `<!---->` anchors, so query the element instead of
+  // relying on `firstChild` like the Solid adapter does.
+  const element = container.querySelector('div') as HTMLElement;
+  expect(element.tagName).toBe('DIV');
+  expect(element.textContent).toBe('hello');
+});
+
+test('Should allow to set custom element', () => {
+  const { container } = render(animated, {
+    as: 'section',
+    animated: 'fade',
+    children: text('<span>hello</span>'),
+  });
+  const element = container.querySelector('section') as HTMLElement;
+  expect(element.tagName).toBe('SECTION');
+});

package/src/Animated/index.ts

@@ -0,0 +1,2 @@
+export { default as Animated } from './Animated.svelte';
+export type * from './types.js';

package/src/Animated/types.ts

@@ -0,0 +1,20 @@
+import type { AnimatedProp } from '@elyndra/animated';
+import type { AnimatorNode } from '@elyndra/animator';
+import type { Snippet } from 'svelte';
+
+type ElementRef<E> = ((element: E | null) => void) | { current: E | null };
+
+interface AnimatedProps<E extends HTMLElement | SVGElement = HTMLDivElement> {
+  elementRef?: ElementRef<E>;
+  className?: string;
+  style?: string | Record<string, string | number | undefined>;
+  animated?: AnimatedProp;
+  hideOnExited?: boolean;
+  hideOnEntered?: boolean;
+  onTransition?: (element: E, node: AnimatorNode) => void;
+  as?: string;
+  id?: string;
+  children?: Snippet;
+}
+
+export type { AnimatedProps };

package/src/AnimatedX/AnimatedX.svelte

@@ -0,0 +1,82 @@
+<script lang="ts">
+  import { formatAnimatedCSSProps, type AnimatedSettings } from '@elyndra/animated';
+  import { useAnimatedX } from '../useAnimatedX/index.js';
+  import { toStyleText } from '../internal/style.js';
+  import type { AnimatedXProps } from './types.js';
+
+  // No destructured rest: only direct `props.*` reads stay reactive.
+  const props: AnimatedXProps<string, HTMLElement | SVGElement> = $props();
+
+  let el: HTMLElement | SVGElement | null = $state(null);
+  const elementRef: { current: HTMLElement | SVGElement | null } = $state({ current: null });
+
+  $effect(() => {
+    elementRef.current = el;
+  });
+
+  $effect(() => {
+    const target = el;
+    const ref = props.elementRef;
+
+    if (typeof ref === 'function') {
+      ref(target as HTMLElement & SVGElement);
+    } else if (ref) {
+      ref.current = target as HTMLElement & SVGElement;
+    }
+  });
+
+  const hasState = $derived(props.state !== undefined && props.state !== null);
+
+  // Settings intentionally capture the initial render values, same as the
+  // Solid adapter (vanilla `settingsRef` only tracks `state`/`animated`
+  // afterwards).
+  // svelte-ignore state_referenced_locally
+  useAnimatedX<string, HTMLElement | SVGElement>(
+    () => props.state,
+    elementRef,
+    () => props.animated,
+    {
+      renderInitials: false,
+      hideOnStates: (props.hideOnStates ?? []) as string[],
+    },
+  );
+
+  const animatedSettingsList = $derived.by(() => {
+    const received = Array.isArray(props.animated) ? props.animated : [props.animated];
+    return received.filter(Boolean) as AnimatedSettings[];
+  });
+
+  const initialAttributes = $derived.by(() => {
+    if (!hasState) {
+      return undefined;
+    }
+    return animatedSettingsList
+      .map((item) => item?.initialAttributes)
+      .reduce<Record<string, string>>((total, item) => ({ ...total, ...item }), {});
+  });
+
+  const dynamicStyles = $derived.by(() => {
+    if (!hasState) {
+      return undefined;
+    }
+    return animatedSettingsList
+      .map((item) => item.initialStyle)
+      .filter((style): style is NonNullable<typeof style> => Boolean(style))
+      .map((styles) => formatAnimatedCSSProps(styles) as Record<string, string>)
+      .reduce<Record<string, string>>((total, item) => ({ ...total, ...item }), {});
+  });
+
+  const visibility = $derived(hasState && (props.hideOnStates ?? []).includes(props.state as string) ? 'hidden' : undefined);
+  const styleText = $derived(toStyleText(props.style, visibility ? { visibility } : undefined, dynamicStyles));
+</script>
+
+<svelte:element
+  this={props.as ?? 'div'}
+  bind:this={el}
+  {...initialAttributes ?? {}}
+  id={props.id}
+  class={props.className}
+  style={styleText}
+>
+  {@render props.children?.()}
+</svelte:element>

package/src/AnimatedX/AnimatedX.test.ts

@@ -0,0 +1,35 @@
+import { render } from '@testing-library/svelte';
+import type { Component } from 'svelte';
+import { createRawSnippet, type Snippet } from 'svelte';
+import { expect, test } from 'vitest';
+import AnimatedX from './AnimatedX.svelte';
+
+const text = (html: string): Snippet =>
+  createRawSnippet(() => ({
+    render: () => html,
+  }));
+
+// `.svelte` components are `unknown` in-repo (ambient decl, tests only).
+const animatedX = AnimatedX as Component;
+
+test('Should render element with children and default "div" element', () => {
+  const { container } = render(animatedX, {
+    state: 'on',
+    children: text('<span>hello</span>'),
+  });
+  // Svelte renders `<!---->` anchors, so query the element instead of
+  // relying on `firstChild` like the Solid adapter does.
+  const element = container.querySelector('div') as HTMLElement;
+  expect(element.tagName).toBe('DIV');
+  expect(element.textContent).toBe('hello');
+});
+
+test('Should allow to set custom element', () => {
+  const { container } = render(animatedX, {
+    as: 'section',
+    state: 'on',
+    children: text('<span>hello</span>'),
+  });
+  const element = container.querySelector('section') as HTMLElement;
+  expect(element.tagName).toBe('SECTION');
+});

package/src/AnimatedX/index.ts

@@ -0,0 +1,2 @@
+export { default as AnimatedX } from './AnimatedX.svelte';
+export type * from './types.js';

package/src/AnimatedX/types.ts

@@ -0,0 +1,18 @@
+import type { AnimatedXProp } from '@elyndra/animated';
+import type { Snippet } from 'svelte';
+
+type ElementRef<E> = ((element: E | null) => void) | { current: E | null };
+
+interface AnimatedXProps<S extends string, E extends HTMLElement | SVGElement = HTMLDivElement> {
+  elementRef?: ElementRef<E>;
+  className?: string;
+  style?: string | Record<string, string | number | undefined>;
+  state: S | undefined | null;
+  hideOnStates?: S[];
+  animated?: AnimatedXProp<S>;
+  as?: string;
+  id?: string;
+  children?: Snippet;
+}
+
+export type { AnimatedXProps };

package/src/index.ts

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

package/src/internal/style.ts

@@ -0,0 +1,52 @@
+type StyleValue = string | number | undefined;
+type StyleInput = string | Record<string, StyleValue> | undefined;
+
+const toKebabCase = (key: string): string => key.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+
+const stringifyStyleObject = (style: Record<string, StyleValue>): string => {
+  const parts: string[] = [];
+
+  for (const [key, value] of Object.entries(style)) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+
+    parts.push(`${toKebabCase(key)}: ${value}`);
+  }
+
+  return parts.join('; ');
+};
+
+/**
+ * Serializes Svelte `style` props to CSS text. Accepts the React-style
+ * object (camelCase keys) for API parity plus plain CSS strings, so vanilla
+ * `initialStyle` objects and user styles merge declaratively.
+ */
+const toStyleText = (...styles: StyleInput[]): string | undefined => {
+  const parts: string[] = [];
+
+  for (const style of styles) {
+    if (!style) {
+      continue;
+    }
+
+    if (typeof style === 'string') {
+      const trimmed = style.trim().replace(/;$/, '');
+
+      if (trimmed) {
+        parts.push(trimmed);
+      }
+    } else {
+      const text = stringifyStyleObject(style);
+
+      if (text) {
+        parts.push(text);
+      }
+    }
+  }
+
+  return parts.length ? parts.join('; ') : undefined;
+};
+
+export { toStyleText };
+export type { StyleInput };

package/src/svelte.d.ts

@@ -0,0 +1,7 @@
+// In-repo ambient types for `.svelte` imports (tests only). The published
+// package ships the `.svelte` sources and consumers get full prop inference
+// from the `$props()` interfaces via their own Svelte setup.
+declare module '*.svelte' {
+  const Component: unknown;
+  export default Component;
+}

package/src/useAnimated/index.ts

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

package/src/useAnimated/useAnimated.svelte.ts

@@ -0,0 +1,51 @@
+import { type AnimatedElementPropsSettings, type AnimatedProp, createAnimatedElement } from '@elyndra/animated';
+import { useAnimator } from '@elyndra/svelte-animator';
+
+interface ElementRef<Element> {
+  current: Element | null;
+}
+
+/**
+ * Mechanical Svelte port of the React/Preact `useAnimated` hook. Differences
+ * are Svelte idiom only: `$effect` + `$effect` cleanup replace `useEffect`,
+ * the animator is read through the `useAnimator` accessor, and `animated`
+ * is an accessor so updates stay tracked (same convention as `Animator`'s
+ * `refreshOn`). Must be called during component init.
+ */
+const useAnimated = <Element extends HTMLElement | SVGElement = HTMLElement>(
+  elementRef: ElementRef<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>,
+  };
+
+  $effect(() => {
+    settingsRef.current = {
+      ...settings,
+      animated: animated(),
+    } as AnimatedElementPropsSettings<Element>;
+  });
+
+// oxlint-disable-next-line react/refs -- L4 arquitectura intencional: latest-ref/mergeRefs/ref-callback en render; mover a efecto cambia timing/identidad
+  $effect(() => {
+    const animator = getAnimator?.();
+    const element = elementRef.current;
+
+    if (!element || !animator) {
+      return;
+    }
+
+    const animatedElement = createAnimatedElement({
+      element,
+      animator: animator.node,
+      settingsRef,
+    });
+
+    return () => animatedElement.cancel();
+  });
+};
+
+export { useAnimated };

package/src/useAnimatedX/index.ts

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

package/src/useAnimatedX/useAnimatedX.svelte.ts

@@ -0,0 +1,45 @@
+import { type AnimatedXElementPropsSettings, type AnimatedXProp, createAnimatedXElement } from '@elyndra/animated';
+
+/**
+ * Mechanical Svelte port of the React/Preact `useAnimatedX` hook. `state`
+ * is an accessor so state transitions stay tracked (same convention as
+ * `Animator`'s `refreshOn`); `$effect` + cleanup replace `useEffect`.
+ * Must be called during component init.
+ */
+const useAnimatedX = <States extends string, Element extends HTMLElement | SVGElement = HTMLDivElement>(
+  state: () => undefined | null | States,
+  elementRef: { current: Element | null },
+  animated: () => undefined | AnimatedXProp<States>,
+  settings?: Omit<AnimatedXElementPropsSettings<States>, 'state' | 'animated'>,
+): void => {
+  const settingsRef: { current: AnimatedXElementPropsSettings<States> } = {
+    current: {} as unknown as AnimatedXElementPropsSettings<States>,
+  };
+
+  $effect(() => {
+    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 effect 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(),
+    };
+
+    const element = elementRef.current;
+
+    if (currentState === undefined || currentState === null || !element) {
+      return;
+    }
+
+    const animatedXElement = createAnimatedXElement({ element, settingsRef });
+
+    return () => animatedXElement.cancel();
+  });
+};
+
+export { useAnimatedX };