@heyramzi/ui 0.0.0-stage → 1.53.0

package/src/effects/marquee/Marquee.svelte

@@ -0,0 +1,160 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./Marquee.css";
+	import { cn } from "@heyramzi/utils";
+	import type { Snippet } from "svelte";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface MarqueeProps {
+		children: Snippet;
+		class?: string;
+		reverse?: boolean;
+		pauseOnHover?: boolean;
+		vertical?: boolean;
+		repeat?: number;
+		duration?: string;
+		gap?: string;
+		/** Scroll speed in px/s. Sets the loop time from the measured track, and wins over `duration`. */
+		speed?: number;
+		/** Fades both ends along the scroll axis. Any CSS length, such as `16px` or `13%`. */
+		fade?: string;
+		/** Waits this many ms before the first scroll starts. */
+		delay?: number;
+		/**
+		 * Scrolls only while the content is longer than the box, for a line of text with a max width.
+		 * The box shrinks to its content, drops its padding, and shows one still copy when it fits.
+		 */
+		overflowOnly?: boolean;
+		style?: string;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		children,
+		class: className = "",
+		reverse = false,
+		pauseOnHover = false,
+		vertical = false,
+		repeat = 4,
+		duration,
+		gap,
+		speed,
+		fade,
+		delay,
+		overflowOnly = false,
+		style,
+	}: MarqueeProps = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let rootEl = $state<HTMLDivElement | null>(null);
+	let isVisible = $state(true);
+	let tabActive = $state(true);
+	let boxSize = $state(0);
+	let trackSize = $state(0);
+	let gapSize = $state(0);
+
+	// =========================
+	// DERIVED
+	// =========================
+	// WHY: pause the scroll whenever it can't be seen, so an offscreen or
+	// background-tab marquee stops burning paint/compositor budget.
+	let paused = $derived(!isVisible || !tabActive);
+
+	// WHY: the 0.5px slack absorbs the rounding between a fractional text width and its box.
+	let overflowing = $derived(trackSize > boxSize + 0.5);
+	let still = $derived(overflowOnly && !overflowing);
+	// WHY: two copies loop seamlessly once one copy is wider than the box.
+	let copies = $derived(overflowOnly ? (overflowing ? 2 : 1) : repeat);
+	let loopSeconds = $derived(
+		speed && trackSize > 0 ? (trackSize + gapSize) / speed : undefined,
+	);
+
+	// WHY: only emit the CSS vars that were passed as props, so a consumer can
+	// still override timing or spacing with a `[--duration:24s]` utility class.
+	let styleVars = $derived(
+		[
+			loopSeconds ? `--duration:${loopSeconds}s` : duration && `--duration:${duration}`,
+			gap && `--gap:${gap}`,
+			fade && `--marquee-fade:${fade}`,
+			delay && `--marquee-delay:${delay}ms`,
+			style,
+		]
+			.filter(Boolean)
+			.join(";"),
+	);
+
+	// =========================
+	// EFFECTS
+	// =========================
+	$effect(() => {
+		if (!rootEl) return;
+		const observer = new IntersectionObserver(
+			([entry]) => {
+				isVisible = entry.isIntersecting;
+			},
+			{ threshold: 0 },
+		);
+		observer.observe(rootEl);
+		return () => observer.disconnect();
+	});
+
+	$effect(() => {
+		const firstTrack = rootEl?.firstElementChild;
+		if (!rootEl || !firstTrack || !(speed || overflowOnly)) return;
+		const root = rootEl;
+		const measure = () => {
+			const computed = getComputedStyle(root);
+			const box = root.getBoundingClientRect();
+			const track = firstTrack.getBoundingClientRect();
+			const padStart = parseFloat(vertical ? computed.paddingTop : computed.paddingLeft) || 0;
+			const padEnd = parseFloat(vertical ? computed.paddingBottom : computed.paddingRight) || 0;
+			boxSize = (vertical ? box.height : box.width) - padStart - padEnd;
+			trackSize = vertical ? track.height : track.width;
+			gapSize = parseFloat(vertical ? computed.rowGap : computed.columnGap) || 0;
+		};
+		measure();
+		const observer = new ResizeObserver(measure);
+		observer.observe(root);
+		observer.observe(firstTrack);
+		return () => observer.disconnect();
+	});
+
+	$effect(() => {
+		const onVisibility = () => {
+			tabActive = document.visibilityState === "visible";
+		};
+		document.addEventListener("visibilitychange", onVisibility);
+		return () => document.removeEventListener("visibilitychange", onVisibility);
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div
+	bind:this={rootEl}
+	class={cn("marquee", vertical && "marquee--vertical", className)}
+	style={styleVars}
+	data-pause-hover={pauseOnHover ? "" : undefined}
+	data-paused={paused ? "" : undefined}
+	data-overflow-only={overflowOnly ? "" : undefined}
+	data-still={still ? "" : undefined}
+	data-fade={fade && !still ? "" : undefined}
+>
+	{#each Array(copies).fill(0) as _, i (i)}
+		<div
+			class={cn("marquee__track", reverse && "marquee__track--reverse")}
+			aria-hidden={i > 0 ? "true" : undefined}
+		>
+			{@render children?.()}
+		</div>
+	{/each}
+</div>

package/src/effects/progressive-blur/ProgressiveBlur.css

@@ -0,0 +1,9 @@
+.hr-progressive-blur {
+  position: relative;
+  pointer-events: none;
+}
+.hr-progressive-blur__layer {
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+}

package/src/effects/progressive-blur/ProgressiveBlur.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./ProgressiveBlur.css";
+	import { cn } from "@heyramzi/utils";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Direction = "top" | "right" | "bottom" | "left";
+
+	interface ProgressiveBlurProps {
+		/** Edge the blur builds towards. Default `bottom`. */
+		direction?: Direction;
+		/** Stacked masked layers. More layers, smoother ramp, more compositing. */
+		layers?: number;
+		/** Blur added per layer, in px. */
+		intensity?: number;
+		class?: string;
+	}
+
+	// =========================
+	// CONSTANTS
+	// =========================
+	const ANGLES: Record<Direction, number> = { top: 0, right: 90, bottom: 180, left: 270 };
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		direction = "bottom",
+		layers = 8,
+		intensity = 0.25,
+		class: className,
+	}: ProgressiveBlurProps = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+	// WHY: one uniform backdrop-filter banks up hard at its edge. Overlapping
+	// windowed masks, each blurred a little more, ramp it instead.
+	let steps = $derived(
+		Array.from({ length: Math.max(layers, 2) }, (_, i) => {
+			const size = 100 / (layers + 1);
+			const stops = [i, i + 1, i + 2, i + 3]
+				.map((n, at) => `rgb(255 255 255 / ${at === 1 || at === 2 ? 1 : 0}) ${n * size}%`)
+				.join(", ");
+			const mask = `linear-gradient(${ANGLES[direction]}deg, ${stops})`;
+			const blur = `blur(${i * intensity}px)`;
+			return `mask-image:${mask};-webkit-mask-image:${mask};backdrop-filter:${blur};-webkit-backdrop-filter:${blur}`;
+		}),
+	);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div class={cn("hr-progressive-blur", className)} aria-hidden="true">
+	{#each steps as step, i (i)}
+		<div class="hr-progressive-blur__layer" style={step}></div>
+	{/each}
+</div>

package/src/effects/reveal/AnimatedGroup.svelte

@@ -0,0 +1,101 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./reveal.css";
+	import { cn } from "@heyramzi/utils";
+	import type { Snippet } from "svelte";
+	import { observeInView } from "./observe.js";
+	import type { RevealTiming, RevealViewOptions } from "./types.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface AnimatedGroupProps extends RevealTiming, RevealViewOptions {
+		children: Snippet;
+		/** Tag to render. Default `div`. */
+		as?: string;
+		class?: string;
+		/** Play on mount instead of waiting for the group to scroll into view. */
+		onMount?: boolean;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		children,
+		as = "div",
+		class: className,
+		preset = "fade",
+		delay,
+		duration,
+		stagger,
+		once = true,
+		amount,
+		margin,
+		onMount = false,
+	}: AnimatedGroupProps = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let rootEl = $state<HTMLElement | null>(null);
+	let inView = $state(false);
+
+	// =========================
+	// DERIVED
+	// =========================
+	let styleVars = $derived(
+		[
+			delay !== undefined && `--hr-reveal-delay:${delay}ms`,
+			duration !== undefined && `--hr-reveal-duration:${duration}ms`,
+			stagger !== undefined && `--hr-reveal-stagger:${stagger}ms`,
+		]
+			.filter(Boolean)
+			.join(";"),
+	);
+
+	// =========================
+	// EFFECTS
+	// =========================
+	// WHY: children arrive as an opaque snippet, so the stagger index is stamped on
+	// the rendered elements, and MutationObserver reindexes when `{#each}` changes.
+	$effect(() => {
+		if (!rootEl) return;
+		const el = rootEl;
+		const index = () => {
+			Array.from(el.children).forEach((child, i) => {
+				child.classList.add("hr-reveal__item");
+				(child as HTMLElement).style.setProperty("--i", String(i));
+			});
+		};
+		index();
+		const mutations = new MutationObserver(index);
+		mutations.observe(el, { childList: true });
+		return () => mutations.disconnect();
+	});
+
+	$effect(() => {
+		if (onMount) {
+			inView = true;
+			return;
+		}
+		if (!rootEl) return;
+		return observeInView(rootEl, { once, amount, margin }, (v) => (inView = v));
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<svelte:element
+	this={as}
+	bind:this={rootEl}
+	class={cn("hr-reveal", className)}
+	style={styleVars}
+	data-preset={preset}
+	data-reveal={inView ? "in" : undefined}
+>
+	{@render children()}
+</svelte:element>

package/src/effects/reveal/InView.svelte

@@ -0,0 +1,77 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./reveal.css";
+	import { cn } from "@heyramzi/utils";
+	import type { Snippet } from "svelte";
+	import { observeInView } from "./observe.js";
+	import type { RevealTiming, RevealViewOptions } from "./types.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface InViewProps extends RevealTiming, RevealViewOptions {
+		children: Snippet<[boolean]>;
+		/** Tag to render. Default `div`. */
+		as?: string;
+		class?: string;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		children,
+		as = "div",
+		class: className,
+		preset = "fade",
+		delay,
+		duration,
+		once = true,
+		amount,
+		margin,
+	}: InViewProps = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let rootEl = $state<HTMLElement | null>(null);
+	let inView = $state(false);
+
+	// =========================
+	// DERIVED
+	// =========================
+	// WHY: emit only the props that were passed, so a `[--hr-reveal-blur:4px]`
+	// utility on the consumer's class still wins.
+	let styleVars = $derived(
+		[
+			delay !== undefined && `--hr-reveal-delay:${delay}ms`,
+			duration !== undefined && `--hr-reveal-duration:${duration}ms`,
+		]
+			.filter(Boolean)
+			.join(";"),
+	);
+
+	// =========================
+	// EFFECTS
+	// =========================
+	$effect(() => {
+		if (!rootEl) return;
+		return observeInView(rootEl, { once, amount, margin }, (v) => (inView = v));
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<svelte:element
+	this={as}
+	bind:this={rootEl}
+	class={cn("hr-reveal hr-reveal__item", className)}
+	style={styleVars}
+	data-preset={preset}
+	data-reveal={inView ? "in" : undefined}
+>
+	{@render children(inView)}
+</svelte:element>

package/src/effects/reveal/TextEffect.svelte

@@ -0,0 +1,142 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./reveal.css";
+	import { cn } from "@heyramzi/utils";
+	import { observeInView } from "./observe.js";
+	import type { RevealPer, RevealTiming, RevealViewOptions } from "./types.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface TextEffectProps extends RevealTiming, RevealViewOptions {
+		/** The line to reveal. Plain text only; `\n` splits lines when `per="line"`. */
+		text: string;
+		/** What one staggered step is. Default `word`. */
+		per?: RevealPer;
+		/** Tag to render. Default `p`. */
+		as?: string;
+		class?: string;
+		/** Play on mount instead of waiting for the text to scroll into view. */
+		onMount?: boolean;
+	}
+
+	type Token =
+		| { kind: "plain"; text: string }
+		| { kind: "item"; text: string; i: number; block: boolean }
+		| { kind: "word"; chars: Array<{ text: string; i: number }> };
+
+	// =========================
+	// CONSTANTS
+	// =========================
+	const DEFAULT_STAGGER: Record<RevealPer, number> = { char: 25, word: 40, line: 80 };
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		text,
+		per = "word",
+		as = "p",
+		class: className,
+		preset = "fade",
+		delay,
+		duration,
+		stagger,
+		once = true,
+		amount,
+		margin,
+		onMount = false,
+	}: TextEffectProps = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let rootEl = $state<HTMLElement | null>(null);
+	let inView = $state(false);
+
+	// =========================
+	// DERIVED
+	// =========================
+	let tokens = $derived(split(text, per));
+
+	let styleVars = $derived(
+		[
+			delay !== undefined && `--hr-reveal-delay:${delay}ms`,
+			duration !== undefined && `--hr-reveal-duration:${duration}ms`,
+			`--hr-reveal-stagger:${stagger ?? DEFAULT_STAGGER[per]}ms`,
+		]
+			.filter(Boolean)
+			.join(";"),
+	);
+
+	// =========================
+	// FUNCTIONS
+	// =========================
+	function split(value: string, mode: RevealPer): Token[] {
+		if (mode === "line") {
+			return value.split("\n").map((line, i) => ({ kind: "item", text: line, i, block: true }));
+		}
+
+		// WHY: the capturing split keeps the whitespace runs as their own pieces, so
+		// spacing survives without any piece being animated.
+		let i = 0;
+		return value.split(/(\s+)/).flatMap<Token>((piece) => {
+			if (piece === "") return [];
+			if (/^\s+$/.test(piece)) return [{ kind: "plain", text: piece }];
+			if (mode === "word") return [{ kind: "item", text: piece, i: i++, block: false }];
+			return [{ kind: "word", chars: Array.from(piece).map((c) => ({ text: c, i: i++ })) }];
+		});
+	}
+
+	// =========================
+	// EFFECTS
+	// =========================
+	$effect(() => {
+		if (onMount) {
+			inView = true;
+			return;
+		}
+		if (!rootEl) return;
+		return observeInView(rootEl, { once, amount, margin }, (v) => (inView = v));
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<svelte:element
+	this={as}
+	bind:this={rootEl}
+	class={cn("hr-reveal", className)}
+	style={styleVars}
+	data-preset={preset}
+	data-reveal={inView ? "in" : undefined}
+>
+	{#if per !== "line"}
+		<!-- The split spans are decorative; a screen reader gets the whole line once. -->
+		<span class="hr-reveal__sr">{text}</span>
+	{/if}
+	{#each tokens as token, t (t)}
+		{#if token.kind === "plain"}
+			<span class="hr-reveal__segment">{token.text}</span>
+		{:else if token.kind === "item"}
+			<span
+				aria-hidden={per === "line" ? undefined : "true"}
+				class={cn(
+					"hr-reveal__segment",
+					token.block && "hr-reveal__segment--line",
+					"hr-reveal__item",
+				)}
+				style="--i:{token.i}">{token.text}</span
+			>
+		{:else}<span class="hr-reveal__segment" aria-hidden="true"
+				>{#each token.chars as char, c (c)}<span
+						class="hr-reveal__segment hr-reveal__item"
+						style="--i:{char.i}">{char.text}</span
+					>{/each}</span
+			>
+		{/if}
+	{/each}
+</svelte:element>

package/src/effects/reveal/index.ts

@@ -0,0 +1,11 @@
+export { default as InView } from "./InView.svelte";
+export { default as AnimatedGroup } from "./AnimatedGroup.svelte";
+export { default as TextEffect } from "./TextEffect.svelte";
+export { observeInView, onInView } from "./observe.js";
+export type {
+  RevealPreset,
+  RevealPer,
+  RevealTiming,
+  RevealViewOptions,
+  InViewActionOptions,
+} from "./types.js";

package/src/effects/reveal/observe.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import { onInView } from "./observe.js";
+
+type Callback = (entries: { isIntersecting: boolean }[]) => void;
+
+let callbacks: Callback[] = [];
+
+class FakeObserver {
+  constructor(callback: Callback) {
+    callbacks.push(callback);
+  }
+  observe() {}
+  disconnect() {}
+}
+
+function fire(isIntersecting: boolean) {
+  for (const callback of callbacks) callback([{ isIntersecting }]);
+}
+
+describe("onInView", () => {
+  beforeEach(() => {
+    callbacks = [];
+    vi.stubGlobal("IntersectionObserver", FakeObserver);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("calls onEnter once when the node first shows", () => {
+    const onEnter = vi.fn();
+    onInView(document.createElement("div"), { onEnter });
+    fire(true);
+    fire(true);
+    expect(onEnter).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onLeave only after an enter, and only when once is off", () => {
+    const onEnter = vi.fn();
+    const onLeave = vi.fn();
+    onInView(document.createElement("div"), { once: false, onEnter, onLeave });
+    fire(false);
+    expect(onLeave).not.toHaveBeenCalled();
+    fire(true);
+    fire(false);
+    fire(true);
+    expect(onEnter).toHaveBeenCalledTimes(2);
+    expect(onLeave).toHaveBeenCalledTimes(1);
+  });
+
+  it("reads the callbacks from the latest update", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const action = onInView(document.createElement("div"), { onEnter: first });
+    action?.update?.({ onEnter: second });
+    fire(true);
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});

package/src/effects/reveal/observe.ts

@@ -0,0 +1,65 @@
+import type { Action } from "svelte/action";
+import type { InViewActionOptions, RevealViewOptions } from "./types.js";
+
+/**
+ * Runs `onChange` when `el` enters or leaves the viewport. Returns the teardown.
+ * Shared by InView, AnimatedGroup and TextEffect so there is one observer contract.
+ */
+export function observeInView(
+  el: Element,
+  options: RevealViewOptions,
+  onChange: (inView: boolean) => void,
+): () => void {
+  // WHY: no IntersectionObserver means SSR or an ancient engine; reveal the
+  // content rather than leaving it stuck at the hidden keyframe.
+  if (typeof IntersectionObserver === "undefined") {
+    onChange(true);
+    return () => {};
+  }
+
+  const observer = new IntersectionObserver(
+    ([entry]) => {
+      if (entry.isIntersecting) {
+        onChange(true);
+        if (options.once !== false) observer.disconnect();
+        return;
+      }
+      if (options.once === false) onChange(false);
+    },
+    { threshold: options.amount ?? 0, rootMargin: options.margin ?? "0px" },
+  );
+
+  observer.observe(el);
+  return () => observer.disconnect();
+}
+
+/**
+ * Svelte action that calls back when the node enters or leaves the viewport.
+ * Options are read at call time, so a `use:onInView={...}` update swaps the callbacks.
+ *
+ * @example
+ * <section use:onInView={{ amount: 0.2, onEnter: () => (visible = true) }}>
+ */
+export const onInView: Action<HTMLElement, InViewActionOptions | undefined> = (node, initial) => {
+  let options = initial ?? {};
+  let entered = false;
+
+  const { amount = 0.1, margin, once } = options;
+
+  const stop = observeInView(node, { amount, margin, once }, (inView) => {
+    if (inView && !entered) {
+      entered = true;
+      options.onEnter?.();
+    } else if (!inView && entered) {
+      entered = false;
+      options.onLeave?.();
+    }
+  });
+
+  return {
+    update(next) {
+      options = next ?? {};
+    },
+    destroy: stop,
+  };
+};