@heyramzi/ui 0.0.0-stage → 6.1.0

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,66 @@
+.hr-compare {
+  position: relative;
+  overflow: hidden;
+  user-select: none;
+  isolation: isolate;
+}
+.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__handle {
+  position: absolute;
+  inset-block: 0;
+  left: calc(var(--hr-compare-pos) * 1%);
+  width: 2px;
+  translate: -1px 0;
+  background: var(--hr-compare-handle-color, white);
+  box-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: 2rem;
+  height: 2rem;
+  border-radius: 999px;
+  background: inherit;
+  color: var(--hr-compare-grip-color, black);
+  font-size: 0.75rem;
+  line-height: 1;
+}
+/* The range covers the frame so pointer drag, touch and arrow keys all work. */
+.hr-compare__range {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  opacity: 0;
+  cursor: ew-resize;
+  appearance: none;
+  background: transparent;
+}
+.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);
+  }
+}

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

@@ -0,0 +1,92 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./ImageComparison.css";
+	import { cn } from "@heyramzi/utils";
+	import { untrack } from "svelte";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface ImageComparisonProps {
+		/** Image shown on the left of the handle. */
+		before: { src: string; alt: string };
+		/** Image shown on the right of the handle. */
+		after: { src: string; alt: string };
+		/** Handle position at rest, 0-100. */
+		start?: number;
+		/** Track the pointer without a press. */
+		hover?: boolean;
+		/** Label announced for the slider. */
+		label?: string;
+		class?: string;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		before,
+		after,
+		start = 50,
+		hover = false,
+		label = "Compare before and after",
+		class: className,
+	}: ImageComparisonProps = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	// WHY: `start` seeds the handle and then stops mattering; the pointer and the
+	// range own the position from there.
+	let position = $state(untrack(() => start));
+	let dragging = $state(false);
+
+	// =========================
+	// FUNCTIONS
+	// =========================
+	function trackPointer(event: PointerEvent) {
+		if (!hover && !dragging) return;
+		const rect =
+			event.currentTarget instanceof HTMLElement && event.currentTarget.getBoundingClientRect();
+		if (!rect) return;
+		position = Math.min(Math.max(((event.clientX - rect.left) / rect.width) * 100, 0), 100);
+	}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div
+	role="group"
+	aria-label={label}
+	class={cn("hr-compare", className)}
+	style="--hr-compare-pos:{position}"
+	data-eased={dragging ? undefined : ""}
+	onpointermove={trackPointer}
+	onpointerdown={() => (dragging = true)}
+	onpointerup={() => (dragging = false)}
+	onpointerleave={() => {
+		dragging = false;
+		if (hover) position = start;
+	}}
+>
+	<img class="hr-compare__img" src={before.src} alt={before.alt} draggable="false" />
+	<img
+		class="hr-compare__img hr-compare__img--after"
+		src={after.src}
+		alt={after.alt}
+		draggable="false"
+	/>
+	<input
+		class="hr-compare__range"
+		type="range"
+		min="0"
+		max="100"
+		step="0.1"
+		aria-label={label}
+		bind:value={position}
+	/>
+	<div class="hr-compare__handle"><span class="hr-compare__grip">◀▶</span></div>
+</div>

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%;
+}