@elyndra/svelte-text 1.2.0

package/package.json

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

@@ -0,0 +1,145 @@
+<script lang="ts">
+  import type { Animation } from '@elyndra/animated';
+  import { useAnimator } from '@elyndra/svelte-animator';
+  import { animateTextDecipher, animateTextSequence, getAnimationTextDuration } from '@elyndra/text';
+  import { cx } from '@elyndra/tools';
+  import { toStyleText } from '../internal/style.js';
+  import type { TextProps } from './types.js';
+
+  // No destructured rest: only direct `props.*` reads stay reactive.
+  const props: TextProps = $props();
+
+  const getAnimator = useAnimator();
+  const animator = $derived(getAnimator?.());
+
+  let rootElement: HTMLElement | null = $state(null);
+  let contentElement: HTMLSpanElement | null = $state(null);
+  let childrenText = $state('');
+  let transitionControl: Animation | null = null;
+
+  $effect(() => {
+    // Track children so the text snapshot follows content updates.
+    void props.children;
+    childrenText = contentElement?.textContent ?? '';
+  });
+
+  $effect(() => {
+    const currentAnimator = animator;
+    const text = childrenText;
+    const root = rootElement;
+    const content = contentElement;
+
+    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 => {
+      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;
+        }
+      }
+    });
+
+    return () => {
+      unsubscribe();
+      transitionControl?.cancel();
+      transitionControl = null;
+    };
+  });
+
+  $effect(() => {
+    const target = rootElement;
+    const ref = props.elementRef;
+
+    if (typeof ref === 'function') {
+      ref(target);
+    } else if (ref) {
+      ref.current = target;
+    }
+  });
+
+  // Snapshot visibility like React/Preact render: the node state is vanilla
+  // (not a signal), live show/hide during transitions is owned by the
+  // animation above.
+  const contentVisibility = $derived(
+    animator
+      ? ((animator.node.state === 'exited' && (props.hideOnExited ?? true)) ||
+          (animator.node.state === 'entered' && props.hideOnEntered)
+          ? 'hidden'
+          : undefined)
+      : undefined,
+  );
+  const styleText = $derived(toStyleText({ position: 'relative' }, props.style));
+  const contentStyleText = $derived(
+    toStyleText({ position: 'relative' }, contentVisibility ? { visibility: contentVisibility } : undefined, props.contentStyle),
+  );
+</script>
+
+<svelte:element
+  this={props.as ?? 'p'}
+  bind:this={rootElement}
+  id={props.id}
+  class={cx('elyndra-text-text', props.className)}
+  style={styleText}
+>
+  <span
+    bind:this={contentElement}
+    class={cx('elyndra-text-text__content', props.contentClassName)}
+    style={contentStyleText}
+  >
+    {@render props.children?.()}
+  </span>
+</svelte:element>

package/src/Text/Text.test.ts

@@ -0,0 +1,25 @@
+import { render } from '@testing-library/svelte';
+import type { Component } from 'svelte';
+import { createRawSnippet, type Snippet } from 'svelte';
+import { expect, test } from 'vitest';
+import Text from './Text.svelte';
+
+const text = (html: string): Snippet =>
+  createRawSnippet(() => ({
+    render: () => html,
+  }));
+
+// `.svelte` components are `unknown` in-repo (ambient decl, tests only).
+const textComponent = Text as Component;
+
+test('Should render component classes and content with default "p" element', () => {
+  const { container } = render(textComponent, {
+    children: text('<span>Furutistic <b>Sci-Fi</b> UI Web Framework</span>'),
+  });
+  const element = container.querySelector('p') as HTMLElement;
+  expect(element.classList.contains('elyndra-text-text')).toBe(true);
+  expect(element.tagName).toBe('P');
+  const contentEl = element.querySelector('.elyndra-text-text__content') as HTMLElement;
+  expect(contentEl.classList.contains('elyndra-text-text__content')).toBe(true);
+  expect(contentEl.textContent).toContain('Furutistic');
+});

package/src/Text/index.ts

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

package/src/Text/types.ts

@@ -0,0 +1,34 @@
+import type { Easing } from '@elyndra/animated';
+import type { AnimateTextManager } from '@elyndra/text';
+import type { Snippet } from 'svelte';
+
+type ElementRef<E> = ((element: E | null) => void) | { current: E | null };
+
+interface TextProps {
+  as?: string;
+  className?: string;
+  style?: string | Record<string, string | number | undefined>;
+  contentClassName?: string;
+  contentStyle?: string | Record<string, string | number | undefined>;
+  elementRef?: ElementRef<HTMLElement>;
+  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;
+  id?: string;
+  children?: Snippet;
+}
+
+export type { TextProps };

package/src/index.ts

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

package/src/internal/style.ts

@@ -0,0 +1,51 @@
+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.
+ */
+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;
+}