@heyramzi/ui 1.54.2 → 2.0.1

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/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/gallery.test.ts

@@ -28,7 +28,12 @@ const SITE = join(PKG, "..", "..", "site", "src", "lib");
 
 describe("site gallery coverage", () => {
   it("gives every animation a stage", () => {
-    const section = readFileSync(join(SITE, "demos", "motion.svelte"), "utf8");
+    // Each animation's stage is its own file under demos/motion/.
+    const stages = join(SITE, "demos", "motion");
+    const section = readdirSync(stages)
+      .filter((file) => file.endsWith(".svelte"))
+      .map((file) => readFileSync(join(stages, file), "utf8"))
+      .join("\n");
     const missing = readdirSync(join(PKG, "src", "animations"))
       .filter((file) => file.endsWith(".css") && file !== "index.css")
       .filter((file) => !section.includes(`animations/${file.replace(".css", "")}`));
@@ -43,6 +48,20 @@ describe("site gallery coverage", () => {
     expect(vendored.filter((name) => !manifest.includes(`name: "${name}"`))).toEqual([]);
   });
 
+  it("gives every component, AI part and effect a place on the site", () => {
+    const walk = (dir: string): string[] =>
+      readdirSync(dir, { withFileTypes: true }).flatMap((d) =>
+        d.isDirectory() ? walk(join(dir, d.name)) : /\.(svelte|ts)$/.test(d.name) ? [join(dir, d.name)] : [],
+      );
+    const site = walk(join(SITE, "..")).map((file) => readFileSync(file, "utf8")).join("\n");
+    const parts = ["components", "ai", "effects"].flatMap((top) =>
+      readdirSync(join(PKG, "src", top), { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => `${top}/${d.name}`),
+    );
+    expect(parts.filter((part) => !site.includes(`${part}/`) && !site.includes(`${part}"`))).toEqual([]);
+  });
+
   it("keeps a demo file behind every listed primitive", () => {
     const manifest = readFileSync(join(SITE, "shadcn-demos", "index.ts"), "utf8");
     const listed = [...manifest.matchAll(/name: "([a-z-]+)"/g)].map((m) => m[1]);

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

package/src/onboarding/demo.svelte

@@ -0,0 +1,86 @@
+<script lang="ts">
+	import { Button } from "../shadcn/button/index.js";
+	import { Badge } from "../shadcn/badge/index.js";
+	import { Plus } from "phosphor-svelte";
+	import OnboardingProvider from "./onboarding-provider.svelte";
+	import { defineTours } from "./define-tours.js";
+	import { memoryStore } from "./stores.js";
+	import type { Strings } from "./types.js";
+
+	const tours = defineTours([
+		{
+			id: "demo:intro",
+			route: "/demo/intro",
+			kind: "intro",
+			title: "The week in one place",
+			body: "Open work sits on the left. Anything late floats to the top.",
+		},
+		{
+			id: "demo:board",
+			route: "/demo/board",
+			kind: "steps",
+			steps: [
+				{ target: '[data-tour="demo-new"]', title: "Start here", body: "A new project takes a name and a client. That's all.", placement: "bottom-end" },
+				{ target: '[data-tour="demo-filter"]', title: "Narrow it down", body: "Late shows what slipped. Mine shows what's yours.", placement: "bottom-start" },
+				{ target: '[data-tour="demo-list"]', title: "Open a row", body: "Click a project to see its tasks, files and notes.", placement: "top" },
+			],
+		},
+	]);
+
+	const strings: Strings = {
+		next: "Next",
+		back: "Back",
+		done: "Got it",
+		skip: "Skip the tour",
+		progress: (n, total) => `Step ${n} of ${total}`,
+	};
+
+	const rows = [
+		{ name: "Brand refresh", client: "Northwind", tone: "success" as const, label: "On track" },
+		{ name: "Pricing page", client: "Acme", tone: "warning" as const, label: "Late" },
+		{ name: "Launch email", client: "Globex", tone: "neutral" as const, label: "Draft" },
+	];
+
+	let routeId = $state<string | null>(null);
+	let run = $state(0);
+	let store = $state(memoryStore());
+
+	// A fresh store each time, so the button always has an unseen tour to show.
+	function start(route: string) {
+		store = memoryStore();
+		routeId = route;
+		run += 1;
+	}
+</script>
+
+<div class="flex flex-col gap-4">
+	<div class="flex flex-wrap gap-2">
+		<Button variant="outline" size="sm" onclick={() => start("/demo/board")}>Show the page tour</Button>
+		<Button variant="outline" size="sm" onclick={() => start("/demo/intro")}>Show the intro card</Button>
+	</div>
+
+	<div class="bg-card ring-foreground/10 flex flex-col gap-4 rounded-xl p-4 ring-1">
+		<div class="flex items-center justify-between gap-3">
+			<h2 class="text-sm font-semibold">Projects</h2>
+			<Button size="sm" data-tour="demo-new"><Plus weight="bold" />New project</Button>
+		</div>
+		<div class="flex gap-1.5" data-tour="demo-filter">
+			<Badge variant="outline">All</Badge>
+			<Badge variant="outline">Late</Badge>
+			<Badge variant="outline">Mine</Badge>
+		</div>
+		<ul class="divide-border border-border divide-y rounded-lg border" data-tour="demo-list">
+			{#each rows as row (row.name)}
+				<li class="flex items-center justify-between gap-3 px-3 py-2.5 text-sm">
+					<span class="min-w-0 truncate font-medium">{row.name}</span>
+					<span class="text-muted-foreground hidden sm:block">{row.client}</span>
+					<Badge variant="outline">{row.label}</Badge>
+				</li>
+			{/each}
+		</ul>
+	</div>
+</div>
+
+{#key run}
+	<OnboardingProvider {tours} {store} {strings} {routeId} replayKey={false} />
+{/key}

package/src/onboarding/index.ts

@@ -0,0 +1,12 @@
+export { default as OnboardingProvider } from "./onboarding-provider.svelte";
+export { onboarding } from "./onboarding.svelte.js";
+export { defineTours } from "./define-tours.js";
+export { localStorageStore, memoryStore } from "./stores.js";
+export type {
+	Outcome,
+	Placement,
+	SeenStore,
+	Step,
+	Strings,
+	Tour,
+} from "./types.js";