create-obsidian-arrow 0.2.2 → 0.4.0

package/template/tools/viewer/TokensPage.ts

@@ -0,0 +1,82 @@
+import { component, html, reactive } from "@arrow-js/core";
+import { themeState } from "../sandbox/theme";
+import { copyText } from "./StoryPage";
+import type { TokenDecl } from "./token-utils";
+import { classifyValue, filterTokens, groupTokens } from "./token-utils";
+import { collectTokenDecls, resolveToken } from "./tokens";
+
+const state = reactive({ query: "" });
+
+function tokenRow(decl: TokenDecl) {
+	// Depend on themeState.theme so rows re-resolve when the theme toggles.
+	const resolved = (): string => {
+		void themeState.theme;
+		return resolveToken(decl.name) || decl.value;
+	};
+	return html`
+		<div class="oas-token-row">
+			<code class="oas-token-name">${decl.name}</code>
+			<span class="oas-token-value">${() => resolved()}</span>
+			${() => {
+				const kind = classifyValue(resolved());
+				if (kind === "color") {
+					return html`<span class="oas-swatch" style="${() => `background: ${resolved()};`}"></span>`;
+				}
+				if (kind === "length") {
+					return html`<span class="oas-sizebar" style="${() => `width: ${resolved()};`}"></span>`;
+				}
+				return html`<span class="oas-swatch-none"></span>`;
+			}}
+			<button class="oas-copy" @click="${() => copyText(`var(${decl.name})`)}">Copy</button>
+		</div>
+	`;
+}
+
+export const TokensPage = component(() => {
+	const decls = collectTokenDecls();
+	return html`
+		<div class="oas-reference">
+			<div class="setting-item setting-item-heading">
+				<div class="setting-item-info">
+					<div class="setting-item-name">Obsidian tokens (${String(decls.length)})</div>
+					<div class="setting-item-description">
+						Parsed live from the loaded app.css; values resolve in the current theme. Copy gives
+						you the var() reference.
+					</div>
+				</div>
+			</div>
+			${
+				decls.length === 0
+					? html`<div class="setting-item">
+						<div class="setting-item-info">
+							<div class="setting-item-name">No tokens found</div>
+							<div class="setting-item-description">
+								app.css doesn't appear to be loaded — run \`pnpm pull-css\`, then reload.
+							</div>
+						</div>
+					</div>`
+					: ""
+			}
+			<input
+				class="oas-token-filter"
+				type="search"
+				placeholder="Filter tokens…"
+				.value="${() => state.query}"
+				@input="${(e: Event) => {
+					state.query = (e.target as HTMLInputElement).value;
+				}}"
+			/>
+			${() =>
+				groupTokens(filterTokens(decls, state.query)).map((group) =>
+					html`
+						<div class="oas-token-group">
+							<div class="vertical-tab-header-group-title">
+								${group.label} (${String(group.tokens.length)})
+							</div>
+							${group.tokens.map((decl) => tokenRow(decl))}
+						</div>
+					`.key(group.label)
+				)}
+		</div>
+	`;
+});

package/template/tools/viewer/derive.ts

@@ -0,0 +1,91 @@
+/**
+ * Pure derivation helpers for the component viewer. DOM-free so node:test can
+ * cover them directly (via --experimental-strip-types).
+ *
+ * Glob keys come from import.meta.glob in src/viewer/discovery.ts, relative to
+ * src/viewer/ — e.g. "../../stories/SettingsPanel.stories.ts".
+ */
+
+export interface StoryPathMeta {
+	slug: string;
+	storiesPath: string;
+	componentPath: string;
+}
+
+export function kebabCase(name: string): string {
+	return name
+		.replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+		.replace(/[\s_]+/g, "-")
+		.toLowerCase();
+}
+
+export function titleFromSlug(slug: string): string {
+	return slug
+		.split("-")
+		.filter(Boolean)
+		.map((word) => word[0].toUpperCase() + word.slice(1))
+		.join(" ");
+}
+
+/**
+ * "../../stories/Foo.stories.ts" → project-relative paths + slug.
+ *
+ * Glob keys are relative to src/viewer/, so "../../" reaches the project root.
+ * Default componentPath mirrors the stories/ subtree into src/components/:
+ *   stories/Foo.stories.ts       → src/components/Foo.ts
+ *   stories/chat/Foo.stories.ts  → src/components/chat/Foo.ts
+ * Override with componentPath in the story def when the component lives elsewhere.
+ */
+export function storyMetaFromGlobKey(globKey: string): StoryPathMeta {
+	const storiesPath = globKey.replace(/^(\.\.\/)+/, "");
+	const componentPath = storiesPath
+		.replace(/^stories\//, "src/components/")
+		.replace(/\.stories\.ts$/, ".ts");
+	const base = storiesPath.split("/").pop() ?? "";
+	const slug = kebabCase(base.replace(/\.stories\.ts$/, ""));
+	return { slug, storiesPath, componentPath };
+}
+
+export interface TreeNode {
+	slug: string;
+	children: TreeNode[];
+}
+
+/**
+ * Build the sidebar tree: stories referenced as another story's child nest
+ * under it; unreferenced stories are roots. Cycles are guarded (a slug never
+ * nests under itself); if a cycle leaves no natural roots, all items become
+ * flat roots so nothing disappears from the sidebar.
+ */
+export function buildStoryTree(items: { slug: string; children?: string[] }[]): {
+	roots: TreeNode[];
+	unknownChildren: { parent: string; child: string }[];
+} {
+	const bySlug = new Map(items.map((item) => [item.slug, item]));
+	const referenced = new Set<string>();
+	const unknownChildren: { parent: string; child: string }[] = [];
+
+	for (const item of items) {
+		for (const child of item.children ?? []) {
+			if (bySlug.has(child)) {
+				referenced.add(child);
+			} else {
+				unknownChildren.push({ parent: item.slug, child });
+			}
+		}
+	}
+
+	const build = (slug: string, seen: Set<string>): TreeNode => {
+		const next = new Set(seen).add(slug);
+		const children = (bySlug.get(slug)?.children ?? [])
+			.filter((child) => bySlug.has(child) && !next.has(child))
+			.map((child) => build(child, next));
+		return { slug, children };
+	};
+
+	let rootItems = items.filter((item) => !referenced.has(item.slug));
+	if (rootItems.length === 0 && items.length > 0) {
+		rootItems = items;
+	}
+	return { roots: rootItems.map((item) => build(item.slug, new Set())), unknownChildren };
+}

package/template/tools/viewer/discovery.ts

@@ -0,0 +1,64 @@
+import { buildStoryTree, storyMetaFromGlobKey, titleFromSlug } from "./derive";
+import type { StoryDef, StoryVariant } from "./stories";
+import { normalizeVariants, validateStoryDef } from "./stories";
+
+/**
+ * Discovers stories/*.stories.ts files at build time. Stories live in the
+ * top-level stories/ directory (not in src/), keeping src/ pure component code.
+ * The glob key IS the file path, so src locations shown in the viewer are
+ * derived, never hand-maintained. One malformed story file is skipped (with a
+ * console.warn and an entry in invalidStories) — it never blanks the viewer.
+ */
+
+export interface DiscoveredStory {
+	slug: string;
+	title: string;
+	description?: string;
+	storiesPath: string;
+	componentPath: string;
+	variants: Record<string, StoryVariant>;
+	children: string[];
+	status: "live" | "draft";
+}
+
+export interface InvalidStory {
+	storiesPath: string;
+	reason: string;
+}
+
+const modules = import.meta.glob("../../stories/**/*.stories.ts", { eager: true }) as Record<
+	string,
+	{ default?: unknown }
+>;
+
+export const stories: DiscoveredStory[] = [];
+export const invalidStories: InvalidStory[] = [];
+
+for (const [globKey, mod] of Object.entries(modules)) {
+	const meta = storyMetaFromGlobKey(globKey);
+	const check = validateStoryDef(mod.default);
+	if (!check.ok) {
+		console.warn(`[viewer] skipping ${meta.storiesPath}: ${check.reason}`);
+		invalidStories.push({ storiesPath: meta.storiesPath, reason: check.reason });
+		continue;
+	}
+	const def = mod.default as StoryDef;
+	stories.push({
+		slug: meta.slug,
+		title: def.title ?? titleFromSlug(meta.slug),
+		description: def.description,
+		storiesPath: meta.storiesPath,
+		componentPath: def.componentPath ?? meta.componentPath,
+		variants: normalizeVariants(def.variants),
+		children: def.children ?? [],
+		status: def.status ?? "draft",
+	});
+}
+
+stories.sort((a, b) => a.title.localeCompare(b.title));
+
+export const storyTree = buildStoryTree(stories);
+
+export function findStory(slug: string): DiscoveredStory | undefined {
+	return stories.find((story) => story.slug === slug);
+}

package/template/tools/viewer/obsidian-classes.ts

@@ -0,0 +1,269 @@
+import { html, reactive } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
+
+/**
+ * Curated catalog of the Obsidian pattern classes worth leveraging, each with
+ * a live preview rendered against the real app.css. Curated on purpose:
+ * extracting selectors from app.css yields thousands of internal one-offs.
+ * When the utility-class layer lands (spec 2), its classes get documented here.
+ */
+
+export interface ClassEntry {
+	className: string;
+	whenToUse: string;
+	preview: () => ArrowExpression;
+}
+
+export interface ClassGroup {
+	label: string;
+	entries: ClassEntry[];
+}
+
+const toggleState = reactive({ on: true });
+
+export const classGroups: ClassGroup[] = [
+	{
+		label: "Settings",
+		entries: [
+			{
+				className: ".setting-item",
+				whenToUse: "Any labeled row with a control (with .setting-item-info / -control).",
+				preview: () => html`
+					<div class="setting-item">
+						<div class="setting-item-info">
+							<div class="setting-item-name">Setting name</div>
+							<div class="setting-item-description">One-line description.</div>
+						</div>
+						<div class="setting-item-control"><button class="mod-cta">Action</button></div>
+					</div>
+				`,
+			},
+			{
+				className: ".setting-item-heading",
+				whenToUse: "Section header row inside a settings-style list.",
+				preview: () => html`
+					<div class="setting-item setting-item-heading">
+						<div class="setting-item-info">
+							<div class="setting-item-name">Section heading</div>
+						</div>
+					</div>
+				`,
+			},
+		],
+	},
+	{
+		label: "Controls",
+		entries: [
+			{
+				className: "button.mod-cta",
+				whenToUse: "Primary call-to-action button.",
+				preview: () => html`<button class="mod-cta">Primary action</button>`,
+			},
+			{
+				className: ".clickable-icon",
+				whenToUse: "Icon button — escapes Obsidian's global button background rule.",
+				preview: () => html`<button class="clickable-icon" aria-label="Example">☾</button>`,
+			},
+			{
+				className: ".checkbox-container (.is-enabled)",
+				whenToUse: "Obsidian's toggle; flip is-enabled to switch state.",
+				preview: () => html`
+					<div
+						class="${() => (toggleState.on ? "checkbox-container is-enabled" : "checkbox-container")}"
+						@click="${() => {
+							toggleState.on = !toggleState.on;
+						}}"
+					>
+						<input type="checkbox" tabindex="0" .checked="${() => toggleState.on}" />
+					</div>
+				`,
+			},
+		],
+	},
+	{
+		label: "Navigation",
+		entries: [
+			{
+				className: ".vertical-tab-nav-item (.is-active)",
+				whenToUse: "Settings-style vertical tab rows (as used by this sidebar).",
+				preview: () => html`
+					<div class="vertical-tab-nav-item is-active">Active tab</div>
+					<div class="vertical-tab-nav-item">Inactive tab</div>
+				`,
+			},
+		],
+	},
+	{
+		label: "Modal & prompt",
+		entries: [
+			{
+				className: ".modal",
+				whenToUse:
+					"Dialog card (.modal-title + .modal-content). Preview is contained by a transformed wrapper.",
+				preview: () => html`
+					<div class="modal oas-modal-preview">
+						<div class="modal-title">Modal title</div>
+						<div class="modal-content">Modal content goes here.</div>
+					</div>
+				`,
+			},
+			{
+				className: ".prompt-input",
+				whenToUse: "Fuzzy-finder style text input inside prompts.",
+				preview: () =>
+					html`<input class="prompt-input" type="text" placeholder="Type to filter…" />`,
+			},
+		],
+	},
+	{
+		label: "Workspace chrome",
+		entries: [
+			{
+				className: ".view-header / .view-header-title",
+				whenToUse: "Pane header bar, as used by this sandbox's Frame.",
+				preview: () => html`
+					<div class="view-header">
+						<div class="view-header-title">View title</div>
+					</div>
+				`,
+			},
+		],
+	},
+	{
+		label: "Callout",
+		entries: [
+			{
+				className: '.callout[data-callout="info"]',
+				whenToUse:
+					'Info callout block. Swap data-callout for "warning", "danger", "tip", "success", "note" etc.',
+				preview: () => html`
+					<div class="callout" data-callout="info">
+						<div class="callout-title"><div class="callout-title-inner">Info</div></div>
+						<div class="callout-content"><p>Callout body text.</p></div>
+					</div>
+				`,
+			},
+			{
+				className: '.callout[data-callout="warning"]',
+				whenToUse:
+					"Warning callout — same structure, different data-callout triggers Obsidian's color + icon.",
+				preview: () => html`
+					<div class="callout" data-callout="warning">
+						<div class="callout-title"><div class="callout-title-inner">Warning</div></div>
+						<div class="callout-content"><p>Something to be aware of.</p></div>
+					</div>
+				`,
+			},
+		],
+	},
+	{
+		label: "Tags & badges",
+		entries: [
+			{
+				className: ".tag",
+				whenToUse: "Inline tag pill — styled like Obsidian's note tags.",
+				preview: () => html`<span class="tag">#plugin</span> <span class="tag">#arrow-js</span>`,
+			},
+			{
+				className: ".badge",
+				whenToUse: "Numeric counter badge (e.g. unread count on a nav item).",
+				preview: () => html`
+					<div style="display:flex;align-items:center;gap:8px;">
+						<span>Notifications</span><span class="badge">3</span>
+					</div>
+				`,
+			},
+		],
+	},
+	{
+		label: "Suggestion list",
+		entries: [
+			{
+				className: ".suggestion-item (.is-selected)",
+				whenToUse:
+					"Fuzzy-finder / autocomplete row. .suggestion-container wraps the list; .is-selected highlights the focused item.",
+				preview: () => html`
+					<div class="suggestion-container">
+						<div class="suggestion">
+							<div class="suggestion-item is-selected">selected-file.md</div>
+							<div class="suggestion-item">another-file.md</div>
+							<div class="suggestion-item">third-file.md</div>
+						</div>
+					</div>
+				`,
+			},
+		],
+	},
+	{
+		label: "Status modifiers",
+		entries: [
+			{
+				className: "button.mod-warning",
+				whenToUse: "Secondary/warning button variant.",
+				preview: () => html`<button class="mod-warning">Warning action</button>`,
+			},
+			{
+				className: "button.mod-destructive",
+				whenToUse: "Destructive / danger button.",
+				preview: () => html`<button class="mod-destructive">Delete</button>`,
+			},
+			{
+				className: ".mod-muted (text)",
+				whenToUse: "Muted text color applied to any element via this modifier.",
+				preview: () => html`<span class="mod-muted">Secondary text</span>`,
+			},
+		],
+	},
+	{
+		label: "File tree",
+		entries: [
+			{
+				className: ".nav-file-title (.is-active)",
+				whenToUse: "File row in a nav/file-tree pane. Use .is-active for the currently open file.",
+				preview: () => html`
+					<div class="nav-files-container">
+						<div class="nav-file">
+							<div class="nav-file-title is-active">active-note.md</div>
+						</div>
+						<div class="nav-file">
+							<div class="nav-file-title">another-note.md</div>
+						</div>
+					</div>
+				`,
+			},
+			{
+				className: ".nav-folder-title",
+				whenToUse: "Folder row — collapsible; pair with .nav-folder-collapse-indicator.",
+				preview: () => html`
+					<div class="nav-folder">
+						<div class="nav-folder-title">
+							<div class="nav-folder-collapse-indicator collapse-icon"></div>
+							My Folder
+						</div>
+					</div>
+				`,
+			},
+		],
+	},
+	{
+		label: "Metadata",
+		entries: [
+			{
+				className: ".metadata-container",
+				whenToUse: "Frontmatter property table rendered by Obsidian's properties view.",
+				preview: () => html`
+					<div class="metadata-container">
+						<div class="metadata-property">
+							<div class="metadata-property-key">
+								<div class="metadata-property-key-input">status</div>
+							</div>
+							<div class="metadata-property-value">
+								<div class="metadata-input-markdown">draft</div>
+							</div>
+						</div>
+					</div>
+				`,
+			},
+		],
+	},
+];

package/template/tools/viewer/sidebar.ts

@@ -0,0 +1,55 @@
+import { html } from "@arrow-js/core";
+import type { ArrowTemplate } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
+import type { TreeNode } from "./derive";
+import { findStory, invalidStories, storyTree } from "./discovery";
+
+/**
+ * Viewer navigation: component tree (children indented under parents) plus the
+ * Reference section. Rendered OUTSIDE the pane, as the first child of the
+ * stage. Sandbox chrome — never ports to a plugin.
+ */
+
+function navClass(active: boolean): string {
+	return active
+		? "vertical-tab-nav-item oas-nav-item is-active"
+		: "vertical-tab-nav-item oas-nav-item";
+}
+
+function nodeRows(node: TreeNode, activePath: string, depth: number): ArrowTemplate | string {
+	const story = findStory(node.slug);
+	if (!story) {
+		return "";
+	}
+	const href = `/components/${node.slug}`;
+	return html`
+		<a
+			class="${navClass(activePath === href)}"
+			style="${`padding-left: calc(var(--size-4-3) * ${depth + 1});`}"
+			href="${href}"
+		>${story.title}</a>
+		${node.children.map((child) => nodeRows(child, activePath, depth + 1))}
+	`;
+}
+
+export function ViewerSidebar(activePath: string): ArrowExpression {
+	return html`
+		<nav class="oas-sidebar">
+			<div class="vertical-tab-header-group">
+				<div class="vertical-tab-header-group-title">Components</div>
+				${storyTree.roots.map((node) => nodeRows(node, activePath, 0))}
+				${invalidStories.map(
+					(bad) =>
+						html`<div class="vertical-tab-nav-item oas-nav-invalid" title="${bad.reason}">
+							invalid: ${bad.storiesPath}
+						</div>`
+				)}
+			</div>
+			<div class="vertical-tab-header-group">
+				<div class="vertical-tab-header-group-title">Reference</div>
+				<a class="${navClass(activePath === "/reference")}" href="/reference">Tokens</a>
+				<a class="${navClass(activePath === "/reference/classes")}" href="/reference/classes">Classes</a>
+			</div>
+		</nav>
+	`;
+}

package/template/tools/viewer/stories.ts

@@ -0,0 +1,83 @@
+import type { ArrowExpression } from "@arrow-js/core";
+
+/**
+ * Single-object story format (see the 2026-06-30 spec's decision record: CSF 3
+ * and Ladle were the references; we diverged because no Storybook renderer
+ * exists for Arrow, and one validated object is harder to get wrong).
+ */
+
+export interface StoryVariant {
+	render: () => ArrowExpression;
+	notes?: string;
+}
+
+export type VariantInput = StoryVariant | (() => ArrowExpression);
+
+export interface StoryDef {
+	/** Display name; defaults to the start-cased filename. */
+	title?: string;
+	/** One-line description shown in the tree and header. */
+	description?: string;
+	/** Repo-relative override for where the component lives (e.g. a subcomponent
+	 * defined inside its parent's file). Defaults to the stories path minus `.stories`. */
+	componentPath?: string;
+	/** Named variants; keys are human strings ("default", "dev mode off"). */
+	variants: Record<string, VariantInput>;
+	/** Slugs of subcomponent stories for drill-in nesting. */
+	children?: string[];
+	/** Whether this component is production-ready or still in development. */
+	status?: "live" | "draft";
+}
+
+export function defineStories(def: StoryDef): StoryDef {
+	return def;
+}
+
+export type ValidationResult = { ok: true } | { ok: false; reason: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function validateStoryDef(def: unknown): ValidationResult {
+	if (!isRecord(def)) {
+		return { ok: false, reason: "default export is not an object (use defineStories({...}))" };
+	}
+	for (const field of ["title", "description", "componentPath"] as const) {
+		if (field in def && typeof def[field] !== "string") {
+			return { ok: false, reason: `"${field}" must be a string` };
+		}
+	}
+	if (!isRecord(def.variants) || Object.keys(def.variants).length === 0) {
+		return { ok: false, reason: '"variants" must be a non-empty object' };
+	}
+	for (const [name, variant] of Object.entries(def.variants)) {
+		const valid =
+			typeof variant === "function" || (isRecord(variant) && typeof variant.render === "function");
+		if (!valid) {
+			return { ok: false, reason: `variant "${name}" must be a render fn or { render }` };
+		}
+	}
+	if ("children" in def) {
+		const children = def.children;
+		if (!Array.isArray(children) || children.some((child) => typeof child !== "string")) {
+			return { ok: false, reason: '"children" must be an array of story slugs' };
+		}
+	}
+	if ("status" in def) {
+		if (def.status !== "live" && def.status !== "draft") {
+			return { ok: false, reason: '"status" must be "live" or "draft"' };
+		}
+	}
+	return { ok: true };
+}
+
+export function normalizeVariants(
+	variants: Record<string, VariantInput>
+): Record<string, StoryVariant> {
+	const out: Record<string, StoryVariant> = {};
+	for (const [name, variant] of Object.entries(variants)) {
+		out[name] = typeof variant === "function" ? { render: variant } : variant;
+	}
+	return out;
+}