@elyndra/svelte-bgs 1.2.0

package/package.json

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

@@ -0,0 +1,59 @@
+<script lang="ts">
+  import { createBackgroundDots } from '@elyndra/bgs';
+  import { useAnimator } from '@elyndra/svelte-animator';
+  import { cx } from '@elyndra/tools';
+  import { positionedStyleText, toStyleText } from '../internal/styles.js';
+  import type { DotsProps } from './types.js';
+
+  // No destructured rest: only direct `props.*` reads stay reactive.
+  const props: DotsProps = $props();
+
+  const getAnimator = useAnimator();
+  let canvas: HTMLCanvasElement | null = $state(null);
+
+  // The props object stays live, so the vanilla background always reads the
+  // latest settings, same as the per-render ref update in React/Preact.
+  // Intentionally captures the props proxy (Solid does the same).
+  // svelte-ignore state_referenced_locally
+  const settingsRef: { current: DotsProps } = { current: props };
+
+  $effect(() => {
+    const animator = getAnimator?.();
+    const target = canvas;
+
+    if (!target) {
+      return;
+    }
+
+    const background = createBackgroundDots({
+      canvas: target,
+      animator: animator?.node,
+      settingsRef,
+    });
+
+    return () => background.cancel();
+  });
+
+  $effect(() => {
+    const target = canvas;
+    const ref = props.elementRef;
+
+    if (typeof ref === 'function') {
+      ref(target);
+    } else if (ref) {
+      ref.current = target;
+    }
+  });
+
+  const styleText = $derived(toStyleText((props.positioned ?? true) ? positionedStyleText : undefined, props.style));
+</script>
+
+<!-- `role="presentation"` mirrors the React/Solid adapters: decorative background canvas. -->
+<!-- svelte-ignore a11y_no_interactive_element_to_noninteractive_role -->
+<canvas
+  role="presentation"
+  bind:this={canvas}
+  id={props.id}
+  class={cx('elyndra-bgs-dots', props.className)}
+  style={styleText}
+></canvas>

package/src/Dots/Dots.test.ts

@@ -0,0 +1,16 @@
+import { render } from '@testing-library/svelte';
+import type { Component } from 'svelte';
+import { expect, test, vi } from 'vitest';
+import Dots from './Dots.svelte';
+
+HTMLCanvasElement.prototype.getContext = vi.fn<() => void>() as unknown as typeof HTMLCanvasElement.prototype.getContext;
+
+// `.svelte` components are `unknown` in-repo (ambient decl, tests only).
+const dots = Dots as Component;
+
+test('Should render canvas element with elyndra class', () => {
+  const { container } = render(dots, { color: 'cyan' });
+  const element = container.querySelector('canvas') as HTMLElement;
+  expect(element.tagName).toBe('CANVAS');
+  expect(element.classList.contains('elyndra-bgs-dots')).toBe(true);
+});

package/src/Dots/index.ts

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

package/src/Dots/types.ts

@@ -0,0 +1,13 @@
+import type { CreateBackgroundDotsSettings } from '@elyndra/bgs';
+
+type ElementRef<E> = ((element: E | null) => void) | { current: E | null };
+
+interface DotsProps extends CreateBackgroundDotsSettings {
+  elementRef?: ElementRef<HTMLCanvasElement>;
+  id?: string;
+  className?: string;
+  style?: string | Record<string, string | number | undefined>;
+  positioned?: boolean;
+}
+
+export type { DotsProps };

package/src/GridLines/GridLines.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+  import { createBackgroundGridLines } from '@elyndra/bgs';
+  import { useAnimator } from '@elyndra/svelte-animator';
+  import { cx } from '@elyndra/tools';
+  import { positionedStyleText, toStyleText } from '../internal/styles.js';
+  import type { GridLinesProps } from './types.js';
+
+  // No destructured rest: only direct `props.*` reads stay reactive.
+  const props: GridLinesProps = $props();
+
+  const getAnimator = useAnimator();
+  let canvas: HTMLCanvasElement | null = $state(null);
+
+  // The props object stays live, so the vanilla background always reads the
+  // latest settings, same as the per-render ref update in React/Preact.
+  // Intentionally captures the props proxy (Solid does the same).
+  // svelte-ignore state_referenced_locally
+  const settingsRef: { current: GridLinesProps } = { current: props };
+
+  $effect(() => {
+    const animator = getAnimator?.();
+    const target = canvas;
+
+    if (!target) {
+      return;
+    }
+
+    const background = createBackgroundGridLines({
+      canvas: target,
+      animator: animator?.node,
+      settingsRef,
+    });
+
+    return () => background.cancel();
+  });
+
+  $effect(() => {
+    const target = canvas;
+    const ref = props.elementRef;
+
+    if (typeof ref === 'function') {
+      ref(target);
+    } else if (ref) {
+      ref.current = target;
+    }
+  });
+
+  const styleText = $derived(toStyleText((props.positioned ?? true) ? positionedStyleText : undefined, props.style));
+</script>
+
+<!-- `role="presentation"` mirrors the React/Solid adapters: decorative background canvas. -->
+<!-- svelte-ignore a11y_no_interactive_element_to_noninteractive_role -->
+<canvas
+  role="presentation"
+  bind:this={canvas}
+  id={props.id}
+  class={cx('elyndra-bgs-gridlines', props.className)}
+  style={styleText}
+></canvas>

package/src/GridLines/GridLines.test.ts

@@ -0,0 +1,16 @@
+import { render } from '@testing-library/svelte';
+import type { Component } from 'svelte';
+import { expect, test, vi } from 'vitest';
+import GridLines from './GridLines.svelte';
+
+HTMLCanvasElement.prototype.getContext = vi.fn<() => void>() as unknown as typeof HTMLCanvasElement.prototype.getContext;
+
+// `.svelte` components are `unknown` in-repo (ambient decl, tests only).
+const gridLines = GridLines as Component;
+
+test('Should render canvas element with elyndra class', () => {
+  const { container } = render(gridLines, { color: 'cyan' });
+  const element = container.querySelector('canvas') as HTMLElement;
+  expect(element.tagName).toBe('CANVAS');
+  expect(element.classList.contains('elyndra-bgs-gridlines')).toBe(true);
+});

package/src/GridLines/index.ts

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

package/src/GridLines/types.ts

@@ -0,0 +1,13 @@
+import type { CreateBackgroundGridLinesSettings } from '@elyndra/bgs';
+
+type ElementRef<E> = ((element: E | null) => void) | { current: E | null };
+
+interface GridLinesProps extends CreateBackgroundGridLinesSettings {
+  elementRef?: ElementRef<HTMLCanvasElement>;
+  id?: string;
+  className?: string;
+  style?: string | Record<string, string | number | undefined>;
+  positioned?: boolean;
+}
+
+export type { GridLinesProps };

package/src/MovingLines/MovingLines.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+  import { createBackgroundMovingLines } from '@elyndra/bgs';
+  import { useAnimator } from '@elyndra/svelte-animator';
+  import { cx } from '@elyndra/tools';
+  import { positionedStyleText, toStyleText } from '../internal/styles.js';
+  import type { MovingLinesProps } from './types.js';
+
+  // No destructured rest: only direct `props.*` reads stay reactive.
+  const props: MovingLinesProps = $props();
+
+  const getAnimator = useAnimator();
+  let canvas: HTMLCanvasElement | null = $state(null);
+
+  // The props object stays live, so the vanilla background always reads the
+  // latest settings, same as the per-render ref update in React/Preact.
+  // Intentionally captures the props proxy (Solid does the same).
+  // svelte-ignore state_referenced_locally
+  const settingsRef: { current: MovingLinesProps } = { current: props };
+
+  $effect(() => {
+    const animator = getAnimator?.();
+    const target = canvas;
+
+    if (!target) {
+      return;
+    }
+
+    const background = createBackgroundMovingLines({
+      canvas: target,
+      animator: animator?.node,
+      settingsRef,
+    });
+
+    return () => background.cancel();
+  });
+
+  $effect(() => {
+    const target = canvas;
+    const ref = props.elementRef;
+
+    if (typeof ref === 'function') {
+      ref(target);
+    } else if (ref) {
+      ref.current = target;
+    }
+  });
+
+  const styleText = $derived(toStyleText((props.positioned ?? true) ? positionedStyleText : undefined, props.style));
+</script>
+
+<!-- `role="presentation"` mirrors the React/Solid adapters: decorative background canvas. -->
+<!-- svelte-ignore a11y_no_interactive_element_to_noninteractive_role -->
+<canvas
+  role="presentation"
+  bind:this={canvas}
+  id={props.id}
+  class={cx('elyndra-bgs-movinglines', props.className)}
+  style={styleText}
+></canvas>

package/src/MovingLines/MovingLines.test.ts

@@ -0,0 +1,16 @@
+import { render } from '@testing-library/svelte';
+import type { Component } from 'svelte';
+import { expect, test, vi } from 'vitest';
+import MovingLines from './MovingLines.svelte';
+
+HTMLCanvasElement.prototype.getContext = vi.fn<() => void>() as unknown as typeof HTMLCanvasElement.prototype.getContext;
+
+// `.svelte` components are `unknown` in-repo (ambient decl, tests only).
+const movingLines = MovingLines as Component;
+
+test('Should render canvas element with elyndra class', () => {
+  const { container } = render(movingLines, { color: 'cyan' });
+  const element = container.querySelector('canvas') as HTMLElement;
+  expect(element.tagName).toBe('CANVAS');
+  expect(element.classList.contains('elyndra-bgs-movinglines')).toBe(true);
+});

package/src/MovingLines/index.ts

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

package/src/MovingLines/types.ts

@@ -0,0 +1,13 @@
+import type { CreateBackgroundMovingLinesSettings } from '@elyndra/bgs';
+
+type ElementRef<E> = ((element: E | null) => void) | { current: E | null };
+
+interface MovingLinesProps extends CreateBackgroundMovingLinesSettings {
+  elementRef?: ElementRef<HTMLCanvasElement>;
+  id?: string;
+  className?: string;
+  style?: string | Record<string, string | number | undefined>;
+  positioned?: boolean;
+}
+
+export type { MovingLinesProps };

package/src/Puffs/Puffs.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+  import { createBackgroundPuffs } from '@elyndra/bgs';
+  import { useAnimator } from '@elyndra/svelte-animator';
+  import { cx } from '@elyndra/tools';
+  import { positionedStyleText, toStyleText } from '../internal/styles.js';
+  import type { PuffsProps } from './types.js';
+
+  // No destructured rest: only direct `props.*` reads stay reactive.
+  const props: PuffsProps = $props();
+
+  const getAnimator = useAnimator();
+  let canvas: HTMLCanvasElement | null = $state(null);
+
+  // The props object stays live, so the vanilla background always reads the
+  // latest settings, same as the per-render ref update in React/Preact.
+  // Intentionally captures the props proxy (Solid does the same).
+  // svelte-ignore state_referenced_locally
+  const settingsRef: { current: PuffsProps } = { current: props };
+
+  $effect(() => {
+    const animator = getAnimator?.();
+    const target = canvas;
+
+    if (!target) {
+      return;
+    }
+
+    const background = createBackgroundPuffs({
+      canvas: target,
+      animator: animator?.node,
+      settingsRef,
+    });
+
+    return () => background.cancel();
+  });
+
+  $effect(() => {
+    const target = canvas;
+    const ref = props.elementRef;
+
+    if (typeof ref === 'function') {
+      ref(target);
+    } else if (ref) {
+      ref.current = target;
+    }
+  });
+
+  const styleText = $derived(toStyleText((props.positioned ?? true) ? positionedStyleText : undefined, props.style));
+</script>
+
+<!-- `role="presentation"` mirrors the React/Solid adapters: decorative background canvas. -->
+<!-- svelte-ignore a11y_no_interactive_element_to_noninteractive_role -->
+<canvas
+  role="presentation"
+  bind:this={canvas}
+  id={props.id}
+  class={cx('elyndra-bgs-puffs', props.className)}
+  style={styleText}
+></canvas>

package/src/Puffs/Puffs.test.ts

@@ -0,0 +1,16 @@
+import { render } from '@testing-library/svelte';
+import type { Component } from 'svelte';
+import { expect, test, vi } from 'vitest';
+import Puffs from './Puffs.svelte';
+
+HTMLCanvasElement.prototype.getContext = vi.fn<() => void>() as unknown as typeof HTMLCanvasElement.prototype.getContext;
+
+// `.svelte` components are `unknown` in-repo (ambient decl, tests only).
+const puffs = Puffs as Component;
+
+test('Should render canvas element with elyndra class', () => {
+  const { container } = render(puffs, { color: 'cyan' });
+  const element = container.querySelector('canvas') as HTMLElement;
+  expect(element.tagName).toBe('CANVAS');
+  expect(element.classList.contains('elyndra-bgs-puffs')).toBe(true);
+});

package/src/Puffs/index.ts

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

package/src/Puffs/types.ts

@@ -0,0 +1,13 @@
+import type { CreateBackgroundPuffsSettings } from '@elyndra/bgs';
+
+type ElementRef<E> = ((element: E | null) => void) | { current: E | null };
+
+interface PuffsProps extends CreateBackgroundPuffsSettings {
+  elementRef?: ElementRef<HTMLCanvasElement>;
+  id?: string;
+  className?: string;
+  style?: string | Record<string, string | number | undefined>;
+  positioned?: boolean;
+}
+
+export type { PuffsProps };

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './Dots/index.js';
+export * from './GridLines/index.js';
+export * from './MovingLines/index.js';
+export * from './Puffs/index.js';

package/src/internal/styles.ts

@@ -0,0 +1,54 @@
+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;
+};
+
+const positionedStyleText =
+  'position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%';
+
+export { positionedStyleText, 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;
+}