create-obsidian-arrow 0.1.0

package/template/src/components/SettingsPanel.ts

@@ -0,0 +1,232 @@
+import { component, html, reactive } from "@arrow-js/core";
+import type { ArrowTemplate } from "@arrow-js/core";
+import { boundary } from "@arrow-js/framework";
+import { loadStatus } from "../data/loadStatus";
+
+/**
+ * Baseline Arrow component for the Obsidian sandbox.
+ *
+ * Built only with Obsidian's own classes (.setting-item, .checkbox-container,
+ * .vertical-tab-*) + var(--…) tokens, so it copy-pastes into an ItemView /
+ * settings tab. It deliberately exercises the template features that matter:
+ *
+ *   - reactive `${() => …}` vs static `${…}`
+ *   - attribute sync with false-removal: `disabled="${() => !cond}"` (false ⇒ removed)
+ *   - property binding: `.checked="${() => …}"`
+ *   - events: `@click`
+ *   - keyed lists: `.key(id)` + fine-grained in-place reactivity
+ *   - an async section via component(asyncFn, { fallback }) wrapped in boundary()
+ */
+
+interface Feature {
+	id: string;
+	name: string;
+	description: string;
+	enabled: boolean;
+}
+
+const tabs = [
+	{ id: "general", label: "General" },
+	{ id: "advanced", label: "Advanced engine" },
+] as const;
+
+type TabId = (typeof tabs)[number]["id"];
+
+const state = reactive({
+	activeTab: "general" as TabId,
+	developerMode: true,
+	pluginName: "Arrow Component",
+	lastAction: "—",
+	features: [
+		{
+			id: "live-queue",
+			name: "Live queue",
+			description: "Stream queue updates into the side panel.",
+			enabled: true,
+		},
+		{
+			id: "semantic",
+			name: "Semantic search",
+			description: "Embed notes for vault-wide similarity search.",
+			enabled: false,
+		},
+		{
+			id: "telemetry",
+			name: "Anonymous telemetry",
+			description: "Share usage metrics to improve the plugin.",
+			enabled: false,
+		},
+	] as Feature[],
+});
+
+const enabledCount = (): number => state.features.filter((f) => f.enabled).length;
+
+function rebuildIndex(): void {
+	state.lastAction = `Rebuilt index at tick ${performance.now().toFixed(0)}`;
+}
+
+/**
+ * Reusable Obsidian-style toggle. `enabled` is a getter so the control tracks
+ * live state; clicking flips it in place (deep reactivity re-runs only the
+ * tracked expressions below — no list re-render).
+ */
+const Toggle = (enabled: () => boolean, onToggle: () => void): ArrowTemplate => html`<div
+    class="${() => `checkbox-container${enabled() ? " is-enabled" : ""}`}"
+    @click="${onToggle}"
+  >
+    <input type="checkbox" tabindex="0" .checked="${() => enabled()}" />
+  </div>`;
+
+const generalTab = (): ArrowTemplate => html`
+  <div class="setting-item setting-item-heading">
+    <div class="setting-item-info">
+      <div class="setting-item-name">${() => state.pluginName}</div>
+      <div class="setting-item-description">
+        ${() => `${enabledCount()} of ${state.features.length} features enabled`}
+      </div>
+    </div>
+  </div>
+
+  <div class="setting-item">
+    <div class="setting-item-info">
+      <div class="setting-item-name">Developer sandbox mode</div>
+      <div class="setting-item-description">Run isolated component rendering routines.</div>
+    </div>
+    <div class="setting-item-control">
+      ${Toggle(
+				() => state.developerMode,
+				() => {
+					state.developerMode = !state.developerMode;
+				}
+			)}
+    </div>
+  </div>
+
+  ${() =>
+		state.features.map((feature) =>
+			html`
+        <div class="setting-item">
+          <div class="setting-item-info">
+            <div class="setting-item-name">${feature.name}</div>
+            <div class="setting-item-description">${feature.description}</div>
+          </div>
+          <div class="setting-item-control">
+            ${Toggle(
+							() => feature.enabled,
+							() => {
+								feature.enabled = !feature.enabled;
+							}
+						)}
+          </div>
+        </div>
+      `.key(feature.id)
+		)}
+
+  <div class="setting-item">
+    <div class="setting-item-info">
+      <div class="setting-item-name">Sandbox state</div>
+    </div>
+    <div class="setting-item-control">
+      <span
+        style="${() =>
+					`color: ${state.developerMode ? "var(--text-accent)" : "var(--text-error)"}; font-weight: var(--font-semibold);`}"
+      >${() => (state.developerMode ? "ONLINE" : "OFFLINE")}</span>
+    </div>
+  </div>
+
+  ${boundary(statusCard())}
+`;
+
+const advancedTab = (): ArrowTemplate => html`
+  <div class="setting-item setting-item-heading">
+    <div class="setting-item-info">
+      <div class="setting-item-name">Advanced engine</div>
+    </div>
+  </div>
+
+  <div class="setting-item">
+    <div class="setting-item-info">
+      <div class="setting-item-name">Rebuild index</div>
+      <div class="setting-item-description">
+        ${() =>
+					state.developerMode
+						? "Available while developer mode is on."
+						: "Enable developer mode to rebuild."}
+      </div>
+    </div>
+    <div class="setting-item-control">
+      <button
+        class="mod-cta"
+        disabled="${() => !state.developerMode}"
+        @click="${rebuildIndex}"
+      >Rebuild</button>
+    </div>
+  </div>
+
+  <div class="setting-item">
+    <div class="setting-item-info">
+      <div class="setting-item-name">Last action</div>
+      <div class="setting-item-description" style="font-family: var(--font-monospace);">
+        ${() => state.lastAction}
+      </div>
+    </div>
+  </div>
+`;
+
+/** Async component: resolves to a setting row; shows a fallback while pending. */
+const statusCard = component(
+	async () => {
+		const status = await loadStatus();
+		return html`
+      <div class="setting-item">
+        <div class="setting-item-info">
+          <div class="setting-item-name">Connection</div>
+          <div class="setting-item-description">${status.detail}</div>
+        </div>
+        <div class="setting-item-control">
+          <span style="color: var(--text-success); font-weight: var(--font-semibold);">
+            ${status.label}
+          </span>
+        </div>
+      </div>
+    `;
+	},
+	{
+		fallback: html`
+      <div class="setting-item">
+        <div class="setting-item-info">
+          <div class="setting-item-name">Connection</div>
+          <div class="setting-item-description">Checking connection…</div>
+        </div>
+        <div class="setting-item-control">
+          <span style="color: var(--text-muted);">…</span>
+        </div>
+      </div>
+    `,
+	}
+);
+
+export const SettingsPanel = component(
+	() => html`
+    <div class="oas-settings">
+      <div class="vertical-tab-header">
+        <div class="vertical-tab-header-group">
+          <div class="vertical-tab-header-group-title">Plugin settings</div>
+          ${() =>
+						tabs.map((tab) =>
+							html`<div
+                  class="${() => `vertical-tab-nav-item${state.activeTab === tab.id ? " is-active" : ""}`}"
+                  @click="${() => {
+										state.activeTab = tab.id;
+									}}"
+                >${tab.label}</div>`.key(tab.id)
+						)}
+        </div>
+      </div>
+
+      <div class="vertical-tab-content">
+        ${() => (state.activeTab === "general" ? generalTab() : advancedTab())}
+      </div>
+    </div>
+  `
+);

package/template/src/data/loadStatus.ts

@@ -0,0 +1,17 @@
+/**
+ * Stand-in async data source for the boundary() demo. In the real plugin this
+ * would be an RPC call (session scan, model list, connection probe). The
+ * artificial delay lets us actually see the async fallback render.
+ */
+export interface StatusInfo {
+	label: string;
+	detail: string;
+}
+
+export async function loadStatus(): Promise<StatusInfo> {
+	await new Promise((resolve) => setTimeout(resolve, 900));
+	return {
+		label: "Connected",
+		detail: "pi daemon reachable · 12ms latency · 3 vaults synced",
+	};
+}

package/template/src/examples/ExamplesIndex.ts

@@ -0,0 +1,36 @@
+import { html } from "@arrow-js/core";
+import type { ArrowTemplate } from "@arrow-js/core";
+import type { Example } from "./registry";
+
+/**
+ * Landing page at "/" — an Obsidian-styled list of the available example
+ * components, each linking to its own route. Plain anchors (full reloads) keep
+ * the router trivial; the sandbox doesn't need SPA navigation.
+ */
+export const ExamplesIndex = (items: Example[]): ArrowTemplate => html`
+	<div class="oas-settings">
+		<div class="setting-item setting-item-heading">
+			<div class="setting-item-info">
+				<div class="setting-item-name">Examples</div>
+				<div class="setting-item-description">
+					Component demos rendered with real Obsidian styling.
+				</div>
+			</div>
+		</div>
+		${items.map((example) =>
+			html`
+					<div class="setting-item">
+						<div class="setting-item-info">
+							<div class="setting-item-name">
+								<a href="${example.path}">${example.label}</a>
+							</div>
+							<div class="setting-item-description">${example.description}</div>
+						</div>
+						<div class="setting-item-control">
+							<a class="mod-cta oas-open-link" href="${example.path}">Open</a>
+						</div>
+					</div>
+				`.key(example.path)
+		)}
+	</div>
+`;

package/template/src/examples/registry.ts

@@ -0,0 +1,26 @@
+import type { ArrowExpression } from "@arrow-js/core";
+import { SettingsPanel } from "../components/SettingsPanel";
+
+/**
+ * Registry of example components, keyed by route path. Add a new demo here and
+ * it shows up on the index page and at its own path automatically.
+ */
+export interface Example {
+	path: string;
+	label: string;
+	description: string;
+	view: () => ArrowExpression;
+}
+
+export const examples: Example[] = [
+	{
+		path: "/example",
+		label: "Settings panel",
+		description: "Vertical tabs, toggles, a keyed list, and an async boundary() section.",
+		view: () => SettingsPanel(),
+	},
+];
+
+export function findExample(path: string): Example | undefined {
+	return examples.find((example) => example.path === path);
+}

package/template/src/main.ts

@@ -0,0 +1,18 @@
+// Side-effect import installs the framework runtime (async components + boundary).
+// This is the one extra line a plugin would add to adopt @arrow-js/framework.
+import "@arrow-js/framework";
+
+import { startRouter } from "./router/client";
+import { applyTheme } from "./sandbox/theme";
+import "./sandbox/sandbox.css";
+
+applyTheme();
+
+const root = document.getElementById("app");
+if (!root) {
+	throw new Error("Sandbox mount point #app not found.");
+}
+
+// Routes resolve through routeToPage() and mount via template(container) —
+// the same call an Obsidian ItemView.onOpen() makes.
+startRouter(root);

package/template/src/router/client.ts

@@ -0,0 +1,85 @@
+import { Frame } from "../sandbox/frame";
+import { Shell } from "../sandbox/shell";
+import { routeToPage } from "./routeToPage";
+
+/**
+ * Client router. Prefers the native Navigation API (single `navigate` event
+ * stream, reliable history traversal) and falls back to the History API +
+ * click interception for browsers without it. Both paths resolve through the
+ * one `routeToPage()` and re-mount the Frame into the root.
+ *
+ * Minimal Navigation API typings — TS lib coverage varies by version, so we
+ * structurally type only the members we touch instead of relying on lib.dom.
+ */
+interface NavigateEventLike {
+	canIntercept: boolean;
+	hashChange: boolean;
+	downloadRequest: string | null;
+	destination: { url: string };
+	intercept(options: { handler: () => Promise<void> | void }): void;
+}
+
+interface NavigationLike {
+	addEventListener(type: "navigate", listener: (event: NavigateEventLike) => void): void;
+}
+
+function getNavigation(): NavigationLike | undefined {
+	return (window as unknown as { navigation?: NavigationLike }).navigation;
+}
+
+export function startRouter(root: HTMLElement): void {
+	const render = (url: string): void => {
+		const page = routeToPage(url);
+		document.title = page.title;
+		root.replaceChildren();
+		Shell(Frame(page.title, page.view))(root);
+	};
+
+	render(window.location.href);
+
+	const navigation = getNavigation();
+	if (navigation) {
+		navigation.addEventListener("navigate", (event) => {
+			if (!event.canIntercept || event.hashChange || event.downloadRequest !== null) {
+				return;
+			}
+			const destination = new URL(event.destination.url);
+			if (destination.origin !== window.location.origin) {
+				return;
+			}
+			event.intercept({
+				handler: () => {
+					render(destination.href);
+				},
+			});
+		});
+		return;
+	}
+
+	// History API fallback for browsers without the Navigation API.
+	document.addEventListener("click", (event) => {
+		if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey) {
+			return;
+		}
+		const target = event.target as Element | null;
+		const link = target?.closest("a");
+		if (!link) {
+			return;
+		}
+		const href = link.getAttribute("href");
+		if (!href || link.target === "_blank" || link.hasAttribute("download")) {
+			return;
+		}
+		const destination = new URL(href, window.location.origin);
+		if (destination.origin !== window.location.origin) {
+			return;
+		}
+		event.preventDefault();
+		window.history.pushState({}, "", destination.href);
+		render(destination.href);
+	});
+
+	window.addEventListener("popstate", () => {
+		render(window.location.href);
+	});
+}

package/template/src/router/routeToPage.ts

@@ -0,0 +1,57 @@
+import { html } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
+import { ExamplesIndex } from "../examples/ExamplesIndex";
+import { examples, findExample } from "../examples/registry";
+
+/**
+ * Single route resolver, shared by every entry point. Returns the page status,
+ * title (metadata), and Arrow view together — the same shape the Arrow Vite
+ * scaffold uses, so a future SSR/hydration lane can call this identically on
+ * both server and client. The client router (./client.ts) wraps the view in the
+ * sandbox Frame and sets document.title from this.
+ */
+export interface Page {
+	status: number;
+	title: string;
+	view: ArrowExpression;
+}
+
+const APP_NAME = "Arrow Sandbox";
+
+export function routeToPage(url: string): Page {
+	const { pathname } = new URL(url, window.location.origin);
+
+	if (pathname === "/" || pathname === "") {
+		return {
+			status: 200,
+			title: `Examples · ${APP_NAME}`,
+			view: ExamplesIndex(examples),
+		};
+	}
+
+	const match = findExample(pathname);
+	if (match) {
+		return {
+			status: 200,
+			title: `${match.label} · ${APP_NAME}`,
+			view: match.view(),
+		};
+	}
+
+	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 to examples</a>.
+						</div>
+					</div>
+				</div>
+			</div>
+		`,
+	};
+}

package/template/src/sandbox/frame.ts

@@ -0,0 +1,35 @@
+import { html } from "@arrow-js/core";
+import type { ArrowExpression, ArrowTemplate } from "@arrow-js/core";
+import { layoutState, startResize } from "./layout";
+import { themeState, toggleTheme } from "./theme";
+
+/**
+ * Wraps a route view in an Obsidian workspace-leaf shell so the sandbox looks
+ * like a real side-panel view. Uses Obsidian's own layout classes
+ * (.workspace-leaf, .view-header, .view-content) so the chrome is styled by
+ * app.css. Width is driven by reactive layout state (toolbar slider / presets /
+ * the edge drag handle); height fills the stage.
+ *
+ * Sandbox chrome only — the route view mounted inside is what ports to a plugin.
+ */
+export const Frame = (title: string, content: ArrowExpression): ArrowTemplate => html`
+	<div class="workspace-leaf oas-frame" style="${() => `width:${layoutState.width}px`}">
+		<div class="workspace-leaf-content" data-type="arrow-sandbox">
+			<div class="view-header">
+				<div class="oas-view-header-left">
+					<a class="clickable-icon oas-home" href="/" aria-label="Examples">⌂</a>
+					<div class="view-header-title">${title}</div>
+				</div>
+				<div class="view-actions">
+					<button
+						class="clickable-icon oas-theme-toggle"
+						aria-label="Toggle theme"
+						@click="${toggleTheme}"
+					>${() => (themeState.theme === "theme-dark" ? "☾" : "☀")}</button>
+				</div>
+			</div>
+			<div class="view-content oas-view-content">${content}</div>
+		</div>
+		<div class="oas-resize-handle" aria-hidden="true" @mousedown="${startResize}"></div>
+	</div>
+`;

package/template/src/sandbox/layout.ts

@@ -0,0 +1,40 @@
+import { reactive } from "@arrow-js/core";
+
+/**
+ * Sandbox-only panel sizing. Obsidian side panels are user-resizable, so we let
+ * the tester adjust the pane width (height stays pinned to the window). Sandbox
+ * chrome — not ported into the plugin.
+ */
+export const MIN_WIDTH = 240;
+export const WIDTH_PRESETS = [280, 360, 480, 640];
+
+export const layoutState = reactive<{ width: number }>({ width: 420 });
+
+function maxWidth(): number {
+	return Math.max(MIN_WIDTH, window.innerWidth);
+}
+
+export function setWidth(px: number): void {
+	layoutState.width = Math.min(maxWidth(), Math.max(MIN_WIDTH, Math.round(px)));
+}
+
+/** Start a drag-resize from the panel's edge handle. Typed as `Event` so it
+ * binds directly to Arrow's `@mousedown` handler signature. */
+export function startResize(event: Event): void {
+	event.preventDefault();
+	const startX = (event as MouseEvent).clientX;
+	const startWidth = layoutState.width;
+
+	const onMove = (move: MouseEvent): void => {
+		setWidth(startWidth + (move.clientX - startX));
+	};
+	const onUp = (): void => {
+		document.removeEventListener("mousemove", onMove);
+		document.removeEventListener("mouseup", onUp);
+		document.body.style.userSelect = "";
+	};
+
+	document.body.style.userSelect = "none";
+	document.addEventListener("mousemove", onMove);
+	document.addEventListener("mouseup", onUp);
+}

package/template/src/sandbox/sandbox.css

@@ -0,0 +1,125 @@
+/*
+ * Sandbox-only chrome. NOT ported into the plugin.
+ *
+ * Per the arrow-js-obsidian CSS-specificity lesson, every custom rule is scoped
+ * under a container class + element type so it can't lose to Obsidian's global
+ * rules (e.g. `button:not(.clickable-icon)`) and can't leak. All values use
+ * Obsidian tokens so the sandbox tracks the active theme.
+ */
+
+html,
+body {
+	margin: 0;
+	height: 100%;
+	background: var(--background-primary);
+	color: var(--text-normal);
+	font-family: var(--font-interface);
+}
+
+#app {
+	height: 100vh;
+}
+
+/* Shell: width-control toolbar on top, pane stage below. */
+.oas-shell {
+	display: flex;
+	flex-direction: column;
+	height: 100vh;
+}
+
+.oas-toolbar {
+	display: flex;
+	align-items: center;
+	gap: var(--size-4-2);
+	padding: var(--size-4-1) var(--size-4-3);
+	background: var(--background-secondary);
+	border-bottom: 1px solid var(--background-modifier-border);
+	color: var(--text-muted);
+	font-size: var(--font-ui-small);
+}
+
+.oas-toolbar .oas-toolbar-label {
+	font-weight: var(--font-medium);
+}
+
+.oas-toolbar .oas-width-range {
+	flex: 0 1 220px;
+}
+
+.oas-toolbar .oas-width-readout {
+	min-width: 52px;
+	font-family: var(--font-monospace);
+	color: var(--text-normal);
+}
+
+.oas-toolbar button.oas-preset {
+	height: var(--size-4-5);
+	padding: 0 var(--size-4-2);
+	font-size: var(--font-ui-smaller);
+}
+
+/* Stage: left-aligned so the edge drag handle resizes width 1:1. */
+.oas-stage {
+	flex: 1;
+	display: flex;
+	justify-content: flex-start;
+	overflow: hidden;
+	background: var(--background-secondary);
+}
+
+.oas-frame.workspace-leaf {
+	position: relative;
+	flex: 0 0 auto;
+	height: 100%;
+	min-width: 240px;
+	display: flex;
+	flex-direction: column;
+	background: var(--background-primary);
+	border-right: 1px solid var(--background-modifier-border);
+}
+
+.oas-frame .oas-view-content {
+	flex: 1;
+	overflow-y: auto;
+	padding: var(--size-4-3);
+}
+
+.oas-frame .view-header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+}
+
+.oas-frame .oas-view-header-left {
+	display: flex;
+	align-items: center;
+	gap: var(--size-4-2);
+}
+
+.oas-frame .view-header .oas-theme-toggle,
+.oas-frame .view-header .oas-home {
+	font-size: var(--font-ui-medium);
+	line-height: 1;
+	text-decoration: none;
+}
+
+.oas-frame a.oas-open-link {
+	text-decoration: none;
+	display: inline-flex;
+	align-items: center;
+}
+
+/* Drag-to-resize handle on the pane's right edge (Obsidian-like). */
+.oas-frame .oas-resize-handle {
+	position: absolute;
+	top: 0;
+	right: 0;
+	width: 6px;
+	height: 100%;
+	cursor: ew-resize;
+}
+
+.oas-frame .oas-resize-handle:hover {
+	background: var(--interactive-accent);
+	opacity: 0.5;
+}

package/template/src/sandbox/shell.ts

@@ -0,0 +1,15 @@
+import { html } from "@arrow-js/core";
+import type { ArrowExpression, ArrowTemplate } from "@arrow-js/core";
+import { Toolbar } from "./toolbar";
+
+/**
+ * Sandbox shell: the width-control toolbar plus a stage that holds the pane.
+ * The Frame (and the component under test) mount inside the stage. Sandbox
+ * chrome — only the pane contents port into a plugin.
+ */
+export const Shell = (content: ArrowExpression): ArrowTemplate => html`
+	<div class="oas-shell">
+		${Toolbar()}
+		<div class="oas-stage">${content}</div>
+	</div>
+`;