@heyramzi/ui 3.6.0 → 3.7.1

package/src/components/docs/scroll-spy.svelte.js

@@ -0,0 +1,76 @@
+/** How far below the scroller's top edge a heading counts as "reached" and lands. */
+export const READ_LINE = 80;
+export class ScrollSpy {
+	active = $state("");
+	#scroller = null;
+	#items = [];
+	#locate;
+	#frame = 0;
+	/** Point the spy at a scroller and a list. Returns the cleanup. */
+	attach(scroller, items, locate) {
+		this.#scroller = scroller;
+		this.#items = items;
+		this.#locate = locate;
+		if (!scroller || items.length === 0) {
+			this.active = "";
+			return () => {};
+		}
+		const schedule = () => {
+			this.#frame ||= requestAnimationFrame(() => {
+				this.#frame = 0;
+				this.update();
+			});
+		};
+		scroller.addEventListener("scroll", schedule, { passive: true });
+		const observer = new ResizeObserver(schedule);
+		observer.observe(scroller);
+		// A document that grows after load (a diagram, a chart) moves every
+		// heading below it, so watch the content too.
+		for (const child of scroller.children) observer.observe(child);
+		this.update();
+		return () => {
+			scroller.removeEventListener("scroll", schedule);
+			observer.disconnect();
+			if (this.#frame) cancelAnimationFrame(this.#frame);
+			this.#frame = 0;
+		};
+	}
+	topOf(id) {
+		const scroller = this.#scroller;
+		if (!scroller) return null;
+		if (this.#locate) return this.#locate(id);
+		const el = scroller.querySelector(`#${CSS.escape(id)}`);
+		if (!el) return null;
+		return el.getBoundingClientRect().top - scroller.getBoundingClientRect().top + scroller.scrollTop;
+	}
+	update() {
+		const scroller = this.#scroller;
+		if (!scroller || this.#items.length === 0) return;
+		// At the very bottom the last heading wins, or a short final section could
+		// never be the current one.
+		const atEnd = scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 2;
+		if (atEnd && scroller.scrollTop > 0) {
+			this.active = this.#items[this.#items.length - 1].id;
+			return;
+		}
+		const line = scroller.scrollTop + READ_LINE + 1;
+		let current = this.#items[0].id;
+		for (const item of this.#items) {
+			const top = this.topOf(item.id);
+			if (top !== null && top <= line) current = item.id;
+		}
+		this.active = current;
+	}
+	/** Scroll so the heading lands on the read line, instant under reduced motion. */
+	jump(id) {
+		const scroller = this.#scroller;
+		const top = this.topOf(id);
+		if (!scroller || top === null) return;
+		const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+		this.active = id;
+		scroller.scrollTo({
+			top: Math.max(0, top - READ_LINE),
+			behavior: reduced ? "auto" : "smooth"
+		});
+	}
+}

package/src/components/open-in/open-in.svelte

@@ -14,8 +14,8 @@
 	}
 
 	/** `chip` is the bordered inline tag, `button` sits in a header beside other
-	 *  buttons, `icon` is the bare mark for a dense row. */
-	export type OpenInVariant = "chip" | "button" | "icon";
+	 *  buttons. A bare-mark form was cut: at 20px it failed WCAG 2.5.8. */
+	export type OpenInVariant = "chip" | "button";
 	export type OpenInSize = "sm" | "default";
 </script>
 
@@ -86,22 +86,21 @@
 		class={cn(
 			variant === "button"
 				? buttonVariants({ variant: "outline", size: size === "sm" ? "sm" : "default" })
-				: variant === "icon"
-					? "inline-flex shrink-0 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
-					: cn(
-							"inline-flex shrink-0 items-center gap-1.5 whitespace-nowrap rounded-md border border-border text-muted-foreground transition-colors hover:bg-muted hover:text-foreground",
-							size === "sm" ? "px-1.5 py-0.5 text-2xs" : "px-2 py-1 text-xs",
-						),
-			variant === "icon" && (size === "sm" ? "size-5" : "size-6"),
+				: cn(
+						"inline-flex shrink-0 items-center gap-1.5 whitespace-nowrap rounded-md border border-border text-muted-foreground transition-colors hover:bg-muted hover:text-foreground",
+						// WHY the button heights: the sm chip was 19px, under the 24px target
+						// floor. Under a thumb it grows to 40 and 44, and the sm hit area to 44.
+						size === "sm"
+							? "relative h-7 px-2 text-2xs after:absolute after:top-1/2 after:left-1/2 after:h-[max(100%,1.5rem)] after:w-[max(100%,1.5rem)] after:-translate-x-1/2 after:-translate-y-1/2 any-pointer-coarse:h-10 any-pointer-coarse:after:h-[max(100%,2.75rem)] any-pointer-coarse:after:w-[max(100%,2.75rem)]"
+							: "h-8 px-2.5 text-xs any-pointer-coarse:h-11 any-pointer-coarse:px-3",
+					),
 			className,
 		)}
 	>
 		<Icon aria-hidden="true" size={iconSize} />
-		{#if variant !== "icon"}
-			{text}
-			<!-- The one thing the mark can't say: this leaves the app. It stays muted
-				     so the eye lands on the tool name first. -->
-			<ArrowSquareOut aria-hidden="true" size={iconSize} class="text-muted-foreground" />
-		{/if}
+		{text}
+		<!-- The one thing the mark can't say: this leaves the app. It stays muted
+		     so the eye lands on the tool name first. -->
+		<ArrowSquareOut aria-hidden="true" size={iconSize} class="text-muted-foreground" />
 	</a>
 </div>

package/src/components/open-in/open-in.svelte.d.ts

@@ -15,8 +15,8 @@ export interface OpenInTool {
     }>;
 }
 /** `chip` is the bordered inline tag, `button` sits in a header beside other
- *  buttons, `icon` is the bare mark for a dense row. */
-export type OpenInVariant = "chip" | "button" | "icon";
+ *  buttons. A bare-mark form was cut: at 20px it failed WCAG 2.5.8. */
+export type OpenInVariant = "chip" | "button";
 export type OpenInSize = "sm" | "default";
 interface Props {
     /** The tool to link to: its name, accessible sentence and mark. */

package/src/consumer-prebundle.test.ts

@@ -0,0 +1,126 @@
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { afterAll, describe, expect, it } from "vite-plus/test";
+import { writeSvelteModules } from "../scripts/lib/svelte-modules.mjs";
+
+// A consumer's dev server prebundles this package, types still in each `.svelte.ts`. 3.6.0's
+// reveal.svelte.ts killed Locameublé's dev server at startup on `import type`.
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+  scripts: Record<string, string>;
+  exports: Record<string, string | string[] | Record<string, string | string[]>>;
+};
+
+/** The Vite core a consumer gets beside vite-plugin-svelte; this package only depends on vite-plus. */
+type Vite = {
+  resolveConfig(config: object, command: "serve", mode: string): Promise<unknown>;
+  optimizeDeps(
+    config: unknown,
+    force: boolean,
+  ): Promise<{ optimized: Record<string, { file: string }> }>;
+};
+const plugin = createRequire(import.meta.url).resolve("@sveltejs/vite-plugin-svelte");
+const vite: Vite = await import(pathToFileURL(createRequire(plugin).resolve("vite")).href);
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else out.push(p);
+  }
+  return out;
+}
+
+/** The tarball's shape: `files` as prepack leaves them, under a consumer's node_modules. */
+async function consumer(): Promise<{ dir: string; ui: string }> {
+  const dir = mkdtempSync(join(tmpdir(), "ui-consumer-"));
+  const nm = join(dir, "node_modules");
+  const ui = join(nm, "@heyramzi/ui");
+  mkdirSync(ui, { recursive: true });
+  cpSync(join(root, "src"), join(ui, "src"), { recursive: true });
+  cpSync(join(root, "package.json"), join(ui, "package.json"));
+  await writeSvelteModules(join(ui, "src"));
+  for (const name of readdirSync(join(root, "node_modules"))) {
+    const from = join(root, "node_modules", name);
+    const scoped = name.startsWith("@") ? readdirSync(from).map((s) => join(name, s)) : [name];
+    if (name.startsWith("@")) mkdirSync(join(nm, name));
+    for (const dep of scoped)
+      symlinkSync(realpathSync(join(root, "node_modules", dep)), join(nm, dep));
+  }
+  writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "consumer", type: "module" }));
+  return { dir, ui };
+}
+
+/** Every subpath a Svelte app can import, wildcards expanded against the tarball's files. */
+function browserEntries(ui: string): string[] {
+  const out = new Set<string>();
+  for (const [key, value] of Object.entries(pkg.exports)) {
+    if (typeof value !== "object" || Array.isArray(value)) continue;
+    const target = value.svelte;
+    if (typeof target !== "string") continue;
+    if (!key.includes("*")) {
+      out.add(`@heyramzi/ui${key.slice(1)}`);
+      continue;
+    }
+    const [head, tail] = target.split("*");
+    for (const file of walk(join(ui, head))) {
+      const rel = relative(join(ui, head), file);
+      if (!rel.endsWith(tail) || /\.(test|spec)\./.test(rel)) continue;
+      out.add(`@heyramzi/ui${key.slice(1).replace("*", rel.slice(0, -tail.length))}`);
+    }
+  }
+  return [...out].toSorted();
+}
+
+const made: string[] = [];
+afterAll(() => {
+  for (const dir of made) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("a consumer's dev server", () => {
+  it("writes the type-free modules on every pack and removes them after", () => {
+    expect(pkg.scripts.prepack).toContain("node scripts/svelte-modules.mjs");
+    expect(pkg.scripts.postpack).toContain("node scripts/svelte-modules.mjs --clean");
+  });
+
+  it("prebundles every Svelte subpath, chat windows included", async () => {
+    const { dir, ui } = await consumer();
+    made.push(dir);
+    const include = browserEntries(ui);
+    expect(include).toContain("@heyramzi/ui/ai/chat-window");
+    expect(include).toContain("@heyramzi/ui/shadcn/hooks/use-highlighted-code.svelte");
+    expect(include).toContain("@heyramzi/ui/canvas/editor/dispatch.svelte.js");
+
+    const config = await vite.resolveConfig(
+      {
+        root: dir,
+        configFile: false,
+        logLevel: "error",
+        plugins: [svelte({ configFile: false })],
+        optimizeDeps: { include, noDiscovery: true },
+      },
+      "serve",
+      "development",
+    );
+    const { optimized } = await vite.optimizeDeps(config, true);
+    const chat = optimized["@heyramzi/ui/ai/chat-window"];
+    expect(chat && existsSync(chat.file)).toBe(true);
+    expect(readFileSync(chat.file, "utf8")).toContain("REVEAL_BEATS");
+  }, 120_000);
+});

package/src/effects/animated-beam/path-calculator.svelte.js

@@ -0,0 +1,54 @@
+function anchorX(rect, containerLeft, anchor, offset) {
+	const left = rect.left - containerLeft;
+	if (anchor === "left") return left + offset;
+	if (anchor === "right") return left + rect.width + offset;
+	return left + rect.width / 2 + offset;
+}
+export function usePathCalculator() {
+	let pathD = $state("");
+	let svgDimensions = $state({
+		width: 0,
+		height: 0
+	});
+	function calculatePath(containerRef, fromRef, toRef, curvature, startXOffset, startYOffset, endXOffset, endYOffset, fromAnchor = "center", toAnchor = "center") {
+		if (!containerRef || !fromRef || !toRef) return;
+		const containerRect = containerRef.getBoundingClientRect();
+		const rectA = fromRef.getBoundingClientRect();
+		const rectB = toRef.getBoundingClientRect();
+		// A scaled ancestor shrinks every rect, but the SVG draws in the container's own pixels.
+		// Divide the scale out, or the beams stop short of their nodes.
+		const scaleX = containerRef.offsetWidth ? containerRect.width / containerRef.offsetWidth : 1;
+		const scaleY = containerRef.offsetHeight ? containerRect.height / containerRef.offsetHeight : 1;
+		const local = (rect) => new DOMRect((rect.left - containerRect.left) / scaleX, (rect.top - containerRect.top) / scaleY, rect.width / scaleX, rect.height / scaleY);
+		const a = local(rectA);
+		const b = local(rectB);
+		svgDimensions = {
+			width: containerRect.width / scaleX,
+			height: containerRect.height / scaleY
+		};
+		const startX = anchorX(a, 0, fromAnchor, startXOffset);
+		const startY = a.top + a.height / 2 + startYOffset;
+		const endX = anchorX(b, 0, toAnchor, endXOffset);
+		const endY = b.top + b.height / 2 + endYOffset;
+		// A cubic with horizontal handles, not a quadratic through a raised midpoint.
+		// The quadratic put its single control point at `midY` minus `curvature`, which for a fan into one node lands past the far end:
+		// the top beam dove below the hub and crossed the middle beam before arriving, and three beams bundled into a lens for the last stretch.
+		// Handles along the axis of travel make each beam leave and arrive perpendicular to its anchor, so a fan converges at the anchor and nowhere else.
+		// `curvature` still bows the middle, and zero still draws a straight line between two anchors at the same height.
+		const span = Math.abs(endX - startX);
+		const handle = Math.max(span * .5, 24);
+		const direction = endX >= startX ? 1 : -1;
+		const c1x = startX + handle * direction;
+		const c2x = endX - handle * direction;
+		pathD = `M ${startX},${startY} C ${c1x},${startY - curvature} ${c2x},${endY - curvature} ${endX},${endY}`;
+	}
+	return {
+		get pathD() {
+			return pathD;
+		},
+		get svgDimensions() {
+			return svgDimensions;
+		},
+		calculatePath
+	};
+}

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

@@ -12,7 +12,8 @@
 		/** `submit` posts the form the button sits in. */
 		type?: "button" | "submit";
 		disabled?: boolean;
-		size?: "default" | "md" | "sm";
+		/** `sm` is 40px for a condensed bar; under a thumb both are 44px. */
+		size?: "default" | "sm";
 		tone?: "ink" | "coral";
 		beam?: boolean;
 		dot?: boolean;
@@ -43,7 +44,6 @@
 	let classes = $derived(
 		[
 			"cta-hover",
-			size === "md" && "cta-hover--md",
 			size === "sm" && "cta-hover--sm",
 			tone === "coral" && "cta-hover--coral",
 			!beam && "cta-hover--no-beam",
@@ -168,28 +168,24 @@
 			pointer-events: none;
 		}
 
-		/* 40px, between 44px and 32px, for a CTA in a condensed bar. 32px is too
-		   small to read as the main action, so only the label shrinks, to 13px. */
-		.cta-hover--md {
+		/* 40px for a CTA in a condensed bar. The old 32px was too small to read as
+		   the main action, so only the label shrinks, to 13px. */
+		.cta-hover--sm {
 			height: 40px;
 			padding: 0 24px;
 			font-size: 13px;
 		}
 
-		.cta-hover--md .cta-hover__dot {
+		.cta-hover--sm .cta-hover__dot {
 			width: 7px;
 			height: 7px;
 		}
 
-		.cta-hover--sm {
-			height: 32px;
-			padding: 0 20px;
-			font-size: 13px;
-		}
-
-		.cta-hover--sm .cta-hover__dot {
-			width: 6px;
-			height: 6px;
+		/* Under a thumb both sizes clear the 44px touch target, as Button does. */
+		@media (any-pointer: coarse) {
+			.cta-hover--sm {
+				height: 44px;
+			}
 		}
 
 		.cta-hover--no-beam::before {
@@ -344,11 +340,39 @@
 			}
 		}
 
+		/* The beam stops, and hover swaps the fill and label in place: no dot
+		   growing out, no label sliding across. */
 		@media (prefers-reduced-motion: reduce) {
 			.cta-hover::before {
 				animation: none;
 				opacity: 0;
 			}
+
+			.cta-hover,
+			.cta-hover__resting,
+			.cta-hover__dot,
+			.cta-hover__label,
+			.cta-hover__reveal,
+			:global(.cta-hover__arrow--inline) {
+				transition-property: opacity, background-color, color;
+			}
+		}
+
+		@media (prefers-reduced-motion: reduce) and (hover: hover) and (pointer: fine) {
+			.cta-hover:hover .cta-hover__dot,
+			.cta-hover:not(.cta-hover--no-dot):hover .cta-hover__resting .cta-hover__label,
+			.cta-hover:not(.cta-hover--no-dot):hover .cta-hover__reveal,
+			.cta-hover--no-dot:hover :global(.cta-hover__arrow--inline) {
+				transform: none;
+			}
+
+			.cta-hover:not(.cta-hover--no-dot):hover::after {
+				background: var(--color-signal-600);
+			}
+
+			.cta-hover--coral:not(.cta-hover--no-dot):hover::after {
+				background: var(--color-ink);
+			}
 		}
 	}
 

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

@@ -3,7 +3,8 @@ interface Props {
     /** `submit` posts the form the button sits in. */
     type?: "button" | "submit";
     disabled?: boolean;
-    size?: "default" | "md" | "sm";
+    /** `sm` is 40px for a condensed bar; under a thumb both are 44px. */
+    size?: "default" | "sm";
     tone?: "ink" | "coral";
     beam?: boolean;
     dot?: boolean;

package/src/onboarding/onboarding.svelte.js

@@ -0,0 +1,19 @@
+class Onboarding {
+	/** True when the current page has a tour, so a menu item can hide itself. */
+	hasTour = $state(false);
+	/** True while a tour is on screen. */
+	running = $state(false);
+	#replay = null;
+	/** The provider registers itself here. Returns the undo for cleanup. */
+	bind(replay) {
+		this.#replay = replay;
+		return () => {
+			if (this.#replay === replay) this.#replay = null;
+		};
+	}
+	/** Restarts this page's tour, or the one named. Writes no seen-state. False when nothing started. */
+	replay(tourId) {
+		return this.#replay ? this.#replay(tourId) : Promise.resolve(false);
+	}
+}
+export const onboarding = new Onboarding();

package/src/shadcn/hooks/is-mobile.svelte.js

@@ -0,0 +1,7 @@
+import { MediaQuery } from "svelte/reactivity";
+const DEFAULT_MOBILE_BREAKPOINT = 768;
+export class IsMobile extends MediaQuery {
+	constructor(breakpoint = DEFAULT_MOBILE_BREAKPOINT) {
+		super(`max-width: ${breakpoint - 1}px`);
+	}
+}

package/src/shadcn/hooks/use-highlighted-code.svelte.js

@@ -0,0 +1,65 @@
+import { loadHighlighter } from "./highlighter.js";
+/**
+* Highlights `code`. Each `current` entry is a plain string until the highlighter loads, then
+* tokens, so pass it to `CodeBlock.Line`'s `code` prop either way.
+*/
+export function useHighlightedCode(value, language) {
+	let loaded = $state.raw(null);
+	$effect(() => {
+		const lang = language();
+		let cancelled = false;
+		loadHighlighter(lang).then((next) => {
+			if (!cancelled) {
+				loaded = {
+					language: lang,
+					highlighter: next
+				};
+			}
+		}).catch(() => {});
+		return () => {
+			cancelled = true;
+		};
+	});
+	// The complete lines, highlighted. While the code streams, only the new
+	// lines are tokenized, starting from the grammar state of the last one.
+	let done = {
+		highlighter: null,
+		text: "",
+		lines: []
+	};
+	const lines = $derived.by(() => {
+		const raw = value();
+		// A trailing newline would render as an extra empty line.
+		const code = raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+		const lang = language();
+		const highlighter = loaded?.language === lang ? loaded.highlighter : null;
+		if (!highlighter) {
+			return code.split("\n");
+		}
+		let next = done;
+		if (next.highlighter !== highlighter || !code.startsWith(next.text)) {
+			next = {
+				highlighter,
+				text: "",
+				lines: []
+			};
+		}
+		const end = code.lastIndexOf("\n") + 1;
+		if (end > next.text.length) {
+			const result = highlighter.highlight(code.slice(next.text.length, end - 1), next.state);
+			next = {
+				highlighter,
+				text: code.slice(0, end),
+				lines: [...next.lines, ...result.lines],
+				state: result.state
+			};
+		}
+		done = next;
+		// The last line is still being written, so it is tokenized every time.
+		const tail = code.slice(end);
+		return [...next.lines, highlighter.highlight(tail, next.state).lines[0]];
+	});
+	return { get current() {
+		return lines;
+	} };
+}

package/src/shadcn/sidebar/context.svelte.js

@@ -0,0 +1,63 @@
+import { IsMobile } from "../hooks/is-mobile.svelte.js";
+import { getContext, setContext } from "svelte";
+import { SIDEBAR_KEYBOARD_SHORTCUT } from "./constants.js";
+// Cmd+B in a field means bold, so the shortcut leaves typing alone.
+function isEditable(target) {
+	if (!(target instanceof HTMLElement)) return false;
+	return target.closest("input, textarea, [contenteditable]:not([contenteditable=\"false\"])") !== null;
+}
+class SidebarState {
+	props;
+	open = $derived.by(() => this.props.open());
+	openMobile = $state(false);
+	setOpen;
+	#isMobile;
+	state = $derived.by(() => this.open ? "expanded" : "collapsed");
+	id;
+	constructor(props) {
+		this.setOpen = props.setOpen;
+		this.id = props.id;
+		this.#isMobile = new IsMobile();
+		this.props = props;
+	}
+	// Convenience getter for checking if the sidebar is mobile
+	// without this, we would need to use `sidebar.isMobile.current` everywhere
+	get isMobile() {
+		return this.#isMobile.current;
+	}
+	/** Whether the sidebar a trigger controls is showing: the sheet on a phone, the panel otherwise. */
+	get expanded() {
+		return this.#isMobile.current ? this.openMobile : this.open;
+	}
+	// Event handler to apply to the `<svelte:window>`
+	handleShortcutKeydown = (e) => {
+		if (e.key === SIDEBAR_KEYBOARD_SHORTCUT && (e.metaKey || e.ctrlKey) && !isEditable(e.target)) {
+			e.preventDefault();
+			this.toggle();
+		}
+	};
+	setOpenMobile = (value) => {
+		this.openMobile = value;
+	};
+	toggle = () => {
+		return this.#isMobile.current ? this.openMobile = !this.openMobile : this.setOpen(!this.open);
+	};
+}
+const SYMBOL_KEY = "scn-sidebar";
+/**
+* Instantiates a new `SidebarState` instance and sets it in the context.
+*
+* @param props The constructor props for the `SidebarState` class.
+* @returns  The `SidebarState` instance.
+*/
+export function setSidebar(props) {
+	return setContext(Symbol.for(SYMBOL_KEY), new SidebarState(props));
+}
+/**
+* Retrieves the `SidebarState` instance from the context. This is a class instance,
+* so you cannot destructure it.
+* @returns The `SidebarState` instance.
+*/
+export function useSidebar() {
+	return getContext(Symbol.for(SYMBOL_KEY));
+}

package/src/shadcn/sidebar/sidebar-provider.svelte

@@ -14,6 +14,7 @@
 		ref = $bindable(null),
 		open = $bindable(true),
 		onOpenChange = () => {},
+		persist = true,
 		class: className,
 		style,
 		children,
@@ -21,6 +22,11 @@
 	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & {
 		open?: boolean;
 		onOpenChange?: (open: boolean) => void;
+		/**
+		 * False for a sidebar that isn't the app's shell, such as a docs demo: it then
+		 * writes no state cookie and takes no Cmd+B, so it can't fold the real one.
+		 */
+		persist?: boolean;
 	} = $props();
 
 	let openState = $state(open);
@@ -40,12 +46,13 @@
 			onOpenChange(value);
 
 			// This sets the cookie to keep the sidebar state.
-			document.cookie = `${SIDEBAR_COOKIE_NAME}=${value}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`;
+			if (persist)
+				document.cookie = `${SIDEBAR_COOKIE_NAME}=${value}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`;
 		},
 	});
 </script>
 
-<svelte:window onkeydown={sidebar.handleShortcutKeydown} />
+<svelte:window onkeydown={persist ? sidebar.handleShortcutKeydown : undefined} />
 
 <Tooltip.Provider delayDuration={0}>
 	<!-- An h-svh frame that never scrolls: the app puts its page in a

package/src/shadcn/sidebar/sidebar-provider.svelte.d.ts

@@ -3,6 +3,11 @@ import type { HTMLAttributes } from "svelte/elements";
 type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
+    /**
+     * False for a sidebar that isn't the app's shell, such as a docs demo: it then
+     * writes no state cookie and takes no Cmd+B, so it can't fold the real one.
+     */
+    persist?: boolean;
 };
 declare const $$Component: import("svelte").Component<$$ComponentProps, {}, "ref" | "open">;
 type $$Component = ReturnType<typeof $$Component>;