create-obsidian-arrow 0.4.1 → 0.5.1

package/template/scripts/create-view.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Usage:
+ *   pnpm create:view ChatView   → src/views/ChatView/ + stories/views/ChatView.stories.ts
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const viewName = process.argv[2];
+
+if (!viewName) {
+	console.error("Usage: pnpm create:view <ViewName>");
+	process.exit(1);
+}
+
+const viewDir = path.join(root, "src", "views", viewName);
+const storyDir = path.join(root, "stories", "views");
+
+if (fs.existsSync(viewDir)) {
+	console.error(`Already exists: src/views/${viewName}/`);
+	process.exit(1);
+}
+
+fs.mkdirSync(viewDir, { recursive: true });
+fs.mkdirSync(storyDir, { recursive: true });
+
+const tsContent = `import "./${viewName}.css";
+import { component, html } from "@arrow-js/core";
+import type { ArrowTemplate } from "@arrow-js/core";
+
+export const ${viewName} = component((): ArrowTemplate => {
+	return html\`
+		<div class="oas-settings">
+			<div class="setting-item setting-item-heading">
+				<div class="setting-item-info">
+					<div class="setting-item-name">${viewName}</div>
+				</div>
+			</div>
+		</div>
+	\`;
+});
+`;
+
+const cssContent = `/* ${viewName} layout and chrome */\n`;
+
+const stateContent = `import { reactive } from "@arrow-js/core";
+
+export const state = reactive({
+	// TODO: add view state
+});
+`;
+
+const storyContent = `import { defineStories } from "../../tools/viewer/stories";
+import { ${viewName} } from "../../src/views/${viewName}/${viewName}";
+
+export default defineStories({
+	kind: "view",
+	description: "TODO: describe ${viewName}.",
+	status: "draft",
+	variants: {
+		default: () => ${viewName}(),
+	},
+});
+`;
+
+fs.writeFileSync(path.join(viewDir, `${viewName}.ts`), tsContent);
+fs.writeFileSync(path.join(viewDir, `${viewName}.css`), cssContent);
+fs.writeFileSync(path.join(viewDir, "state.ts"), stateContent);
+fs.writeFileSync(path.join(storyDir, `${viewName}.stories.ts`), storyContent);
+
+console.log(`Created src/views/${viewName}/`);
+console.log(`  ${viewName}.ts, ${viewName}.css, state.ts`);
+console.log(`Created stories/views/${viewName}.stories.ts`);

package/template/scripts/port-css.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * PostCSS prefix pipeline — port time only, never modifies source files.
+ *
+ * Usage: pnpm port:css
+ *
+ * Reads porting.config.json, walks CSS files matching `include` globs,
+ * prefixes all class selectors with `cssPrefix`, writes prefixed output
+ * to `outDir/`. Also generates outDir/index.css that @imports all outputs.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import postcss from "postcss";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const configPath = path.join(root, "porting.config.json");
+
+if (!fs.existsSync(configPath)) {
+	console.error("porting.config.json not found. Create it at the project root.");
+	process.exit(1);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+const {
+	cssPrefix = "my-plugin-",
+	outDir = "port-output/css",
+	include = [],
+	viewSubScope = false,
+} = config;
+
+// Kebab-case a PascalCase view name for the ancestor selector.
+function toKebab(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+// Collect CSS files matching include patterns (simple glob expansion)
+function matchesGlob(file, pattern) {
+	// Convert glob to regex: ** → .*, * → [^/]*
+	const re = new RegExp(
+		`^${pattern.replace(/\*\*/g, "@@").replace(/\*/g, "[^/]*").replace(/@@/g, ".*")}$`
+	);
+	return re.test(file);
+}
+
+function walk(dir, results = []) {
+	if (!fs.existsSync(dir)) return results;
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) walk(full, results);
+		else if (entry.name.endsWith(".css")) results.push(full);
+	}
+	return results;
+}
+
+const allCss = walk(path.join(root, "src"));
+const cssFiles = allCss.filter((f) => {
+	const rel = path.relative(root, f).replace(/\\/g, "/");
+	return include.some((pattern) => matchesGlob(rel, pattern));
+});
+
+if (cssFiles.length === 0) {
+	console.log("No CSS files matched include patterns.");
+	process.exit(0);
+}
+
+// PostCSS plugin: prefix all class selectors; optionally prepend an ancestor.
+// When ancestorClass is provided (viewSubScope for view-folder CSS), every rule
+// selector gains the ancestor: ".composer" → ".vault-mind-chat-view .vault-mind-composer"
+const prefixPlugin = (prefix, ancestorClass) => ({
+	postcssPlugin: "postcss-prefix-classes",
+	Rule(rule) {
+		rule.selector = rule.selector.replace(/\.([a-zA-Z][\w-]*)/g, `.${prefix}$1`);
+		if (ancestorClass) {
+			rule.selector = rule.selector
+				.split(",")
+				.map((s) => `${ancestorClass} ${s.trim()}`)
+				.join(", ");
+		}
+	},
+});
+prefixPlugin.postcss = true;
+
+const outDirAbs = path.join(root, outDir);
+fs.mkdirSync(outDirAbs, { recursive: true });
+
+const outputFiles = [];
+
+for (const cssFile of cssFiles) {
+	const rel = path.relative(path.join(root, "src"), cssFile).replace(/\\/g, "/");
+	const outFile = path.join(outDirAbs, rel);
+	fs.mkdirSync(path.dirname(outFile), { recursive: true });
+
+	// Determine view ancestor class when viewSubScope is enabled.
+	// src/views/ChatView/X.css → ancestor ".vault-mind-chat-view"
+	let ancestorClass = null;
+	if (viewSubScope) {
+		const viewMatch = rel.match(/^views\/([^/]+)\//);
+		if (viewMatch) {
+			ancestorClass = `.${cssPrefix}${toKebab(viewMatch[1])}`;
+		}
+	}
+
+	const source = fs.readFileSync(cssFile, "utf8");
+	const result = await postcss([prefixPlugin(cssPrefix, ancestorClass)]).process(source, {
+		from: cssFile,
+		to: outFile,
+	});
+
+	fs.writeFileSync(outFile, result.css);
+	outputFiles.push(path.relative(outDirAbs, outFile).replace(/\\/g, "/"));
+	console.log(`Prefixed: ${rel} → ${path.relative(root, outFile)}`);
+}
+
+// Generate index.css
+const indexContent = `${outputFiles.map((f) => `@import "./${f}";`).join("\n")}\n`;
+fs.writeFileSync(path.join(outDirAbs, "index.css"), indexContent);
+console.log(`\nGenerated: ${outDir}/index.css (${outputFiles.length} files)`);

package/template/src/components/EmptyState/EmptyState.css

@@ -0,0 +1,30 @@
+.empty-state {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: var(--size-4-2);
+	padding: var(--size-4-4);
+	text-align: center;
+	color: var(--text-muted);
+}
+
+.empty-state-icon {
+	font-size: var(--font-ui-larger, 2rem);
+	line-height: 1;
+	color: var(--text-faint);
+}
+
+.empty-state-title {
+	font-size: var(--font-ui-medium);
+	font-weight: var(--font-semibold);
+	color: var(--text-normal);
+}
+
+.empty-state-description {
+	font-size: var(--font-ui-small);
+	max-width: 280px;
+}
+
+.empty-state-action {
+	margin-top: var(--size-4-2);
+}

package/template/src/components/EmptyState/EmptyState.ts

@@ -0,0 +1,35 @@
+import "./EmptyState.css";
+import { html } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
+import { icon } from "../icons";
+
+export interface EmptyStateOptions {
+	icon?: string;
+	title: string;
+	description?: string;
+	action?: { label: string; onClick: () => void };
+}
+
+export function EmptyState(options: EmptyStateOptions): ArrowExpression {
+	return html`
+		<div class="empty-state">
+			${options.icon ? html`<div class="empty-state-icon">${icon(options.icon)}</div>` : ""}
+			<div class="empty-state-title">${options.title}</div>
+			${
+				options.description
+					? html`<div class="empty-state-description">${options.description}</div>`
+					: ""
+			}
+			${
+				options.action
+					? html`<button
+							class="mod-cta empty-state-action"
+							@click="${options.action.onClick}"
+						>
+							${options.action.label}
+						</button>`
+					: ""
+			}
+		</div>
+	`;
+}

package/template/src/components/LoadingState.ts

@@ -0,0 +1,12 @@
+import { html } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
+import { icon } from "./icons";
+
+export function LoadingState(message?: string): ArrowExpression {
+	return html`
+		<div class="oas-flex oas-flex-col oas-items-center oas-gap-2 oas-p-4 oas-text-muted">
+			<span>${icon("loader")}</span>
+			${message ? html`<span class="oas-text-sm">${message}</span>` : ""}
+		</div>
+	`;
+}

package/template/src/components/icons.ts

@@ -0,0 +1,17 @@
+export const ICON_MAP: Record<string, string> = {
+	check: "✓",
+	x: "✕",
+	"chevron-right": "›",
+	"chevron-down": "⌄",
+	loader: "◌",
+	search: "⌕",
+	file: "◻",
+	folder: "◱",
+	info: "ℹ",
+	warning: "⚠",
+	error: "✕",
+};
+
+export function icon(name: string): string {
+	return ICON_MAP[name] ?? "•";
+}

package/template/src/utilities.css

@@ -52,7 +52,56 @@
 	flex-shrink: 0;
 }
 
-/* ── Spacing (Obsidian 4-px step scale) ─────────────────────── */
+/*
+ * Spacing — two Obsidian token families:
+ *
+ * 4-px scale  oas-gap-N / oas-p-N / oas-px-N / oas-py-N / oas-mt-N / oas-mb-N
+ *   N=1 → --size-4-1 (4px)   N=2 → --size-4-2 (8px)   N=3 → --size-4-3 (12px)
+ *   N=4 → --size-4-4 (16px)  N=5 → --size-4-5 (20px)  N=6 → --size-4-6 (24px)
+ *
+ * 2-px sub-scale  oas-gap-2-1 / oas-p-2-1 … (mirrors Obsidian token name)
+ *   2-1 → --size-2-1 (2px)   2-3 → --size-2-3 (6px)
+ */
+
+/* 2-px sub-scale ── */
+.oas-gap-2-1 {
+	gap: var(--size-2-1);
+}
+.oas-p-2-1 {
+	padding: var(--size-2-1);
+}
+.oas-px-2-1 {
+	padding-inline: var(--size-2-1);
+}
+.oas-py-2-1 {
+	padding-block: var(--size-2-1);
+}
+.oas-mt-2-1 {
+	margin-top: var(--size-2-1);
+}
+.oas-mb-2-1 {
+	margin-bottom: var(--size-2-1);
+}
+.oas-gap-2-3 {
+	gap: var(--size-2-3);
+}
+.oas-p-2-3 {
+	padding: var(--size-2-3);
+}
+.oas-px-2-3 {
+	padding-inline: var(--size-2-3);
+}
+.oas-py-2-3 {
+	padding-block: var(--size-2-3);
+}
+.oas-mt-2-3 {
+	margin-top: var(--size-2-3);
+}
+.oas-mb-2-3 {
+	margin-bottom: var(--size-2-3);
+}
+
+/* 4-px scale ── */
 .oas-gap-1 {
 	gap: var(--size-4-1);
 }
@@ -65,6 +114,12 @@
 .oas-gap-4 {
 	gap: var(--size-4-4);
 }
+.oas-gap-5 {
+	gap: var(--size-4-5);
+}
+.oas-gap-6 {
+	gap: var(--size-4-6);
+}
 .oas-p-1 {
 	padding: var(--size-4-1);
 }
@@ -77,12 +132,27 @@
 .oas-p-4 {
 	padding: var(--size-4-4);
 }
+.oas-p-5 {
+	padding: var(--size-4-5);
+}
+.oas-p-6 {
+	padding: var(--size-4-6);
+}
 .oas-px-2 {
 	padding-inline: var(--size-4-2);
 }
 .oas-px-3 {
 	padding-inline: var(--size-4-3);
 }
+.oas-px-4 {
+	padding-inline: var(--size-4-4);
+}
+.oas-px-5 {
+	padding-inline: var(--size-4-5);
+}
+.oas-px-6 {
+	padding-inline: var(--size-4-6);
+}
 .oas-py-1 {
 	padding-block: var(--size-4-1);
 }
@@ -92,6 +162,15 @@
 .oas-py-3 {
 	padding-block: var(--size-4-3);
 }
+.oas-py-4 {
+	padding-block: var(--size-4-4);
+}
+.oas-py-5 {
+	padding-block: var(--size-4-5);
+}
+.oas-py-6 {
+	padding-block: var(--size-4-6);
+}
 .oas-mt-1 {
 	margin-top: var(--size-4-1);
 }
@@ -101,6 +180,15 @@
 .oas-mt-3 {
 	margin-top: var(--size-4-3);
 }
+.oas-mt-4 {
+	margin-top: var(--size-4-4);
+}
+.oas-mt-5 {
+	margin-top: var(--size-4-5);
+}
+.oas-mt-6 {
+	margin-top: var(--size-4-6);
+}
 .oas-mb-1 {
 	margin-bottom: var(--size-4-1);
 }
@@ -110,6 +198,15 @@
 .oas-mb-3 {
 	margin-bottom: var(--size-4-3);
 }
+.oas-mb-4 {
+	margin-bottom: var(--size-4-4);
+}
+.oas-mb-5 {
+	margin-bottom: var(--size-4-5);
+}
+.oas-mb-6 {
+	margin-bottom: var(--size-4-6);
+}
 .oas-ml-auto {
 	margin-left: auto;
 }
@@ -195,6 +292,9 @@
 .oas-rounded-m {
 	border-radius: var(--radius-m);
 }
+.oas-rounded-l {
+	border-radius: var(--radius-l);
+}
 
 /* ── Interaction ─────────────────────────────────────────────── */
 .oas-cursor-pointer {

package/template/stories/components/EmptyState.stories.ts

@@ -0,0 +1,25 @@
+import { EmptyState } from "../../src/components/EmptyState/EmptyState";
+import { defineStories } from "../../tools/viewer/stories";
+
+export default defineStories({
+	description: "Reusable empty state for any view — icon, title, description, optional action.",
+	status: "live",
+	variants: {
+		default: () => EmptyState({ title: "Nothing here yet" }),
+		"with description": () => {
+			return EmptyState({
+				icon: "file",
+				title: "No files found",
+				description: "Try a different search or create a new file.",
+			});
+		},
+		"with action": () => {
+			return EmptyState({
+				icon: "search",
+				title: "No results",
+				description: "Your search returned no matches.",
+				action: { label: "Clear search", onClick: () => {} },
+			});
+		},
+	},
+});

package/template/stories/components/LoadingState.stories.ts

@@ -0,0 +1,11 @@
+import { LoadingState } from "../../src/components/LoadingState";
+import { defineStories } from "../../tools/viewer/stories";
+
+export default defineStories({
+	description: "Loading indicator for async view content.",
+	status: "live",
+	variants: {
+		default: () => LoadingState(),
+		"with message": () => LoadingState("Loading sessions…"),
+	},
+});

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

@@ -63,3 +63,9 @@ test("buildStoryTree guards cycles: mutual refs fall back to flat roots", () =>
 	assert.equal(roots[0].children[0].slug, "b");
 	assert.equal(roots[0].children[0].children.length, 0);
 });
+
+test("storyMetaFromGlobKey: stories/views/ path auto-kind is view", () => {
+	const meta = storyMetaFromGlobKey("../../stories/views/ChatView.stories.ts");
+	// auto-kind logic lives in discovery.ts, not derive.ts — just confirm storiesPath prefix
+	assert.ok(meta.storiesPath.startsWith("stories/views/"));
+});

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

@@ -42,3 +42,29 @@ test("normalizeVariants wraps bare functions and passes objects through", () =>
 	assert.equal(out.full.render, fn);
 	assert.equal(out.full.notes, "n");
 });
+
+test("validateStoryDef accepts kind: view and kind: component", () => {
+	const base = { variants: { default: () => {} } };
+	assert.deepEqual(validateStoryDef({ ...base, kind: "view" }), { ok: true });
+	assert.deepEqual(validateStoryDef({ ...base, kind: "component" }), { ok: true });
+});
+
+test("validateStoryDef rejects invalid kind", () => {
+	const r = validateStoryDef({ variants: { default: () => {} }, kind: "panel" });
+	assert.equal(r.ok, false);
+	assert.match(r.reason, /kind/);
+});
+
+test("validateStoryDef accepts decorator function", () => {
+	const r = validateStoryDef({
+		variants: { default: () => {} },
+		decorator: (c) => c,
+	});
+	assert.deepEqual(r, { ok: true });
+});
+
+test("validateStoryDef rejects non-function decorator", () => {
+	const r = validateStoryDef({ variants: { default: () => {} }, decorator: "bad" });
+	assert.equal(r.ok, false);
+	assert.match(r.reason, /decorator/);
+});

package/template/tools/router/client.ts

@@ -1,4 +1,5 @@
 import { html } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
 import { Frame } from "../sandbox/frame";
 import { Shell } from "../sandbox/shell";
 import type { Page } from "./routeToPage";
@@ -29,6 +30,10 @@ function getNavigation(): NavigationLike | undefined {
 	return (window as unknown as { navigation?: NavigationLike }).navigation;
 }
 
+function ComponentCanvas(content: ArrowExpression): ArrowExpression {
+	return html`<div class="oas-component-canvas">${content}</div>`;
+}
+
 export function startRouter(root: HTMLElement): void {
 	const render = (url: string): void => {
 		let resolved = routeToPage(url);
@@ -42,9 +47,15 @@ export function startRouter(root: HTMLElement): void {
 		const page: Page = resolved;
 		document.title = page.title;
 		root.replaceChildren();
-		const content = page.sidebar
-			? html`${page.sidebar}${Frame(page.title, page.view)}`
-			: Frame(page.title, page.view);
+
+		let content: ArrowExpression;
+		if (page.sidebar && page.canvas) {
+			content = html`${page.sidebar}${Frame(page.title, page.view)}${ComponentCanvas(page.canvas)}`;
+		} else if (page.sidebar) {
+			content = html`${page.sidebar}${Frame(page.title, page.view)}`;
+		} else {
+			content = Frame(page.title, page.view);
+		}
 		Shell(content)(root);
 	};
 

package/template/tools/router/routeToPage.ts

@@ -3,7 +3,7 @@ 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 { StoryPageCanvas, StoryPageDetails, StoryPageView } from "../viewer/StoryPage";
 import { TokensPage } from "../viewer/TokensPage";
 import { findStory } from "../viewer/discovery";
 import { ViewerSidebar } from "../viewer/sidebar";
@@ -19,6 +19,7 @@ export interface Page {
 	title: string;
 	view: ArrowExpression;
 	sidebar?: ArrowExpression;
+	canvas?: ArrowExpression;
 }
 
 export interface Redirect {
@@ -74,11 +75,22 @@ export function routeToPage(url: string): Page | Redirect {
 		}
 		const requested = searchParams.get("variant");
 		const variantName = requested ?? Object.keys(story.variants)[0];
+		// kind: "view" → full page in the frame
+		if (story.kind === "view") {
+			return {
+				status: story.variants[variantName] ? 200 : 404,
+				title: `${story.title} · ${APP_NAME}`,
+				view: StoryPageView(story, variantName),
+				sidebar: ViewerSidebar(`/components/${story.slug}`),
+			};
+		}
+		// kind: "component" → details in frame, canvas separate
 		return {
 			status: story.variants[variantName] ? 200 : 404,
 			title: `${story.title} · ${APP_NAME}`,
-			view: StoryPage(story, variantName),
+			view: StoryPageDetails(story, variantName),
 			sidebar: ViewerSidebar(`/components/${story.slug}`),
+			canvas: StoryPageCanvas(story, variantName),
 		};
 	}
 

package/template/tools/sandbox/sandbox.css

@@ -130,6 +130,19 @@ body {
 	opacity: 0.5;
 }
 
+/* Component canvas — fills remaining stage width for kind: "component" stories */
+.oas-component-canvas {
+	flex: 1;
+	min-width: 0;
+	min-height: 0;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	padding: var(--size-4-4);
+	overflow: auto;
+	background: var(--background-secondary);
+}
+
 /* Collapsible card — Getting Started accordion and other expandable sections. */
 .oas-card {
 	border-bottom: 1px solid var(--background-modifier-border);