@heyramzi/ui 7.0.0 → 8.0.0

package/src/components/star-rating-input/star-rating-input.svelte

@@ -0,0 +1,256 @@
+<script lang="ts" module>
+/**
+ * Two sizes, picked by the job: `sm` reads a value back in a row or cell,
+ * `lg` is the ask.
+ */
+// A middle `md` step used to exist. Nobody could place it, so the same question
+// ended up asked at three sizes.
+export type StarRatingSize = "sm" | "lg";
+
+const STAR_SIZE: Record<StarRatingSize, string> = {
+	sm: "size-4",
+	lg: "size-7",
+};
+
+const HIT_SIZE: Record<StarRatingSize, string> = {
+	sm: "p-0.5",
+	lg: "p-1",
+};
+
+/** Pop duration plus the longest stagger, after which the class can come off. */
+const POP_WINDOW_MS = 350 + 4 * 40;
+</script>
+
+<script lang="ts">
+import { Star } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+
+type Props = {
+	/** Current rating value (0 = unrated). */
+	value: number;
+	/** Maximum rating. Defaults to 5. */
+	max?: number;
+	/** Visual size of each star. `sm` reads back, `lg` asks. */
+	size?: StarRatingSize;
+	/** Render as static display, no hover or click. */
+	readonly?: boolean;
+	/** Disable interaction. */
+	disabled?: boolean;
+	/** Form field name for native submission. When set, a hidden input is rendered. */
+	name?: string;
+	/** ARIA label for the radiogroup. */
+	ariaLabel?: string;
+	/** Per-step descriptive labels (length must equal max). */
+	labels?: readonly string[];
+	/** Show the label of the currently hovered/selected step beside the stars. */
+	showLabel?: boolean;
+	class?: string;
+	onchange?: (value: number) => void;
+};
+
+let {
+	value = $bindable(0),
+	max = 5,
+	size = "sm",
+	readonly = false,
+	disabled = false,
+	name,
+	ariaLabel,
+	labels,
+	showLabel = false,
+	class: className,
+	onchange,
+}: Props = $props();
+
+let hover = $state(0);
+/** Held for the length of the pop, then dropped so the next pick can replay it. */
+let popping = $state(false);
+let popTimer: ReturnType<typeof setTimeout> | undefined;
+let displayed = $derived(hover || value);
+let starSize = $derived(STAR_SIZE[size]);
+let hitSize = $derived(HIT_SIZE[size]);
+let groupAriaLabel = $derived(ariaLabel ?? `Rating, ${max} stars`);
+let labelText = $derived(
+	displayed > 0 && labels && labels.length >= displayed ? labels[displayed - 1] : "",
+);
+
+function buttonAriaLabel(step: number): string {
+	const stepLabel = labels?.[step - 1];
+	const base = `${step} of ${max}`;
+	return stepLabel ? `${base} (${stepLabel})` : base;
+}
+
+function setRating(step: number) {
+	if (readonly || disabled) return;
+	value = step;
+	onchange?.(step);
+
+	// Drop the class before re-adding it, or a second pick inside the animation
+	// window finds it already set and nothing replays.
+	popping = false;
+	clearTimeout(popTimer);
+	requestAnimationFrame(() => {
+		popping = true;
+		popTimer = setTimeout(() => (popping = false), POP_WINDOW_MS);
+	});
+}
+
+function handleEnter(step: number) {
+	if (readonly || disabled) return;
+	hover = step;
+}
+
+function handleLeave() {
+	if (readonly || disabled) return;
+	hover = 0;
+}
+</script>
+
+<!-- One star, drawn once. It used to be written twice, once per branch, and the
+     two copies had already drifted apart on the glow. -->
+{#snippet star(step: number)}
+	<Star
+		class={cn("star", starSize, step <= displayed && "is-filled")}
+		weight={step <= displayed ? "fill" : "regular"}
+	/>
+{/snippet}
+
+<div class={cn("rating", `rating-${size}`, className)}>
+	<div
+		class={cn("stars", popping && "is-popping")}
+		role={readonly ? "img" : "radiogroup"}
+		aria-label={groupAriaLabel}
+		onmouseleave={handleLeave}
+	>
+		{#each Array(max) as _, i (i)}
+			{@const step = i + 1}
+			{#if readonly}
+				<span class={cn("hit", hitSize)}>{@render star(step)}</span>
+			{:else}
+				<button
+					type="button"
+					role="radio"
+					aria-checked={value === step}
+					aria-label={buttonAriaLabel(step)}
+					{disabled}
+					data-on={step <= value}
+					onclick={() => setRating(step)}
+					onmouseenter={() => handleEnter(step)}
+					onfocus={() => handleEnter(step)}
+					onblur={handleLeave}
+					style:--pop-delay="{i * 40}ms"
+					class={cn("hit hit-button", hitSize, disabled && "is-disabled")}
+				>
+					{@render star(step)}
+				</button>
+			{/if}
+		{/each}
+	</div>
+
+	{#if showLabel && labelText}
+		<span class="rating-caption">{labelText}</span>
+	{/if}
+
+	{#if name}
+		<input type="hidden" {name} value={value} />
+	{/if}
+</div>
+
+<style>
+	.rating {
+		--like-pop: var(--duration-medium);
+		--like-pop-ease: var(--ease-smooth-out);
+		--like-fill: var(--duration-quick);
+		--like-ease: var(--ease-smooth-out);
+
+		display: flex;
+		align-items: center;
+		gap: 0.25rem;
+	}
+
+	.stars {
+		display: flex;
+		align-items: center;
+	}
+
+	.hit {
+		display: inline-flex;
+		border-radius: var(--radius-sm);
+	}
+
+	.hit-button {
+		transition: transform var(--duration-quick, 150ms) var(--ease-smooth-out, ease);
+	}
+
+	.hit-button:focus-visible {
+		outline: none;
+		box-shadow: 0 0 0 2px var(--color-ring);
+	}
+
+	.hit-button:not(.is-disabled):hover {
+		transform: scale(1.1);
+	}
+
+	.hit-button:not(.is-disabled):active {
+		transform: scale(0.95);
+	}
+
+	.is-disabled {
+		cursor: not-allowed;
+		opacity: 0.6;
+	}
+
+	.rating :global(.star) {
+		color: var(--color-border);
+		transition: color var(--like-fill) var(--like-ease);
+	}
+
+	.rating :global(.star.is-filled) {
+		color: var(--color-warning-400);
+	}
+
+	/* The glow is the size's business, not a prop: it belongs to the ask, where
+	   the stars are large enough to carry it, and it turned to mud at 16px. */
+	.rating-lg :global(.star.is-filled) {
+		filter: drop-shadow(0 0 4px color-mix(in oklab, var(--color-warning-400) 45%, transparent));
+	}
+
+	/* transitions.dev like-button pop. Every selected star pops, left to right,
+	   as one gesture. A class on the group drives it, since rebuilding the row
+	   would drop keyboard focus. */
+	.is-popping .hit-button[data-on="true"] {
+		animation: t-like-pop var(--like-pop) var(--like-pop-ease) var(--pop-delay, 0ms);
+	}
+
+	@keyframes t-like-pop {
+		0% {
+			transform: scale(1);
+		}
+		30% {
+			transform: scale(0.82);
+		}
+		100% {
+			transform: scale(1);
+		}
+	}
+
+	.rating-caption {
+		font-size: 0.75rem;
+		font-weight: 500;
+		font-variant-numeric: tabular-nums;
+		color: var(--color-muted-foreground);
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hit-button,
+		.is-popping .hit-button[data-on="true"] {
+			animation: none;
+			transition: none;
+		}
+
+		.hit-button:not(.is-disabled):hover,
+		.hit-button:not(.is-disabled):active {
+			transform: none;
+		}
+	}
+</style>

package/src/components/svg/index.ts

@@ -0,0 +1 @@
+export { default as Svg } from "./svg.svelte";

package/src/components/svg/svg.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+// Renders a drawing kept in its own .svg file, imported with `?raw`.
+// The markup is ours and static, so rendering it as HTML is safe.
+let { src, class: className = "" }: { src: string; class?: string } = $props();
+
+const markup = $derived(className ? src.replace("<svg", `<svg class="${className}"`) : src);
+</script>
+
+{@html markup}

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

@@ -37,7 +37,7 @@
 
 	// STATE
 	const uid = `bb-${Math.random().toString(36).slice(2, 10)}`;
-	let container = null;
+	let container = $state<HTMLElement | null>(null);
 	let systemTheme = $state<ResolvedTheme>("dark");
 	let isActive = $state(false);
 	let isFading = $state(false);

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

@@ -1,9 +1,18 @@
+/*
+ * 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%;
@@ -15,14 +24,32 @@
   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: 2px;
-  translate: -1px 0;
+  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(--elev-2, 0 2px 8px rgb(0 0 0 / 0.25));
+  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 {
@@ -32,18 +59,18 @@
   translate: -50% -50%;
   display: grid;
   place-items: center;
-  width: 2rem;
-  height: 2rem;
+  width: var(--hr-compare-grip-size, 2rem);
+  height: var(--hr-compare-grip-size, 2rem);
   border-radius: 999px;
-  background: inherit;
+  background: var(--hr-compare-grip-bg, var(--hr-compare-handle-color, white));
   color: var(--hr-compare-grip-color, black);
-  font-size: 0.75rem;
-  line-height: 1;
+  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;
@@ -51,6 +78,8 @@
   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);
@@ -63,4 +92,9 @@
       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

@@ -1,3 +1,18 @@
+<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
@@ -5,21 +20,35 @@
 	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: { src: string; alt: string };
+		before: ComparisonImage;
 		/** 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. */
+		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;
 	}
 
@@ -29,64 +58,152 @@
 	let {
 		before,
 		after,
-		start = 50,
+		position = $bindable(50),
 		hover = false,
+		hint,
+		eager = false,
 		label = "Compare before and after",
+		beforeBadge,
+		afterBadge,
+		badgeEdge = "bottom",
 		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));
+	// 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 = Math.min(Math.max(((event.clientX - rect.left) / rect.width) * 100, 0), 100);
+		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)}
+	onpointerdown={() => {
+		dragging = true;
+		touch();
+	}}
 	onpointerup={() => (dragging = false)}
+	onpointercancel={() => (dragging = false)}
 	onpointerleave={() => {
 		dragging = false;
-		if (hover) position = start;
+		if (hover) position = rest;
 	}}
+	onkeydown={touch}
 >
-	<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"
-	/>
+	{@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="0.1"
+		step="1"
 		aria-label={label}
 		bind:value={position}
 	/>
-	<div class="hr-compare__handle"><span class="hr-compare__grip">◀▶</span></div>
+	<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);
+}