@karimsa/mdxserve 0.2.0 → 0.4.0

package/client/builtins/DataTable.tsx

@@ -0,0 +1,269 @@
+import { useRef, useState, type ReactNode, type TableHTMLAttributes } from "react";
+import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
+import { z } from "zod";
+import { TableHeaderCell } from "../data-table/TableHeaderCell";
+import { useTableState } from "../data-table/useTableState";
+import {
+	clearFilter,
+	deriveTableView,
+	hasFilter,
+	filterSummary,
+	type ActiveCell,
+} from "../data-table/table-state";
+import { TableCell } from "../data-table/TableCell";
+import { useDocumentBlockScope } from "../block-state/useBlockState";
+import { blockStateKey, type BlockStateScope } from "../block-state/storage";
+import { columnSchema, unitFactor } from "../data-table/model";
+
+export const dataTableProps = z.object({
+	id: z
+		.string()
+		.trim()
+		.min(1)
+		.describe(
+			"Required stable ID, unique within this document. Retain it across edits to preserve local sorting, filters and units.",
+		),
+	caption: z.string().optional(),
+	columns: z
+		.array(columnSchema)
+		.min(1)
+		.describe(
+			"Ordered columns: key, label, type; optional group and bars. Time/bytes require a base unit. Percent data uses fractions (0.15 displays 15%). Currency requires format(value).",
+		),
+	data: z.array(z.record(z.string(), z.union([z.string(), z.number().finite(), z.null()]))),
+});
+
+export type DataTableProps = z.infer<typeof dataTableProps>;
+type InternalProps = DataTableProps & {
+	renderCell?: (row: number, key: string) => ReactNode;
+	renderHeader?: (key: string) => ReactNode;
+	tableProps?: Omit<TableHTMLAttributes<HTMLTableElement>, "children">;
+	persistState?: boolean;
+};
+
+function validateTableProps(props: InternalProps) {
+	const parsed = dataTableProps.parse(props);
+	const keys = new Set(parsed.columns.map((column) => column.key));
+	if (keys.size !== parsed.columns.length) throw new Error("DataTable column keys must be unique.");
+	for (const column of parsed.columns) {
+		if (column.type === "time" || column.type === "bytes") unitFactor(column.type, column.unit);
+		if (
+			parsed.data.some(
+				(row) =>
+					row[column.key] !== undefined &&
+					row[column.key] !== null &&
+					typeof row[column.key] !== (column.type === "text" ? "string" : "number"),
+			)
+		)
+			throw new Error(
+				`DataTable: ${column.key} requires ${column.type === "text" ? "text" : "numeric"} values.`,
+			);
+	}
+
+	return parsed;
+}
+
+export default function DataTable(props: InternalProps) {
+	const parsed = validateTableProps(props);
+
+	const scope = useDocumentBlockScope({ kind: "table", version: 1, blockId: parsed.id });
+
+	return (
+		<TableView
+			key={blockStateKey(scope)}
+			{...parsed}
+			renderCell={props.renderCell}
+			renderHeader={props.renderHeader}
+			tableProps={props.tableProps}
+			persistState={props.persistState}
+			scope={scope}
+		/>
+	);
+}
+
+function TableView({
+	id,
+	caption,
+	columns,
+	data,
+	renderCell,
+	renderHeader,
+	tableProps,
+	persistState = true,
+	scope,
+}: InternalProps & { scope: BlockStateScope }) {
+	const [state, setState] = useTableState(scope, columns, persistState);
+	const [openColumn, setOpenColumn] = useState<string | null>(null);
+	const [active, setActive] = useState<ActiveCell>(null);
+	const tableRef = useRef<HTMLTableElement>(null);
+	const reducedMotion = useReducedMotion();
+
+	const { units, errors, rows, bounds, groups } = deriveTableView(columns, data, state);
+	const activeVisible =
+		active &&
+		(active.row === -1 || rows.some(({ index }) => index === active.row)) &&
+		active.column < columns.length;
+	const filteredColumns = columns.filter((column) => hasFilter(state.filters[column.key]));
+
+	const headerProps = {
+		renderHeader,
+		columnCount: columns.length,
+		data,
+		rows,
+		state,
+		setState,
+		units,
+		errors,
+		active,
+		activeVisible: Boolean(activeVisible),
+		setActive,
+		openColumn,
+		setOpenColumn,
+		tableRef,
+	};
+
+	return (
+		<div className="data-table not-prose" data-table-id={id} data-table-persist={persistState}>
+			<div className="data-table-toolbar">
+				<span>{caption ?? "Table"}</span>
+				<span className="data-table-count">{data.length} rows</span>
+			</div>
+			{(state.sort || filteredColumns.length > 0) && (
+				<div className="data-table-chips">
+					{state.sort && (
+						<button
+							type="button"
+							aria-label="Clear sorting"
+							onClick={() => setState((previous) => ({ ...previous, sort: undefined }))}
+						>
+							{columns.find((column) => column.key === state.sort?.key)?.label}{" "}
+							{state.sort.descending ? "↓" : "↑"} <span aria-hidden="true">×</span>
+						</button>
+					)}
+					{filteredColumns.map((column) => (
+						<button
+							type="button"
+							key={column.key}
+							aria-label={`Clear ${column.label} filter`}
+							onClick={() => setState((previous) => clearFilter(previous, column.key))}
+						>
+							{column.label}: {filterSummary(column, state.filters[column.key])}{" "}
+							<span aria-hidden="true">×</span>
+						</button>
+					))}
+				</div>
+			)}
+
+			<div className="data-table-scroll">
+				<table aria-label={caption ?? "Data table"} {...tableProps} ref={tableRef}>
+					<thead>
+						{columns.some((column) => column.group) ? (
+							<>
+								<tr className="data-table-groups">
+									{groups.map((group) =>
+										group.label ? (
+											<th
+												key={group.columns[0].key}
+												colSpan={group.columns.length}
+												scope="colgroup"
+											>
+												{group.label}
+											</th>
+										) : (
+											<TableHeaderCell
+												key={group.columns[0].key}
+												{...headerProps}
+												column={group.columns[0]}
+												columnIndex={columns.indexOf(group.columns[0])}
+												rowSpan={2}
+											/>
+										),
+									)}
+								</tr>
+								<tr>
+									{groups
+										.filter((group) => group.label)
+										.flatMap((group) =>
+											group.columns.map((column) => (
+												<TableHeaderCell
+													key={column.key}
+													{...headerProps}
+													column={column}
+													columnIndex={columns.indexOf(column)}
+												/>
+											)),
+										)}
+								</tr>
+							</>
+						) : (
+							<tr>
+								{columns.map((column) => (
+									<TableHeaderCell
+										key={column.key}
+										{...headerProps}
+										column={column}
+										columnIndex={columns.indexOf(column)}
+									/>
+								))}
+							</tr>
+						)}
+					</thead>
+					<tbody>
+						<AnimatePresence initial={false}>
+							{rows.map(({ row, index }, rowIndex) => (
+								<motion.tr
+									key={index}
+									layout={!reducedMotion}
+									initial={reducedMotion ? false : { opacity: 0 }}
+									animate={{ opacity: 1 }}
+									exit={{ opacity: 0 }}
+									transition={{ duration: reducedMotion ? 0 : 0.18 }}
+								>
+									{columns.map((column, columnIndex) => (
+										<TableCell
+											key={column.key}
+											column={column}
+											columnIndex={columnIndex}
+											columnCount={columns.length}
+											row={row}
+											index={index}
+											rowIndex={rowIndex}
+											rows={rows}
+											unit={units[column.key]}
+											limits={bounds[column.key]}
+											active={active}
+											setActive={setActive}
+											tableRef={tableRef}
+											renderCell={renderCell}
+										/>
+									))}
+								</motion.tr>
+							))}
+						</AnimatePresence>
+						{rows.length === 0 && (
+							<tr>
+								<td colSpan={columns.length}>No matching rows. Adjust or reset filters.</td>
+							</tr>
+						)}
+					</tbody>
+				</table>
+			</div>
+			<div className="data-table-note">
+				<span aria-live="polite">
+					{rows.length} of {data.length} rows
+				</span>
+				{columns.some((column) => column.bars) && <span>Lines compare within each column</span>}
+			</div>
+			{Object.keys(errors).length > 0 && (
+				<div role="alert" className="data-table-error">
+					Invalid filter:{" "}
+					{columns
+						.filter((column) => errors[column.key])
+						.map((column) => column.label)
+						.join(", ")}
+					. Open its column menu to correct it.
+				</div>
+			)}
+		</div>
+	);
+}

package/client/builtins/chart-data.ts

@@ -81,22 +81,34 @@ export function binValues(values: number[], bins?: number): HistogramBin[] {
 		return [{ label: formatBinEdge(min, 1), value: finite.length, start: min, end: max }];
 	}
 	const count = clamp(bins ?? autoBinCount(finite.length), 1, 50);
-	const step = (max - min) / count;
-	const counts = new Array(count).fill(0) as number[];
-	for (const value of finite) {
-		const index = Math.min(count - 1, Math.floor(((value - min) / (max - min)) * count));
-		counts[index]++;
-	}
-	return counts.map((value, index) => {
-		const start = min + step * index;
-		const end = index === count - 1 ? max : min + step * (index + 1);
+	const range = max - min;
+	const step = range / count;
+	const edges = Array.from({ length: count + 1 }, (_element, index) => {
+		if (index === 0) return min;
+		if (index === count) return max;
+		const fraction = index / count;
+		// Interpolate the full range so a rounded subnormal step cannot accumulate error.
+		const edge = Number.isFinite(range)
+			? min + range * fraction
+			: min * (1 - fraction) + max * fraction;
+		return clamp(edge, min, max);
+	});
+	const result = Array.from({ length: count }, (_element, index) => {
+		const start = edges[index]!;
+		const end = edges[index + 1]!;
 		return {
 			label: `${formatBinEdge(start, step)}–${formatBinEdge(end, step)}`,
-			value,
+			value: 0,
 			start,
 			end,
 		};
 	});
+	for (const value of finite) {
+		// Use the rounded edges so boundary values agree with the displayed ranges.
+		const index = result.findIndex((bin, index) => index === count - 1 || value < bin.end);
+		result[index]!.value++;
+	}
+	return result;
 }
 
 /** A stride-thinned subset of `[0, edgeCount)`, always including the first

package/client/builtins/index.ts

@@ -12,6 +12,7 @@ import FileTree, { fileTreeProps } from "./FileTree";
 import Chart, { chartProps } from "./Chart";
 import Sparkline, { sparklineProps } from "./Sparkline";
 import Dropdown, { Option, dropdownProps, optionProps } from "./Dropdown";
+import DataTable, { dataTableProps } from "./DataTable";
 import Screenshot, { screenshotProps } from "./Screenshot";
 
 export interface BuiltinDefinition {
@@ -23,6 +24,15 @@ export interface BuiltinDefinition {
 }
 
 export const builtins: BuiltinDefinition[] = [
+	{
+		name: "DataTable",
+		description:
+			"A bordered, sortable, filterable data table with typed columns, unit selection, grouped headers and optional bars.",
+		whenToUse:
+			"Use for datasets and quantitative comparisons; use native Markdown tables for facts and prose. Required stable document-unique id. Columns have key, label, type (text/number/percent/time/bytes/currency), optional group and bars. Percent values are fractions (0.15 means 15%). Time and bytes require unit; currency requires a format function and numeric data. Bars are opt-in and independently scaled by column. Reader state is local to the document and ID.",
+		props: dataTableProps,
+		Component: DataTable,
+	},
 	{
 		name: "Callout",
 		description:

package/client/data-table/ColumnMenu.tsx

@@ -0,0 +1,168 @@
+import { useId, useRef, type ReactNode, type KeyboardEvent, type FocusEvent } from "react";
+import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
+import { enterTransition, exitTransition } from "../motion";
+import { createPortal } from "react-dom";
+import { useColumnMenu } from "./useColumnMenu";
+import ChevronDown from "lucide-react/dist/esm/icons/chevron-down.mjs";
+
+function closeColumnMenu(onOpenChange: (open: boolean) => void, trigger: HTMLDivElement | null) {
+	onOpenChange(false);
+	trigger?.focus();
+}
+
+function handleHeaderKey(
+	event: KeyboardEvent<HTMLDivElement>,
+	onSort: () => void,
+	onOpenChange: (open: boolean) => void,
+	onNavigate: (event: KeyboardEvent<HTMLDivElement>) => void,
+) {
+	if (event.target !== event.currentTarget) return;
+
+	if (event.key === " ") {
+		event.preventDefault();
+		onSort();
+	} else if (event.key === "Enter") {
+		event.preventDefault();
+		onOpenChange(true);
+	} else {
+		onNavigate(event);
+	}
+}
+
+function handleMenuKey(event: KeyboardEvent<HTMLDivElement>, close: () => void) {
+	if (event.key !== "Escape") return;
+
+	event.preventDefault();
+	event.stopPropagation();
+	close();
+}
+
+function handleMenuBlur(
+	event: FocusEvent<HTMLDivElement>,
+	trigger: HTMLDivElement | null,
+	onOpenChange: (open: boolean) => void,
+) {
+	const nextTarget = event.relatedTarget;
+	if (
+		!nextTarget ||
+		event.currentTarget.contains(nextTarget) ||
+		trigger?.parentElement?.contains(nextTarget)
+	)
+		return;
+
+	onOpenChange(false);
+}
+
+/** Portaled to escape the table scroller, positioned against the triggering header. */
+export function ColumnMenu({
+	label,
+	headerContent,
+	unit,
+	indicator,
+	open,
+	onOpenChange,
+	onActivate,
+	onSort,
+	onNavigate,
+	tabIndex,
+	children,
+}: {
+	label: string;
+	headerContent?: ReactNode;
+	unit?: string;
+	indicator?: string;
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	onActivate: () => void;
+	onSort: () => void;
+	onNavigate: (event: KeyboardEvent<HTMLDivElement>) => void;
+	tabIndex: number;
+	children: (close: () => void) => ReactNode;
+}) {
+	const trigger = useRef<HTMLDivElement>(null);
+	const menu = useRef<HTMLDivElement>(null);
+	const menuId = useId();
+	const reducedMotion = useReducedMotion();
+	const positioned = useColumnMenu(open, onOpenChange, trigger, menu);
+	const close = () => closeColumnMenu(onOpenChange, trigger.current);
+
+	return (
+		<>
+			<div className="data-table-header-control">
+				<div
+					ref={trigger}
+					role="button"
+					className="data-table-heading"
+					aria-label={`${label} column header`}
+					aria-keyshortcuts="Space Enter ArrowUp ArrowDown ArrowLeft ArrowRight"
+					tabIndex={tabIndex}
+					onFocus={onActivate}
+					aria-haspopup="dialog"
+					aria-expanded={open}
+					aria-controls={open ? menuId : undefined}
+					onClick={() => {
+						onActivate();
+						onOpenChange(false);
+					}}
+					onKeyDown={(event) => handleHeaderKey(event, onSort, onOpenChange, onNavigate)}
+				>
+					<span>{headerContent ?? label}</span>
+					{unit && <span className="data-table-unit">· {unit}</span>}
+					{indicator && <span className="data-table-indicator">{indicator}</span>}
+				</div>
+				<button
+					type="button"
+					className="data-table-header-chevron"
+					tabIndex={-1}
+					aria-label={`${label} column options`}
+					aria-haspopup="dialog"
+					aria-expanded={open}
+					aria-controls={open ? menuId : undefined}
+					onClick={() => {
+						onActivate();
+						if (open) close();
+						else onOpenChange(true);
+					}}
+				>
+					<ChevronDown size={12} aria-hidden="true" />
+				</button>
+			</div>
+			{typeof document !== "undefined" &&
+				createPortal(
+					<AnimatePresence>
+						{open && (
+							<motion.div
+								key="menu"
+								initial={{ opacity: 0, y: reducedMotion ? 0 : -4, scale: reducedMotion ? 1 : 0.98 }}
+								animate={
+									positioned
+										? { opacity: 1, y: 0, scale: 1 }
+										: { opacity: 0, y: reducedMotion ? 0 : -4, scale: reducedMotion ? 1 : 0.98 }
+								}
+								exit={{
+									opacity: 0,
+									y: reducedMotion ? 0 : -3,
+									scale: reducedMotion ? 1 : 0.98,
+									transition: reducedMotion ? { duration: 0 } : exitTransition,
+								}}
+								transition={reducedMotion ? { duration: 0 } : enterTransition}
+								id={menuId}
+								ref={menu}
+								className="data-table-menu"
+								role="dialog"
+								aria-label={`${label} column options`}
+								style={{ transformOrigin: "top left" }}
+								onDoubleClick={(event) => event.stopPropagation()}
+								onKeyDown={(event) => handleMenuKey(event, close)}
+								onBlur={(event) => handleMenuBlur(event, trigger.current, onOpenChange)}
+							>
+								<div className="data-table-menu-title">{label}</div>
+								{children(close)}
+							</motion.div>
+						)}
+					</AnimatePresence>,
+					document.body,
+				)}
+		</>
+	);
+}

package/client/data-table/ColumnOptions.tsx

@@ -0,0 +1,141 @@
+import type { Dispatch, SetStateAction } from "react";
+import { autoUnit, byteUnits, timeUnits, type Column, type Row, type TableState } from "./model";
+import { changeUnit, clearFilter, hasFilter, updateFilter } from "./table-state";
+
+interface ColumnOptionsProps {
+	column: Column;
+	data: Row[];
+	state: TableState;
+	setState: Dispatch<SetStateAction<TableState>>;
+	unit: string;
+	error?: string;
+	close: () => void;
+}
+
+export function ColumnOptions({
+	column,
+	data,
+	state,
+	setState,
+	unit,
+	error,
+	close,
+}: ColumnOptionsProps) {
+	const sorted = state.sort?.key === column.key;
+	const filtered = hasFilter(state.filters[column.key]);
+
+	return (
+		<>
+			<div className="data-table-menu-sorting">
+				{[false, true].map((descending) => (
+					<button
+						key={String(descending)}
+						type="button"
+						aria-label={descending ? "Sort descending" : "Sort ascending"}
+						title={descending ? "Sort descending" : "Sort ascending"}
+						aria-pressed={sorted && state.sort?.descending === descending}
+						onClick={() => {
+							setState((previous) => ({
+								...previous,
+								sort: { key: column.key, descending },
+							}));
+							close();
+						}}
+					>
+						<span aria-hidden="true">{descending ? "↓" : "↑"}</span>
+					</button>
+				))}
+			</div>
+
+			<div className="data-table-menu-filter">
+				{column.type === "text" ? (
+					<>
+						<label>
+							Matches regular expression
+							<input
+								aria-label={`Filter ${column.label} by regular expression`}
+								placeholder="e.g. search|api"
+								value={state.filters[column.key]?.pattern ?? ""}
+								onChange={(event) =>
+									setState((previous) =>
+										updateFilter(previous, column.key, { pattern: event.target.value }),
+									)
+								}
+							/>
+						</label>
+					</>
+				) : (
+					<div className="data-table-range">
+						{(["min", "max"] as const).map((bound) => (
+							<label key={bound}>
+								{bound === "min" ? "Minimum" : "Maximum"}
+								{column.type === "percent"
+									? " (%)"
+									: unit
+										? ` (${state.filters[column.key]?.unit ?? unit})`
+										: ""}
+								<input
+									aria-label={`${column.label} ${bound}`}
+									placeholder="Any"
+									value={state.filters[column.key]?.[bound] ?? ""}
+									onChange={(event) =>
+										setState((previous) =>
+											updateFilter(previous, column.key, {
+												[bound]: event.target.value,
+												unit: state.filters[column.key]?.unit ?? unit,
+											}),
+										)
+									}
+								/>
+							</label>
+						))}
+					</div>
+				)}
+				{error && (
+					<div className="data-table-error" role="alert">
+						{error}
+					</div>
+				)}
+			</div>
+
+			{(column.type === "time" || column.type === "bytes") && (
+				<label className="data-table-menu-unit">
+					Display unit
+					<select
+						aria-label={`${column.label} display unit`}
+						value={state.units[column.key] ?? "auto"}
+						onChange={(event) =>
+							setState((previous) => changeUnit(previous, column, event.target.value, data, unit))
+						}
+					>
+						<option value="auto">
+							Auto (
+							{autoUnit(
+								column,
+								data.map((row) => row[column.key] ?? null),
+							)}
+							)
+						</option>
+						{(column.type === "time" ? timeUnits : byteUnits).map((unit) => (
+							<option key={unit}>{unit}</option>
+						))}
+					</select>
+				</label>
+			)}
+
+			{(filtered || sorted) && (
+				<button
+					type="button"
+					className="data-table-clear"
+					onClick={() => {
+						setState((previous) => clearFilter(previous, column.key));
+						if (sorted) setState((previous) => ({ ...previous, sort: undefined }));
+						close();
+					}}
+				>
+					Clear sort and filter
+				</button>
+			)}
+		</>
+	);
+}