@heyramzi/ui 0.0.0-stage → 6.1.0

package/src/effects/animated-beam/path-calculator.svelte.ts

@@ -0,0 +1,70 @@
+import type { AnchorPosition } from "./types.js";
+
+function anchorX(
+  rect: DOMRect,
+  containerLeft: number,
+  anchor: AnchorPosition,
+  offset: number,
+): number {
+  const left = rect.left - containerLeft;
+  if (anchor === "left") return left + offset;
+  if (anchor === "right") return left + rect.width + offset;
+  return left + rect.width / 2 + offset;
+}
+
+export function usePathCalculator() {
+  let pathD = $state("");
+  let svgDimensions = $state({ width: 0, height: 0 });
+
+  function calculatePath(
+    containerRef: HTMLElement | null,
+    fromRef: HTMLElement | null,
+    toRef: HTMLElement | null,
+    curvature: number,
+    startXOffset: number,
+    startYOffset: number,
+    endXOffset: number,
+    endYOffset: number,
+    fromAnchor: AnchorPosition = "center",
+    toAnchor: AnchorPosition = "center",
+  ) {
+    if (!containerRef || !fromRef || !toRef) return;
+
+    const containerRect = containerRef.getBoundingClientRect();
+    const rectA = fromRef.getBoundingClientRect();
+    const rectB = toRef.getBoundingClientRect();
+
+    svgDimensions = { width: containerRect.width, height: containerRect.height };
+
+    const startX = anchorX(rectA, containerRect.left, fromAnchor, startXOffset);
+    const startY = rectA.top - containerRect.top + rectA.height / 2 + startYOffset;
+    const endX = anchorX(rectB, containerRect.left, toAnchor, endXOffset);
+    const endY = rectB.top - containerRect.top + rectB.height / 2 + endYOffset;
+
+    // A cubic with horizontal handles, not a quadratic through a raised midpoint.
+
+    // The quadratic put its single control point at `midY - curvature`, which for a fan into one node lands past the far end:
+
+    // the top beam dove below the hub and crossed the middle beam before arriving, and three beams bundled into a lens for the last stretch.
+
+    // Handles along the axis of travel make each beam leave and arrive perpendicular to its anchor, so a fan converges at the anchor and nowhere else.
+
+    // `curvature` still bows the middle, and zero still draws a straight line between two anchors at the same height.
+    const span = Math.abs(endX - startX);
+    const handle = Math.max(span * 0.5, 24);
+    const direction = endX >= startX ? 1 : -1;
+    const c1x = startX + handle * direction;
+    const c2x = endX - handle * direction;
+    pathD = `M ${startX},${startY} C ${c1x},${startY - curvature} ${c2x},${endY - curvature} ${endX},${endY}`;
+  }
+
+  return {
+    get pathD() {
+      return pathD;
+    },
+    get svgDimensions() {
+      return svgDimensions;
+    },
+    calculatePath,
+  };
+}

package/src/effects/animated-beam/types.ts

@@ -0,0 +1,23 @@
+export type AnchorPosition = "center" | "left" | "right";
+
+export interface AnimatedBeamProps {
+  class?: string;
+  containerRef: HTMLElement | null;
+  fromRef: HTMLElement | null;
+  toRef: HTMLElement | null;
+  curvature?: number;
+  reverse?: boolean;
+  pathColor?: string;
+  pathWidth?: number;
+  pathOpacity?: number;
+  gradientStartColor?: string;
+  gradientStopColor?: string;
+  delay?: number;
+  duration?: number;
+  startXOffset?: number;
+  startYOffset?: number;
+  endXOffset?: number;
+  endYOffset?: number;
+  fromAnchor?: AnchorPosition;
+  toAnchor?: AnchorPosition;
+}

package/src/effects/border-beam/BorderBeam.svelte

@@ -0,0 +1,223 @@
+<script lang="ts" module>
+	import type { ResolvedTheme } from "./presets.js";
+	import type { BorderBeamProps } from "./types.js";
+</script>
+
+<script lang="ts">
+	// IMPORTS
+	import { onDestroy, onMount } from "svelte";
+	import { generateCss } from "./css.js";
+	import { sizePresets, sizeThemePresets } from "./presets.js";
+	import { registerBorderBeamProperties } from "./register-properties.js";
+
+	// PROPS
+	let {
+		children,
+		size = "md",
+		colorVariant = "colorful",
+		theme = "dark",
+		staticColors = false,
+		duration,
+		active = true,
+		borderRadius,
+		brightness = 1.3,
+		saturation,
+		hueRange = 30,
+		strength = 1,
+		colors,
+		bloom = true,
+		pauseWhenOffscreen = true,
+		class: className,
+		onActivate,
+		onDeactivate,
+		onanimationend: userAnimationEnd,
+		style: userStyle,
+		...rest
+	}: BorderBeamProps = $props();
+
+	// STATE
+	const uid = `bb-${Math.random().toString(36).slice(2, 10)}`;
+	let container = null;
+	let systemTheme = $state<ResolvedTheme>("dark");
+	let isActive = $state(false);
+	let isFading = $state(false);
+	let detectedRadius = $state<number | null>(null);
+	let isOffscreen = $state(false);
+	let isDocHidden = $state(false);
+
+	// DERIVED
+	const resolvedTheme = $derived(theme === "auto" ? systemTheme : theme);
+	const sizeConfig = $derived(sizePresets[size]);
+	const themeColorsForSize = $derived(sizeThemePresets[size][resolvedTheme]);
+	const effectiveRadius = $derived(borderRadius ?? detectedRadius ?? sizeConfig.borderRadius);
+	const effectiveDuration = $derived(duration ?? (size === "line" ? 2.4 : 1.96));
+	const effectiveSaturation = $derived(saturation ?? themeColorsForSize.saturation);
+	const effectiveHueRange = $derived(size === "line" ? Math.min(hueRange, 13) : hueRange);
+	const resolvedStatic = $derived(colorVariant === "mono" ? true : staticColors);
+
+	const css = $derived(
+		generateCss({
+			id: uid,
+			borderRadius: effectiveRadius,
+			borderWidth: sizeConfig.borderWidth,
+			duration: effectiveDuration,
+			strokeOpacity: themeColorsForSize.strokeOpacity,
+			innerOpacity: themeColorsForSize.innerOpacity,
+			bloomOpacity: themeColorsForSize.bloomOpacity,
+			innerShadow: themeColorsForSize.innerShadow,
+			size,
+			colorVariant,
+			staticColors: resolvedStatic,
+			brightness,
+			saturation: effectiveSaturation,
+			hueRange: effectiveHueRange,
+			theme: resolvedTheme,
+			colors,
+			bloom,
+		}),
+	);
+
+	// WHY: paused state combines viewport visibility and document visibility.
+	// Either being false freezes the beam via `animation-play-state: paused`.
+	const paused = $derived(pauseWhenOffscreen && (isOffscreen || isDocHidden));
+
+	const clampedStrength = $derived(Math.max(0, Math.min(1, strength)));
+
+	// EFFECTS
+	let mediaQuery: MediaQueryList | null = null;
+	let radiusObserver: MutationObserver | null = null;
+	let visibilityObserver: IntersectionObserver | null = null;
+
+	onMount(() => {
+		// WHY: shadow-DOM consumers (chrome extensions, embedded widgets) hit a Chromium edge case where @property at-rules emitted in an injected stylesheet do not register reliably for the shadow scope.
+
+		// Without the registration, the angle property is treated as a string, the keyframe can't interpolate, and the beam appears frozen with one repaint per iteration.
+
+		// CSS.registerProperty is global and document-scoped so it always succeeds, and duplicate registrations are silently ignored.
+		registerBorderBeamProperties(uid, size);
+
+		if (typeof window !== "undefined") {
+			mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+			systemTheme = mediaQuery.matches ? "dark" : "light";
+			const handler = (e: MediaQueryListEvent) => {
+				systemTheme = e.matches ? "dark" : "light";
+			};
+			mediaQuery.addEventListener("change", handler);
+			return () => mediaQuery?.removeEventListener("change", handler);
+		}
+	});
+
+	$effect(() => {
+		if (borderRadius != null || !container) return;
+		const detect = () => {
+			const first = container?.firstElementChild as HTMLElement | null;
+			if (!first) return;
+			const cs = getComputedStyle(first);
+			const r = parseFloat(cs.borderTopLeftRadius);
+			if (!isNaN(r) && r > 0) detectedRadius = r;
+		};
+		detect();
+		radiusObserver = new MutationObserver(detect);
+		radiusObserver.observe(container, { childList: true, subtree: false });
+		return () => radiusObserver?.disconnect();
+	});
+
+	$effect(() => {
+		if (active && !isActive && !isFading) {
+			isActive = true;
+		} else if (!active && isActive && !isFading) {
+			isFading = true;
+		}
+	});
+
+	// WHY: pause beam animation while the host is offscreen or the tab is hidden.
+
+	// CSS animations keep ticking on backgrounded tabs in some browsers, and an offscreen beam burns rasterization budget for nothing.
+	$effect(() => {
+		if (!pauseWhenOffscreen || !container || typeof window === "undefined") return;
+
+		visibilityObserver = new IntersectionObserver(
+			(entries) => {
+				const entry = entries[0];
+				if (entry) isOffscreen = !entry.isIntersecting;
+			},
+			{ rootMargin: "64px" },
+		);
+		visibilityObserver.observe(container);
+
+		const onVisChange = () => {
+			isDocHidden = document.hidden;
+		};
+		isDocHidden = document.hidden;
+		document.addEventListener("visibilitychange", onVisChange);
+
+		return () => {
+			visibilityObserver?.disconnect();
+			visibilityObserver = null;
+			document.removeEventListener("visibilitychange", onVisChange);
+		};
+	});
+
+	onDestroy(() => {
+		mediaQuery = null;
+		radiusObserver?.disconnect();
+		visibilityObserver?.disconnect();
+	});
+
+	// FUNCTIONS
+	function handleAnimationEnd(e: AnimationEvent) {
+		const name = e.animationName;
+		if (name.includes("fade-out")) {
+			isActive = false;
+			isFading = false;
+			onDeactivate?.();
+		} else if (name.includes("fade-in")) {
+			onActivate?.();
+		}
+		userAnimationEnd?.(e as AnimationEvent & { currentTarget: EventTarget & HTMLDivElement });
+	}
+
+	// WHY: imperative CSS injection via Svelte action. The rolldown-based
+
+	// vite-plugin-svelte preprocessor does naive substring matching for the stylesheet markup, so an inline @html template literal containing the markup tag would trip postcss on the interpolated text.
+
+	// The action route attaches a real stylesheet node next to the host, bypassing the HTML parser entirely.
+	function injectStyle(node: Element, value: string) {
+		const styleEl = node.ownerDocument.createElement("style");
+		styleEl.textContent = value;
+		node.parentNode?.insertBefore(styleEl, node);
+		// WHY: $derived recomputes on any prop change, but the CSS string is
+		// often identical across reruns. Skip the DOM write so the browser
+		// doesn't re-parse the stylesheet for no reason.
+		let last = value;
+		return {
+			update(next: string) {
+				if (next === last) return;
+				last = next;
+				styleEl.textContent = next;
+			},
+			destroy() {
+				styleEl.remove();
+			},
+		};
+	}
+</script>
+
+<!-- MARKUP -->
+<div
+	bind:this={container}
+	{...rest}
+	data-beam={uid}
+	data-active={isActive && !isFading ? "" : undefined}
+	data-fading={isFading ? "" : undefined}
+	data-paused={paused ? "" : undefined}
+	class={className}
+	style="--beam-strength: {clampedStrength};{userStyle ?? ''}"
+	onanimationend={handleAnimationEnd}
+	use:injectStyle={css}
+>
+	{@render children()}
+	{#if bloom}
+		<div data-beam-bloom></div>
+	{/if}
+</div>

package/src/effects/border-beam/css.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "vite-plus/test";
+import { generateCss, type CssOptions } from "./css.js";
+
+function options(overrides: Partial<CssOptions> = {}): CssOptions {
+  return {
+    id: "bb-test",
+    borderRadius: 16,
+    borderWidth: 1,
+    duration: 1.96,
+    strokeOpacity: 0.48,
+    innerOpacity: 0.7,
+    bloomOpacity: 0.8,
+    innerShadow: "rgba(255, 255, 255, 0.27)",
+    size: "md",
+    colorVariant: "colorful",
+    staticColors: false,
+    brightness: 1.3,
+    saturation: 1.2,
+    hueRange: 30,
+    theme: "dark",
+    bloom: true,
+    ...overrides,
+  };
+}
+
+describe("generateCss", () => {
+  test("cycles the hue when the colours are the beam's own", () => {
+    const css = generateCss(options());
+
+    expect(css).toContain("animation: beam-hue-shift-bb-test");
+    expect(css).toContain("hue-rotate(-30deg) brightness(1.30) saturate(1.20)");
+  });
+
+  test("keeps brightness and saturation when the colours are fixed", () => {
+    const css = generateCss(options({ staticColors: true }));
+
+    expect(css).not.toContain("beam-hue-shift");
+    expect(css).toContain("filter: brightness(1.30) saturate(1.20);");
+  });
+
+  test("keeps the line bloom's blur when the colours are fixed", () => {
+    const css = generateCss(options({ size: "line", staticColors: true }));
+
+    expect(css).toContain("filter: blur(8px) brightness(1.30) saturate(1.20);");
+  });
+});