@karimsa/mdxserve 0.2.0 → 0.4.0

package/client/data-table/TableCell.tsx

@@ -0,0 +1,76 @@
+import type { Dispatch, ReactNode, RefObject, SetStateAction } from "react";
+import { formatValue, type Column, type Row } from "./model";
+import { navigateTable } from "./navigation";
+import type { ActiveCell, VisibleRow } from "./table-state";
+
+interface TableCellProps {
+	column: Column;
+	columnIndex: number;
+	columnCount: number;
+	row: Row;
+	index: number;
+	rowIndex: number;
+	rows: VisibleRow[];
+	unit: string;
+	limits?: number[];
+	active: ActiveCell;
+	setActive: Dispatch<SetStateAction<ActiveCell>>;
+	tableRef: RefObject<HTMLTableElement | null>;
+	renderCell?: (row: number, key: string) => ReactNode;
+}
+
+export function TableCell({
+	column,
+	columnIndex,
+	columnCount,
+	row,
+	index,
+	rowIndex,
+	rows,
+	unit,
+	limits,
+	active,
+	setActive,
+	tableRef,
+	renderCell,
+}: TableCellProps) {
+	const value = row[column.key] ?? null;
+	const span = limits ? limits[1] - limits[0] : 0;
+	const selected = active?.row === index && active.column === columnIndex;
+
+	return (
+		<td
+			key={column.key}
+			data-row={index}
+			data-column={columnIndex}
+			data-numeric={column.type !== "text"}
+			data-align={column.align ?? (column.type === "text" ? "left" : "right")}
+			data-active={selected}
+			data-bars={Boolean(limits)}
+			tabIndex={selected ? 0 : -1}
+			onFocus={() => setActive({ row: index, column: columnIndex })}
+			onClick={(event) => {
+				setActive({ row: index, column: columnIndex });
+				if (!(event.target as HTMLElement).closest("a,button,input,select"))
+					event.currentTarget.focus();
+			}}
+			onKeyDown={(event) =>
+				navigateTable(event, rowIndex, columnIndex, rows, columnCount, tableRef.current)
+			}
+		>
+			{limits && typeof value === "number" && span > 0 && (
+				<span
+					className="data-table-bar"
+					aria-hidden="true"
+					style={{
+						left: `calc(16px + (100% - 32px) * ${(Math.min(0, value) - limits[0]) / span})`,
+						width: `calc((100% - 32px) * ${Math.abs(value) / span})`,
+					}}
+				/>
+			)}
+			<span className="data-table-value">
+				{renderCell?.(index, column.key) ?? formatValue(value, column, unit)}
+			</span>
+		</td>
+	);
+}

package/client/data-table/TableHeaderCell.tsx

@@ -0,0 +1,94 @@
+import type { Dispatch, ReactNode, RefObject, SetStateAction } from "react";
+import { ColumnOptions } from "./ColumnOptions";
+import { ColumnMenu } from "./ColumnMenu";
+import { type Column, type Row, type TableState } from "./model";
+import { cycleSort, hasFilter, type ActiveCell, type VisibleRow } from "./table-state";
+import { navigateTable } from "./navigation";
+
+export interface TableHeaderCellProps {
+	renderHeader?: (key: string) => ReactNode;
+	column: Column;
+	columnIndex: number;
+	rowSpan?: number;
+	columnCount: number;
+	data: Row[];
+	rows: VisibleRow[];
+	state: TableState;
+	setState: Dispatch<SetStateAction<TableState>>;
+	units: Record<string, string>;
+	errors: Record<string, string>;
+	active: ActiveCell;
+	activeVisible: boolean;
+	setActive: Dispatch<SetStateAction<ActiveCell>>;
+	openColumn: string | null;
+	setOpenColumn: Dispatch<SetStateAction<string | null>>;
+	tableRef: RefObject<HTMLTableElement | null>;
+}
+
+export function TableHeaderCell({
+	renderHeader,
+	column,
+	columnIndex,
+	rowSpan = 1,
+	columnCount,
+	data,
+	rows,
+	state,
+	setState,
+	units,
+	errors,
+	active,
+	activeVisible,
+	setActive,
+	openColumn,
+	setOpenColumn,
+	tableRef,
+}: TableHeaderCellProps) {
+	const filtered = hasFilter(state.filters[column.key]);
+	const sorted = state.sort?.key === column.key;
+	const selected = active?.row === -1 && active.column === columnIndex;
+
+	return (
+		<th
+			key={column.key}
+			scope="col"
+			rowSpan={rowSpan}
+			data-column={columnIndex}
+			data-active={selected}
+			data-numeric={column.type !== "text"}
+			data-align={column.align ?? (column.type === "text" ? "left" : "right")}
+			aria-sort={sorted ? (state.sort?.descending ? "descending" : "ascending") : "none"}
+		>
+			<ColumnMenu
+				tabIndex={selected || (!activeVisible && columnIndex === 0) ? 0 : -1}
+				onActivate={() => setActive({ row: -1, column: columnIndex })}
+				onNavigate={(event) =>
+					navigateTable(event, -1, columnIndex, rows, columnCount, tableRef.current)
+				}
+				onSort={() => setState((previous) => cycleSort(previous, column.key))}
+				label={column.label}
+				headerContent={renderHeader?.(column.key)}
+				unit={units[column.key] || undefined}
+				indicator={`${sorted ? (state.sort?.descending ? "↓" : "↑") : ""}${filtered ? " •" : ""}`}
+				open={openColumn === column.key}
+				onOpenChange={(open) =>
+					setOpenColumn((previous) =>
+						open ? column.key : previous === column.key ? null : previous,
+					)
+				}
+			>
+				{(close) => (
+					<ColumnOptions
+						column={column}
+						data={data}
+						state={state}
+						setState={setState}
+						unit={units[column.key]}
+						error={errors[column.key]}
+						close={close}
+					/>
+				)}
+			</ColumnMenu>
+		</th>
+	);
+}

package/client/data-table/model.ts

@@ -0,0 +1,194 @@
+import ms from "ms";
+import bytes from "bytes";
+import { z } from "zod";
+
+const common = {
+	key: z.string().min(1),
+	label: z.string().min(1),
+	group: z.string().optional(),
+	align: z
+		.enum(["left", "center", "right"])
+		.optional()
+		.describe("Explicit alignment overrides the column type default."),
+	bars: z
+		.boolean()
+		.optional()
+		.describe("Opt-in magnitude bars; zero is always included in the scale."),
+};
+const formatter = z.custom<(value: number) => string>((value) => typeof value === "function");
+export const columnSchema = z.discriminatedUnion("type", [
+	z.object({ ...common, type: z.literal("text") }),
+	z.object({ ...common, type: z.literal("number") }),
+	z.object({ ...common, type: z.literal("percent") }),
+	z.object({ ...common, type: z.literal("time"), unit: z.string().min(1) }),
+	z.object({ ...common, type: z.literal("bytes"), unit: z.string().min(1) }),
+	z.object({
+		...common,
+		type: z.literal("currency"),
+		format: formatter.describe(
+			"Required numeric-to-string currency formatter, e.g. value => `$${value}`",
+		),
+	}),
+]);
+export type Column = z.infer<typeof columnSchema>;
+export type Value = string | number | null;
+export type Row = Record<string, Value>;
+export type Filter = {
+	pattern?: string;
+	caseSensitive?: boolean;
+	min?: string;
+	max?: string;
+	unit?: string;
+};
+export type TableState = {
+	columnTypes?: Record<string, Column["type"]>;
+	sort?: { key: string; descending: boolean };
+	filters: Record<string, Filter>;
+	units: Record<string, string>;
+};
+export const emptyState = (): TableState => ({ filters: {}, units: {} });
+export const timeUnits = ["ms", "s", "m", "h", "d", "w", "y"];
+export const byteUnits = ["B", "KB", "MB", "GB", "TB", "PB"];
+export function unitFactor(type: "time" | "bytes", unit: string): number {
+	try {
+		if (type === "bytes" && !/^(b|kb|mb|gb|tb|pb)$/i.test(unit))
+			throw new Error("Invalid bytes unit");
+		const result = type === "time" ? ms(`1 ${unit}` as ms.StringValue) : bytes.parse(`1${unit}`);
+		if (typeof result === "number" && Number.isFinite(result) && result > 0) return result;
+	} catch {
+		/* invalid unit is reported by the component */
+	}
+	throw new Error(`Unsupported ${type} unit: ${unit}`);
+}
+export function parseBound(
+	input: string,
+	column: Column,
+	displayUnit?: string,
+): number | undefined {
+	if (!input.trim()) return undefined;
+	const raw = input.trim();
+	const numeric = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
+	let result: number | null | undefined;
+	if (column.type === "time" || column.type === "bytes") {
+		const base = unitFactor(column.type, column.unit);
+		if (numeric.test(raw))
+			result = (Number(raw) * unitFactor(column.type, displayUnit ?? column.unit)) / base;
+		else {
+			try {
+				result = column.type === "time" ? ms(raw as ms.StringValue) : bytes.parse(raw);
+			} catch {
+				result = undefined;
+			}
+			// bytes.parse accepts arbitrary trailing text; require a complete supported unit.
+			if (
+				column.type === "bytes" &&
+				!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)\s*(?:b|kb|mb|gb|tb|pb)$/i.test(raw)
+			)
+				result = undefined;
+			if (typeof result === "number") result /= base;
+		}
+	} else if (column.type === "percent") {
+		const percentage = raw.replace(/%$/, "").trim();
+		if (numeric.test(percentage)) result = Number(percentage) / 100;
+	} else if (column.type === "currency") {
+		const match = raw.match(/^([+-]?(?:\d+(?:\.\d*)?|\.\d+))\s*([kmbt])?$/i);
+		if (match)
+			result =
+				Number(match[1]) * ({ k: 1e3, m: 1e6, b: 1e9, t: 1e12 }[match[2]?.toLowerCase()] ?? 1);
+	} else if (numeric.test(raw)) result = Number(raw);
+	if (typeof result !== "number" || !Number.isFinite(result))
+		throw new Error("Enter a valid number or supported unit.");
+	return result;
+}
+export function autoUnit(column: Column, values: Value[]): string {
+	if (column.type !== "time" && column.type !== "bytes") return "";
+	const magnitude = Math.max(
+		0,
+		...values
+			.filter((value): value is number => typeof value === "number")
+			.map((value) => Math.abs(value) * unitFactor(column.type as "time" | "bytes", column.unit)),
+	);
+	const units = column.type === "time" ? timeUnits : byteUnits;
+	return (
+		[...units]
+			.reverse()
+			.find((unit) => magnitude >= unitFactor(column.type as "time" | "bytes", unit)) ?? units[0]
+	);
+}
+export function formatValue(value: Value, column: Column, unit?: string): string {
+	if (value === null) return "—";
+	if (typeof value !== "number") return value;
+	const numberFormat = new Intl.NumberFormat("en-US", { maximumFractionDigits: 20 });
+	if (column.type === "percent")
+		return `${new Intl.NumberFormat("en-US", { maximumSignificantDigits: 12 }).format(value * 100)}%`;
+	if (column.type === "currency") return column.format(value);
+	if (column.type === "time" || column.type === "bytes") {
+		const chosen = unit ?? column.unit;
+		return `${new Intl.NumberFormat("en-US", { maximumSignificantDigits: 6 }).format((value * unitFactor(column.type, column.unit)) / unitFactor(column.type, chosen))} ${chosen}`;
+	}
+	return numberFormat.format(value);
+}
+export function filterPredicate(
+	column: Column,
+	filter: Filter,
+	unit?: string,
+): (value: Value) => boolean {
+	if (column.type === "text") {
+		const regexp = new RegExp(filter.pattern ?? "", filter.caseSensitive ? "" : "i");
+		return (value) => regexp.test(String(value ?? ""));
+	}
+	const min = parseBound(filter.min ?? "", column, filter.unit ?? unit);
+	const max = parseBound(filter.max ?? "", column, filter.unit ?? unit);
+	if (min !== undefined && max !== undefined && min > max)
+		throw new Error("Minimum must not exceed maximum.");
+	return (value) =>
+		(min === undefined && max === undefined) ||
+		(typeof value === "number" &&
+			(min === undefined || value >= min) &&
+			(max === undefined || value <= max));
+}
+export function compareValues(left: Value, right: Value, descending: boolean): number {
+	if (left === null) return right === null ? 0 : 1;
+	if (right === null) return -1;
+	const order =
+		typeof left === "number" && typeof right === "number"
+			? left - right
+			: String(left).localeCompare(String(right), undefined, { numeric: true });
+	return descending ? -order : order;
+}
+
+/** Infer only when every nonmissing cell agrees; never infer bars from numeric data. */
+export function inferColumn(key: string, label: string, values: string[]): Column {
+	const present = values
+		.map((value) => value.trim())
+		.filter((value) => value !== "" && value !== "—");
+	const base = { key, label };
+	const numeric = /^[+-]?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+	if (present.length && present.every((value) => numeric.test(value)))
+		return { ...base, type: "number" };
+	if (
+		present.length &&
+		present.every((value) => value.endsWith("%") && numeric.test(value.slice(0, -1)))
+	)
+		return { ...base, type: "percent" };
+	const size: Column = { ...base, type: "bytes", unit: "B" };
+	if (
+		present.length &&
+		present.every((value) => /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)\s*(b|kb|mb|gb|tb|pb)$/i.test(value))
+	)
+		return size;
+	const duration: Column = { ...base, type: "time", unit: "ms" };
+	if (
+		present.length &&
+		present.every((value) => {
+			if (!/[a-z]/i.test(value)) return false;
+			try {
+				return parseBound(value, duration) !== undefined;
+			} catch {
+				return false;
+			}
+		})
+	)
+		return duration;
+	return { ...base, type: "text" };
+}

package/client/data-table/navigation.ts

@@ -0,0 +1,34 @@
+import type { KeyboardEvent } from "react";
+import type { VisibleRow } from "./table-state";
+
+export function navigateTable(
+	event: KeyboardEvent<HTMLElement>,
+	rowIndex: number,
+	columnIndex: number,
+	rows: VisibleRow[],
+	columnCount: number,
+	table: HTMLTableElement | null,
+) {
+	if (event.target !== event.currentTarget) return;
+	let nextRow = rowIndex;
+	let nextColumn = columnIndex;
+	if (event.key === "ArrowDown") nextRow++;
+	else if (event.key === "ArrowUp") nextRow--;
+	else if (event.key === "ArrowLeft") nextColumn--;
+	else if (event.key === "ArrowRight") nextColumn++;
+	else if (event.key === "Home") {
+		nextColumn = 0;
+		if (event.ctrlKey || event.metaKey) nextRow = -1;
+	} else if (event.key === "End") {
+		nextColumn = columnCount - 1;
+		if (event.ctrlKey || event.metaKey) nextRow = rows.length - 1;
+	} else return;
+	event.preventDefault();
+	nextRow = Math.max(-1, Math.min(rows.length - 1, nextRow));
+	nextColumn = Math.max(0, Math.min(columnCount - 1, nextColumn));
+	const target =
+		nextRow === -1
+			? `thead th[data-column="${nextColumn}"] .data-table-heading`
+			: `tbody [data-row="${rows[nextRow]?.index}"][data-column="${nextColumn}"]`;
+	table?.querySelector<HTMLElement>(target)?.focus();
+}

package/client/data-table/table-state.ts

@@ -0,0 +1,196 @@
+import {
+	autoUnit,
+	byteUnits,
+	compareValues,
+	filterPredicate,
+	parseBound,
+	timeUnits,
+	unitFactor,
+	type Column,
+	type Filter,
+	type Row,
+	type TableState,
+} from "./model";
+
+export type ActiveCell = { row: number; column: number } | null;
+export type VisibleRow = { row: Row; index: number };
+
+function normalizeFilter(filter: Filter, column: Column): Filter {
+	if (column.type === "text") {
+		return filter.pattern === undefined ? {} : { pattern: filter.pattern };
+	}
+
+	const options = column.type === "time" ? timeUnits : column.type === "bytes" ? byteUnits : [];
+	// A bound recorded in a different measurement must not be silently reinterpreted.
+	if (filter.unit && !options.includes(filter.unit)) return {};
+
+	return {
+		...(filter.min === undefined ? {} : { min: filter.min }),
+		...(filter.max === undefined ? {} : { max: filter.max }),
+		...(filter.unit && options.includes(filter.unit) ? { unit: filter.unit } : {}),
+	};
+}
+
+/** Reconcile persisted preferences before they reach sorting, filters, or labels. */
+export function normalizeTableState(state: TableState, columns: Column[]): TableState {
+	const columnTypes = Object.fromEntries(columns.map((column) => [column.key, column.type]));
+	const normalized: TableState = { columnTypes, filters: {}, units: {} };
+
+	if (state.sort && columns.some((column) => column.key === state.sort?.key)) {
+		normalized.sort = state.sort;
+	}
+
+	for (const column of columns) {
+		const previousType = state.columnTypes?.[column.key];
+		if (previousType && previousType !== column.type) continue;
+
+		const filter = state.filters[column.key];
+		if (filter) {
+			const compatible = normalizeFilter(filter, column);
+			if (Object.keys(compatible).length) normalized.filters[column.key] = compatible;
+		}
+
+		const options = column.type === "time" ? timeUnits : column.type === "bytes" ? byteUnits : [];
+		const unit = state.units[column.key];
+		if (options.length && (unit === "auto" || options.includes(unit))) {
+			normalized.units[column.key] = unit;
+		}
+	}
+
+	// Keep the same reference when already normalized so persistence does not cause render loops.
+	return JSON.stringify(normalized) === JSON.stringify(state) ? state : normalized;
+}
+
+export function deriveTableView(columns: Column[], data: Row[], state: TableState) {
+	const units = Object.fromEntries(
+		columns.map((column) => {
+			const options = column.type === "time" ? timeUnits : column.type === "bytes" ? byteUnits : [];
+			return [
+				column.key,
+				options.includes(state.units[column.key])
+					? state.units[column.key]
+					: autoUnit(
+							column,
+							data.map((row) => row[column.key] ?? null),
+						),
+			];
+		}),
+	);
+
+	const errors: Record<string, string> = {};
+	const predicates = columns.map((column) => {
+		try {
+			return {
+				key: column.key,
+				match: filterPredicate(
+					column,
+					{ ...state.filters[column.key], caseSensitive: false },
+					units[column.key],
+				),
+			};
+		} catch (error) {
+			errors[column.key] = error instanceof Error ? error.message : "Invalid filter";
+			return { key: column.key, match: () => true };
+		}
+	});
+
+	const rows = data
+		.map((row, index) => ({ row, index }))
+		.filter(({ row }) => predicates.every(({ key, match }) => match(row[key] ?? null)));
+
+	const sort = state.sort;
+	if (sort && columns.some((column) => column.key === sort.key))
+		rows.sort(
+			(left, right) =>
+				compareValues(left.row[sort.key] ?? null, right.row[sort.key] ?? null, sort.descending) ||
+				left.index - right.index,
+		);
+
+	const bounds = Object.fromEntries(
+		columns
+			.filter((column) => column.bars)
+			.map((column) => {
+				const values = data
+					.map((row) => row[column.key])
+					.filter((value): value is number => typeof value === "number");
+				return [column.key, [Math.min(0, ...values), Math.max(0, ...values)]];
+			}),
+	);
+
+	const groups: { label: string; columns: Column[] }[] = [];
+	for (const column of columns) {
+		const label = column.group ?? "";
+		const last = groups.at(-1);
+		if (label && last?.label === label) last.columns.push(column);
+		else groups.push({ label, columns: [column] });
+	}
+
+	return { units, errors, rows, bounds, groups };
+}
+
+export function updateFilter(state: TableState, key: string, patch: Partial<Filter>): TableState {
+	return { ...state, filters: { ...state.filters, [key]: { ...state.filters[key], ...patch } } };
+}
+
+export function clearFilter(state: TableState, key: string): TableState {
+	return { ...state, filters: { ...state.filters, [key]: {} } };
+}
+
+export function cycleSort(state: TableState, key: string): TableState {
+	const sort =
+		state.sort?.key !== key
+			? { key, descending: false }
+			: state.sort.descending
+				? undefined
+				: { key, descending: true };
+
+	return { ...state, sort };
+}
+
+export function hasFilter(filter: Filter = {}): boolean {
+	return Object.entries(filter).some(
+		([key, value]) => key !== "unit" && typeof value === "string" && value !== "",
+	);
+}
+
+export function changeUnit(
+	state: TableState,
+	column: Column,
+	selected: string,
+	data: Row[],
+	displayUnit: string,
+): TableState {
+	if (column.type !== "time" && column.type !== "bytes") return state;
+	const nextUnit =
+		selected === "auto"
+			? autoUnit(
+					column,
+					data.map((row) => row[column.key] ?? null),
+				)
+			: selected;
+	const nextFilter = { ...state.filters[column.key] };
+	for (const bound of ["min", "max"] as const) {
+		try {
+			const value = parseBound(nextFilter[bound] ?? "", column, nextFilter.unit ?? displayUnit);
+			if (value !== undefined)
+				nextFilter[bound] = String(
+					(value * unitFactor(column.type, column.unit)) / unitFactor(column.type, nextUnit),
+				);
+		} catch {
+			/* retain invalid input for correction */
+		}
+	}
+	nextFilter.unit = nextUnit;
+	return {
+		...state,
+		units: { ...state.units, [column.key]: selected },
+		filters: { ...state.filters, [column.key]: nextFilter },
+	};
+}
+
+export function filterSummary(column: Column, filter: Filter = {}): string {
+	if (column.type === "text") return filter.pattern ?? "";
+
+	const unit = column.type === "percent" ? "%" : filter.unit ? ` ${filter.unit}` : "";
+	return `${filter.min || "Any"} – ${filter.max || "Any"}${unit}`;
+}

package/client/data-table/useColumnMenu.ts

@@ -0,0 +1,84 @@
+import { useEffect, useRef, useState, type RefObject } from "react";
+import { autoUpdate, computePosition, flip, offset, shift, size } from "@floating-ui/dom";
+
+function observeColumnMenu(
+	anchor: HTMLDivElement,
+	popup: HTMLDivElement,
+	onPositioned: () => void,
+	onDismiss: () => void,
+) {
+	popup.inert = false;
+	popup.style.pointerEvents = "auto";
+	let disposed = false;
+
+	const cleanup = autoUpdate(anchor.closest("th") ?? anchor, popup, () => {
+		void computePosition(anchor.closest("th") ?? anchor, popup, {
+			placement: "bottom-start",
+			strategy: "fixed",
+			middleware: [
+				offset(6),
+				flip(),
+				shift({ padding: 8 }),
+				size({
+					padding: 8,
+					apply({ availableHeight }) {
+						popup.style.maxHeight = `${Math.max(0, availableHeight)}px`;
+					},
+				}),
+			],
+		}).then(({ x, y }) => {
+			if (disposed) return;
+			Object.assign(popup.style, { left: `${x}px`, top: `${y}px` });
+			onPositioned();
+		});
+	});
+
+	const dismiss = (event: PointerEvent) => {
+		if (
+			!popup.contains(event.target as Node) &&
+			!anchor.parentElement?.contains(event.target as Node)
+		)
+			onDismiss();
+	};
+
+	document.addEventListener("pointerdown", dismiss);
+
+	return () => {
+		disposed = true;
+		cleanup();
+		document.removeEventListener("pointerdown", dismiss);
+		popup.inert = true;
+		popup.style.pointerEvents = "none";
+	};
+}
+
+export function useColumnMenu(
+	open: boolean,
+	onOpenChange: (open: boolean) => void,
+	trigger: RefObject<HTMLDivElement | null>,
+	menu: RefObject<HTMLDivElement | null>,
+) {
+	const [positioned, setPositioned] = useState(false);
+	const change = useRef(onOpenChange);
+	change.current = onOpenChange;
+
+	useEffect(() => {
+		if (!open) {
+			setPositioned(false);
+			return;
+		}
+		if (!trigger.current || !menu.current) return;
+		return observeColumnMenu(
+			trigger.current,
+			menu.current,
+			() => setPositioned(true),
+			() => change.current(false),
+		);
+	}, [open, trigger, menu]);
+
+	useEffect(() => {
+		if (open && positioned) menu.current?.querySelector<HTMLInputElement>("input")?.focus();
+	}, [open, positioned, menu]);
+
+	return positioned;
+}