create-obsidian-arrow 0.2.2 → 0.4.0

package/template/test/token-utils.test.mjs

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	classifyValue,
+	filterTokens,
+	groupTokens,
+	parseCustomProps,
+} from "../tools/viewer/token-utils.ts";
+
+test("parseCustomProps extracts custom property declarations from rule text", () => {
+	const css = "body.theme-dark { --text-accent: #a288ff; --size-4-2: 8px; color: red; }";
+	assert.deepEqual(parseCustomProps(css), [
+		{ name: "--text-accent", value: "#a288ff" },
+		{ name: "--size-4-2", value: "8px" },
+	]);
+});
+
+test("parseCustomProps does not false-match var() references in values", () => {
+	const css = ".x { --a: var(--b); background: var(--c); }";
+	assert.deepEqual(parseCustomProps(css), [{ name: "--a", value: "var(--b)" }]);
+});
+
+test("groupTokens groups by prefix in stable order, dedupes last-wins, sorts names", () => {
+	const groups = groupTokens([
+		{ name: "--zeta-thing", value: "1" },
+		{ name: "--size-4-4", value: "16px" },
+		{ name: "--size-4-2", value: "8px" },
+		{ name: "--size-4-2", value: "9px" },
+		{ name: "--color-red", value: "#e11" },
+	]);
+	assert.deepEqual(
+		groups.map((g) => g.label),
+		["Size & spacing", "Colors", "Other"]
+	);
+	const size = groups[0];
+	assert.deepEqual(size.tokens, [
+		{ name: "--size-4-2", value: "9px" },
+		{ name: "--size-4-4", value: "16px" },
+	]);
+});
+
+test("classifyValue detects colors, lengths, other", () => {
+	assert.equal(classifyValue("#fff"), "color");
+	assert.equal(classifyValue("#a288ffcc"), "color");
+	assert.equal(classifyValue("rgba(0, 0, 0, 0.3)"), "color");
+	assert.equal(classifyValue("hsl(254, 80%, 68%)"), "color");
+	assert.equal(classifyValue("16px"), "length");
+	assert.equal(classifyValue("0.875em"), "length");
+	assert.equal(classifyValue("inherit"), "other");
+	assert.equal(classifyValue("var(--x)"), "other");
+	assert.equal(classifyValue("100%"), "length");
+	assert.equal(classifyValue("100vw"), "length");
+	assert.equal(classifyValue("0"), "length");
+	assert.equal(classifyValue("2pt"), "length");
+	assert.equal(classifyValue("#abc12"), "other");
+});
+
+test("filterTokens is a case-insensitive substring match; blank query passes all", () => {
+	const decls = [
+		{ name: "--text-accent", value: "x" },
+		{ name: "--size-4-2", value: "y" },
+	];
+	assert.deepEqual(filterTokens(decls, "ACCENT"), [decls[0]]);
+	assert.deepEqual(filterTokens(decls, "  "), decls);
+});

package/template/test/viewer-derive.test.mjs

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	buildStoryTree,
+	kebabCase,
+	storyMetaFromGlobKey,
+	titleFromSlug,
+} from "../tools/viewer/derive.ts";
+
+test("kebabCase converts PascalCase and spaces/underscores", () => {
+	assert.equal(kebabCase("SettingsPanel"), "settings-panel");
+	assert.equal(kebabCase("Toggle"), "toggle");
+	assert.equal(kebabCase("message_feed thing"), "message-feed-thing");
+});
+
+test("titleFromSlug start-cases", () => {
+	assert.equal(titleFromSlug("settings-panel"), "Settings Panel");
+	assert.equal(titleFromSlug("toggle"), "Toggle");
+});
+
+test("storyMetaFromGlobKey derives slug + repo-relative paths", () => {
+	const meta = storyMetaFromGlobKey("../../stories/SettingsPanel.stories.ts");
+	assert.equal(meta.slug, "settings-panel");
+	assert.equal(meta.storiesPath, "stories/SettingsPanel.stories.ts");
+	assert.equal(meta.componentPath, "src/components/SettingsPanel.ts");
+});
+
+test("storyMetaFromGlobKey handles nested directories", () => {
+	const meta = storyMetaFromGlobKey("../../stories/chat/MessageFeed.stories.ts");
+	assert.equal(meta.slug, "message-feed");
+	assert.equal(meta.storiesPath, "stories/chat/MessageFeed.stories.ts");
+	assert.equal(meta.componentPath, "src/components/chat/MessageFeed.ts");
+});
+
+test("buildStoryTree nests children under parents", () => {
+	const { roots, unknownChildren } = buildStoryTree([
+		{ slug: "settings-panel", children: ["toggle"] },
+		{ slug: "toggle" },
+	]);
+	assert.equal(unknownChildren.length, 0);
+	assert.equal(roots.length, 1);
+	assert.equal(roots[0].slug, "settings-panel");
+	assert.equal(roots[0].children[0].slug, "toggle");
+});
+
+test("buildStoryTree reports unknown children and keeps them out of the tree", () => {
+	const { roots, unknownChildren } = buildStoryTree([{ slug: "a", children: ["ghost"] }]);
+	assert.deepEqual(unknownChildren, [{ parent: "a", child: "ghost" }]);
+	assert.equal(roots[0].children.length, 0);
+});
+
+test("buildStoryTree guards cycles: mutual refs fall back to flat roots", () => {
+	const { roots } = buildStoryTree([
+		{ slug: "a", children: ["b"] },
+		{ slug: "b", children: ["a"] },
+	]);
+	// both are referenced, so no natural roots — fall back to all items flat
+	assert.deepEqual(
+		roots.map((r) => r.slug),
+		["a", "b"]
+	);
+	// and recursion must not loop forever: nested child stops at the cycle
+	assert.equal(roots[0].children[0].slug, "b");
+	assert.equal(roots[0].children[0].children.length, 0);
+});

package/template/test/viewer-stories.test.mjs

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { defineStories, normalizeVariants, validateStoryDef } from "../tools/viewer/stories.ts";
+
+test("defineStories is an identity that preserves the def", () => {
+	const def = { variants: { default: () => "x" } };
+	assert.equal(defineStories(def), def);
+});
+
+test("validateStoryDef accepts a minimal valid def", () => {
+	assert.deepEqual(validateStoryDef({ variants: { default: () => "x" } }), { ok: true });
+});
+
+test("validateStoryDef accepts full metadata incl. componentPath override", () => {
+	const def = {
+		title: "Toggle",
+		description: "d",
+		componentPath: "src/components/SettingsPanel.ts",
+		variants: { on: { render: () => "x", notes: "n" } },
+		children: ["other"],
+	};
+	assert.deepEqual(validateStoryDef(def), { ok: true });
+});
+
+test("validateStoryDef rejects non-objects and missing/empty variants", () => {
+	assert.equal(validateStoryDef(undefined).ok, false);
+	assert.equal(validateStoryDef(null).ok, false);
+	assert.equal(validateStoryDef({}).ok, false);
+	assert.equal(validateStoryDef({ variants: {} }).ok, false);
+});
+
+test("validateStoryDef rejects bad variant values and bad children", () => {
+	assert.equal(validateStoryDef({ variants: { a: 42 } }).ok, false);
+	assert.equal(validateStoryDef({ variants: { a: { notes: "no render" } } }).ok, false);
+	assert.equal(validateStoryDef({ variants: { a: () => "x" }, children: [1] }).ok, false);
+});
+
+test("normalizeVariants wraps bare functions and passes objects through", () => {
+	const fn = () => "x";
+	const out = normalizeVariants({ bare: fn, full: { render: fn, notes: "n" } });
+	assert.deepEqual(out.bare, { render: fn });
+	assert.equal(out.full.render, fn);
+	assert.equal(out.full.notes, "n");
+});

package/template/{src → tools}/router/client.ts

@@ -1,5 +1,7 @@
+import { html } from "@arrow-js/core";
 import { Frame } from "../sandbox/frame";
 import { Shell } from "../sandbox/shell";
+import type { Page } from "./routeToPage";
 import { routeToPage } from "./routeToPage";
 
 /**
@@ -29,10 +31,21 @@ function getNavigation(): NavigationLike | undefined {
 
 export function startRouter(root: HTMLElement): void {
 	const render = (url: string): void => {
-		const page = routeToPage(url);
+		let resolved = routeToPage(url);
+		for (let hops = 0; "redirect" in resolved && hops < 3; hops++) {
+			window.history.replaceState({}, "", resolved.redirect);
+			resolved = routeToPage(resolved.redirect);
+		}
+		if ("redirect" in resolved) {
+			return;
+		}
+		const page: Page = resolved;
 		document.title = page.title;
 		root.replaceChildren();
-		Shell(Frame(page.title, page.view))(root);
+		const content = page.sidebar
+			? html`${page.sidebar}${Frame(page.title, page.view)}`
+			: Frame(page.title, page.view);
+		Shell(content)(root);
 	};
 
 	render(window.location.href);

package/template/tools/router/routeToPage.ts

@@ -0,0 +1,104 @@
+import { html } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
+import { Home } from "../sandbox/home";
+import { ClassesPage } from "../viewer/ClassesPage";
+import { ComponentsIndex } from "../viewer/ComponentsIndex";
+import { StoryPage } from "../viewer/StoryPage";
+import { TokensPage } from "../viewer/TokensPage";
+import { findStory } from "../viewer/discovery";
+import { ViewerSidebar } from "../viewer/sidebar";
+
+/**
+ * Single route resolver, shared by every entry point (Arrow scaffold shape, so
+ * a future SSR lane could call it identically). Pages may carry a sidebar
+ * (rendered outside the pane) and routes may resolve to a redirect, which the
+ * client router applies via history.replaceState.
+ */
+export interface Page {
+	status: number;
+	title: string;
+	view: ArrowExpression;
+	sidebar?: ArrowExpression;
+}
+
+export interface Redirect {
+	redirect: string;
+}
+
+const APP_NAME = "Arrow Sandbox";
+
+function notFound(pathname: string): Page {
+	return {
+		status: 404,
+		title: `Not found · ${APP_NAME}`,
+		view: html`
+			<div class="oas-settings">
+				<div class="setting-item setting-item-heading">
+					<div class="setting-item-info">
+						<div class="setting-item-name">Not found</div>
+						<div class="setting-item-description">
+							No route for <code>${pathname}</code>. <a href="/">Back home</a>.
+						</div>
+					</div>
+				</div>
+			</div>
+		`,
+	};
+}
+
+export function routeToPage(url: string): Page | Redirect {
+	const { pathname, searchParams } = new URL(url, window.location.origin);
+
+	if (pathname === "/" || pathname === "") {
+		return { status: 200, title: APP_NAME, view: Home() };
+	}
+
+	if (pathname === "/example") {
+		return { redirect: "/components/settings-panel" };
+	}
+
+	if (pathname === "/components" || pathname === "/components/") {
+		return {
+			status: 200,
+			title: `Components · ${APP_NAME}`,
+			view: ComponentsIndex(),
+			sidebar: ViewerSidebar(pathname),
+		};
+	}
+
+	const storyMatch = pathname.match(/^\/components\/([^/]+)$/);
+	if (storyMatch) {
+		const story = findStory(storyMatch[1]);
+		if (!story) {
+			return { ...notFound(pathname), sidebar: ViewerSidebar(pathname) };
+		}
+		const requested = searchParams.get("variant");
+		const variantName = requested ?? Object.keys(story.variants)[0];
+		return {
+			status: story.variants[variantName] ? 200 : 404,
+			title: `${story.title} · ${APP_NAME}`,
+			view: StoryPage(story, variantName),
+			sidebar: ViewerSidebar(`/components/${story.slug}`),
+		};
+	}
+
+	if (pathname === "/reference") {
+		return {
+			status: 200,
+			title: `Tokens · ${APP_NAME}`,
+			view: TokensPage(),
+			sidebar: ViewerSidebar(pathname),
+		};
+	}
+
+	if (pathname === "/reference/classes") {
+		return {
+			status: 200,
+			title: `Classes · ${APP_NAME}`,
+			view: ClassesPage(),
+			sidebar: ViewerSidebar(pathname),
+		};
+	}
+
+	return notFound(pathname);
+}

package/template/{src → tools}/sandbox/home.ts

@@ -1,22 +1,12 @@
 import { component, html, reactive } from "@arrow-js/core";
 import type { ArrowTemplate } from "@arrow-js/core";
-import { ExamplesIndex } from "../examples/ExamplesIndex";
-import { examples } from "../examples/registry";
 import { layoutState } from "./layout";
 import { themeState } from "./theme";
 
-/**
- * Sandbox landing page at "/": a readiness check + getting-started commands +
- * the examples list. Sandbox chrome — does not port to a plugin.
- *
- * The readiness probe catches the #1 fresh-machine gotcha: running `pnpm dev`
- * before `pnpm pull-css` leaves app.css unloaded, so every `var(--…)` token is
- * empty. We detect that by reading the computed value of a known token.
- */
 const probe = reactive({ tick: 0 });
 
 function stylingLoaded(): boolean {
-	const generation = probe.tick; // reactive dependency; Re-check bumps it
+	const generation = probe.tick;
 	const style = getComputedStyle(document.body);
 	return (
 		generation >= 0 &&
@@ -29,6 +19,8 @@ function recheck(): void {
 	probe.tick++;
 }
 
+const gettingStarted = reactive({ expanded: false });
+
 const GETTING_STARTED = [
 	{ cmd: "pnpm pull-css", note: "extract Obsidian's app.css — run once (macOS auto-detect)" },
 	{ cmd: "pnpm dev", note: "this dev server (Vite + HMR)" },
@@ -36,9 +28,13 @@ const GETTING_STARTED = [
 	{ cmd: "pnpm run ci", note: "biome + typecheck + tests + build" },
 ];
 
+const VIEWS = [
+	{ label: "Components", path: "/components", note: "Component story viewer" },
+	{ label: "Tokens", path: "/reference", note: "CSS custom property reference" },
+	{ label: "Classes", path: "/reference/classes", note: "Obsidian class catalog" },
+];
+
 export const Home = component((): ArrowTemplate => {
-	// Re-probe shortly after mount, in case app.css finished loading after the
-	// first paint (stylesheets load async).
 	setTimeout(recheck, 250);
 
 	return html`
@@ -79,28 +75,61 @@ export const Home = component((): ArrowTemplate => {
 					</div>
 				</div>
 			</div>
+		</div>
 
+		<div class="${() => (gettingStarted.expanded ? "oas-card is-expanded" : "oas-card")}">
+			<div
+				class="oas-card-header"
+				@click="${() => {
+					gettingStarted.expanded = !gettingStarted.expanded;
+				}}"
+			>
+				<span class="oas-card-title">Getting started</span>
+				<span class="oas-card-chevron">›</span>
+			</div>
+			<div class="oas-card-body">
+				<div class="oas-settings">
+					${GETTING_STARTED.map((step) =>
+						html`
+							<div class="setting-item">
+								<div class="setting-item-info">
+									<div class="setting-item-name" style="font-family: var(--font-monospace);">
+										${step.cmd}
+									</div>
+									<div class="setting-item-description">${step.note}</div>
+								</div>
+							</div>
+						`.key(step.cmd)
+					)}
+				</div>
+				<p class="oas-card-note">
+					See AGENTS.md + docs/ for the full flow; agent prompts in docs/prompts/.
+				</p>
+			</div>
+		</div>
+
+		<div class="oas-settings">
 			<div class="setting-item setting-item-heading">
 				<div class="setting-item-info">
-					<div class="setting-item-name">Getting started</div>
-					<div class="setting-item-description">
-						See AGENTS.md + docs/ for the full flow; agent prompts in docs/prompts/.
-					</div>
+					<div class="setting-item-name">Views</div>
+					<div class="setting-item-description">Main pages in this sandbox.</div>
 				</div>
 			</div>
-			${GETTING_STARTED.map((step) =>
+			${VIEWS.map((view) =>
 				html`
-						<div class="setting-item">
-							<div class="setting-item-info">
-								<div class="setting-item-name" style="font-family: var(--font-monospace);">
-									${step.cmd}
-								</div>
-								<div class="setting-item-description">${step.note}</div>
+					<div class="setting-item">
+						<div class="setting-item-info">
+							<div class="setting-item-name">
+								<a href="${view.path}">${view.label}</a>
 							</div>
+							<div class="setting-item-description">${view.note}</div>
 						</div>
-					`.key(step.cmd)
+						<div class="setting-item-control">
+							<a class="mod-cta oas-open-link" href="${view.path}">Open</a>
+						</div>
+					</div>
+				`.key(view.label)
 			)}
 		</div>
-		${ExamplesIndex(examples)}
 	`;
 });