@siyahi/ui 0.1.9-next.3 → 0.1.9-next.30

package/dist/components/siyahi/delta.js

@@ -1,24 +1,29 @@
 import { useFormat } from "../../lib/format.js";
 import { cn } from "cn";
+import { MinusIcon, TrendingDownIcon, TrendingUpIcon } from "lucide-react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/siyahi/delta.tsx
-/** A signed figure: ▲ in --positive, ▼ in --negative, so colour is never the only cue. */
+const MINUS = "−";
+/**
+* A signed change: the figure in the surrounding text colour with its sign, and a trend icon in --positive or
+* --negative. The sign and the icon's shape carry the direction, so colour is never the only cue, and a column of
+* changes reads as figures rather than a wall of red and green.
+*/
 function Delta({ value, format = "pct", className }) {
 	const f = useFormat();
 	const size = format === "money" ? f.money(Math.abs(value)) : f.pct(Math.abs(value));
-	const direction = value > 0 ? "up" : value < 0 ? "down" : null;
+	const direction = value > 0 ? "up" : value < 0 ? "down" : "none";
+	const Icon = direction === "up" ? TrendingUpIcon : direction === "down" ? TrendingDownIcon : MinusIcon;
 	return /* @__PURE__ */ jsxs("span", {
 		"data-slot": "delta",
-		className: cn("inline-flex items-center gap-1 tabular-nums", direction === "up" && "text-positive", direction === "down" && "text-negative", direction === null && "text-muted-foreground", className),
+		"data-direction": direction,
+		className: cn("inline-flex items-baseline gap-1 whitespace-nowrap", className),
 		children: [
-			direction && /* @__PURE__ */ jsx("span", {
+			/* @__PURE__ */ jsx(Icon, {
 				"aria-hidden": "true",
-				children: direction === "up" ? "▲" : "▼"
-			}),
-			direction && /* @__PURE__ */ jsx("span", {
-				className: "sr-only",
-				children: direction
+				className: cn("size-3.5 shrink-0 self-center", direction === "up" && "text-positive", direction === "down" && "text-negative", direction === "none" && "text-muted-foreground")
 			}),
+			direction === "up" ? "+" : direction === "down" ? MINUS : "",
 			size
 		]
 	});

package/dist/components/siyahi/drawdown-chart.d.ts

@@ -0,0 +1,34 @@
+import { NumericKey, SeriesChartProps } from "../../lib/chart-series.js";
+//#region src/components/siyahi/drawdown-chart.d.ts
+/** One point as drawn: how far the level sits below the highest it had reached, and that high. */
+export interface DrawdownPoint<X> {
+  x: X;
+  /** The fall from the peak as a fraction, 0 at a new high and −0.25 a quarter below it; null when the level is unknown. */
+  drawdown: number | null;
+  /** The highest level so far. */
+  peak: number;
+  level: number | null;
+}
+/**
+ * Walks the levels in order, keeping the highest so far. A level that is not a finite number has no drawdown and
+ * leaves the peak as it was; the first level is the first peak.
+ */
+export declare function drawdowns<X>(levels: readonly {
+  x: X;
+  level: number | null;
+}[]): DrawdownPoint<X>[];
+export interface DrawdownChartCardProps<T extends object, K extends keyof T> extends Pick<SeriesChartProps<T, K>, "title" | "description" | "action" | "data" | "xKey" | "height" | "xFormatter" | "xTooltipFormatter" | "xTicks" | "placeholder" | "footer"> {
+  /** The field holding the level, such as the day's cash balance or a fund's value. */
+  levelKey: NumericKey<T>;
+  /** Writes the level and the peak in the tooltip. Defaults to useFormat().money. */
+  levelFormatter?: (value: number) => string;
+  /** Names the fall in the legend and tooltip. */
+  label?: string;
+}
+/**
+ * How far a level sits below the highest it had reached, over time: a fund's or a cash balance's fall from its
+ * peak. The area hangs from zero in the loss colour, so the deepest and longest falls read at once, and a dashed
+ * line marks the deepest one. Levels must be above zero: a fall is a share of the peak.
+ */
+export declare function DrawdownChartCard<T extends object, K extends keyof T>({ data, xKey, levelKey, levelFormatter, label, xFormatter, xTooltipFormatter, xTicks, ...props }: DrawdownChartCardProps<T, K>): import("react").JSX.Element;
+//#endregion

package/dist/components/siyahi/drawdown-chart.js

@@ -0,0 +1,102 @@
+import { linearTicks } from "../../lib/ticks.js";
+import { ChartFrame } from "../../lib/chart-frame.js";
+import { useFormat } from "../../lib/format.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { Area, AreaChart } from "recharts";
+//#region src/components/siyahi/drawdown-chart.tsx
+/**
+* Walks the levels in order, keeping the highest so far. A level that is not a finite number has no drawdown and
+* leaves the peak as it was; the first level is the first peak.
+*/
+function drawdowns(levels) {
+	let peak = Number.NEGATIVE_INFINITY;
+	return levels.map(({ x, level }) => {
+		if (level === null || !Number.isFinite(level)) return {
+			x,
+			level: null,
+			drawdown: null,
+			peak
+		};
+		peak = Math.max(peak, level);
+		return {
+			x,
+			level,
+			peak,
+			drawdown: peak > 0 ? level / peak - 1 : 0
+		};
+	});
+}
+/**
+* How far a level sits below the highest it had reached, over time: a fund's or a cash balance's fall from its
+* peak. The area hangs from zero in the loss colour, so the deepest and longest falls read at once, and a dashed
+* line marks the deepest one. Levels must be above zero: a fall is a share of the peak.
+*/
+function DrawdownChartCard({ data, xKey, levelKey, levelFormatter, label = "Below peak", xFormatter = String, xTooltipFormatter, xTicks, ...props }) {
+	const f = useFormat();
+	const formatLevel = levelFormatter ?? ((value) => f.money(value));
+	const points = useMemo(() => drawdowns(data.map((row) => ({
+		x: row[xKey],
+		level: row[levelKey]
+	}))), [
+		data,
+		xKey,
+		levelKey
+	]);
+	const fall = (value) => value < 0 ? `−${f.pct(-value)}` : f.pct(0);
+	const deepest = Math.min(0, ...points.flatMap(({ drawdown }) => drawdown ?? []));
+	const ticks = linearTicks(Math.min(deepest, -.01), 0);
+	return /* @__PURE__ */ jsx(ChartFrame, {
+		chart: AreaChart,
+		...props,
+		data: points,
+		xKey: "x",
+		xFormatter: (x) => xFormatter(x),
+		xTooltipFormatter: (x) => (xTooltipFormatter ?? xFormatter)(x),
+		xTicks,
+		series: [{
+			key: "drawdown",
+			label,
+			color: "var(--negative)"
+		}],
+		yDomain: [Math.min(deepest, ticks[0] ?? deepest), 0],
+		yTicks: ticks,
+		yTickFormatter: (value) => fall(value),
+		referenceLines: deepest < 0 ? [{
+			y: deepest,
+			label: `Deepest ${fall(deepest)}`,
+			labelPosition: "insideBottomRight"
+		}] : [],
+		tooltipRow: (_value, _name, item) => {
+			const point = item.payload;
+			return (point.drawdown === null ? [[label, "—"]] : [
+				[label, fall(point.drawdown)],
+				["Level", formatLevel(point.level ?? 0)],
+				["Peak so far", formatLevel(point.peak)]
+			]).map(([name, figure]) => /* @__PURE__ */ jsxs("div", {
+				className: "flex w-full items-center gap-2",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "text-muted-foreground",
+					children: name
+				}), /* @__PURE__ */ jsx("span", {
+					className: "ml-auto font-mono font-medium text-foreground tabular-nums",
+					children: figure
+				})]
+			}, name));
+		},
+		children: /* @__PURE__ */ jsx(Area, {
+			dataKey: "drawdown",
+			name: label,
+			type: "linear",
+			baseValue: 0,
+			stroke: "var(--negative)",
+			strokeWidth: 2,
+			fill: "color-mix(in oklab, var(--negative) 25%, var(--card))",
+			fillOpacity: 1,
+			dot: false,
+			connectNulls: false
+		})
+	});
+}
+//#endregion
+export { DrawdownChartCard, drawdowns };

package/dist/components/siyahi/histogram-chart.d.ts

@@ -0,0 +1,57 @@
+import { ChartReferenceLine, SeriesChartProps } from "../../lib/chart-series.js";
+//#region src/components/siyahi/histogram-chart.d.ts
+/** One bucket: the values from `from` up to, not including, `to`; the last bucket takes its upper edge too. */
+export interface HistogramBin {
+  key: string;
+  from: number;
+  to: number;
+  count: number;
+}
+/**
+ * Buckets of one round width (1, 2, 2.5 or 5 × 10ⁿ) covering the values, about `target` of them. Values that are not
+ * finite numbers are left out.
+ */
+export declare function histogram(values: readonly number[], target?: number): HistogramBin[];
+/**
+ * The bucket a value falls in, read against the buckets' own edges: dividing by the width instead put 0.3 in the
+ * 0.2–0.3 bucket, as 0.3 / 0.1 is 2.9999999999999996. A value past the last edge belongs to the last bucket.
+ */
+export declare function bucketOf(bins: readonly HistogramBin[], value: number): number;
+/** The value below which `share` of the values fall, interpolating between the two nearest, as spreadsheets do. */
+export declare function percentile(values: readonly number[], share: number): number | null;
+declare const MARKS: {
+  readonly median: 0.5;
+  readonly p90: 0.9;
+  readonly p95: 0.95;
+  readonly p99: 0.99;
+};
+export type HistogramMark = keyof typeof MARKS;
+/**
+ * One line per bucket that holds a mark, named by its marks: marks that share a bucket share a line and a name,
+ * "median, p90", rather than drawing over each other.
+ */
+export declare function markLines(bins: readonly HistogramBin[], marked: readonly {
+  mark: HistogramMark;
+  value: number;
+}[]): ChartReferenceLine[];
+export interface HistogramChartCardProps extends Pick<SeriesChartProps<HistogramBin, "key">, "title" | "description" | "action" | "height" | "xLabel" | "yLabel" | "placeholder" | "footer"> {
+  /** The raw values, one per item, such as each request's response time. */
+  values: readonly number[];
+  /** About how many buckets; the width is rounded, so the count varies a little. */
+  bins?: number;
+  /** Writes the bucket edges and the marks, such as (v) => `${v} ms`. Defaults to the locale's numbers. */
+  valueFormatter?: (value: number) => string;
+  /** The bucket edges under the axis, when they should be shorter than valueFormatter: 1,000 against 1,000 ms. */
+  tickFormatter?: (value: number) => string;
+  /** What is counted, in the legend and tooltip, such as "Requests". */
+  countLabel?: string;
+  /** Percentiles to mark with a line at their bucket; their exact values are written under the chart. */
+  marks?: readonly HistogramMark[];
+}
+/**
+ * How values spread: counts in buckets of one round width, such as response times by 50 ms, with the median or a
+ * high percentile marked. The page gives the raw values; the card buckets them.
+ */
+export declare function HistogramChartCard({ values, bins: target, valueFormatter, tickFormatter, countLabel, marks, ...props }: HistogramChartCardProps): import("react").JSX.Element;
+//#endregion
+export {};

package/dist/components/siyahi/histogram-chart.js

@@ -0,0 +1,134 @@
+import { useLocale } from "./siyahi-provider.js";
+import { linearTicks } from "../../lib/ticks.js";
+import { ChartFrame, barFill } from "../../lib/chart-frame.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { Bar, BarChart, Cell } from "recharts";
+//#region src/components/siyahi/histogram-chart.tsx
+/**
+* Buckets of one round width (1, 2, 2.5 or 5 × 10ⁿ) covering the values, about `target` of them. Values that are not
+* finite numbers are left out.
+*/
+function histogram(values, target = 12) {
+	const known = values.filter(Number.isFinite);
+	if (known.length === 0) return [];
+	let low = known[0];
+	let high = low;
+	for (const value of known) {
+		low = Math.min(low, value);
+		high = Math.max(high, value);
+	}
+	const edges = linearTicks(low, high, target + 1);
+	if (edges.length < 2) return [{
+		key: "0",
+		from: low,
+		to: high,
+		count: known.length
+	}];
+	const bins = edges.slice(0, -1).map((from, i) => ({
+		key: String(i),
+		from,
+		to: edges[i + 1],
+		count: 0
+	}));
+	for (const value of known) bins[bucketOf(bins, value)].count += 1;
+	return bins;
+}
+/**
+* The bucket a value falls in, read against the buckets' own edges: dividing by the width instead put 0.3 in the
+* 0.2–0.3 bucket, as 0.3 / 0.1 is 2.9999999999999996. A value past the last edge belongs to the last bucket.
+*/
+function bucketOf(bins, value) {
+	const index = bins.findIndex((bin) => value < bin.to);
+	return index === -1 ? bins.length - 1 : index;
+}
+/** The value below which `share` of the values fall, interpolating between the two nearest, as spreadsheets do. */
+function percentile(values, share) {
+	const sorted = values.filter(Number.isFinite).toSorted((a, b) => a - b);
+	if (sorted.length === 0) return null;
+	const at = (sorted.length - 1) * share;
+	const low = Math.floor(at);
+	return sorted[low] + (sorted[Math.ceil(at)] - sorted[low]) * (at - low);
+}
+const MARKS = {
+	median: .5,
+	p90: .9,
+	p95: .95,
+	p99: .99
+};
+/**
+* One line per bucket that holds a mark, named by its marks: marks that share a bucket share a line and a name,
+* "median, p90", rather than drawing over each other.
+*/
+function markLines(bins, marked) {
+	return [...Map.groupBy(marked, ({ value }) => bucketOf(bins, value))].flatMap(([index, group]) => {
+		const bin = bins[index];
+		if (!bin) return [];
+		const right = index >= bins.length / 2;
+		const label = group.map(({ mark }) => mark).join(", ");
+		return [{
+			x: bin.key,
+			label,
+			emphasis: "strong",
+			labelPosition: right ? "insideTopRight" : "insideTopLeft"
+		}];
+	});
+}
+const NO_MARKS = [];
+/**
+* How values spread: counts in buckets of one round width, such as response times by 50 ms, with the median or a
+* high percentile marked. The page gives the raw values; the card buckets them.
+*/
+function HistogramChartCard({ values, bins: target = 12, valueFormatter, tickFormatter, countLabel = "Count", marks = NO_MARKS, ...props }) {
+	const { numberLocale } = useLocale();
+	const format = valueFormatter ?? new Intl.NumberFormat(numberLocale).format;
+	const bins = useMemo(() => histogram(values, target), [values, target]);
+	const range = (bin) => `${format(bin.from)}–${format(bin.to)}`;
+	const names = new Map(bins.map((bin) => [bin.key, bin]));
+	const marked = marks.flatMap((mark) => {
+		const value = percentile(values, MARKS[mark]);
+		return value === null ? [] : [{
+			mark,
+			value
+		}];
+	});
+	const lines = markLines(bins, marked);
+	return /* @__PURE__ */ jsx(ChartFrame, {
+		chart: BarChart,
+		...props,
+		data: bins,
+		xKey: "key",
+		xFormatter: (key) => {
+			const bin = names.get(key);
+			return bin ? (tickFormatter ?? format)(bin.from) : key;
+		},
+		xTooltipFormatter: (key) => {
+			const bin = names.get(key);
+			return bin ? range(bin) : key;
+		},
+		series: [{
+			key: "count",
+			label: countLabel,
+			color: "var(--chart-1)"
+		}],
+		referenceLines: lines,
+		footer: marked.length > 0 || props.footer ? /* @__PURE__ */ jsxs(Fragment, { children: [marked.length > 0 && /* @__PURE__ */ jsx("p", {
+			"data-slot": "histogram-marks",
+			className: "tabular-nums",
+			children: marked.map(({ mark, value }) => `${mark} ${format(value)}`).join(" · ")
+		}), props.footer] }) : void 0,
+		children: /* @__PURE__ */ jsx(Bar, {
+			dataKey: "count",
+			name: countLabel,
+			fill: "var(--chart-1)",
+			isAnimationActive: false,
+			children: bins.map((bin) => /* @__PURE__ */ jsx(Cell, {
+				fill: barFill("var(--chart-1)"),
+				stroke: "var(--chart-1)",
+				strokeWidth: 1
+			}, bin.key))
+		})
+	});
+}
+//#endregion
+export { HistogramChartCard, bucketOf, histogram, markLines, percentile };

package/dist/components/siyahi/page-hero.d.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from "react";
+//#region src/components/siyahi/page-hero.d.ts
+export interface PageHeroProps {
+  /** A short line above the title in the mono face and the link colour, such as the app or a section name. */
+  eyebrow?: ReactNode;
+  /** The page's h1. */
+  title: ReactNode;
+  /** What the page is, in a sentence, in the muted colour. */
+  lead?: ReactNode;
+  /** Scope, sources or what is left out, run on after the lead in the same muted line. */
+  detail?: ReactNode;
+  /** The one or two places a reader goes next, usually a primary Button and an outline one, at the right. */
+  actions?: ReactNode;
+  /** A small mark before the eyebrow, such as the product's logo as an SVG that paints with currentColor. */
+  mark?: ReactNode;
+}
+/**
+ * The masthead at the top of a page: a small mark and eyebrow, the title, one muted line saying what the page is,
+ * the actions at the right, and a hairline under it all. One per page, above everything else; a section uses
+ * PageSection.
+ */
+export declare function PageHero({ eyebrow, title, lead, detail, actions, mark }: PageHeroProps): import("react").JSX.Element;
+//#endregion

package/dist/components/siyahi/page-hero.js

@@ -0,0 +1,43 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/siyahi/page-hero.tsx
+/**
+* The masthead at the top of a page: a small mark and eyebrow, the title, one muted line saying what the page is,
+* the actions at the right, and a hairline under it all. One per page, above everything else; a section uses
+* PageSection.
+*/
+function PageHero({ eyebrow, title, lead, detail, actions, mark }) {
+	return /* @__PURE__ */ jsxs("header", {
+		"data-slot": "page-hero",
+		className: "flex flex-wrap items-end justify-between gap-x-6 gap-y-3 border-b pb-4",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex min-w-0 flex-col gap-1",
+			children: [
+				(mark || eyebrow) && /* @__PURE__ */ jsxs("p", {
+					className: "flex items-center gap-1.5 font-mono text-xs text-link",
+					children: [mark && /* @__PURE__ */ jsx("span", {
+						"aria-hidden": true,
+						className: "size-3.5 shrink-0 [&>svg]:size-full",
+						children: mark
+					}), eyebrow]
+				}),
+				/* @__PURE__ */ jsx("h1", {
+					className: "text-3xl font-semibold tracking-tight text-balance",
+					children: title
+				}),
+				(lead || detail) && /* @__PURE__ */ jsxs("div", {
+					className: "text-sm text-pretty text-muted-foreground",
+					children: [
+						lead,
+						lead && detail && " ",
+						detail
+					]
+				})
+			]
+		}), actions && /* @__PURE__ */ jsx("div", {
+			className: "flex flex-wrap gap-2",
+			children: actions
+		})]
+	});
+}
+//#endregion
+export { PageHero };

package/dist/components/siyahi/page-section.d.ts

@@ -12,7 +12,10 @@ export interface PageSectionProps {
   action?: ReactNode;
   children?: ReactNode;
 }
-/** One part of a long page: a rule above, then the heading and lead on the canvas, then its content. */
+/**
+ * One part of a long page: a rule above, then the heading and lead on the canvas, then its content. Spaced for
+ * density, 24px under the rule and 16px to the content, so sections stacked 24px apart sit 24px either side of it.
+ */
 export declare function PageSection({ id, eyebrow, title, lead, action, children }: PageSectionProps): import("react").JSX.Element;
 /** A heading inside a PageSection, one level under its title. */
 export declare function PageSubheading({ children }: {

package/dist/components/siyahi/page-section.js

@@ -1,11 +1,14 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/siyahi/page-section.tsx
-/** One part of a long page: a rule above, then the heading and lead on the canvas, then its content. */
+/**
+* One part of a long page: a rule above, then the heading and lead on the canvas, then its content. Spaced for
+* density, 24px under the rule and 16px to the content, so sections stacked 24px apart sit 24px either side of it.
+*/
 function PageSection({ id, eyebrow, title, lead, action, children }) {
 	return /* @__PURE__ */ jsxs("section", {
 		id,
 		"data-slot": "page-section",
-		className: "flex scroll-mt-6 flex-col gap-6 border-t pt-10",
+		className: "flex scroll-mt-6 flex-col gap-4 border-t pt-6",
 		children: [/* @__PURE__ */ jsxs("div", {
 			className: "flex flex-wrap items-end justify-between gap-4",
 			children: [/* @__PURE__ */ jsxs("div", {
@@ -16,7 +19,7 @@ function PageSection({ id, eyebrow, title, lead, action, children }) {
 						children: eyebrow
 					}),
 					/* @__PURE__ */ jsx("h2", {
-						className: "text-2xl font-semibold tracking-tight",
+						className: "text-xl font-semibold tracking-tight",
 						children: title
 					}),
 					lead && /* @__PURE__ */ jsx("div", {

package/dist/components/siyahi/page-toc.d.ts

@@ -0,0 +1,20 @@
+//#region src/components/siyahi/page-toc.d.ts
+export interface PageTocItem {
+  /** The `id` of the PageSection it jumps to. */
+  id: string;
+  title: string;
+}
+export interface PageTocProps {
+  items: PageTocItem[];
+  /** Names the navigation for screen readers. */
+  label?: string;
+  /** Layout only, such as `top-14` under a sticky page header. */
+  className?: string;
+}
+/**
+ * A long page's sections as one sticky "On this page" index. It stays at the top while the reader scrolls,
+ * underlines the section in view in the link colour, and scrolls sideways on a phone with the current link kept
+ * in sight.
+ */
+export declare function PageToc({ items, label, className }: PageTocProps): import("react").JSX.Element;
+//#endregion

package/dist/components/siyahi/page-toc.js

@@ -0,0 +1,76 @@
+import { cn } from "cn";
+import { ChevronRightIcon } from "lucide-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+//#region src/components/siyahi/page-toc.tsx
+/**
+* A long page's sections as one sticky "On this page" index. It stays at the top while the reader scrolls,
+* underlines the section in view in the link colour, and scrolls sideways on a phone with the current link kept
+* in sight.
+*/
+function PageToc({ items, label = "On this page", className }) {
+	const nav = useRef(null);
+	const active = useActiveSection(items, nav);
+	const strip = useRef(null);
+	useEffect(() => {
+		const link = strip.current?.querySelector(`a[href="#${CSS.escape(active ?? "")}"]`);
+		const box = strip.current;
+		if (!link || !box) return;
+		const left = link.offsetLeft - box.clientWidth / 2 + link.offsetWidth / 2;
+		box.scrollTo({
+			left,
+			behavior: "smooth"
+		});
+	}, [active]);
+	return /* @__PURE__ */ jsx("nav", {
+		ref: nav,
+		"aria-label": label,
+		"data-slot": "page-toc",
+		className: cn("sticky top-0 z-10 -mx-4 border-b bg-background px-4 sm:mx-0 sm:px-0", className),
+		children: /* @__PURE__ */ jsxs("div", {
+			ref: strip,
+			className: "flex items-baseline gap-x-4 overflow-x-auto py-2.5 mask-r-from-90% [scrollbar-width:none] sm:mask-none",
+			children: [/* @__PURE__ */ jsxs("span", {
+				"aria-hidden": true,
+				className: "flex shrink-0 cursor-default items-center gap-1 self-center text-[0.6875rem] font-medium tracking-wider text-muted-foreground uppercase select-none",
+				children: [label, /* @__PURE__ */ jsx(ChevronRightIcon, { className: "size-3.5" })]
+			}), items.map((item) => /* @__PURE__ */ jsx("a", {
+				href: `#${item.id}`,
+				"aria-current": item.id === active ? "location" : void 0,
+				onClick: (event) => {
+					event.preventDefault();
+					document.getElementById(item.id)?.scrollIntoView({ behavior: "smooth" });
+				},
+				className: "shrink-0 text-sm whitespace-nowrap text-muted-foreground decoration-2 underline-offset-[6px] transition-colors hover:text-foreground hover:underline hover:decoration-border aria-[current=location]:font-medium aria-[current=location]:text-link aria-[current=location]:underline aria-[current=location]:decoration-current",
+				children: item.title
+			}, item.id))]
+		})
+	});
+}
+function useActiveSection(items, strip) {
+	const [active, setActive] = useState(items[0]?.id);
+	const ids = items.map((item) => item.id).join(" ");
+	useEffect(() => {
+		const sections = ids.split(" ").flatMap((id) => document.getElementById(id) ?? []);
+		if (sections.length === 0) return;
+		const update = () => {
+			const stripBottom = strip.current?.getBoundingClientRect().bottom ?? 0;
+			const line = (section) => Math.max(stripBottom, Number.parseFloat(getComputedStyle(section).scrollMarginTop) || 0, innerHeight * .3);
+			const reached = sections.filter((section) => section.getBoundingClientRect().top <= line(section) + 1);
+			setActive((reached.at(-1) ?? sections[0]).id);
+		};
+		update();
+		addEventListener("scroll", update, {
+			passive: true,
+			capture: true
+		});
+		addEventListener("resize", update);
+		return () => {
+			removeEventListener("scroll", update, { capture: true });
+			removeEventListener("resize", update);
+		};
+	}, [ids, strip]);
+	return active;
+}
+//#endregion
+export { PageToc };

package/dist/components/siyahi/panel-grid.d.ts

@@ -0,0 +1,24 @@
+import { ReactNode } from "react";
+//#region src/components/siyahi/panel-grid.d.ts
+declare const COLUMNS: {
+  readonly 1: "";
+  readonly 2: "@2xl/panels:grid-cols-2";
+  readonly 3: "@2xl/panels:grid-cols-2 @5xl/panels:grid-cols-3";
+  readonly 4: "@2xl/panels:grid-cols-2 @5xl/panels:grid-cols-4";
+};
+export interface PanelGridProps {
+  /** Blocks across on a wide page; two on a medium one, and one on a phone. */
+  columns?: keyof typeof COLUMNS;
+  children: ReactNode;
+  className?: string;
+}
+/**
+ * Data blocks side by side: chart cards, tables, a MetricStrip. On a ruled surface, the default, the grid is filled
+ * with the card colour and a hairline parts the blocks across and down, with a rule above and below the grid and none
+ * on its sides; open leaves whitespace between them, and card an 8px gap between boxes. Each block's bottom and end
+ * edges carry its rules and the grid clips the ones on its own edges, so an empty cell at the end of a short last row
+ * is a blank stretch of the sheet, ruled off like the rest. The theme numbers each block's card title 01, 02.
+ */
+export declare function PanelGrid({ columns, children, className }: PanelGridProps): import("react").JSX.Element;
+//#endregion
+export {};

package/dist/components/siyahi/panel-grid.js

@@ -0,0 +1,37 @@
+import { useSurface } from "./siyahi-provider.js";
+import { cn } from "cn";
+import { jsx } from "react/jsx-runtime";
+import { Children } from "react";
+//#region src/components/siyahi/panel-grid.tsx
+const COLUMNS = {
+	1: "",
+	2: "@2xl/panels:grid-cols-2",
+	3: "@2xl/panels:grid-cols-2 @5xl/panels:grid-cols-3",
+	4: "@2xl/panels:grid-cols-2 @5xl/panels:grid-cols-4"
+};
+/**
+* Data blocks side by side: chart cards, tables, a MetricStrip. On a ruled surface, the default, the grid is filled
+* with the card colour and a hairline parts the blocks across and down, with a rule above and below the grid and none
+* on its sides; open leaves whitespace between them, and card an 8px gap between boxes. Each block's bottom and end
+* edges carry its rules and the grid clips the ones on its own edges, so an empty cell at the end of a short last row
+* is a blank stretch of the sheet, ruled off like the rest. The theme numbers each block's card title 01, 02.
+*/
+function PanelGrid({ columns = 2, children, className }) {
+	const surface = useSurface();
+	const ruled = surface === "ruled";
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "panel-grid",
+		"data-surface": surface,
+		className: cn("@container/panels", ruled && "overflow-clip border-y", className),
+		children: /* @__PURE__ */ jsx("div", {
+			className: cn("grid grid-cols-1", COLUMNS[columns], ruled ? "-me-px -mb-px bg-card" : surface === "open" ? "gap-x-8 gap-y-6" : "gap-2"),
+			children: Children.map(children, (child) => /* @__PURE__ */ jsx("div", {
+				"data-slot": "panel",
+				className: cn("min-w-0", ruled && "border-e border-b"),
+				children: child
+			}))
+		})
+	});
+}
+//#endregion
+export { PanelGrid };

package/dist/components/siyahi/quote.d.ts

@@ -0,0 +1,12 @@
+import { ComponentProps, ReactNode } from "react";
+//#region src/components/siyahi/quote.d.ts
+export interface QuoteProps extends ComponentProps<"blockquote"> {
+  /** Who said it, or where it is from, set under the quote. */
+  source?: ReactNode;
+}
+/**
+ * A quotation set apart from the prose on a muted panel, with its source under it. The panel is the whole box, not a
+ * stripe down one side.
+ */
+export declare function Quote({ source, className, children, ...props }: QuoteProps): import("react").JSX.Element;
+//#endregion