@heyramzi/ui 0.0.0-stage → 1.53.1

package/src/effects/border-beam/register-properties.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, test, vi } from "vite-plus/test";
+import { registerBorderBeamProperties } from "./register-properties.js";
+
+const originalCss = globalThis.CSS;
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  Object.defineProperty(globalThis, "CSS", {
+    configurable: true,
+    value: originalCss,
+  });
+});
+
+describe("registerBorderBeamProperties", () => {
+  test("registers angle and opacity properties for md beams", () => {
+    const registerProperty = vi.fn();
+    Object.defineProperty(globalThis, "CSS", {
+      configurable: true,
+      value: { registerProperty },
+    });
+
+    registerBorderBeamProperties("bb-test", "md");
+
+    expect(registerProperty).toHaveBeenCalledWith({
+      name: "--beam-angle-bb-test",
+      syntax: "<angle>",
+      initialValue: "0deg",
+      inherits: true,
+    });
+    expect(registerProperty).toHaveBeenCalledWith({
+      name: "--beam-opacity-bb-test",
+      syntax: "<number>",
+      initialValue: "0",
+      inherits: true,
+    });
+  });
+
+  test("registers line beam numeric properties", () => {
+    const registerProperty = vi.fn();
+    Object.defineProperty(globalThis, "CSS", {
+      configurable: true,
+      value: { registerProperty },
+    });
+
+    registerBorderBeamProperties("bb-line", "line");
+
+    expect(registerProperty).toHaveBeenCalledWith({
+      name: "--beam-x-bb-line",
+      syntax: "<number>",
+      initialValue: "0",
+      inherits: true,
+    });
+    expect(registerProperty).toHaveBeenCalledWith({
+      name: "--beam-edge-bb-line",
+      syntax: "<number>",
+      initialValue: "1",
+      inherits: true,
+    });
+    expect(registerProperty).toHaveBeenCalledTimes(7);
+  });
+
+  test("ignores unsupported or duplicate registrations", () => {
+    const registerProperty = vi.fn(() => {
+      throw new Error("already registered");
+    });
+    Object.defineProperty(globalThis, "CSS", {
+      configurable: true,
+      value: { registerProperty },
+    });
+
+    expect(() => registerBorderBeamProperties("bb-test", "sm")).not.toThrow();
+    expect(registerProperty).toHaveBeenCalledTimes(2);
+  });
+});

package/src/effects/border-beam/register-properties.ts

@@ -0,0 +1,73 @@
+import { tryCatch } from "@heyramzi/utils";
+import type { BorderBeamSize } from "./presets.js";
+
+interface PropertyRegistration {
+  name: string;
+  syntax: "<angle>" | "<number>";
+  initialValue: string;
+  inherits: boolean;
+}
+
+interface CssPropertyRegistry {
+  registerProperty?: (registration: PropertyRegistration) => void;
+}
+
+/**
+ * WHY this exists at all, when generateCss already emits the same @property rules: Chrome ignores an @property rule that sits inside a shadow root,
+ */
+
+/*
+ * so a beam rendered in one has no registration.
+ */
+
+/*
+ * Unregistered, the angle cannot be interpolated and, worse, every mask that reads it is invalid at computed-value time, which resolves the mask to none and floods the whole element instead
+ */
+
+/*
+ * of drawing a border. This call registers on the document, which is why the ids are unique per instance.
+ */
+export function registerBorderBeamProperties(id: string, size: BorderBeamSize): void {
+  const registry = globalThis.CSS as CssPropertyRegistry | undefined;
+  if (typeof registry?.registerProperty !== "function") return;
+
+  for (const registration of getBorderBeamPropertyRegistrations(id, size)) {
+    tryCatch(() => registry.registerProperty?.(registration));
+  }
+}
+
+function getBorderBeamPropertyRegistrations(
+  id: string,
+  size: BorderBeamSize,
+): PropertyRegistration[] {
+  if (size === "line") {
+    return [
+      numberProperty(`--beam-x-${id}`, "0"),
+      numberProperty(`--beam-w-${id}`, "1"),
+      numberProperty(`--beam-h-${id}`, "1"),
+      numberProperty(`--beam-spike-${id}`, "1"),
+      numberProperty(`--beam-spike2-${id}`, "1"),
+      numberProperty(`--beam-edge-${id}`, "1"),
+      numberProperty(`--beam-opacity-${id}`, "0"),
+    ];
+  }
+
+  return [
+    {
+      name: `--beam-angle-${id}`,
+      syntax: "<angle>",
+      initialValue: "0deg",
+      inherits: true,
+    },
+    numberProperty(`--beam-opacity-${id}`, "0"),
+  ];
+}
+
+function numberProperty(name: string, initialValue: string): PropertyRegistration {
+  return {
+    name,
+    syntax: "<number>",
+    initialValue,
+    inherits: true,
+  };
+}

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

@@ -0,0 +1,38 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type {
+  BorderBeamColorVariant,
+  BorderBeamSize,
+  BorderBeamTheme,
+} from "./presets.js";
+
+export interface BorderBeamProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  children: Snippet;
+  size?: BorderBeamSize;
+  colorVariant?: BorderBeamColorVariant;
+  theme?: BorderBeamTheme;
+  staticColors?: boolean;
+  /** Seconds for one lap. Default 1.96s, or 2.4s at size="line". */
+  duration?: number;
+  active?: boolean;
+  borderRadius?: number;
+  brightness?: number;
+  saturation?: number;
+  hueRange?: number;
+  strength?: number;
+  // WHY: caller-supplied palette overrides the colorVariant preset. Each
+  // preset stop is mapped by index (cycling if shorter) so layout/timing
+  // stay identical, only hues swap. Accepts hex (#rrggbb), rgb(), rgba().
+  colors?: string[];
+  // WHY: the bloom layer is the single most expensive part of the beam: a blurred conic-gradient re-rasterized every frame.
+
+  // Opt-out gives a 2-3x perf win for callers who only need the stroke and inner shimmer.
+  bloom?: boolean;
+  // WHY: pause beam animation while the host is off-screen (IntersectionObserver) or the document is hidden.
+
+  // Default true; opt-out for callers that mount outside the viewport but still want the beam ticking.
+  pauseWhenOffscreen?: boolean;
+  class?: string;
+  onActivate?: () => void;
+  onDeactivate?: () => void;
+}

package/src/effects/image-comparison/ImageComparison.css

@@ -0,0 +1,100 @@
+/*
+ * Brand hooks, all optional, set on the element's class:
+ * --hr-compare-handle-color, --hr-compare-handle-width, --hr-compare-handle-shadow,
+ * --hr-compare-grip-bg, --hr-compare-grip-color, --hr-compare-grip-size, --hr-compare-grip-shadow,
+ * --hr-compare-badge-inset, --hr-compare-hint-duration.
+ */
+.hr-compare {
+  position: relative;
+  overflow: hidden;
+  user-select: none;
+  isolation: isolate;
+}
+.hr-compare picture {
+  display: contents;
+}
+.hr-compare__img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.hr-compare__img--after {
+  position: absolute;
+  inset: 0;
+  clip-path: inset(0 0 0 calc(var(--hr-compare-pos) * 1%));
+}
+.hr-compare__badge {
+  position: absolute;
+  z-index: 1;
+  pointer-events: none;
+}
+.hr-compare__badge--before {
+  inset-inline-start: var(--hr-compare-badge-inset, 0.75rem);
+}
+.hr-compare__badge--after {
+  inset-inline-end: var(--hr-compare-badge-inset, 0.75rem);
+}
+.hr-compare[data-badges="top"] .hr-compare__badge {
+  inset-block-start: var(--hr-compare-badge-inset, 0.75rem);
+}
+.hr-compare[data-badges="bottom"] .hr-compare__badge {
+  inset-block-end: var(--hr-compare-badge-inset, 0.75rem);
+}
+.hr-compare__handle {
+  position: absolute;
+  z-index: 2;
+  inset-block: 0;
+  left: calc(var(--hr-compare-pos) * 1%);
+  width: var(--hr-compare-handle-width, 2px);
+  translate: calc(var(--hr-compare-handle-width, 2px) / -2) 0;
+  background: var(--hr-compare-handle-color, white);
+  box-shadow: var(--hr-compare-handle-shadow, var(--elev-2, 0 2px 8px rgb(0 0 0 / 0.25)));
+  pointer-events: none;
+}
+.hr-compare__grip {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  translate: -50% -50%;
+  display: grid;
+  place-items: center;
+  width: var(--hr-compare-grip-size, 2rem);
+  height: var(--hr-compare-grip-size, 2rem);
+  border-radius: 999px;
+  background: var(--hr-compare-grip-bg, var(--hr-compare-handle-color, white));
+  color: var(--hr-compare-grip-color, black);
+  box-shadow: var(--hr-compare-grip-shadow, none);
+}
+/* The range covers the frame so pointer drag, touch and arrow keys all work. */
+.hr-compare__range {
+  position: absolute;
+  inset: 0;
+  z-index: 3;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  opacity: 0;
+  cursor: ew-resize;
+  appearance: none;
+  background: transparent;
+  /* A vertical swipe over the frame still scrolls the page. */
+  touch-action: pan-y pinch-zoom;
+}
+.hr-compare__range:focus-visible ~ .hr-compare__handle {
+  outline: 2px solid var(--hr-compare-handle-color, white);
+  outline-offset: 2px;
+}
+@media (prefers-reduced-motion: no-preference) {
+  .hr-compare[data-eased] .hr-compare__img--after,
+  .hr-compare[data-eased] .hr-compare__handle {
+    transition:
+      clip-path var(--duration-quick, 150ms) var(--ease-smooth-out, ease-out),
+      left var(--duration-quick, 150ms) var(--ease-smooth-out, ease-out);
+  }
+  /* A slower glide while the handle hints, so the sweep reads as a gesture. */
+  .hr-compare[data-hinting] .hr-compare__img--after,
+  .hr-compare[data-hinting] .hr-compare__handle {
+    transition-duration: var(--hr-compare-hint-duration, 800ms);
+  }
+}

package/src/effects/image-comparison/ImageComparison.svelte

@@ -0,0 +1,209 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+
+	/** One side of the comparison. `sources` turns the image into a `<picture>`. */
+	export interface ComparisonImage {
+		src: string;
+		alt: string;
+		/** Modern formats tried before `src`, such as an AVIF with the PNG as the fallback. */
+		sources?: readonly { srcset: string; type: string }[];
+		/** Intrinsic size, so the browser reserves the frame before the image lands. */
+		width?: number;
+		height?: number;
+	}
+</script>
+
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./ImageComparison.css";
+	import { cn } from "@heyramzi/utils";
+	import { untrack } from "svelte";
+	import { positionAt } from "./compare.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface ImageComparisonProps {
+		/** Image shown on the left of the handle. */
+		before: ComparisonImage;
+		/** Image shown on the right of the handle. */
+		after: ComparisonImage;
+		/** Handle position, 0-100. Bind it to read it or to move the handle from outside. */
+		position?: number;
+		/** Track the pointer without a press. The handle returns to where it began. */
+		hover?: boolean;
+		/**
+		 * Positions the handle visits once on mount, then it returns to where it began.
+		 * It stops for good at the first touch. Tells a visitor the frame moves.
+		 */
+		hint?: readonly number[];
+		/** Load both images now, ahead of the rest of the page. For a frame above the fold. */
+		eager?: boolean;
+		/** Label announced for the slider. */
+		label?: string;
+		/** A label drawn over the left side, such as "Before". */
+		beforeBadge?: Snippet;
+		/** A label drawn over the right side, such as "After". */
+		afterBadge?: Snippet;
+		/** Which edge the badges sit on. */
+		badgeEdge?: "top" | "bottom";
+		class?: string;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		before,
+		after,
+		position = $bindable(50),
+		hover = false,
+		hint,
+		eager = false,
+		label = "Compare before and after",
+		beforeBadge,
+		afterBadge,
+		badgeEdge = "bottom",
+		class: className,
+	}: ImageComparisonProps = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	// WHY: the handle's first position is where `hover` and `hint` bring it back to.
+	const rest = untrack(() => position);
+	let dragging = $state(false);
+	let hinting = $state(false);
+	let touched = $state(false);
+
+	// =========================
+	// EFFECTS
+	// =========================
+	const HINT_DELAY = 800;
+	const HINT_STEP = 900;
+
+	$effect(() => {
+		const steps = hint;
+		if (touched || !steps?.length) return;
+		if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;
+		const timers: ReturnType<typeof setTimeout>[] = [];
+		hinting = true;
+		[...steps, rest].forEach((stop, index) => {
+			timers.push(
+				setTimeout(
+					() => {
+						position = stop;
+					},
+					HINT_DELAY + index * HINT_STEP,
+				),
+			);
+		});
+		timers.push(
+			setTimeout(
+				() => {
+					hinting = false;
+				},
+				HINT_DELAY + steps.length * HINT_STEP + HINT_STEP / 2,
+			),
+		);
+		return () => {
+			timers.forEach(clearTimeout);
+			hinting = false;
+		};
+	});
+
+	// =========================
+	// FUNCTIONS
+	// =========================
+	// WHY: the effect reads `touched`, so setting it runs the effect's cleanup and cancels the timers.
+	function touch() {
+		touched = true;
+	}
+
+	function trackPointer(event: PointerEvent) {
+		if (!hover && !dragging) return;
+		const rect =
+			event.currentTarget instanceof HTMLElement && event.currentTarget.getBoundingClientRect();
+		if (!rect) return;
+		position = positionAt(event.clientX, rect.left, rect.width);
+	}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{#snippet picture(side: ComparisonImage, cls: string)}
+	{#if side.sources?.length}
+		<picture>
+			{#each side.sources as source (source.type)}
+				<source srcset={source.srcset} type={source.type} />
+			{/each}
+			{@render img(side, cls)}
+		</picture>
+	{:else}
+		{@render img(side, cls)}
+	{/if}
+{/snippet}
+
+{#snippet img(side: ComparisonImage, cls: string)}
+	<img
+		class={cls}
+		src={side.src}
+		alt={side.alt}
+		width={side.width}
+		height={side.height}
+		draggable="false"
+		loading={eager ? "eager" : undefined}
+		fetchpriority={eager ? "high" : undefined}
+	/>
+{/snippet}
+
+<div
+	role="group"
+	aria-label={label}
+	class={cn("hr-compare", className)}
+	style="--hr-compare-pos:{position}"
+	data-eased={dragging ? undefined : ""}
+	data-hinting={hinting ? "" : undefined}
+	data-badges={badgeEdge}
+	onpointermove={trackPointer}
+	onpointerdown={() => {
+		dragging = true;
+		touch();
+	}}
+	onpointerup={() => (dragging = false)}
+	onpointercancel={() => (dragging = false)}
+	onpointerleave={() => {
+		dragging = false;
+		if (hover) position = rest;
+	}}
+	onkeydown={touch}
+>
+	{@render picture(before, "hr-compare__img")}
+	{@render picture(after, "hr-compare__img hr-compare__img--after")}
+	{#if beforeBadge}
+		<div class="hr-compare__badge hr-compare__badge--before">{@render beforeBadge()}</div>
+	{/if}
+	{#if afterBadge}
+		<div class="hr-compare__badge hr-compare__badge--after">{@render afterBadge()}</div>
+	{/if}
+	<input
+		class="hr-compare__range"
+		type="range"
+		min="0"
+		max="100"
+		step="1"
+		aria-label={label}
+		bind:value={position}
+	/>
+	<div class="hr-compare__handle">
+		<span class="hr-compare__grip">
+			<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+				<polyline points="10 6 4 12 10 18"></polyline>
+				<polyline points="14 6 20 12 14 18"></polyline>
+			</svg>
+		</span>
+	</div>
+</div>

package/src/effects/image-comparison/compare.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vite-plus/test";
+import { positionAt } from "./compare.js";
+
+describe("positionAt", () => {
+  it("maps the pointer to a percentage of the frame", () => {
+    expect(positionAt(150, 100, 200)).toBe(25);
+  });
+
+  it("clamps a pointer outside the frame", () => {
+    expect(positionAt(50, 100, 200)).toBe(0);
+    expect(positionAt(400, 100, 200)).toBe(100);
+  });
+
+  it("rests in the middle of a frame with no width", () => {
+    expect(positionAt(10, 0, 0)).toBe(50);
+  });
+});

package/src/effects/image-comparison/compare.ts

@@ -0,0 +1,5 @@
+/** Where the handle sits for a pointer at `clientX`, as a 0-100 percentage of the frame. */
+export function positionAt(clientX: number, left: number, width: number): number {
+  if (width <= 0) return 50;
+  return Math.min(Math.max(((clientX - left) / width) * 100, 0), 100);
+}

package/src/effects/image-reveal/ImageReveal.css

@@ -0,0 +1,10 @@
+.hr-image-reveal {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+.hr-image-reveal canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+}