@heyramzi/ui 0.0.0-stage → 6.0.1

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,10 @@
+export { default as InView } from "./InView.svelte";
+export { default as AnimatedGroup } from "./AnimatedGroup.svelte";
+export { default as TextEffect } from "./TextEffect.svelte";
+export { observeInView } from "./observe.js";
+export type {
+  RevealPreset,
+  RevealPer,
+  RevealTiming,
+  RevealViewOptions,
+} from "./types.js";

package/src/effects/reveal/observe.ts

@@ -0,0 +1,33 @@
+import type { 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();
+}

package/src/effects/reveal/reveal.css

@@ -0,0 +1,141 @@
+/* Reveal engine shared by InView, AnimatedGroup and TextEffect. */
+/* Preset geometry from motion-primitives (MIT); timing from @heyramzi/ui/design. */
+
+.hr-reveal {
+  --hr-reveal-name: hr-reveal-fade;
+  --hr-reveal-play: paused;
+  --hr-reveal-duration: var(--duration-slow, 400ms);
+  --hr-reveal-ease: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+  --hr-reveal-stagger: var(--duration-stagger, 40ms);
+  --hr-reveal-delay: 0ms;
+  --hr-reveal-distance: 20px;
+  --hr-reveal-blur: 12px;
+  --hr-reveal-scale: 0.9;
+}
+
+/* WHY: every knob is an inherited custom property, so one attribute on the root
+   drives the root itself and every descendant item without a paired selector. */
+.hr-reveal[data-reveal="in"] {
+  --hr-reveal-play: running;
+}
+
+.hr-reveal__item {
+  --i: 0;
+  animation-name: var(--hr-reveal-name);
+  animation-duration: var(--hr-reveal-duration);
+  animation-timing-function: var(--hr-reveal-ease);
+  animation-fill-mode: both;
+  animation-play-state: var(--hr-reveal-play);
+  animation-delay: calc(var(--hr-reveal-delay) + var(--i) * var(--hr-reveal-stagger));
+}
+
+.hr-reveal[data-preset="fade"] {
+  --hr-reveal-name: hr-reveal-fade;
+}
+.hr-reveal[data-preset="slide"] {
+  --hr-reveal-name: hr-reveal-slide;
+}
+.hr-reveal[data-preset="blur"] {
+  --hr-reveal-name: hr-reveal-blur;
+}
+.hr-reveal[data-preset="blur-slide"] {
+  --hr-reveal-name: hr-reveal-blur-slide;
+}
+.hr-reveal[data-preset="scale"] {
+  --hr-reveal-name: hr-reveal-scale;
+}
+.hr-reveal[data-preset="zoom"] {
+  --hr-reveal-name: hr-reveal-zoom;
+  --hr-reveal-ease: var(--ease-smooth-out);
+}
+
+@keyframes hr-reveal-fade {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+@keyframes hr-reveal-slide {
+  from {
+    opacity: 0;
+    transform: translateY(var(--hr-reveal-distance));
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+@keyframes hr-reveal-blur {
+  from {
+    opacity: 0;
+    filter: blur(var(--hr-reveal-blur));
+  }
+  to {
+    opacity: 1;
+    filter: blur(0);
+  }
+}
+@keyframes hr-reveal-blur-slide {
+  from {
+    opacity: 0;
+    filter: blur(var(--hr-reveal-blur));
+    transform: translateY(var(--hr-reveal-distance));
+  }
+  to {
+    opacity: 1;
+    filter: blur(0);
+    transform: translateY(0);
+  }
+}
+@keyframes hr-reveal-scale {
+  from {
+    opacity: 0;
+    transform: scale(var(--hr-reveal-scale));
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+@keyframes hr-reveal-zoom {
+  from {
+    opacity: 0;
+    transform: scale(0.5);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+/* Segment spans TextEffect emits; per-char needs the space kept and the box laid out. */
+.hr-reveal__segment {
+  display: inline-block;
+  white-space: pre;
+}
+.hr-reveal__segment--line {
+  display: block;
+  white-space: normal;
+}
+.hr-reveal__sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hr-reveal__item {
+    animation: none;
+    opacity: 1;
+    filter: none;
+    transform: none;
+  }
+}

package/src/effects/reveal/types.ts

@@ -0,0 +1,25 @@
+/** Entrance geometry. Names match motion-primitives so a port reads the same. */
+export type RevealPreset = "fade" | "slide" | "blur" | "blur-slide" | "scale" | "zoom";
+
+/** How TextEffect cuts its string before staggering the pieces. */
+export type RevealPer = "char" | "word" | "line";
+
+export type RevealTiming = {
+  /** Preset geometry. Default `fade`. */
+  preset?: RevealPreset;
+  /** Wait before the first item starts, in ms. */
+  delay?: number;
+  /** Gap between consecutive items, in ms. Defaults to `--duration-stagger`. */
+  stagger?: number;
+  /** One item's run time, in ms. Defaults to `--duration-slow`. */
+  duration?: number;
+};
+
+export type RevealViewOptions = {
+  /** Play once and stay revealed, instead of replaying on every re-entry. */
+  once?: boolean;
+  /** Fraction of the element that must be visible before it plays. */
+  amount?: number;
+  /** `rootMargin` for the observer, e.g. `"0px 0px -15% 0px"`. */
+  margin?: string;
+};