@twango/twiki 0.0.0-stage → 0.1.1

package/site/src/lib/components/graph/GraphPanel.svelte

@@ -0,0 +1,275 @@
+<script lang="ts">
+	import { onMount, tick } from 'svelte';
+	import { page } from '$app/state';
+	import { Spring, prefersReducedMotion } from 'svelte/motion';
+	import Maximize2 from '@lucide/svelte/icons/maximize-2';
+	import X from '@lucide/svelte/icons/x';
+	import {
+		addToVisited,
+		idForRoute,
+		loadGraph,
+		localGraphConfig,
+		globalGraphConfig,
+		type GraphData
+	} from './graph-data';
+	import GraphView from './GraphView.svelte';
+	import IconButton from '../ui/IconButton.svelte';
+
+	let data = $state<GraphData | null>(null);
+	let failed = $state(false);
+	let renderReady = $state(false);
+	let expanded = $state(false);
+	let closing = $state(false);
+	let wide = $state(false);
+	let mode = $state<'local' | 'global'>('local');
+	let dialog: HTMLDialogElement;
+	let slot: HTMLDivElement;
+	let opener: HTMLElement | null = null;
+	const bounds = new Spring(
+		{ x: 0, y: 0, width: 0, height: 0 },
+		{ stiffness: 0.16, damping: 0.85, precision: 0.5 }
+	);
+	const currentId = $derived(data ? idForRoute(page.url.pathname, data) : undefined);
+	function homeBounds() {
+		const rect = slot.getBoundingClientRect();
+		return wide
+			? { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+			: { x: innerWidth / 2, y: innerHeight / 2, width: 1, height: 1 };
+	}
+	async function openGraph() {
+		if (!data || expanded) return;
+		opener = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+		await bounds.set(homeBounds(), { instant: true });
+		expanded = true;
+		if (!wide) mode = 'global';
+		await tick();
+		dialog.showModal();
+		void bounds.set(
+			{ x: 0, y: 0, width: innerWidth, height: innerHeight },
+			{ instant: prefersReducedMotion.current }
+		);
+	}
+	async function closeGraph() {
+		if (!expanded || closing) return;
+		closing = true;
+		await bounds.set(homeBounds(), { instant: prefersReducedMotion.current }).catch(() => {});
+		dialog.close();
+		expanded = false;
+		closing = false;
+		mode = 'local';
+		await tick();
+		opener?.focus({ preventScroll: true });
+	}
+	onMount(() => {
+		const breakpoint = getComputedStyle(document.documentElement)
+			.getPropertyValue('--breakpoint-rail')
+			.trim();
+		const media = window.matchMedia(`(width >= ${breakpoint})`);
+		const updateWidth = () => (wide = media.matches);
+		const resize = () => {
+			if (expanded)
+				void bounds.set(
+					closing ? homeBounds() : { x: 0, y: 0, width: innerWidth, height: innerHeight },
+					{ instant: true }
+				);
+		};
+		updateWidth();
+		media.addEventListener('change', updateWidth);
+		window.addEventListener('resize', resize);
+		let cancelled = false;
+		void Promise.all([loadGraph(), import('./render-graph')]).then(
+			([graph]) => {
+				if (!cancelled) data = graph;
+			},
+			() => {
+				if (!cancelled) failed = true;
+			}
+		);
+		return () => {
+			cancelled = true;
+			media.removeEventListener('change', updateWidth);
+			window.removeEventListener('resize', resize);
+		};
+	});
+	$effect(() => {
+		if (currentId) addToVisited(currentId);
+	});
+	$effect(() => {
+		if (!expanded) return;
+		const previous = document.documentElement.style.overflow;
+		document.documentElement.style.overflow = 'hidden';
+		return () => {
+			document.documentElement.style.overflow = previous;
+		};
+	});
+	function onKeydown(event: KeyboardEvent) {
+		if (data && event.key === 'g' && (event.ctrlKey || event.metaKey) && !event.shiftKey) {
+			event.preventDefault();
+			void (expanded ? closeGraph() : openGraph());
+		}
+	}
+</script>
+
+<svelte:window onkeydown={onKeydown} />
+
+<button
+	type="button"
+	class="doc-compact-graph cursor-pointer rounded-md border border-border px-3 py-1.5 text-sm hover:bg-surface disabled:opacity-50"
+	disabled={!data}
+	onclick={openGraph}>Open global graph</button
+>
+<section
+	class="graph-panel min-w-0 shrink-0"
+	class:expanded
+	class:compact={!wide}
+	aria-label="Graph view"
+>
+	<div class="relative h-(--graph-preview-height)" data-graph-outer bind:this={slot}>
+		<dialog
+			bind:this={dialog}
+			class:expanded
+			class:closing
+			role={expanded ? 'dialog' : 'group'}
+			aria-label="Graph canvas"
+			oncancel={(event) => {
+				event.preventDefault();
+				void closeGraph();
+			}}
+			style={expanded
+				? `left:${bounds.current.x}px;top:${bounds.current.y}px;width:${bounds.current.width}px;height:${bounds.current.height}px`
+				: undefined}
+		>
+			{#if failed}
+				<p class="status">Graph unavailable.</p>
+			{:else if data && (currentId || mode === 'global') && (wide || expanded)}
+				<GraphView
+					{data}
+					{currentId}
+					config={mode === 'local' ? localGraphConfig : globalGraphConfig}
+					global={expanded}
+					onready={() => (renderReady = true)}
+					onerror={() => (failed = true)}
+					onnavigate={() => {
+						dialog.close();
+						expanded = false;
+						closing = false;
+						mode = 'local';
+					}}
+				/>
+				{#if !renderReady}<div
+						class="status pointer-events-none absolute inset-0"
+						aria-hidden="true"
+					>
+						<span class="size-5 animate-pulse rounded-full bg-subtle"></span>
+					</div>{/if}
+			{:else}<p class="status">{data ? 'This page is not in the graph.' : 'Loading graph…'}</p>{/if}
+			<h3
+				class="pointer-events-none absolute top-1 left-1 m-0 rounded bg-bg/80 px-1.5 py-1 text-xs font-medium text-muted"
+			>
+				Graph View
+			</h3>
+			{#if expanded}
+				<div class="graph-modes" aria-label="Graph scope">
+					<button
+						aria-pressed={mode === 'local'}
+						disabled={!currentId || closing}
+						onclick={() => (mode = 'local')}>Local</button
+					>
+					<button
+						aria-pressed={mode === 'global'}
+						disabled={closing}
+						onclick={() => (mode = 'global')}>Global</button
+					>
+				</div>
+			{/if}
+			<IconButton
+				class="graph-expand absolute top-1 right-1 size-6 rounded"
+				aria-label={expanded ? 'Close' : 'Expand graph'}
+				title={expanded ? 'Close graph (Escape)' : 'Expand graph'}
+				disabled={!data || closing}
+				onclick={() => (expanded ? closeGraph() : openGraph())}
+			>
+				{#if expanded}<X size={16} />{:else}<Maximize2 size={14} />{/if}
+			</IconButton>
+		</dialog>
+	</div>
+</section>
+
+<style>
+	dialog {
+		display: block;
+		position: relative;
+		inset: auto;
+		margin: 0;
+		padding: 0;
+		width: 100%;
+		height: var(--graph-preview-height);
+		max-width: none;
+		max-height: none;
+		border: 0;
+		overflow: hidden;
+		color: var(--color-text);
+		background: var(--color-bg);
+	}
+	dialog.expanded {
+		position: fixed;
+	}
+	dialog::backdrop {
+		background: rgb(0 0 0 / 0.35);
+		animation: backdrop-in 180ms ease-out;
+	}
+	dialog.closing::backdrop {
+		opacity: 0;
+		transition: opacity 180ms;
+	}
+	.status {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		height: 100%;
+		font-size: 0.75rem;
+		color: var(--color-muted);
+	}
+	.graph-modes {
+		position: absolute;
+		top: 0.5rem;
+		left: 50%;
+		transform: translateX(-50%);
+		display: flex;
+		padding: 0.125rem;
+		border: 1px solid var(--color-border);
+		border-radius: 0.375rem;
+		background: var(--color-bg);
+	}
+	.graph-modes button {
+		padding: 0.25rem 0.75rem;
+		border-radius: 0.25rem;
+		font-size: 0.75rem;
+		cursor: pointer;
+	}
+	.graph-modes button[aria-pressed='true'] {
+		background: var(--color-surface);
+		color: var(--color-accent);
+	}
+	.graph-modes button:focus-visible {
+		outline: 2px solid var(--color-accent);
+	}
+	@keyframes backdrop-in {
+		from {
+			opacity: 0;
+		}
+		to {
+			opacity: 1;
+		}
+	}
+	.graph-panel.compact.expanded {
+		display: block;
+		height: 0;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		dialog::backdrop {
+			animation: none;
+			transition: none;
+		}
+	}
+</style>

package/site/src/lib/components/graph/GraphView.svelte

@@ -0,0 +1,100 @@
+<script lang="ts">
+	/**
+	 * Persistent graph renderer shell, shared by the inline and expanded view.
+	 *
+	 * The actual rendering is a faithful port of Quartz's pixi.js + d3-force
+	 * implementation living in ./render-graph.ts, loaded via dynamic
+	 * `import()` from an $effect so pixi/d3/tween never touch the page
+	 * bundle. This component only owns the container element, the lazy
+	 * mount/destroy lifecycle, theme-flip re-renders and navigation.
+	 */
+	import type { ClassValue } from 'svelte/elements';
+	import { goto } from '$app/navigation';
+	import { cn } from '$lib/utils';
+	import { hrefForId, type GraphConfig, type GraphData } from './graph-data';
+
+	interface Props {
+		data: GraphData;
+		/** Node id of the page being viewed (Quartz's `slug`). */
+		currentId?: string;
+		/** Quartz D3Config equivalent (localGraphConfig / globalGraphConfig). */
+		config: GraphConfig;
+		/**
+		 * Global graph: wheel zoom works bare; the local graph requires
+		 * ctrl/meta (Quartz's .global-graph-container class check).
+		 */
+		global?: boolean;
+		class?: ClassValue;
+		/** Called when a node navigation starts (lets the expanded view close). */
+		onnavigate?: () => void;
+		/** Called after Pixi has drawn the first node/link frame. */
+		onready?: () => void;
+		/** Called when the renderer cannot initialize. */
+		onerror?: (error: unknown) => void;
+	}
+
+	const {
+		data,
+		currentId,
+		config,
+		global = false,
+		class: className,
+		onnavigate,
+		onready,
+		onerror
+	}: Props = $props();
+
+	let container = $state<HTMLDivElement | null>(null);
+
+	// Quartz re-renders the graph on its `themechange` event; the equivalent
+	// here is watching the .dark class flip on <html> (mode-watcher toggles it).
+	let themeTick = $state(0);
+	$effect(() => {
+		const observer = new MutationObserver(() => themeTick++);
+		observer.observe(document.documentElement, {
+			attributes: true,
+			attributeFilter: ['class']
+		});
+		return () => observer.disconnect();
+	});
+
+	$effect(() => {
+		// reactive deps: re-render on data / current page / theme changes
+		void themeTick;
+		const el = container;
+		const args = [data, currentId, config] as const;
+		if (!el) return;
+
+		let cancelled = false;
+		let cleanup: (() => void) | undefined;
+		// lazy: pixi.js + d3 + tween.js load only when a graph actually mounts
+		void import('./render-graph')
+			.then(async ({ renderGraph }) => {
+				if (cancelled) return;
+				cleanup = await renderGraph(el, args[0], args[1], args[2], false, (id) => {
+					onnavigate?.();
+					void goto(hrefForId(id));
+				});
+				if (cancelled) cleanup();
+				else onready?.();
+			})
+			.catch((error: unknown) => {
+				if (!cancelled) {
+					console.error('Knowledge graph renderer failed', error);
+					onerror?.(error);
+				}
+			});
+		return () => {
+			cancelled = true;
+			cleanup?.();
+		};
+	});
+</script>
+
+<div
+	bind:this={container}
+	data-expanded={global}
+	class={cn('h-full w-full overflow-hidden', className)}
+	role="img"
+	aria-label="Knowledge graph"
+></div>

package/site/src/lib/components/graph/graph-data.ts

@@ -0,0 +1,137 @@
+/** Lazily fetch and cache the prerendered /graph.json endpoint. */
+
+export interface GraphNode {
+	id: string;
+	title: string;
+	tags: string[];
+}
+
+export interface GraphLink {
+	source: string;
+	target: string;
+}
+
+export interface GraphData {
+	nodes: GraphNode[];
+	links: GraphLink[];
+}
+
+let graphPromise: Promise<GraphData> | undefined;
+
+/** Fetch (once) and cache the sitewide graph. */
+export function loadGraph(fetcher: typeof fetch = fetch): Promise<GraphData> {
+	graphPromise ??= fetcher('/graph.json').then((res) => {
+		if (!res.ok) {
+			graphPromise = undefined; // allow retry on transient failure
+			throw new Error(`Failed to load /graph.json: ${res.status}`);
+		}
+		return res.json() as Promise<GraphData>;
+	});
+	return graphPromise;
+}
+
+// Node ordering affects the seeded force layout; keep it stable in graph-model.ts.
+
+export interface GraphConfig {
+	drag: boolean;
+	zoom: boolean;
+	depth: number;
+	scale: number;
+	repelForce: number;
+	centerForce: number;
+	linkDistance: number;
+	fontSize: number;
+	opacityScale: number;
+	removeTags: string[];
+	showTags: boolean;
+	focusOnHover: boolean;
+	enableRadial: boolean;
+	centerCurrentNode: boolean;
+}
+
+export const localGraphConfig: GraphConfig = {
+	drag: true,
+	zoom: true,
+	depth: 2,
+	scale: 1.1,
+	repelForce: 0.5,
+	centerForce: 0.3,
+	linkDistance: 30,
+	fontSize: 0.6,
+	opacityScale: 1,
+	showTags: true,
+	removeTags: [],
+	focusOnHover: false,
+	enableRadial: false,
+	centerCurrentNode: true
+};
+
+export const globalGraphConfig: GraphConfig = {
+	drag: true,
+	zoom: true,
+	depth: -1,
+	scale: 0.9,
+	repelForce: 0.5,
+	centerForce: 0.2,
+	linkDistance: 30,
+	fontSize: 0.6,
+	opacityScale: 1,
+	showTags: true,
+	removeTags: [],
+	focusOnHover: true,
+	enableRadial: true,
+	centerCurrentNode: false
+};
+
+// ---------------------------------------------------------------------------
+// Visited tracking — Quartz keeps a `graph-visited` set in localStorage and
+// tints visited nodes differently from unvisited ones.
+// ---------------------------------------------------------------------------
+
+const visitedKey = 'graph-visited';
+
+export function getVisited(): Set<string> {
+	try {
+		return new Set(JSON.parse(localStorage.getItem(visitedKey) ?? '[]'));
+	} catch {
+		return new Set();
+	}
+}
+
+export function addToVisited(id: string): void {
+	try {
+		const visited = getVisited();
+		visited.add(id);
+		localStorage.setItem(visitedKey, JSON.stringify([...visited]));
+	} catch {
+		// localStorage unavailable (private mode etc.) — visited is cosmetic
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Route ↔ node id mapping
+// ---------------------------------------------------------------------------
+
+/** Display-form node id → site href (SvelteKit route, trailingSlash 'never'). */
+export function hrefForId(id: string): string {
+	if (id === '/' || id === '') return '/';
+	return `/${id.replace(/\/+$/, '')}`;
+}
+
+/**
+ * Current pathname → graph node id, or undefined when the route has no node
+ * (generated folder listings, 404). `/tags/<tag>` pages resolve to the
+ * synthesized `tags/<tag>` node when any page carries that tag, matching
+ * Quartz where tag pages are part of the content index.
+ */
+export function idForRoute(pathname: string, data: GraphData): string | undefined {
+	const route = decodeURIComponent(pathname).replace(/^\/+|\/+$/g, '');
+	if (route === '') return data.nodes.some((n) => n.id === '/') ? '/' : undefined;
+	if (data.nodes.some((n) => n.id === route)) return route;
+	if (data.nodes.some((n) => n.id === `${route}/`)) return `${route}/`; // folder index page
+	if (route.startsWith('tags/')) {
+		const tag = route.slice('tags/'.length);
+		if (data.nodes.some((n) => n.tags.includes(tag))) return route;
+	}
+	return undefined;
+}

package/site/src/lib/components/graph/graph-model.ts

@@ -0,0 +1,103 @@
+import type { GraphData, GraphLink } from './graph-data';
+
+interface GraphSelectionConfig {
+	depth: number;
+	showTags: boolean;
+	removeTags: string[];
+}
+
+export interface OrderedGraphElements {
+	nodeIds: string[];
+	links: GraphLink[];
+}
+
+/**
+ * Select and order the graph exactly like Quartz's graph.inline.ts.
+ *
+ * The order is observable: d3-force initializes nodes by array index, and its
+ * link force iterates links in insertion order. An adjacency-map BFS returns
+ * the same set but produces a visibly different layout, so retain Quartz's
+ * per-page outgoing/tag link order and outgoing-before-incoming worklist.
+ */
+export function orderedGraphElements(
+	fullData: GraphData,
+	slug: string | undefined,
+	config: GraphSelectionConfig
+): OrderedGraphElements {
+	const data = new Map(fullData.nodes.map((node) => [node.id, node]));
+	const validLinks = new Set(data.keys());
+	const outgoingBySource = new Map<string, GraphLink[]>();
+	for (const link of fullData.links) {
+		if (!validLinks.has(link.source) || !validLinks.has(link.target)) continue;
+		const outgoing = outgoingBySource.get(link.source);
+		if (outgoing) outgoing.push(link);
+		else outgoingBySource.set(link.source, [link]);
+	}
+
+	const links: GraphLink[] = [];
+	const tags: string[] = [];
+	for (const [source, details] of data) {
+		for (const link of outgoingBySource.get(source) ?? []) {
+			links.push({ source: link.source, target: link.target });
+		}
+
+		if (!config.showTags) continue;
+		const localTags = details.tags
+			.filter((tag) => !config.removeTags.includes(tag))
+			.map((tag) => `tags/${tag}`);
+		tags.push(...localTags.filter((tag) => !tags.includes(tag)));
+		for (const tag of localTags) links.push({ source, target: tag });
+	}
+
+	const neighbourhood = new Set<string>();
+	if (config.depth >= 0 && slug !== undefined) {
+		const outgoing = new Map<string, string[]>();
+		const incoming = new Map<string, string[]>();
+		for (const link of links) {
+			const targets = outgoing.get(link.source);
+			if (targets) targets.push(link.target);
+			else outgoing.set(link.source, [link.target]);
+			const sources = incoming.get(link.target);
+			if (sources) sources.push(link.source);
+			else incoming.set(link.target, [link.source]);
+		}
+
+		// Quartz uses a sentinel worklist and deliberately doesn't de-duplicate
+		// queued nodes. Keep that traversal order while avoiding repeated scans
+		// through the complete link array.
+		const sentinel = Symbol('depth');
+		const worklist: (string | typeof sentinel)[] = [slug, sentinel];
+		let cursor = 0;
+		let remainingDepth = config.depth;
+		while (remainingDepth >= 0 && cursor < worklist.length) {
+			const current = worklist[cursor++];
+			if (current === sentinel) {
+				remainingDepth--;
+				worklist.push(sentinel);
+				continue;
+			}
+
+			neighbourhood.add(current);
+			worklist.push(...(outgoing.get(current) ?? []), ...(incoming.get(current) ?? []));
+		}
+	} else {
+		validLinks.forEach((id) => neighbourhood.add(id));
+		if (config.showTags) tags.forEach((tag) => neighbourhood.add(tag));
+	}
+
+	return {
+		nodeIds: [...neighbourhood],
+		links: links.filter((link) => neighbourhood.has(link.source) && neighbourhood.has(link.target))
+	};
+}
+
+/** Translate a simulation coordinate into canvas space; zero is valid. */
+export function canvasPosition(
+	x: number | undefined,
+	y: number | undefined,
+	width: number,
+	height: number
+): { x: number; y: number } | undefined {
+	if (x === undefined || y === undefined) return undefined;
+	return { x: x + width / 2, y: y + height / 2 };
+}

package/site/src/lib/components/graph/index.ts

@@ -0,0 +1,3 @@
+// Ported from Quartz's graph.inline.ts. Dynamically import to defer Pixi and D3.
+export { default as GraphPanel } from './GraphPanel.svelte';
+export * from './graph-data';