markgraphy 0.1.1

package/dist/graphs/GraphPlot.svelte

@@ -0,0 +1,226 @@
+<script module lang="ts">
+	import type { Glyphs } from '../frame/glyphs';
+	import type { GraphPalette } from '../frame/tone';
+
+	/** Line or area plot drawn from columns of glyphs, with y-scale labels. */
+	export interface GraphPlotProps {
+		title: string;
+		data: number[];
+		labels?: string[];
+		height?: number;
+		variant?: 'line' | 'area';
+		progress?: number;
+		glyphs?: Glyphs;
+		palette?: GraphPalette;
+		corner?: string;
+		class?: string;
+	}
+</script>
+
+<script lang="ts">
+	import Graph from '../frame/Graph.svelte';
+	import GraphBody from '../frame/GraphBody.svelte';
+	import GraphRule from '../frame/GraphRule.svelte';
+	import { clamp01, trackMarks } from '../frame/glyphs';
+	import { isMonoPalette } from '../frame/tone';
+	import { reveal, stagger } from '../frame/motion';
+
+	let {
+		title,
+		data,
+		labels,
+		height = 7,
+		variant = 'area',
+		progress = 1,
+		glyphs,
+		palette,
+		corner,
+		class: className = ''
+	}: GraphPlotProps = $props();
+
+	const mono = $derived(isMonoPalette(palette));
+
+	function formatTick(value: number) {
+		if (Number.isInteger(value)) {
+			return String(value);
+		}
+
+		return value.toFixed(1);
+	}
+
+	const view = $derived.by(() => {
+		const max = Math.max(...data, 0);
+		const min = Math.min(0, ...data);
+		const range = max - min || 1;
+		const end = labels?.[labels.length - 1];
+		const start = labels?.[0];
+		const yLabel = formatTick(max);
+		const revealed = Math.round(clamp01(progress) * data.length);
+		const lastLive = Math.max(0, revealed - 1);
+		const marks = trackMarks(glyphs);
+		return { max, min, range, end, start, yLabel, revealed, lastLive, marks };
+	});
+</script>
+
+<Graph {title} {corner} class={className}>
+	<GraphBody>
+		<div class="wrap">
+			<div class="plotrow" style:--plot-h={height}>
+				<div class="yscale">
+					<span>{view.yLabel}</span>
+					<span>{formatTick(view.min)}</span>
+				</div>
+				<div class="plot" aria-hidden="true">
+					{#each data as value, column}
+						{@const level = Math.round(((value - view.min) / view.range) * (height - 1))}
+						{@const live = column === view.lastLive && column < view.revealed}
+						{@const shown = column < view.revealed}
+						<span class="col" use:reveal={{ delay: stagger(column, 40), amount: 0.4 }}>
+							{#each Array.from({ length: height }) as _, row}
+								{@const fromBottom = height - 1 - row}
+								{@const isCap = shown && fromBottom === level}
+								{@const isFill = shown && variant === 'area' && fromBottom < level}
+								<span
+									class="cellrow"
+									class:c-accent={isCap && live}
+									class:c-fg={isCap && !live}
+									class:c-accent2={isFill && !mono}
+									class:c-muted={isFill && mono}
+									class:transparent={!isCap && !isFill}
+								>
+									{isCap ? view.marks.fill : isFill ? view.marks.rest : ' '}
+								</span>
+							{/each}
+						</span>
+					{/each}
+				</div>
+			</div>
+			{#if view.start || view.end}
+				<div class="axisrow">
+					<span class="spacer" aria-hidden="true">{view.yLabel}</span>
+					<div class="rulewrap">
+						<GraphRule />
+					</div>
+				</div>
+				<div class="axisrow">
+					<span class="spacer" aria-hidden="true">{view.yLabel}</span>
+					<div class="axislabels">
+						<span>{view.start}</span>
+						{#if view.end && view.end !== view.start}
+							<span>{view.end}</span>
+						{/if}
+					</div>
+				</div>
+			{/if}
+			<span class="sr-only">
+				{variant} plot, {data.length} points, min {formatTick(view.min)}, max
+				{formatTick(view.max)}
+			</span>
+		</div>
+	</GraphBody>
+</Graph>
+
+<style>
+	.wrap {
+		display: flex;
+		flex-direction: column;
+		gap: 0.75rem;
+	}
+
+	.plotrow {
+		display: flex;
+		gap: 0.75rem;
+	}
+
+	.yscale {
+		display: flex;
+		width: 4ch;
+		flex-shrink: 0;
+		flex-direction: column;
+		align-items: flex-end;
+		justify-content: space-between;
+		padding: 1px 0;
+		height: calc(var(--plot-h, 7) * 1em);
+		text-align: right;
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	.plot {
+		display: flex;
+		min-width: 0;
+		align-items: flex-end;
+		justify-content: center;
+		gap: 0.125rem;
+		height: calc(var(--plot-h, 7) * 1em);
+		user-select: none;
+	}
+
+	.col {
+		display: flex;
+		height: 100%;
+		min-width: 1ch;
+		flex-direction: column;
+		justify-content: flex-end;
+	}
+
+	.cellrow {
+		width: 100%;
+		height: 1em;
+		text-align: center;
+	}
+
+	.transparent {
+		color: transparent;
+	}
+
+	.axisrow {
+		display: flex;
+		gap: 0.75rem;
+	}
+
+	.spacer {
+		width: 4ch;
+		flex-shrink: 0;
+		visibility: hidden;
+	}
+
+	.rulewrap {
+		flex: 1;
+		min-width: 0;
+	}
+
+	.axislabels {
+		display: flex;
+		flex: 1;
+		justify-content: space-between;
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	.c-accent {
+		color: var(--graph-accent, oklch(0.78 0.17 155));
+	}
+
+	.c-accent2 {
+		color: var(--graph-accent-2, oklch(0.78 0.12 70));
+	}
+
+	.c-muted {
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	.c-fg {
+		color: var(--graph-foreground, oklch(0.93 0 0));
+	}
+
+	.sr-only {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+		border-width: 0;
+	}
+</style>

package/dist/graphs/GraphPlot.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { Glyphs } from '../frame/glyphs';
+import type { GraphPalette } from '../frame/tone';
+/** Line or area plot drawn from columns of glyphs, with y-scale labels. */
+export interface GraphPlotProps {
+    title: string;
+    data: number[];
+    labels?: string[];
+    height?: number;
+    variant?: 'line' | 'area';
+    progress?: number;
+    glyphs?: Glyphs;
+    palette?: GraphPalette;
+    corner?: string;
+    class?: string;
+}
+declare const GraphPlot: import("svelte").Component<GraphPlotProps, {}, "">;
+type GraphPlot = ReturnType<typeof GraphPlot>;
+export default GraphPlot;

package/dist/graphs/GraphQuota.svelte

@@ -0,0 +1,303 @@
+<script module lang="ts">
+	/**
+	 * Quota usage bar: used against a hard limit, with reset date and an end-
+	 * of-window projection. Billing-style: surfaces the headline figure, the
+	 * "X of Y" copy, and pace so a customer can see whether they will run out.
+	 */
+	export interface GraphQuotaProps {
+		title: string;
+		used: number;
+		limit: number;
+		/** Unit label, e.g. "API calls" or "GB". */
+		unit?: string;
+		/** Optional reset label, e.g. "Oct 1" or "in 4 days". */
+		resets?: string;
+		/** Days elapsed in the current window. Enables the projection. */
+		daysInto?: number;
+		/** Window length in days. */
+		daysTotal?: number;
+		/** Optional number formatter. Defaults to thousands-grouped. */
+		format?: (n: number) => string;
+		/** Optional caption below the panel. */
+		caption?: string;
+		corner?: string;
+		class?: string;
+	}
+</script>
+
+<script lang="ts">
+	import Graph from '../frame/Graph.svelte';
+	import GraphBody from '../frame/GraphBody.svelte';
+	import GraphTrack from '../frame/GraphTrack.svelte';
+	import GraphTick from '../frame/GraphTick.svelte';
+	import { reveal, stagger } from '../frame/motion';
+	import { trackMarks } from '../frame/glyphs';
+
+	let {
+		title,
+		used,
+		limit,
+		unit,
+		resets,
+		daysInto,
+		daysTotal,
+		format,
+		caption,
+		corner,
+		class: className = ''
+	}: GraphQuotaProps = $props();
+
+	const ticks = 24;
+	const fmt = $derived(format ?? defaultFormat);
+
+	function defaultFormat(n: number): string {
+		if (!Number.isFinite(n)) {
+			return '0';
+		}
+		return Math.round(n).toLocaleString('en-US');
+	}
+
+	const view = $derived.by(() => {
+		const safeLimit = limit > 0 ? limit : 0;
+		const ratio = safeLimit > 0 ? Math.min(1, Math.max(0, used / safeLimit)) : 0;
+		const filled = Math.round(ratio * ticks);
+		const remaining = Math.max(0, safeLimit - used);
+		const percent = Math.round(ratio * 100);
+		const projection =
+			daysInto != null && daysTotal != null && daysInto > 0 && daysTotal > daysInto
+				? (used / daysInto) * daysTotal
+				: null;
+		const overBudget = projection != null && projection > safeLimit;
+		const projectedPct =
+			projection != null && safeLimit > 0 ? (projection / safeLimit) * 100 : null;
+		const daysLeft = daysTotal != null && daysInto != null ? Math.max(0, daysTotal - daysInto) : null;
+		const perDay = daysInto != null && daysInto > 0 ? used / daysInto : null;
+		const pace = projectedPct == null
+			? '—'
+			: overBudget
+				? 'over budget'
+				: projectedPct >= 95
+					? 'tight'
+					: projectedPct >= 75
+						? 'on track'
+						: 'ahead';
+		const willExceed = overBudget;
+		return {
+			ratio,
+			filled,
+			remaining,
+			percent,
+			projection,
+			projectedPct,
+			daysLeft,
+			perDay,
+			pace,
+			willExceed
+		};
+	});
+
+	const marks = $derived(trackMarks(undefined, { empty: '·', rest: '·', fill: '█' }));
+	const indexes = $derived(Array.from({ length: ticks }, (_, i) => i));
+</script>
+
+<Graph {title} {corner} class={className}>
+	<GraphBody>
+		<div class="quota" use:reveal={{ amount: 0.5 }}>
+			<p class="headline">
+				<span class="used" class:warn={view.willExceed}>{fmt(used)}</span>
+				<span class="of">/</span>
+				<span class="limit">{fmt(limit)}</span>
+				{#if unit}<span class="unit">{unit}</span>{/if}
+			</p>
+			<p class="bar">
+				<span class="brace" aria-hidden="true">[</span>
+				<GraphTrack>
+					{#each indexes as index, i (index)}
+						<GraphTick>
+							<span
+								class="g"
+								class:fill={index < view.filled}
+								class:warn={index < view.filled && view.willExceed}
+								use:reveal={{ delay: stagger(i, 14), amount: 0.4 }}
+							>
+								{index < view.filled ? marks.fill : marks.empty}
+							</span>
+						</GraphTick>
+					{/each}
+				</GraphTrack>
+				<span class="brace" aria-hidden="true">]</span>
+				<span class="pct" class:warn={view.willExceed}>{view.percent}%</span>
+			</p>
+			<dl class="rows">
+				{#if resets}
+					<div class="row">
+						<dt>resets</dt>
+						<dd>{resets}</dd>
+					</div>
+				{/if}
+				{#if view.daysLeft != null}
+					<div class="row">
+						<dt>days left</dt>
+						<dd>{view.daysLeft}{daysTotal != null ? ` / ${daysTotal}` : ''}</dd>
+					</div>
+				{/if}
+				{#if view.projection != null && view.projectedPct != null}
+					<div class="row">
+						<dt>projected</dt>
+						<dd class:warn={view.willExceed}>
+							{fmt(view.projection)} ({Math.round(view.projectedPct)}% of limit)
+						</dd>
+					</div>
+				{/if}
+				{#if view.perDay != null}
+					<div class="row">
+						<dt>avg / day</dt>
+						<dd>{fmt(view.perDay)}</dd>
+					</div>
+				{/if}
+				<div class="row">
+					<dt>pace</dt>
+					<dd class:warn={view.willExceed}>{view.pace}</dd>
+				</div>
+			</dl>
+			{#if view.willExceed}
+				<p class="flag">↗ projected to exceed the limit before reset</p>
+			{/if}
+			{#if caption}
+				<p class="muted">{caption}</p>
+			{/if}
+			<span class="sr-only">
+				Used {fmt(used)} of {fmt(limit)}{unit ? ` ${unit}` : ''}, {view.percent} percent of quota
+				{#if resets}, resets {resets}{/if}
+				{#if view.projection != null}, projected to use {fmt(view.projection)} by end of window{/if}.
+			</span>
+		</div>
+	</GraphBody>
+</Graph>
+
+<style>
+	.quota {
+		display: flex;
+		flex-direction: column;
+		gap: 0.85rem;
+	}
+
+	.headline {
+		display: flex;
+		flex-wrap: wrap;
+		justify-content: center;
+		align-items: baseline;
+		gap: 0.4rem;
+		margin: 0;
+		font-size: 1.4rem;
+		line-height: 1.1;
+		letter-spacing: -0.015em;
+	}
+
+	.used {
+		color: var(--graph-accent, oklch(0.78 0.17 155));
+	}
+
+	.used.warn {
+		color: var(--graph-accent-3, oklch(0.72 0.13 30));
+	}
+
+	.of {
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	.limit {
+		color: var(--graph-foreground, oklch(0.93 0 0));
+	}
+
+	.unit {
+		color: var(--graph-muted, oklch(0.62 0 0));
+		font-size: 0.95rem;
+	}
+
+	.bar {
+		display: flex;
+		width: 100%;
+		align-items: center;
+		column-gap: 0.75rem;
+		margin: 0;
+	}
+
+	.brace {
+		user-select: none;
+		color: var(--graph-frame, oklch(0.6 0 0 / 0.5));
+	}
+
+	.g {
+		color: var(--graph-frame, oklch(0.6 0 0 / 0.5));
+	}
+
+	.g.fill {
+		color: var(--graph-accent, oklch(0.78 0.17 155));
+	}
+
+	.g.fill.warn {
+		color: var(--graph-accent-3, oklch(0.72 0.13 30));
+	}
+
+	.pct {
+		width: 5ch;
+		flex-shrink: 0;
+		text-align: right;
+		color: var(--graph-accent, oklch(0.78 0.17 155));
+	}
+
+	.pct.warn {
+		color: var(--graph-accent-3, oklch(0.72 0.13 30));
+	}
+
+	.rows {
+		display: flex;
+		flex-wrap: wrap;
+		justify-content: center;
+		gap: 0.35rem 1.25rem;
+		margin: 0;
+	}
+
+	.row {
+		display: flex;
+		align-items: baseline;
+		gap: 0.4rem;
+	}
+
+	.row dt {
+		margin: 0;
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	.row dd {
+		margin: 0;
+	}
+
+	.warn {
+		color: var(--graph-accent-3, oklch(0.72 0.13 30));
+	}
+
+	.flag {
+		margin: 0;
+		text-align: center;
+		color: var(--graph-accent-3, oklch(0.72 0.13 30));
+	}
+
+	.muted {
+		margin: 0;
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+
+	.sr-only {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+		border-width: 0;
+	}
+</style>

package/dist/graphs/GraphQuota.svelte.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Quota usage bar: used against a hard limit, with reset date and an end-
+ * of-window projection. Billing-style: surfaces the headline figure, the
+ * "X of Y" copy, and pace so a customer can see whether they will run out.
+ */
+export interface GraphQuotaProps {
+    title: string;
+    used: number;
+    limit: number;
+    /** Unit label, e.g. "API calls" or "GB". */
+    unit?: string;
+    /** Optional reset label, e.g. "Oct 1" or "in 4 days". */
+    resets?: string;
+    /** Days elapsed in the current window. Enables the projection. */
+    daysInto?: number;
+    /** Window length in days. */
+    daysTotal?: number;
+    /** Optional number formatter. Defaults to thousands-grouped. */
+    format?: (n: number) => string;
+    /** Optional caption below the panel. */
+    caption?: string;
+    corner?: string;
+    class?: string;
+}
+declare const GraphQuota: import("svelte").Component<GraphQuotaProps, {}, "">;
+type GraphQuota = ReturnType<typeof GraphQuota>;
+export default GraphQuota;

package/dist/graphs/GraphRank.svelte

@@ -0,0 +1,141 @@
+<script module lang="ts">
+	import type { Glyphs } from '../frame/glyphs';
+	import type { GraphPalette } from '../frame/tone';
+
+	/** One ranked row: label, a full-width glyph bar, and the value. */
+	export interface RankItem {
+		label: string;
+		value: number;
+		display?: string;
+	}
+
+	export interface GraphRankProps {
+		title: string;
+		items: RankItem[];
+		max?: number;
+		ticks?: number;
+		glyphs?: Glyphs;
+		palette?: GraphPalette;
+		corner?: string;
+		class?: string;
+	}
+</script>
+
+<script lang="ts">
+	import Graph from '../frame/Graph.svelte';
+	import GraphBody from '../frame/GraphBody.svelte';
+	import GraphTrack from '../frame/GraphTrack.svelte';
+	import GraphTick from '../frame/GraphTick.svelte';
+	import { reveal, stagger } from '../frame/motion';
+	import { trackMarks } from '../frame/glyphs';
+
+	let {
+		title,
+		items,
+		max,
+		ticks = 20,
+		glyphs,
+		palette,
+		corner,
+		class: className = ''
+	}: GraphRankProps = $props();
+
+	const peak = $derived(max ?? Math.max(...items.map((entry) => entry.value), 1));
+	const marks = $derived(trackMarks(glyphs, { empty: '-', rest: '=', fill: '=' }));
+	const indexes = $derived(Array.from({ length: ticks }, (_, i) => i));
+
+	function filledCount(value: number): number {
+		return Math.min(ticks, Math.round((Math.max(value, 0) / peak) * ticks));
+	}
+
+	function formatValue(item: RankItem): string {
+		if (item.display) {
+			return item.display;
+		}
+
+		return item.value.toLocaleString('en-US', {
+			maximumFractionDigits: Number.isInteger(item.value) ? 0 : 1
+		});
+	}
+</script>
+
+<Graph {title} {corner} class={className}>
+	<GraphBody>
+		<ol class="rank" role="list">
+			{#each items as entry, index (entry.label)}
+				{@const filled = filledCount(entry.value)}
+				{@const shown = formatValue(entry)}
+				<li
+					class="row"
+					aria-label="{entry.label} {shown}"
+					use:reveal={{ delay: stagger(index, 50), amount: 0.4 }}
+				>
+					<span class="label">{entry.label}</span>
+					<span class="mid">
+						<span class="brace" aria-hidden="true">[</span>
+						<GraphTrack>
+							{#each indexes as tick (tick)}
+								<GraphTick>
+									<span class="g" class:fill={tick < filled}>
+										{tick < filled ? marks.fill : marks.empty}
+									</span>
+								</GraphTick>
+							{/each}
+						</GraphTrack>
+						<span class="brace" aria-hidden="true">]</span>
+					</span>
+					<span class="value">{shown}</span>
+				</li>
+			{/each}
+		</ol>
+	</GraphBody>
+</Graph>
+
+<style>
+	.rank {
+		display: flex;
+		width: 100%;
+		flex-direction: column;
+		gap: 0.5rem;
+		margin: 0;
+		padding: 0;
+		list-style: none;
+	}
+
+	.row {
+		display: grid;
+		grid-template-columns: 7rem minmax(0, 1fr) 7rem;
+		align-items: center;
+		column-gap: 1rem;
+	}
+
+	.label {
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.mid {
+		display: flex;
+		min-width: 0;
+		align-items: center;
+	}
+
+	.brace {
+		user-select: none;
+		color: var(--graph-frame, oklch(0.6 0 0 / 0.5));
+	}
+
+	.g {
+		color: var(--graph-frame, oklch(0.6 0 0 / 0.5));
+	}
+
+	.g.fill {
+		color: var(--graph-accent, oklch(0.78 0.17 155));
+	}
+
+	.value {
+		text-align: right;
+		color: var(--graph-muted, oklch(0.62 0 0));
+	}
+</style>