markgraphy 0.1.1

package/dist/animated/GraphSequence.svelte

@@ -0,0 +1,247 @@
+<script module lang="ts">
+	export interface GraphSequenceProps {
+		/** Caption drawn on the top edge as `[ TITLE ]`. Uppercase, 1–2 words. */
+		title: string;
+		/** Animate the message flow. Default true. Reduced motion freezes the first message as current. */
+		animated?: boolean;
+		/** Width of the scene in characters; at least 40 so four participants fit. Default 68. */
+		cols?: number;
+		/** Height of the scene in rows; at least 10 so header + 6 messages fit. Default 12. */
+		rows?: number;
+		/** Milliseconds per message. Default 600. */
+		speedMs?: number;
+		/** Short caption under the art; the diagram itself is the message. */
+		label?: string;
+		class?: string;
+	}
+
+	interface Participant {
+		label: string;
+		col: number;
+	}
+
+	interface Message {
+		from: number;
+		to: number;
+		label: string;
+	}
+
+	interface Seg {
+		text: string;
+		cls?: string;
+	}
+</script>
+
+<script lang="ts">
+	import Graph from '../frame/Graph.svelte';
+	import GraphBody from '../frame/GraphBody.svelte';
+	import { overlayRow, type ArtCell } from '../diagram/ascii';
+
+	let {
+		title,
+		animated = true,
+		cols = 68,
+		rows = 12,
+		speedMs = 600,
+		label = 'who calls who, in order',
+		class: className = ''
+	}: GraphSequenceProps = $props();
+
+	// svelte-ignore state_referenced_locally
+	const width = Math.max(40, cols);
+	// svelte-ignore state_referenced_locally
+	const height = Math.max(10, rows);
+
+	// Four participants at 12% / 38% / 62% / 88% of the width so the labels
+	// sit centered on the lifelines and never collide with the side borders.
+	// svelte-ignore state_referenced_locally
+	const participants: Participant[] = (() => {
+		const labels = ['Browser', 'Server', 'DB', 'Worker'];
+		const stops = [0.12, 0.38, 0.62, 0.88];
+		return labels.map((l, i) => ({ label: l, col: Math.max(2, Math.floor(width * stops[i]!)) }));
+	})();
+
+	// A request that fans out to a DB, queues a job, and comes back.
+	const messages: Message[] = [
+		{ from: 0, to: 1, label: 'GET /api' },
+		{ from: 1, to: 2, label: 'query' },
+		{ from: 2, to: 3, label: 'enqueue' },
+		{ from: 3, to: 2, label: 'result' },
+		{ from: 2, to: 1, label: 'rows' },
+		{ from: 1, to: 0, label: '200 OK' }
+	];
+
+	// Each activation is a row-range during which a participant's lifeline is
+	// drawn as a filled bar (the participant is busy). Rows outside are `│`.
+	// svelte-ignore state_referenced_locally
+	const activations: { pIdx: number; startRow: number; endRow: number }[] = (() => {
+		const firstRow = 3;
+		const lastRow = firstRow + messages.length - 1;
+		return [
+			{ pIdx: 0, startRow: firstRow, endRow: lastRow },
+			{ pIdx: 1, startRow: firstRow, endRow: lastRow },
+			{ pIdx: 2, startRow: firstRow + 1, endRow: firstRow + 4 },
+			{ pIdx: 3, startRow: firstRow + 2, endRow: firstRow + 3 }
+		];
+	})();
+
+	const headerRow = 1;
+	const firstMsgRow = 3;
+
+	// svelte-ignore state_referenced_locally
+	let tick = $state(0);
+
+	const moving = $derived(
+		animated &&
+			(typeof window === 'undefined' ||
+				!window.matchMedia('(prefers-reduced-motion: reduce)').matches)
+	);
+
+	$effect(() => {
+		if (!moving) {
+			return;
+		}
+		const timer = window.setInterval(() => {
+			tick = (tick + 1) % messages.length;
+		}, speedMs);
+		return () => window.clearInterval(timer);
+	});
+
+	// Pin the current message at the last one when the loop wraps.
+	const currentMsg = $derived(Math.min(tick, messages.length - 1));
+
+	/**
+	 * Build the three cells that draw a single arrow: a run of dashes, a
+	 * centered label, and the head. The label is opaque so it sits on top of
+	 * the dashes without us having to split the run.
+	 */
+	function arrowCells(c1: number, c2: number, isRight: boolean, lbl: string, cls: string): ArtCell[] {
+		const c1min = Math.min(c1, c2);
+		const c2max = Math.max(c1, c2);
+		const headX = isRight ? c2max - 1 : c1min + 1;
+		const dashStart = isRight ? c1min + 1 : headX + 1;
+		const dashEnd = isRight ? headX - 1 : c2max - 1;
+		const labelCenter = Math.round((dashStart + dashEnd) / 2);
+		const labelStart = Math.max(dashStart, labelCenter - Math.floor(lbl.length / 2));
+		const dashLen = Math.max(0, dashEnd - dashStart + 1);
+		return [
+			{ at: dashStart, text: '─'.repeat(dashLen), cls },
+			{ at: labelStart, text: lbl, cls },
+			{ at: headX, text: isRight ? '▶' : '◀', cls }
+		];
+	}
+
+	const view = $derived.by((): Seg[][] => {
+		const lines: Seg[][] = [];
+
+		for (let y = 0; y < height; y++) {
+			const cells: ArtCell[] = [];
+			const isHeader = y === headerRow;
+			const msgIdx = y - firstMsgRow;
+			const inRange = msgIdx >= 0 && msgIdx < messages.length;
+			const m = inRange ? messages[msgIdx]! : null;
+			const isCurrent = m !== null && msgIdx === currentMsg;
+
+			// Lifelines — skip on the header row so the participant name
+			// can sit centered on the column without a `│` punching through.
+			if (!isHeader) {
+				for (let i = 0; i < participants.length; i++) {
+					const p = participants[i]!;
+					const act = activations.find((a) => a.pIdx === i);
+					const inActivation = !!act && y >= act.startRow && y <= act.endRow;
+					const isCurrentPart = isCurrent && m !== null && (i === m.from || i === m.to);
+
+					if (inActivation) {
+						cells.push({ at: p.col, text: '█', cls: isCurrentPart ? 'on' : 'active' });
+					} else {
+						cells.push({ at: p.col, text: '│', cls: 'lifeline' });
+					}
+				}
+			}
+
+			// Participant labels on the header row.
+			if (isHeader) {
+				for (const p of participants) {
+					const start = p.col - Math.floor(p.label.length / 2);
+					cells.push({ at: start, text: p.label, cls: 'participant' });
+				}
+			}
+
+			// Arrow row for the current message (if any).
+			if (m !== null) {
+				const p1 = participants[m.from]!;
+				const p2 = participants[m.to]!;
+				const isRight = p2.col > p1.col;
+				const cls = isCurrent ? 'on' : 'arrow';
+				cells.push(...arrowCells(p1.col, p2.col, isRight, m.label, cls));
+			}
+
+			lines.push(overlayRow(width, cells));
+		}
+
+		return lines;
+	});
+</script>
+
+<Graph {title} class={className}>
+	<GraphBody>
+		<div class="sequence">
+			<div class="viewport">
+				<pre class="art" aria-hidden="true"><code>{#each view as line, i (i)}{#each line as seg, j (j)}{#if seg.cls}<span class={seg.cls}>{seg.text}</span>{:else}{seg.text}{/if}{/each}{#if i < view.length - 1}{'\n'}{/if}{/each}</code></pre>
+			</div>
+			{#if label}
+				<p class="caption">{label}</p>
+			{/if}
+		</div>
+	</GraphBody>
+</Graph>
+
+<style>
+	.sequence {
+		display: flex;
+		flex-direction: column;
+		gap: 1rem;
+		min-width: 0;
+		font-size: 0.875rem;
+	}
+
+	.viewport {
+		overflow-x: auto;
+	}
+
+	.art {
+		margin: 0;
+		font-size: 0.85rem;
+		line-height: 1.2;
+		color: var(--graph-foreground, oklch(0.93 0 0));
+		white-space: pre;
+	}
+
+	.participant {
+		color: var(--graph-foreground, oklch(0.93 0 0));
+		font-weight: 600;
+	}
+
+	.lifeline {
+		color: var(--graph-frame, oklch(0.6 0 0 / 0.5));
+	}
+
+	.active {
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	.arrow {
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	.on {
+		color: var(--graph-accent, oklch(0.78 0.17 155));
+		font-weight: 600;
+	}
+
+	.caption {
+		margin: 0;
+		font-size: 0.8rem;
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+</style>

package/dist/animated/GraphSequence.svelte.d.ts

@@ -0,0 +1,18 @@
+export interface GraphSequenceProps {
+    /** Caption drawn on the top edge as `[ TITLE ]`. Uppercase, 1–2 words. */
+    title: string;
+    /** Animate the message flow. Default true. Reduced motion freezes the first message as current. */
+    animated?: boolean;
+    /** Width of the scene in characters; at least 40 so four participants fit. Default 68. */
+    cols?: number;
+    /** Height of the scene in rows; at least 10 so header + 6 messages fit. Default 12. */
+    rows?: number;
+    /** Milliseconds per message. Default 600. */
+    speedMs?: number;
+    /** Short caption under the art; the diagram itself is the message. */
+    label?: string;
+    class?: string;
+}
+declare const GraphSequence: import("svelte").Component<GraphSequenceProps, {}, "">;
+type GraphSequence = ReturnType<typeof GraphSequence>;
+export default GraphSequence;

package/dist/animated/GraphSpinners.svelte

@@ -0,0 +1,109 @@
+<script module lang="ts">
+	/** Which built-in glyph spinner to show. */
+	export type SpinnerKind = 'slash' | 'dots' | 'bounce' | 'bar';
+
+	/** Built-in frame sets. All glyphs are inside the Geist Mono whitelist. */
+	const FRAME_SETS: Record<SpinnerKind, string[]> = {
+		slash: ['|', '/', '-', '\\'],
+		dots: ['·', '··', '···', '··'],
+		bounce: ['▁', '▃', '▄', '▅', '▆', '▇', '█', '▇', '▆', '▄', '▃'],
+		bar: ['▏', '▎', '▍', '▌', '▋', '▊', '▉', '█']
+	};
+
+	export interface GraphSpinnersProps {
+		/** Caption drawn on the frame's top edge as `[ TITLE ]`. */
+		title: string;
+		/** Which glyph spinner to show. Default 'dots'. */
+		kind?: SpinnerKind;
+		/** Text shown after the spinner. Default 'loading'. */
+		label?: string;
+		/** Milliseconds per frame. Default 120. */
+		speedMs?: number;
+		/** Custom frame set. Overrides `kind` when non-empty. Padded to equal width. */
+		frames?: string[];
+		/** Animate the frames. Default true. Reduced motion holds frame 0. */
+		animated?: boolean;
+		/** Character at each corner of the frame. Default '+'. */
+		corner?: string;
+		class?: string;
+	}
+</script>
+
+<script lang="ts">
+	import Graph from '../frame/Graph.svelte';
+	import GraphBody from '../frame/GraphBody.svelte';
+
+	let {
+		title,
+		kind = 'dots',
+		label = 'loading',
+		speedMs = 120,
+		frames,
+		animated = true,
+		corner,
+		class: className = ''
+	}: GraphSpinnersProps = $props();
+
+	let frame = $state(0);
+
+	const moving = $derived(
+		animated &&
+			(typeof window === 'undefined' ||
+				!window.matchMedia('(prefers-reduced-motion: reduce)').matches)
+	);
+
+	/** Active frames, padded with trailing spaces so nothing shifts between steps. */
+	const effFrames = $derived.by(() => {
+		const src = frames && frames.length > 0 ? frames : FRAME_SETS[kind];
+		const width = src.reduce((max, f) => Math.max(max, f.length), 1);
+
+		return src.map((f) => f + ' '.repeat(width - f.length));
+	});
+
+	$effect(() => {
+		if (!moving || effFrames.length === 0) {
+			return;
+		}
+
+		const timer = window.setInterval(() => {
+			frame = (frame + 1) % effFrames.length;
+		}, Math.max(50, speedMs));
+
+		return () => window.clearInterval(timer);
+	});
+
+	// Static or reduced motion: hold frame 0.
+	const shown = $derived(
+		moving && effFrames.length > 0 ? effFrames[frame % effFrames.length] : (effFrames[0] ?? '')
+	);
+</script>
+
+<Graph {title} {corner} class={className}>
+	<GraphBody>
+		<div class="spinner">
+			<pre class="art"><code><span class="glyph">{shown}</span><span class="label"> {label}</span></code></pre>
+		</div>
+	</GraphBody>
+</Graph>
+
+<style>
+	.spinner {
+		min-width: 0;
+	}
+
+	.art {
+		margin: 0;
+		font-size: 0.85rem;
+		line-height: 1.35;
+		color: var(--graph-muted, oklch(0.62 0 0));
+		white-space: pre;
+	}
+
+	.glyph {
+		color: var(--graph-accent, oklch(0.78 0.17 155));
+	}
+
+	.label {
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+</style>

package/dist/animated/GraphSpinners.svelte.d.ts

@@ -0,0 +1,22 @@
+/** Which built-in glyph spinner to show. */
+export type SpinnerKind = 'slash' | 'dots' | 'bounce' | 'bar';
+export interface GraphSpinnersProps {
+    /** Caption drawn on the frame's top edge as `[ TITLE ]`. */
+    title: string;
+    /** Which glyph spinner to show. Default 'dots'. */
+    kind?: SpinnerKind;
+    /** Text shown after the spinner. Default 'loading'. */
+    label?: string;
+    /** Milliseconds per frame. Default 120. */
+    speedMs?: number;
+    /** Custom frame set. Overrides `kind` when non-empty. Padded to equal width. */
+    frames?: string[];
+    /** Animate the frames. Default true. Reduced motion holds frame 0. */
+    animated?: boolean;
+    /** Character at each corner of the frame. Default '+'. */
+    corner?: string;
+    class?: string;
+}
+declare const GraphSpinners: import("svelte").Component<GraphSpinnersProps, {}, "">;
+type GraphSpinners = ReturnType<typeof GraphSpinners>;
+export default GraphSpinners;

package/dist/animated/GraphState.svelte

@@ -0,0 +1,270 @@
+<script module lang="ts">
+	export interface GraphStateProps {
+		/** Caption drawn on the top edge as `[ TITLE ]`. Uppercase, 1–2 words. */
+		title: string;
+		/** Animate the state cycle. Default true. Reduced motion freezes on the start state. */
+		animated?: boolean;
+		/** Milliseconds per state step. Default 700. */
+		speedMs?: number;
+		/** Short caption under the art; the chart itself is the message. */
+		label?: string;
+		class?: string;
+	}
+
+	interface State {
+		id: string;
+		label: string;
+		col: number;
+		row: number;
+	}
+
+	interface Transition {
+		from: number;
+		to: number;
+		label: string;
+	}
+
+	interface Seg {
+		text: string;
+		cls?: string;
+	}
+</script>
+
+<script lang="ts">
+	import Graph from '../frame/Graph.svelte';
+	import GraphBody from '../frame/GraphBody.svelte';
+	import { dashEdge, overlayRow, type ArtCell } from '../diagram/ascii';
+
+	let {
+		title,
+		animated = true,
+		speedMs = 700,
+		label = 'state machine, stepping through',
+		class: className = ''
+	}: GraphStateProps = $props();
+
+	// Hardcoded 2×2 layout: 14-wide boxes, vertical and horizontal arrows in
+	// the gutters, 1-char gap between everything. W/H are scene dimensions
+	// in characters; the Graph frame adds one row/col on each side.
+	const W = 44;
+	const H = 15;
+	const BOX_W = 14;
+	const BOX_H = 3;
+
+	// svelte-ignore state_referenced_locally
+	const states: State[] = [
+		{ id: 'ready', label: 'ready', col: 2, row: 2 },
+		{ id: 'think', label: 'think', col: 24, row: 2 },
+		{ id: 'act', label: 'act', col: 24, row: 11 },
+		{ id: 'done', label: 'done', col: 2, row: 11 }
+	];
+
+	// svelte-ignore state_referenced_locally
+	const transitions: Transition[] = [
+		{ from: 0, to: 1, label: 'ask' },
+		{ from: 1, to: 2, label: 'plan' },
+		{ from: 2, to: 3, label: 'ok' },
+		{ from: 3, to: 0, label: 'reset' }
+	];
+
+	// svelte-ignore state_referenced_locally
+	let tick = $state(0);
+
+	const moving = $derived(
+		animated &&
+			(typeof window === 'undefined' ||
+				!window.matchMedia('(prefers-reduced-motion: reduce)').matches)
+	);
+
+	$effect(() => {
+		if (!moving) {
+			return;
+		}
+		const timer = window.setInterval(() => {
+			tick = (tick + 1) % states.length;
+		}, speedMs);
+		return () => window.clearInterval(timer);
+	});
+
+	// The current state and its outgoing transition both glow. Under reduced
+	// motion this freezes on the start state with the first transition lit,
+	// which reads as "ready to begin".
+	const currentState = $derived(tick % states.length);
+	const currentTransition = $derived(transitions[currentState]!);
+
+	/** Build the three cells that draw one state box at (col, row). */
+	function boxRow(s: State, y: number, cls: string): ArtCell {
+		const top = dashEdge(BOX_W);
+		const inner = BOX_W - 2;
+		const pad = inner - s.label.length;
+		const left = Math.floor(pad / 2);
+		const right = pad - left;
+		const mid = '|' + ' '.repeat(left) + s.label + ' '.repeat(right) + '|';
+		const yOff = y - s.row;
+		// yOff: 0 = top edge, 1 = label row, 2 = bottom edge.
+		const text = yOff === 0 || yOff === 2 ? top : mid;
+		return { at: s.col, text, cls };
+	}
+
+	/** Build the cells that draw one horizontal arrow between two boxes. */
+	function hArrowCells(c1: number, c2: number, lbl: string, cls: string): ArtCell[] {
+		const isRight = c2 > c1;
+		if (isRight) {
+			const dashStart = c1 + BOX_W;
+			const dashEnd = c2 - 2;
+			const headX = c2 - 1;
+			const labelCenter = Math.round((dashStart + dashEnd) / 2);
+			const labelStart = Math.max(dashStart, labelCenter - Math.floor(lbl.length / 2));
+			const dashLen = Math.max(0, dashEnd - dashStart + 1);
+			return [
+				{ at: dashStart, text: '─'.repeat(dashLen), cls },
+				{ at: labelStart, text: lbl, cls },
+				{ at: headX, text: '▶', cls }
+			];
+		}
+		const dashStart = c2 + BOX_W + 1;
+		const dashEnd = c1 - 1;
+		const headX = c2 + BOX_W;
+		const labelCenter = Math.round((dashStart + dashEnd) / 2);
+		const labelStart = Math.max(dashStart, labelCenter - Math.floor(lbl.length / 2));
+		const dashLen = Math.max(0, dashEnd - dashStart + 1);
+		return [
+			{ at: headX, text: '◀', cls },
+			{ at: labelStart, text: lbl, cls },
+			{ at: dashStart, text: '─'.repeat(dashLen), cls }
+		];
+	}
+
+	const view = $derived.by((): Seg[][] => {
+		const lines: Seg[][] = [];
+
+		for (let y = 0; y < H; y++) {
+			const cells: ArtCell[] = [];
+
+			// State boxes.
+			for (let i = 0; i < states.length; i++) {
+				const s = states[i]!;
+				const inBox = y >= s.row && y <= s.row + BOX_H - 1;
+				if (!inBox) {
+					continue;
+				}
+				const isCurrent = i === currentState;
+				const cls = isCurrent ? 'on' : 'state';
+				cells.push(boxRow(s, y, cls));
+			}
+
+			// Top horizontal: ready → think (row 3).
+			if (y === 3) {
+				const t = transitions[0]!;
+				const isCurrentT =
+					currentTransition.from === t.from && currentTransition.to === t.to;
+				cells.push(
+					...hArrowCells(
+						states[t.from]!.col,
+						states[t.to]!.col,
+						t.label,
+						isCurrentT ? 'on' : 'arrow'
+					)
+				);
+			}
+
+			// Bottom horizontal: act → done (row 12), right to left.
+			if (y === 12) {
+				const t = transitions[2]!;
+				const isCurrentT =
+					currentTransition.from === t.from && currentTransition.to === t.to;
+				cells.push(
+					...hArrowCells(
+						states[t.from]!.col,
+						states[t.to]!.col,
+						t.label,
+						isCurrentT ? 'on' : 'arrow'
+					)
+				);
+			}
+
+			// Right vertical: think → act (col 38, rows 5–10, head v at row 10).
+			if (y >= 5 && y <= 10) {
+				const t = transitions[1]!;
+				const isCurrentT =
+					currentTransition.from === t.from && currentTransition.to === t.to;
+				const cls = isCurrentT ? 'on' : 'arrow';
+				cells.push({ at: 38, text: y === 10 ? 'v' : '│', cls });
+				if (y === 7) {
+					cells.push({ at: 39, text: t.label, cls });
+				}
+			}
+
+			// Left vertical: done → ready (col 16, rows 5–10, head ^ at row 5).
+			if (y >= 5 && y <= 10) {
+				const t = transitions[3]!;
+				const isCurrentT =
+					currentTransition.from === t.from && currentTransition.to === t.to;
+				const cls = isCurrentT ? 'on' : 'arrow';
+				cells.push({ at: 16, text: y === 5 ? '^' : '│', cls });
+				if (y === 8) {
+					cells.push({ at: 17, text: t.label, cls });
+				}
+			}
+
+			lines.push(overlayRow(W, cells));
+		}
+
+		return lines;
+	});
+</script>
+
+<Graph {title} class={className}>
+	<GraphBody>
+		<div class="state">
+			<div class="viewport">
+				<pre class="art" aria-hidden="true"><code>{#each view as line, i (i)}{#each line as seg, j (j)}{#if seg.cls}<span class={seg.cls}>{seg.text}</span>{:else}{seg.text}{/if}{/each}{#if i < view.length - 1}{'\n'}{/if}{/each}</code></pre>
+			</div>
+			{#if label}
+				<p class="caption">{label}</p>
+			{/if}
+		</div>
+	</GraphBody>
+</Graph>
+
+<style>
+	.state {
+		display: flex;
+		flex-direction: column;
+		gap: 1rem;
+		min-width: 0;
+		font-size: 0.875rem;
+	}
+
+	.viewport {
+		overflow-x: auto;
+	}
+
+	.art {
+		margin: 0;
+		font-size: 0.85rem;
+		line-height: 1.2;
+		color: var(--graph-foreground, oklch(0.93 0 0));
+		white-space: pre;
+	}
+
+	/* Per-class styling for the spans inside <pre>. */
+	:global(.state span.state) {
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	:global(.state span.on) {
+		color: var(--graph-accent, oklch(0.78 0.17 155));
+		font-weight: 600;
+	}
+
+	:global(.state span.arrow) {
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	.caption {
+		margin: 0;
+		font-size: 0.8rem;
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+</style>

package/dist/animated/GraphState.svelte.d.ts

@@ -0,0 +1,14 @@
+export interface GraphStateProps {
+    /** Caption drawn on the top edge as `[ TITLE ]`. Uppercase, 1–2 words. */
+    title: string;
+    /** Animate the state cycle. Default true. Reduced motion freezes on the start state. */
+    animated?: boolean;
+    /** Milliseconds per state step. Default 700. */
+    speedMs?: number;
+    /** Short caption under the art; the chart itself is the message. */
+    label?: string;
+    class?: string;
+}
+declare const GraphState: import("svelte").Component<GraphStateProps, {}, "">;
+type GraphState = ReturnType<typeof GraphState>;
+export default GraphState;