@elyndra/vue-text 1.2.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@elyndra/vue-text",
+  "version": "1.2.0",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Elyndra text 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/text": "^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/Text/Text.test.ts

@@ -0,0 +1,33 @@
+import { flushPromises, mount } from '@vue/test-utils';
+import { h } from 'vue';
+import { expect, test } from 'vitest';
+import { Text } from './index.js';
+
+test('Should render component classes and content with default "p" element', async () => {
+  const wrapper = mount(Text, {
+    slots: { default: () => ['Furutistic ', h('b', 'Sci-Fi'), ' UI Web Framework'] },
+  });
+  await flushPromises();
+
+  const element = wrapper.element as HTMLElement;
+  const contentElement = element.firstChild as HTMLElement;
+  expect(element.classList.contains('elyndra-text-text')).toBe(true);
+  expect(element.tagName).toBe('P');
+  expect(contentElement.classList.contains('elyndra-text-text__content')).toBe(true);
+  expect(contentElement.innerHTML).toBe('Furutistic <b>Sci-Fi</b> UI Web Framework');
+  wrapper.unmount();
+});
+
+test('Should allow to set custom element', async () => {
+  const wrapper = mount(Text, {
+    props: { as: 'a', href: 'https://elyndra.dev', target: 'elyndra' },
+    slots: { default: () => 'Elyndra' },
+  });
+  await flushPromises();
+
+  const element = wrapper.element as HTMLElement;
+  expect(element.tagName).toBe('A');
+  expect(element.getAttribute('href')).toBe('https://elyndra.dev');
+  expect(element.getAttribute('target')).toBe('elyndra');
+  wrapper.unmount();
+});

package/src/Text/Text.vue

@@ -0,0 +1,173 @@
+<script setup lang="ts" generic="E extends HTMLElement = HTMLSpanElement">
+import type { Animation } from '@elyndra/animated';
+import { useAnimator } from '@elyndra/vue-animator';
+import { mergeRefs } from '@elyndra/vue-tools';
+import {
+  animateTextDecipher,
+  animateTextSequence,
+  getAnimationTextDuration,
+} from '@elyndra/text';
+import { cx } from '@elyndra/tools';
+import { computed, onMounted, onUpdated, ref, watch, type CSSProperties } from 'vue';
+import type { TextProps } from '../types.js';
+
+const props = withDefaults(defineProps<TextProps<E>>(), {
+  // Vue boolean-casts absent props with a Boolean type to `false`. These
+  // flags distinguish "absent" from an explicit `false` (or are read with
+  // `??`), so each gets an `undefined` default which skips the cast.
+  fixed: undefined,
+  blink: undefined,
+  hideOnEntered: undefined,
+  hideOnExited: undefined,
+});
+
+const getAnimator = useAnimator();
+// Snapshot like React/Preact/Solid render: the node state is vanilla (not
+// reactive), live show/hide during transitions is owned by the animation.
+const animator = getAnimator?.();
+const as = computed(() => props.as ?? 'p');
+const childrenText = ref('');
+const rootBox: { current: E | null } = { current: null };
+const contentBox: { current: HTMLSpanElement | null } = { current: null };
+let transitionControl: Animation | null = null;
+
+const setElementRef = (value: unknown): void => {
+  const element = value as E | null;
+  rootBox.current = element;
+  mergeRefs(props.elementRef)(element);
+};
+
+const setContentRef = (value: unknown): void => {
+  contentBox.current = value as HTMLSpanElement | null;
+};
+
+const readChildrenText = (): void => {
+  childrenText.value = contentBox.current?.textContent ?? '';
+};
+
+const rootStyle = computed<CSSProperties>(() => ({
+  position: 'relative',
+  ...props.style,
+}));
+
+const contentVisibility = computed<CSSProperties['visibility']>(() => {
+  if (!animator) {
+    return undefined;
+  }
+  const hidden =
+    (animator.node.state === 'exited' && (props.hideOnExited ?? true)) ||
+    (animator.node.state === 'entered' && props.hideOnEntered);
+  // Empty string keeps the runtime contract identical to React/Preact/Solid.
+  return (hidden ? 'hidden' : '') as CSSProperties['visibility'];
+});
+
+const contentStyle = computed<CSSProperties>(() => ({
+  position: 'relative',
+  visibility: contentVisibility.value,
+  ...props.contentStyle,
+}));
+
+// Slot content is only measurable after mount, and again after any update
+// that may have changed it.
+onMounted(readChildrenText);
+onUpdated(readChildrenText);
+
+watch(
+  () => [getAnimator?.(), childrenText.value] as const,
+  ([currentAnimator, text], _previous, onCleanup) => {
+    const root = rootBox.current;
+    const content = contentBox.current;
+
+    if (!currentAnimator || !text.length || !root || !content) {
+      return;
+    }
+
+    if (!props.fixed) {
+      const { settings } = currentAnimator.node;
+      const durationEnter = getAnimationTextDuration({
+        length: text.length,
+        maxDuration: settings.duration.enter,
+      });
+      const durationExit = getAnimationTextDuration({
+        length: text.length,
+        maxDuration: settings.duration.exit,
+      });
+
+      currentAnimator.node.control.setSettings({
+        duration: { enter: durationEnter, exit: durationExit },
+      });
+    }
+
+    const transition = (duration: number, isEntering: boolean): void => {
+      // Props read here are live at call time but untracked (same as Solid,
+      // where the subscription callback runs outside the reactive context).
+      // Only `fixed` above is tracked and re-subscribes.
+      const baseOptions = {
+        rootElement: root,
+        contentElement: content,
+        duration,
+        isEntering,
+        easing: props.easing,
+        hideOnExited: props.hideOnExited,
+        hideOnEntered: props.hideOnEntered,
+      };
+
+      transitionControl?.cancel();
+      if (props.manager === 'decipher') {
+        transitionControl = animateTextDecipher({ ...baseOptions, characters: props.characters });
+      } else {
+        transitionControl = animateTextSequence({
+          ...baseOptions,
+          blink: props.blink,
+          blinkDuration: props.blinkDuration,
+        });
+      }
+    };
+
+    const unsubscribe = currentAnimator.node.subscribe((node) => {
+      switch (node.state) {
+        case 'entering': {
+          transition(node.settings.duration.enter, true);
+          break;
+        }
+        case 'entered': {
+          // If the node is subscribed when the state is entered right away,
+          // then there was not an initial animation of entering, so run animations.
+          if (!transitionControl) {
+            transition(node.settings.duration.enter, true);
+          }
+          break;
+        }
+        case 'exiting': {
+          transition(node.settings.duration.exit, false);
+          break;
+        }
+      }
+    });
+
+    onCleanup(() => {
+      unsubscribe();
+      transitionControl?.cancel();
+      transitionControl = null;
+    });
+  },
+  { immediate: true, flush: 'post' },
+);
+</script>
+
+<template>
+  <component
+    :is="as"
+    :ref="setElementRef"
+    :class="cx('elyndra-text-text', props.className)"
+    :style="rootStyle"
+  >
+    <span
+      :ref="setContentRef"
+      :class="cx('elyndra-text-text__content', props.contentClassName)"
+      :style="contentStyle"
+    >
+      <slot />
+    </span>
+  </component>
+</template>

package/src/Text/index.ts

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

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './Text/index.js';
+export type * from './types.js';

package/src/types.ts

@@ -0,0 +1,31 @@
+import type { CSSProperties } from 'vue';
+import type { Easing } from '@elyndra/animated';
+import type { AnimateTextManager } from '@elyndra/text';
+import type { ElementRef } from '@elyndra/vue-tools';
+
+interface TextProps<E extends HTMLElement = HTMLSpanElement> {
+  as?: keyof HTMLElementTagNameMap;
+  className?: string;
+  style?: CSSProperties;
+  contentClassName?: string;
+  contentStyle?: CSSProperties;
+  elementRef?: ElementRef<E>;
+  manager?: AnimateTextManager;
+  easing?: Easing;
+  /**
+   * If the duration of the animation should be fixed by the parent Animator
+   * or dynamic according to its children.
+   */
+  fixed?: boolean;
+  /**
+   * In manager sequence, add a blinking element at the end of the currently
+   * displayed text.
+   */
+  blink?: boolean;
+  blinkDuration?: number;
+  characters?: string;
+  hideOnEntered?: boolean;
+  hideOnExited?: boolean;
+}
+
+export type { ElementRef, TextProps };

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;
+}