@heyramzi/ui 1.54.1 → 2.0.0

package/src/editor/slash-menu.svelte

@@ -0,0 +1,159 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { SlashItem } from "./slash-items.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	items: SlashItem[];
+	pos: { top: number; left: number };
+	selectedIndex: number;
+	/** The menu element, so the parent can close it on an outside click. */
+	el?: HTMLDivElement;
+	onselect: (item: SlashItem) => void;
+}
+
+// =========================
+// PROPS
+// =========================
+let { items, pos, selectedIndex = $bindable(), el = $bindable(), onselect }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div
+	bind:this={el}
+	class="slash-menu"
+	style="top: {pos.top}px; left: {pos.left}px;"
+	role="listbox"
+>
+	{#each items as item, i}
+		<button
+			type="button"
+			class="slash-item"
+			class:selected={i === selectedIndex}
+			onclick={() => onselect(item)}
+			onpointerenter={() => selectedIndex = i}
+			role="option"
+			aria-selected={i === selectedIndex}
+		>
+			<span class="slash-icon">
+				<item.icon size={18} />
+			</span>
+			<span class="slash-text">
+				<span class="slash-label">{item.label}</span>
+				<span class="slash-desc">{item.description}</span>
+			</span>
+		</button>
+	{/each}
+</div>
+
+<!-- =========================== -->
+<!-- STYLE -->
+<!-- =========================== -->
+<style>
+	/* ---- SLASH COMMAND MENU ---- */
+	.slash-menu {
+		position: absolute;
+		z-index: 50;
+		min-width: 260px;
+		max-height: 340px;
+		overflow-y: auto;
+		padding: 6px;
+		background: var(--color-popover);
+		border: 1px solid var(--color-border);
+		border-radius: var(--radius-xl);
+		box-shadow: var(--elev-overlay);
+		animation: slash-enter var(--duration-fast) var(--ease-out);
+	}
+
+	@keyframes slash-enter {
+		from {
+			opacity: 0;
+			transform: translateY(-3px) scale(0.98);
+		}
+		to {
+			opacity: 1;
+			transform: translateY(0) scale(1);
+		}
+	}
+
+	.slash-item {
+		display: flex;
+		align-items: center;
+		gap: 0.75rem;
+		width: 100%;
+		padding: 0.5rem 0.625rem;
+		border: none;
+		border-radius: var(--radius-md);
+		background: transparent;
+		color: var(--color-foreground);
+		cursor: pointer;
+		text-align: left;
+		transition: background-color var(--duration-micro) var(--ease-smooth-out);
+	}
+
+	.slash-item.selected {
+		background: var(--color-accent);
+	}
+
+	@media (hover: hover) and (pointer: fine) {
+		.slash-item:hover {
+			background: var(--color-accent);
+		}
+	}
+
+	.slash-icon {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 2rem;
+		height: 2rem;
+		border-radius: var(--radius-sm);
+		background: var(--color-muted);
+		color: var(--color-muted-foreground);
+		flex-shrink: 0;
+		transition: background-color var(--duration-micro) var(--ease-smooth-out), color var(--duration-micro) var(--ease-smooth-out);
+	}
+
+	.slash-item.selected .slash-icon {
+		background: oklch(from var(--color-brand) l c h / 0.1);
+		color: var(--color-brand);
+	}
+
+	@media (hover: hover) and (pointer: fine) {
+		.slash-item:hover .slash-icon {
+			background: oklch(from var(--color-brand) l c h / 0.1);
+			color: var(--color-brand);
+		}
+	}
+
+	.slash-text {
+		display: flex;
+		flex-direction: column;
+		gap: 0;
+		min-width: 0;
+	}
+
+	.slash-label {
+		font-size: 0.8125rem;
+		font-weight: 500;
+		line-height: 1.3;
+	}
+
+	.slash-desc {
+		font-size: 0.6875rem;
+		color: var(--color-muted-foreground);
+		line-height: 1.3;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.slash-menu {
+			animation: none;
+		}
+	}
+</style>

package/src/editor/youtube-url.ts

@@ -0,0 +1,35 @@
+// No markdown-it here, so the editor can import it without the markdown engine.
+
+export const YOUTUBE_ID_RE = /^[A-Za-z0-9_-]{11}$/;
+
+export type YoutubeRef = { videoId: string; start: number };
+
+function toUrl(url: string): URL | null {
+  try {
+    return new URL(url);
+  } catch {
+    return null;
+  }
+}
+
+function videoIdOf(parsed: URL): string | null {
+  const host = parsed.hostname.replace(/^www\./, "");
+  if (host === "youtu.be") return parsed.pathname.slice(1);
+  if (host !== "youtube.com" && host !== "m.youtube.com") return null;
+  if (parsed.pathname === "/watch") return parsed.searchParams.get("v");
+  if (parsed.pathname.startsWith("/embed/")) return parsed.pathname.slice("/embed/".length);
+  return null;
+}
+
+/**
+ * Reads youtube.com/watch?v=ID, youtu.be/ID and youtube.com/embed/ID. A `t`
+ * param in seconds becomes `start`.
+ */
+export function parseYoutubeUrl(url: string): YoutubeRef | null {
+  const parsed = toUrl(url);
+  if (!parsed) return null;
+  const videoId = videoIdOf(parsed);
+  if (!videoId || !YOUTUBE_ID_RE.test(videoId)) return null;
+  const t = parseInt(parsed.searchParams.get("t") ?? "", 10);
+  return { videoId, start: Number.isFinite(t) && t > 0 ? t : 0 };
+}

package/src/effects/animated-beam/AnimatedBeam.svelte

@@ -6,7 +6,7 @@
 	// =========================
 	// IMPORTS
 	// =========================
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 	import BeamSvg from "./diagrams/BeamSvg.svelte";
 	import { usePathCalculator } from "./path-calculator.svelte.js";
 

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

@@ -1,4 +1,3 @@
-import { tryCatch } from "@heyramzi/utils";
 import type { BorderBeamSize } from "./presets.js";
 
 interface PropertyRegistration {
@@ -32,7 +31,10 @@ export function registerBorderBeamProperties(id: string, size: BorderBeamSize):
   if (typeof registry?.registerProperty !== "function") return;
 
   for (const registration of getBorderBeamPropertyRegistrations(id, size)) {
-    tryCatch(() => registry.registerProperty?.(registration));
+    // A second register of the same name throws. The first one already holds, so there is nothing to do.
+    try {
+      registry.registerProperty?.(registration);
+    } catch {}
   }
 }
 

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

@@ -18,7 +18,7 @@
 	// IMPORTS
 	// =========================
 	import "./ImageComparison.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 	import { untrack } from "svelte";
 	import { positionAt } from "./compare.js";
 

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

@@ -40,7 +40,7 @@
 	// IMPORTS
 	// =========================
 	import "./ImageReveal.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 
 	// =========================
 	// PROPS

package/src/effects/interactive-hover-button/InteractiveHoverButton.svelte

@@ -233,13 +233,13 @@ let classes = $derived(
 		transition: opacity var(--duration-fast) var(--ease-smooth-out), transform var(--duration-fast) var(--ease-smooth-out);
 	}
 
-	/* terra-600, not terra-400: the dot becomes the hover fill under a cream
-	   label, and cream on terra-400 is 3.24:1. It works in both themes. */
+	/* signal-600, not signal-400: the dot becomes the hover fill under a paper
+	   label, and paper on signal-400 fails AA. It works in both themes. */
 	.cta-hover__dot {
 		width: 8px;
 		height: 8px;
 		border-radius: 50%;
-		background: var(--color-terra-600);
+		background: var(--color-signal-600);
 		flex-shrink: 0;
 		transition: transform var(--duration-fast) var(--ease-smooth-out);
 	}
@@ -264,9 +264,9 @@ let classes = $derived(
 		transition:
 			transform var(--duration-fast) var(--ease-smooth-out),
 			opacity var(--duration-fast) var(--ease-smooth-out);
-		/* The reveal label always lands on the terra-600 dot fill, where cream
+		/* The reveal label always lands on the signal-600 dot fill, where paper
 		   clears AA at button-label sizes. */
-		color: var(--color-brand-cream);
+		color: var(--color-paper);
 		pointer-events: none;
 	}
 
@@ -279,16 +279,16 @@ let classes = $derived(
 	/* Coral fill, heavier than the ink default. It comes after the .dark rules
 	   so one set of colors covers both themes. */
 	.cta-hover--coral {
-		/* Cream label on terra-600: on terra-400 it's 3.24:1 and fails AA. */
-		color: var(--color-brand-cream);
+		/* Paper label on signal-600: on signal-400 it fails AA. */
+		color: var(--color-paper);
 	}
 
 	.cta-hover--coral::after {
-		background: var(--color-terra-600);
+		background: var(--color-signal-600);
 	}
 
 	.cta-hover--coral.cta-hover--no-beam {
-		background: var(--color-terra-600);
+		background: var(--color-signal-600);
 	}
 
 	.cta-hover--coral::before,
@@ -296,17 +296,17 @@ let classes = $derived(
 		background: conic-gradient(
 			transparent 0deg,
 			transparent 220deg,
-			var(--color-brand-cream) 280deg,
-			var(--color-terra-200) 320deg,
+			var(--color-paper) 280deg,
+			var(--color-signal-200) 320deg,
 			transparent 360deg
 		);
 	}
 
-	/* Ink dot on coral, so hover turns the button black under a cream label
+	/* Ink dot on coral, so hover turns the button black under a paper label
 	   instead of washing it out to cream. */
 	.cta-hover--coral .cta-hover__dot,
 	:global(.dark) .cta-hover--coral .cta-hover__dot {
-		background: var(--color-brand-ink);
+		background: var(--color-ink);
 	}
 
 	@media (hover: hover) and (pointer: fine) {

package/src/effects/magic-card/MagicCard.svelte

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import "./MagicCard.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 	import type { Snippet } from "svelte";
 
 	// =========================

package/src/effects/marquee/Marquee.svelte

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import "./Marquee.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 	import type { Snippet } from "svelte";
 
 	// =========================

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

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import "./ProgressiveBlur.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 
 	// =========================
 	// TYPES

package/src/effects/reveal/AnimatedGroup.svelte

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import "./reveal.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 	import type { Snippet } from "svelte";
 	import { observeInView } from "./observe.js";
 	import type { RevealTiming, RevealViewOptions } from "./types.js";

package/src/effects/reveal/InView.svelte

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import "./reveal.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 	import type { Snippet } from "svelte";
 	import { observeInView } from "./observe.js";
 	import type { RevealTiming, RevealViewOptions } from "./types.js";

package/src/effects/reveal/TextEffect.svelte

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import "./reveal.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 	import { observeInView } from "./observe.js";
 	import type { RevealPer, RevealTiming, RevealViewOptions } from "./types.js";
 

package/src/effects/shader-gradient/ShaderGradient.svelte

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import { untrack } from "svelte";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 	import { resolveColor } from "./color.js";
 	import {
 		createShaderGradientRenderer,

package/src/effects/spotlight/Spotlight.svelte

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import "./Spotlight.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 
 	// =========================
 	// TYPES

package/src/effects/theme-toggle/ThemeToggle.svelte

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import "./ThemeToggle.css";
-	import { cn } from "@heyramzi/utils";
+	import { cn } from "../../lib/utils.js";
 	import { Monitor, Moon, Sun } from "phosphor-svelte";
 	import { revealTheme } from "../../lib/theme-transition.js";
 
@@ -69,8 +69,8 @@
 	}
 
 	function iconClass(show: boolean, tilt: "rotate-90" | "-rotate-90") {
-		return `absolute size-4 transition-all duration-300 ${
-			show ? "scale-100 rotate-0 opacity-100" : `scale-0 ${tilt} opacity-0`
+		return `absolute size-4 transition-[opacity,scale,rotate] duration-300 ${
+			show ? "scale-100 rotate-0 opacity-100" : `scale-90 ${tilt} opacity-0`
 		}`;
 	}
 </script>
@@ -107,7 +107,7 @@
 		aria-label={text}
 		{title}
 		class={cn(
-			"theme-toggle relative flex cursor-pointer items-center justify-center rounded-lg transition-all duration-300",
+			"theme-toggle relative flex cursor-pointer items-center justify-center rounded-lg transition-[background-color,border-color,color] duration-300",
 			size === "sm" ? "size-8" : "size-10",
 			style === "inverted" && "theme-toggle--inverted",
 			style === "ghost" && "text-muted-foreground hover:bg-muted/40 hover:text-foreground",

package/src/lib/result.ts

@@ -0,0 +1,19 @@
+// A small Result type, so a throw becomes a value the caller has to look at.
+
+export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+export function tryCatch<T>(fn: () => T): Result<T> {
+  try {
+    return { ok: true, value: fn() };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e : new Error(String(e)) };
+  }
+}
+
+export async function tryCatchAsync<T>(fn: () => Promise<T>): Promise<Result<T>> {
+  try {
+    return { ok: true, value: await fn() };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e : new Error(String(e)) };
+  }
+}

package/src/lib/utils.ts

@@ -0,0 +1,18 @@
+// The class merge and prop types every shadcn primitive is written against. They live here, not in
+// a shared utils package, so this public package installs with nothing private behind it.
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+export type WithElementRef<T, U extends HTMLElement = HTMLElement> = T & {
+  ref?: U | null;
+};
+
+export type WithoutChildren<T> = T extends { children?: unknown } ? Omit<T, "children"> : T;
+
+export type WithoutChild<T> = T extends { child?: unknown } ? Omit<T, "child"> : T;
+
+export type WithoutChildrenOrChild<T> = WithoutChildren<WithoutChild<T>>;

package/src/onboarding/README.md

@@ -0,0 +1,120 @@
+# @heyramzi/ui/onboarding
+
+Svelte 5 page tours. A dimmed page, one lit element and a short card per step, shown once per page and
+remembered per person. Live at [ui.heyramzi.com/onboarding](https://ui.heyramzi.com/onboarding).
+
+It builds on [`@zag-js/tour`](https://zagjs.com/components/svelte/tour) (MIT) for spotlight geometry, focus and
+keys, and draws the card itself with the rest of `@heyramzi/ui`, so it looks like the rest of your app.
+`phosphor-svelte` and `svelte` are peers.
+
+```
+pnpm add @heyramzi/ui phosphor-svelte
+```
+
+## Define the tours
+
+A tour belongs to a SvelteKit route id, so params never matter. `steps` points at elements by CSS selector. `intro`
+is one centred card with no target, for a page's first visit.
+
+```ts
+import { defineTours } from "@heyramzi/ui/onboarding";
+
+export const tours = defineTours([
+  {
+    id: "home",
+    route: "/(app)",
+    kind: "intro",
+    title: "The week in one place",
+    body: "Open work sits on the left. Anything late floats to the top.",
+  },
+  {
+    id: "projects-board",
+    version: 1,
+    route: "/(app)/projects",
+    kind: "steps",
+    steps: [
+      { target: '[data-tour="new-project"]', title: "Start here", body: "A name and a client. That's all." },
+    ],
+  },
+]);
+```
+
+`defineTours` throws on a repeated id, a route that isn't a route id, and a `steps` tour with fewer than 1 or more
+than 6 steps. Past 6, people skip.
+
+## Mount it once
+
+Put the provider in the root layout, next to the page slot.
+
+```svelte
+<script lang="ts">
+  import { page } from "$app/state";
+  import { OnboardingProvider, localStorageStore } from "@heyramzi/ui/onboarding";
+  import { tours } from "$lib/tours";
+
+  const strings = {
+    next: "Next",
+    back: "Back",
+    done: "Got it",
+    skip: "Skip the tour",
+    progress: (n: number, total: number) => `Step ${n} of ${total}`,
+  };
+</script>
+
+<OnboardingProvider {tours} store={localStorageStore()} {strings} routeId={page.route.id} />
+```
+
+On every navigation it picks the first unseen tour for the route, waits up to 2 seconds for the first step's target,
+drops steps whose target never shows, and starts. A tour with no target on the page starts nothing. One tour per page
+view, never two stacked. Strings are yours, so translate them before you pass them in.
+
+| Prop | Default | |
+| --- | --- | --- |
+| `tours` | | From `defineTours`. |
+| `store` | | A `SeenStore`. |
+| `strings` | | `next`, `back`, `done`, `skip`, `progress(n, total)`. |
+| `routeId` | | `page.route.id`. |
+| `enabled` | `true` | Set `false` while signed out. |
+| `replayKey` | `true` | Press `?` to replay. |
+| `waitMs` | `2000` | How long to wait for the first target. |
+
+## Replay
+
+```ts
+import { onboarding } from "@heyramzi/ui/onboarding";
+
+onboarding.replay();          // this page's tour
+onboarding.replay("home");    // a named tour
+onboarding.hasTour;           // true when this page has one
+```
+
+Replay writes no seen-state. `onboarding.hasTour` is reactive, so a "Show me around" menu item can hide itself on
+pages without a tour.
+
+## Seen-state
+
+`SeenStore` is three methods. `load` runs once per session and returns tour id to the version seen.
+
+```ts
+interface SeenStore {
+  load(): Promise<Record<string, number>>;
+  markSeen(tourId: string, version: number, outcome: "completed" | "dismissed"): Promise<void>;
+  reset(tourId?: string): Promise<void>;
+}
+```
+
+The store keeps a version, not a boolean. Raise a tour's `version` after the page changes and everyone sees it
+again. `localStorageStore(key?)` and `memoryStore(initial?)` come with the package and also live at
+`@heyramzi/ui/onboarding/stores`. Server stores belong in the app: a table keyed by user and tour id, and a `fetch`
+adapter.
+
+If `load` rejects, no tour shows that session.
+
+## Phones and motion
+
+Under 640px every step is a bottom sheet over the page, and the target scrolls above it. With
+`prefers-reduced-motion` the spotlight and card stop animating.
+
+## License
+
+MIT

package/src/onboarding/define-tours.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vite-plus/test";
+import { defineTours } from "./define-tours.js";
+import type { Step, Tour } from "./types.js";
+
+const step = (n: number): Step => ({ target: `[data-tour="s${n}"]`, title: `Title ${n}`, body: `Body ${n}` });
+const steps = (count: number) => Array.from({ length: count }, (_, i) => step(i + 1));
+const board = (over: Partial<Extract<Tour, { kind: "steps" }>> = {}): Tour => ({
+	id: "board",
+	route: "/(app)/projects",
+	kind: "steps",
+	steps: steps(3),
+	...over,
+});
+
+describe("defineTours", () => {
+	it("returns the tours it was given", () => {
+		const list = [board(), { id: "home", route: "/(app)", kind: "intro", title: "Hi", body: "Welcome." } as const];
+		expect(defineTours(list)).toBe(list);
+	});
+
+	it("rejects a repeated id", () => {
+		expect(() => defineTours([board(), board({ route: "/(app)/other" })])).toThrow(/"board".*used twice/);
+	});
+
+	it("takes 1 to 6 steps", () => {
+		expect(() => defineTours([board({ steps: steps(1) })])).not.toThrow();
+		expect(() => defineTours([board({ steps: steps(6) })])).not.toThrow();
+		expect(() => defineTours([board({ steps: [] })])).toThrow(/0 steps/);
+		expect(() => defineTours([board({ steps: steps(7) })])).toThrow(/7 steps/);
+	});
+
+	it("rejects a route that isn't a route id", () => {
+		expect(() => defineTours([board({ route: "projects" })])).toThrow(/not a route id/);
+	});
+
+	it("rejects a bad version", () => {
+		expect(() => defineTours([board({ version: 0 })])).toThrow(/version/);
+		expect(() => defineTours([board({ version: 1.5 })])).toThrow(/version/);
+		expect(() => defineTours([board({ version: 2 })])).not.toThrow();
+	});
+
+	it("rejects a step with no target or no words", () => {
+		expect(() => defineTours([board({ steps: [{ ...step(1), target: " " }] })])).toThrow(/step 1 has no target/);
+		expect(() => defineTours([board({ steps: [{ ...step(1), body: "" }] })])).toThrow(/title and a body/);
+	});
+
+	it("rejects an intro with no title", () => {
+		expect(() => defineTours([{ id: "home", route: "/(app)", kind: "intro", title: "", body: "x" }])).toThrow(/intro/);
+	});
+});

package/src/onboarding/define-tours.ts

@@ -0,0 +1,31 @@
+import { MAX_STEPS, type Tour } from "./types.js";
+
+function fail(id: string, problem: string): never {
+	throw new Error(`tour "${id}": ${problem}`);
+}
+
+/** Returns the tours as written, after checking what a typo would hide until a user hits it. */
+export function defineTours<const T extends readonly Tour[]>(tours: T): T {
+	const ids = new Set<string>();
+	for (const tour of tours) {
+		const { id } = tour;
+		if (!id || !id.trim()) throw new Error("a tour needs an id");
+		if (ids.has(id)) fail(id, "its id is used twice");
+		ids.add(id);
+		if (!tour.route.startsWith("/")) fail(id, `route "${tour.route}" is not a route id`);
+		const version = tour.version ?? 1;
+		if (!Number.isInteger(version) || version < 1) fail(id, "version is a whole number from 1");
+		if (tour.kind === "intro") {
+			if (!tour.title || !tour.body) fail(id, "an intro needs a title and a body");
+			continue;
+		}
+		if (tour.steps.length < 1 || tour.steps.length > MAX_STEPS) {
+			fail(id, `has ${tour.steps.length} steps, and a tour takes 1 to ${MAX_STEPS}`);
+		}
+		tour.steps.forEach((step, i) => {
+			if (!step.target.trim()) fail(id, `step ${i + 1} has no target`);
+			if (!step.title || !step.body) fail(id, `step ${i + 1} needs a title and a body`);
+		});
+	}
+	return tours;
+}