@elyndra/astro-text 1.2.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@elyndra/astro-text",
+  "version": "1.2.0",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Elyndra text components for Astro (SSR shells with vanilla client hydration)",
+  "keywords": [
+    "elyndra",
+    "ui",
+    "front-end",
+    "framework",
+    "scifi",
+    "sci-fi",
+    "science-fiction",
+    "astro"
+  ],
+  "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",
+    "./Text": "./src/Text/Text.astro",
+    "./client": "./src/client/textClient.ts"
+  },
+  "types": "./src/index.ts",
+  "module": "./src/index.ts",
+  "main": "./src/index.ts",
+  "peerDependencies": {
+    "astro": "7.3.2"
+  },
+  "dependencies": {
+    "@elyndra/animated": "^1.2.0",
+    "@elyndra/text": "^1.2.0",
+    "@elyndra/tools": "^1.2.0",
+    "tslib": "2.8.1"
+  },
+  "scripts": {
+    "build": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/Text/Text.astro

@@ -0,0 +1,25 @@
+---
+import type { TextElementProps } from '../types.js';
+
+interface Props extends TextElementProps {}
+
+const { as: Tag = 'p', className, contentClassName, ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-text-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<Tag id={nodeId} data-elyndra-text class={className} style="position: relative;">
+  <span data-elyndra-text-content class={contentClassName}><slot /></span>
+</Tag>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initTextElement } from '../client/textClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof HTMLElement) {
+    initTextElement(element, serializable);
+  }
+</script>

package/src/Text/Text.test.ts

@@ -0,0 +1,26 @@
+// @vitest-environment node
+// Render tests assert on SSR strings, so they run in node: under jsdom the
+// Astro plugin compiles `.astro` imports for the browser (client stub).
+import { expect, test } from 'vitest';
+import { renderComponent } from '../testUtils/index.js';
+import Text from './Text.astro';
+
+test('Should render children inside the text shell', async () => {
+  const html = await renderComponent(Text, {
+    slots: { default: 'hello' },
+  });
+
+  expect(html).toContain('data-elyndra-text');
+  expect(html).toContain('data-elyndra-text-content');
+  expect(html).toContain('hello');
+});
+
+test('Should pass serializable settings to the client script', async () => {
+  const html = await renderComponent(Text, {
+    props: { manager: 'decipher', blink: false },
+    slots: { default: 'x' },
+  });
+
+  expect(html).toContain('data-elyndra-text');
+  expect(html).toContain('initTextElement');
+});

package/src/astro.d.ts

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

package/src/client/textClient.test.ts

@@ -0,0 +1,54 @@
+import { beforeEach, expect, test } from 'vitest';
+import { initTextElement } from './textClient.js';
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+const mountText = (text = 'hello'): HTMLElement => {
+  const element = document.createElement('p');
+  element.setAttribute('data-elyndra-text', '');
+  const content = document.createElement('span');
+  content.setAttribute('data-elyndra-text-content', '');
+  content.textContent = text;
+  element.appendChild(content);
+  document.body.appendChild(element);
+  return element;
+};
+
+test('Should run the entering animation and mark the node', () => {
+  const element = mountText();
+
+  expect(() => initTextElement(element, { blink: false, duration: 0.05 })).not.toThrow();
+
+  expect(element.hasAttribute('data-elyndra-text-node')).toBe(true);
+});
+
+test('Should support the decipher manager', () => {
+  const element = mountText();
+
+  expect(() =>
+    initTextElement(element, { manager: 'decipher', blink: false, duration: 0.05 }),
+  ).not.toThrow();
+
+  expect(element.hasAttribute('data-elyndra-text-node')).toBe(true);
+});
+
+test('Should cancel and unmark on dispose, idempotently', () => {
+  const element = mountText();
+  const handle = initTextElement(element, { blink: false, duration: 0.05 });
+
+  handle.dispose();
+  handle.dispose();
+
+  expect(element.hasAttribute('data-elyndra-text-node')).toBe(false);
+});
+
+test('Should cancel the previous animation on second init', () => {
+  const element = mountText();
+
+  initTextElement(element, { blink: false, duration: 0.05 });
+  initTextElement(element, { blink: false, duration: 0.05 });
+
+  expect(element.hasAttribute('data-elyndra-text-node')).toBe(true);
+});

package/src/client/textClient.ts

@@ -0,0 +1,75 @@
+import type { Animation } from '@elyndra/animated';
+import {
+  animateTextDecipher,
+  animateTextSequence,
+  getAnimationTextDuration,
+} from '@elyndra/text';
+import { filterProps } from '@elyndra/tools';
+import type { TextElementProps } from '../types.js';
+
+const TEXT_NODE_MARKER = 'data-elyndra-text-node';
+const TEXT_CONTENT_SELECTOR = '[data-elyndra-text-content]';
+
+interface TextHandle {
+  readonly dispose: () => void;
+}
+
+const textByElement = new WeakMap<Element, TextHandle>();
+
+/**
+ * Hydrates one text element: runs the entering animation once from the
+ * serializable settings (the island replacement for the animator
+ * subscription: no animator states to follow). Idempotent: re-running
+ * cancels the previous animation first.
+ */
+const initTextElement = (element: HTMLElement, props: TextElementProps): TextHandle => {
+  textByElement.get(element)?.dispose();
+
+  const contentElement = element.querySelector(TEXT_CONTENT_SELECTOR);
+
+  let animation: Animation | undefined;
+
+  if (contentElement instanceof HTMLElement) {
+    const length = contentElement.textContent?.length ?? 0;
+    const duration = getAnimationTextDuration({ length, maxDuration: props.duration ?? 1 });
+    const baseOptions = {
+      rootElement: element,
+      contentElement,
+      duration,
+      isEntering: true,
+      ...filterProps({
+        easing: typeof props.easing === 'string' ? props.easing : undefined,
+        hideOnExited: props.hideOnExited,
+        hideOnEntered: props.hideOnEntered,
+      }),
+    };
+
+    animation =
+      props.manager === 'decipher'
+        ? animateTextDecipher({ ...baseOptions, ...filterProps({ characters: props.characters }) })
+        : animateTextSequence({
+            ...baseOptions,
+            ...filterProps({ blink: props.blink, blinkDuration: props.blinkDuration }),
+          });
+  }
+
+  element.setAttribute(TEXT_NODE_MARKER, '');
+
+  const handle: TextHandle = {
+    dispose: () => {
+      if (textByElement.get(element) !== handle) {
+        return;
+      }
+      textByElement.delete(element);
+      element.removeAttribute(TEXT_NODE_MARKER);
+      animation?.cancel();
+    },
+  };
+
+  textByElement.set(element, handle);
+
+  return handle;
+};
+
+export { initTextElement, TEXT_CONTENT_SELECTOR, TEXT_NODE_MARKER };
+export type { TextHandle };

package/src/index.ts

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

package/src/testUtils/index.ts

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

package/src/testUtils/renderComponent.ts

@@ -0,0 +1,16 @@
+import {
+  type ContainerRenderOptions,
+  experimental_AstroContainer as AstroContainer,
+} from 'astro/container';
+
+/**
+ * Renders an `.astro` component to a string. In-repo `.astro` imports are
+ * `unknown` (ambient declaration, tests only), so the factory type is
+ * inferred from the container itself — no drift if Astro changes it.
+ */
+const renderComponent = async (component: unknown, options?: ContainerRenderOptions): Promise<string> => {
+  const container = await AstroContainer.create();
+  return container.renderToString(component as Parameters<typeof container.renderToString>[0], options);
+};
+
+export { renderComponent };

package/src/types.ts

@@ -0,0 +1,35 @@
+import type { Easing } from '@elyndra/animated';
+import type { AnimateTextManager } from '@elyndra/text';
+
+/**
+ * Serializable subset of the text settings. Only JSON crosses the Astro
+ * server/client boundary (`define:vars`):
+ * - `easing` crosses as a name: easing functions are excluded.
+ * - `duration` is a max: the client derives the effective duration from the
+ *   content length via `getAnimationTextDuration` (the React non-fixed mode).
+ * - Excluded: `manager` instances (the `manager` prop selects the vanilla
+ *   `sequence`/`decipher` runner by name instead), `elementRef`,
+ *   `children` (default slot), the Animator subscription (`useAnimator`):
+ *   islands run the entering animation once on hydration instead of
+ *   following animator states, and `fixed` (no animator to fix from).
+ * - `Text` exposes no transition callbacks in React either, so no
+ *   CustomEvent replacement is needed.
+ */
+interface TextSerializableSettings {
+  manager?: AnimateTextManager;
+  easing?: Easing;
+  duration?: number;
+  blink?: boolean;
+  blinkDuration?: number;
+  characters?: string;
+  hideOnEntered?: boolean;
+  hideOnExited?: boolean;
+}
+
+interface TextElementProps extends TextSerializableSettings {
+  as?: string;
+  className?: string;
+  contentClassName?: string;
+}
+
+export type { TextElementProps, TextSerializableSettings };