@karimsa/mdxserve 0.2.0 → 0.4.0

package/client/app.css

@@ -33,6 +33,9 @@
 @import "./design/base/reset.css";
 @import "./design/base/prose.css";
 @import "./design/base/editor.css";
+@import "./ui/modal.css";
+@import "./Settings.css";
+@import "./diagrams/style.css";
 
 /* `:root[...]` (not bare `[data-theme]`) because rehype-pretty-code stamps
    data-theme="<shiki theme name>" on every <pre>/<code> it renders. */
@@ -302,7 +305,8 @@ code[data-line-numbers-max-digits="4"] [data-line]::before {
 
 /* Folder listing titles are rendered from the doc's first h1 as inline HTML. */
 /* Keep this in lockstep with the `.mdx-prose code` chip in design/base/prose.css. */
-.listing-title code {
+.listing-title code,
+.data-table-heading code {
 	font: var(--type-code-inline);
 	background: var(--code-bg-inline);
 	color: var(--text-accent);
@@ -370,3 +374,337 @@ code[data-line-numbers-max-digits="4"] [data-line]::before {
 		display: none;
 	}
 }
+
+/* Document-style tables. Menus are portaled, but anchored to their header. */
+.data-table {
+	margin: 1.5rem 0;
+	border: 1px solid var(--border-default);
+	border-radius: var(--radius-lg);
+	background: var(--surface-card);
+	overflow: hidden;
+	color: var(--text-body);
+	font-size: var(--size-sm);
+}
+.data-table-toolbar {
+	display: flex;
+	align-items: center;
+	gap: 0.75rem;
+	padding: 1rem;
+	flex-wrap: wrap;
+}
+.data-table-toolbar > span:first-child {
+	font-weight: 600;
+	color: var(--text-heading);
+}
+.data-table-count {
+	color: var(--text-muted);
+	font-size: var(--size-xs);
+}
+.data-table-scroll {
+	overflow-x: auto;
+}
+.data-table table {
+	width: 100%;
+	border-collapse: collapse;
+	font-variant-numeric: tabular-nums;
+}
+.data-table th,
+.data-table td {
+	padding: 0 1rem;
+	border-bottom: 1px solid var(--border-subtle);
+	text-align: left;
+	position: relative;
+}
+.data-table tbody tr:last-child td {
+	border-bottom: 0;
+}
+.data-table th {
+	padding: 0;
+	font-size: var(--size-xs);
+	font-weight: 400;
+	color: var(--text-muted);
+	height: 36px;
+	vertical-align: bottom;
+}
+.data-table td {
+	height: 49px;
+	padding-top: 0.6rem;
+	padding-bottom: 0.6rem;
+}
+.data-table td[data-numeric="true"] {
+	white-space: nowrap;
+}
+.data-table th[data-align="right"] .data-table-heading {
+	justify-content: flex-end;
+}
+.data-table [data-align="left"] {
+	text-align: left;
+}
+.data-table [data-align="center"] {
+	text-align: center;
+}
+.data-table [data-align="right"] {
+	text-align: right;
+}
+.data-table th[data-align="left"] .data-table-heading {
+	justify-content: flex-start;
+}
+.data-table th[data-align="center"] .data-table-heading {
+	justify-content: center;
+}
+.data-table td[data-bars="true"] {
+	padding-bottom: 0.9rem;
+}
+.data-table tbody tr:hover {
+	background: var(--surface-hover);
+}
+.data-table td[data-active="true"],
+.data-table td:focus-visible {
+	outline: 1.5px solid var(--border-accent);
+	outline-offset: -1.5px;
+	background: var(--surface-accent-soft);
+}
+.data-table-heading {
+	padding: 8px 0 8px 16px;
+	box-sizing: border-box;
+	flex: 1;
+	min-width: 0;
+	min-height: 36px;
+	display: flex;
+	align-items: center;
+	gap: 0.3rem;
+	white-space: nowrap;
+	cursor: pointer;
+	border-radius: 0;
+}
+.data-table-heading:hover,
+.data-table-heading[aria-expanded="true"] {
+	color: var(--text-heading);
+}
+.data-table-heading svg {
+	flex-shrink: 0;
+	opacity: 0.6;
+}
+.data-table-heading a {
+	color: var(--text-accent);
+	text-decoration: underline;
+	text-underline-offset: 2px;
+}
+.data-table-heading strong {
+	font-weight: 700;
+}
+.data-table-unit {
+	color: var(--text-subtle);
+}
+.data-table-indicator {
+	color: var(--text-accent);
+}
+.data-table-groups th[scope="colgroup"] {
+	text-align: center;
+	height: 24px;
+	border-bottom: 1px solid var(--border-subtle);
+	font-size: var(--size-xs);
+}
+.data-table-bar {
+	position: absolute;
+	height: 2px;
+	bottom: 8px;
+	border-radius: 2px;
+	background: var(--border-accent);
+	opacity: 0.65;
+	pointer-events: none;
+}
+.data-table-value {
+	position: relative;
+	z-index: 1;
+}
+.data-table-note {
+	display: flex;
+	flex-wrap: wrap;
+	justify-content: space-between;
+	gap: 0.5rem;
+	padding: 0.6rem 1rem;
+	color: var(--text-muted);
+	border-top: 1px solid var(--border-subtle);
+	font-size: var(--size-xs);
+}
+.data-table-chips {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.5rem;
+	padding: 0 1rem 0.75rem;
+}
+.data-table-chips button {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.5rem;
+	padding: 0.2rem 0.5rem;
+	font-size: var(--size-xs);
+	color: var(--text-muted);
+	border: 1px solid var(--border-subtle);
+	border-radius: 5px;
+	cursor: pointer;
+	max-width: 100%;
+	overflow-wrap: anywhere;
+}
+.data-table-chips button:hover {
+	background: var(--surface-hover);
+	color: var(--text-heading);
+}
+.data-table-menu {
+	position: fixed;
+	z-index: 1000;
+	width: 260px;
+	max-width: calc(100vw - 16px);
+	overflow-y: auto;
+	background: var(--surface-card);
+	color: var(--text-body);
+	border: 1px solid var(--border-default);
+	border-radius: var(--radius-md);
+	box-shadow: var(--shadow-lg);
+	padding: 0.75rem;
+	font: var(--size-sm)/1.5 var(--font-core);
+}
+.data-table-menu-title {
+	font-weight: 600;
+	color: var(--text-heading);
+	padding: 0 4rem 0 0;
+	display: flex;
+	align-items: center;
+	min-height: 30px;
+}
+.data-table-menu button {
+	cursor: pointer;
+	border-radius: 5px;
+	padding: 0.4rem 0.5rem;
+}
+.data-table-menu button:hover,
+.data-table-menu button[aria-pressed="true"] {
+	background: var(--surface-hover);
+}
+.data-table-menu-sorting {
+	position: absolute;
+	top: 10px;
+	right: 10px;
+	display: flex;
+	gap: 2px;
+}
+.data-table-menu-sorting button {
+	width: 26px;
+	height: 26px;
+	padding: 0;
+	display: grid;
+	place-items: center;
+	font-size: 16px;
+}
+.data-table-menu label {
+	display: block;
+	color: var(--text-muted);
+	font-size: var(--size-xs);
+}
+.data-table-menu-filter {
+	padding: 0.4rem 0;
+}
+.data-table-menu input:not([type="checkbox"]),
+.data-table-menu select {
+	width: 100%;
+	min-width: 0;
+	display: block;
+	border: 1px solid var(--border-default);
+	background: var(--surface-card);
+	color: var(--text-body);
+	border-radius: 5px;
+	padding: 0.4rem 0.5rem;
+	margin-top: 0.35rem;
+	font-size: var(--size-sm);
+}
+.data-table-menu input:focus-visible,
+.data-table-menu select:focus-visible {
+	outline: none;
+	border-color: var(--border-accent);
+	box-shadow: 0 0 0 1px var(--border-accent);
+}
+.data-table-range {
+	display: flex;
+	gap: 0.5rem;
+}
+.data-table-range label {
+	flex: 1;
+	min-width: 0;
+}
+.data-table-menu-unit {
+	border-top: 1px solid var(--border-subtle);
+	padding-top: 0.65rem;
+}
+.data-table-clear {
+	color: var(--text-muted);
+	width: 100%;
+	text-align: left;
+	margin-top: 0.65rem;
+	font-size: var(--size-xs);
+}
+.data-table-error {
+	color: var(--status-danger-fg);
+	padding: 0.5rem;
+	font-size: var(--size-xs);
+}
+@media (pointer: coarse) {
+	.data-table-heading,
+	.data-table-menu button {
+		min-height: 44px;
+	}
+	.data-table-menu input:not([type="checkbox"]),
+	.data-table-menu select {
+		font-size: 16px;
+	}
+}
+
+.data-table-header-control {
+	display: flex;
+	align-items: stretch;
+	min-height: 36px;
+	position: relative;
+}
+.data-table-header-chevron {
+	flex: 0 0 28px;
+	display: grid;
+	place-items: center;
+	cursor: pointer;
+	color: var(--text-subtle);
+	padding-right: 8px;
+}
+.data-table-header-control:hover {
+	background: var(--surface-hover);
+}
+.data-table-header-chevron:hover {
+	color: var(--text-heading);
+}
+.data-table th[data-active="true"] .data-table-header-control {
+	background: var(--surface-accent-soft);
+}
+.data-table th[data-active="true"] .data-table-header-control::after {
+	content: "";
+	position: absolute;
+	inset: 0;
+	border: 1px solid var(--border-accent);
+	pointer-events: none;
+	z-index: 1;
+}
+.data-table-heading:focus-visible,
+.data-table-header-chevron:focus-visible {
+	outline: 0;
+	box-shadow: none;
+}
+@media (pointer: coarse) {
+	.data-table-header-chevron {
+		flex-basis: 40px;
+		min-height: 44px;
+	}
+	.data-table-menu-sorting button {
+		width: 40px;
+	}
+	.data-table-menu-title {
+		min-height: 44px;
+		padding-right: 5rem;
+	}
+}

package/client/block-state/README.md

@@ -0,0 +1,39 @@
+# Document block state
+
+Use this area for local preferences belonging to a block on a document page. App-wide
+preferences (theme, sidebar, listing order) have different scopes and stay in their own modules.
+
+```tsx
+const scope = useDocumentBlockScope({ kind: "chart", version: 1, blockId: id });
+const [state, setState] = useBlockState(scope, {
+	schema: chartStateSchema,
+	initialState: initialChartState,
+	normalize: (saved) => reconcileChartState(saved, series),
+});
+```
+
+Import the hooks from `./useBlockState` and storage helpers/types from `./storage`.
+
+- Keep `blockId` stable across edits and unique within the document. `kind` separates component
+  families; `version` identifies the persisted format. The scope uses `DocContext.path`, with the
+  browser pathname as a fallback for standalone pages.
+- Provide a schema with `safeParse` (Zod schemas work), a fresh default-state factory, and optional
+  pure normalization against current block props. State must be JSON-compatible. Validation
+  checks saved data; normalization handles changes to the block's current content or schema.
+- Server rendering and initial hydration use defaults. Storage is restored in an effect before
+  any state is saved. Changing scope loads that scope's preferences without exposing or saving
+  the old scope's state under the new key. The setter supports React-style functional updates.
+- Invalid saved data, blocked storage, and quota errors fall back to usable in-memory state.
+  Normalization runs before rendering and saving and is committed to memory, so removed
+  preferences do not reappear on later content edits. It may return a fresh object.
+- Set `persist: false` for blocks without an unambiguous identity. They retain in-memory
+  interaction but never read or write saved preferences.
+- For migrations, provide `legacyKeys(scope)`. Only a missing current key permits legacy reads;
+  a corrupt current value does not resurrect older preferences. Successful restoration is saved
+  under the new key. Legacy keys are left intact for compatibility with older app versions.
+- Use `blockStateKey(scope)` as a React key if transient UI state (open menus, focused cells)
+  should also reset when the scope changes. Persistence itself does not require a remount.
+
+`restoreBlockState` and `saveBlockState` accept a small storage interface for direct use and
+contract tests. They contain no component-specific knowledge. `useTableState` supplies table
+validation, column reconciliation, and the old table-key migration as one consumer of this API.

package/client/block-state/storage.ts

@@ -0,0 +1,73 @@
+/** Identity of a reusable block within a document. IDs should survive content edits. */
+export interface BlockStateScope {
+	documentPath: string;
+	blockId: string;
+	kind: string;
+	version: number;
+}
+
+export interface BlockStateSchema<State> {
+	safeParse(value: unknown): { success: true; data: State } | { success: false };
+}
+
+export type BlockStateStorage = Pick<Storage, "getItem" | "setItem">;
+
+/** Tuple encoding prevents separators inside paths or IDs from creating collisions. */
+export function blockStateKey(scope: BlockStateScope): string {
+	return `mdxserve:block:${JSON.stringify([scope.version, scope.kind, scope.documentPath, scope.blockId])}`;
+}
+
+export function browserBlockStorage(): BlockStateStorage | undefined {
+	try {
+		return typeof window === "undefined" ? undefined : window.localStorage;
+	} catch {
+		return undefined;
+	}
+}
+
+export function serializeBlockState<State>(state: State): string | undefined {
+	try {
+		return JSON.stringify(state);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Legacy keys are consulted only when the current key is absent. */
+export function restoreBlockState<State>(
+	storage: BlockStateStorage | undefined,
+	scope: BlockStateScope,
+	schema: BlockStateSchema<State>,
+	legacyKeys: readonly string[] = [],
+): State | undefined {
+	if (!storage) return undefined;
+
+	try {
+		for (const key of [blockStateKey(scope), ...legacyKeys]) {
+			const saved = storage.getItem(key);
+			if (saved === null) continue;
+
+			const parsed = schema.safeParse(JSON.parse(saved));
+			return parsed.success ? parsed.data : undefined;
+		}
+	} catch {
+		// Storage access and untrusted saved data must never prevent rendering a block.
+	}
+
+	return undefined;
+}
+
+export function saveBlockState<State>(
+	storage: BlockStateStorage | undefined,
+	scope: BlockStateScope,
+	state: State,
+): void {
+	const serialized = serializeBlockState(state);
+	if (!storage || serialized === undefined) return;
+
+	try {
+		storage.setItem(blockStateKey(scope), serialized);
+	} catch {
+		// Disabled storage and quota failures leave the block usable in memory.
+	}
+}

package/client/block-state/useBlockState.ts

@@ -0,0 +1,120 @@
+import {
+	useCallback,
+	useContext,
+	useEffect,
+	useRef,
+	useState,
+	type Dispatch,
+	type SetStateAction,
+} from "react";
+import { DocContext } from "../DocContext";
+import {
+	blockStateKey,
+	browserBlockStorage,
+	restoreBlockState,
+	saveBlockState,
+	serializeBlockState,
+	type BlockStateSchema,
+	type BlockStateScope,
+} from "./storage";
+
+export interface BlockStateOptions<State> {
+	schema: BlockStateSchema<State>;
+	persist?: boolean;
+	initialState: () => State;
+	normalize?: (state: State) => State;
+	legacyKeys?: (scope: BlockStateScope) => readonly string[];
+}
+
+interface StateSnapshot<State> {
+	key: string;
+	value: State;
+	loaded: boolean;
+}
+
+/** Standalone exports use their page path; SSR never touches browser globals. */
+export function useDocumentBlockScope(
+	block: Omit<BlockStateScope, "documentPath">,
+): BlockStateScope {
+	const context = useContext(DocContext);
+	const documentPath = context?.path ?? (typeof location === "undefined" ? "" : location.pathname);
+
+	return { ...block, documentPath };
+}
+
+/** Persist JSON-compatible block state after hydration, isolated by document and block identity. */
+export function useBlockState<State>(
+	scope: BlockStateScope,
+	options: BlockStateOptions<State>,
+): readonly [State, Dispatch<SetStateAction<State>>] {
+	const key = JSON.stringify([blockStateKey(scope), options.persist !== false]);
+	const latest = useRef({ scope, options, key });
+	latest.current = { scope, options, key };
+
+	const [snapshot, setSnapshot] = useState<StateSnapshot<State>>(() => ({
+		key,
+		value: options.initialState(),
+		loaded: false,
+	}));
+
+	// A scope change must not expose or persist the previous document's state while loading.
+	const current =
+		snapshot.key === key ? snapshot : { key, value: options.initialState(), loaded: false };
+	const normalized = options.normalize ? options.normalize(current.value) : current.value;
+
+	useEffect(() => {
+		const { scope: currentScope, options: currentOptions } = latest.current;
+		if (latest.current.key !== key) return;
+
+		const restored =
+			currentOptions.persist === false
+				? undefined
+				: restoreBlockState(
+						browserBlockStorage(),
+						currentScope,
+						currentOptions.schema,
+						currentOptions.legacyKeys?.(currentScope),
+					);
+
+		setSnapshot({
+			key,
+			value: restored === undefined ? currentOptions.initialState() : restored,
+			loaded: true,
+		});
+	}, [key]);
+
+	useEffect(() => {
+		if (!current.loaded || latest.current.key !== key) return;
+
+		// Commit reconciliation so removed preferences cannot return on later schema edits.
+		setSnapshot((previous) => {
+			if (
+				previous.key !== key ||
+				serializeBlockState(previous.value) === serializeBlockState(normalized)
+			)
+				return previous;
+			return { ...previous, value: normalized };
+		});
+		if (latest.current.options.persist !== false)
+			saveBlockState(browserBlockStorage(), latest.current.scope, normalized);
+	}, [key, current.loaded, normalized]);
+
+	const setState = useCallback<Dispatch<SetStateAction<State>>>(
+		(update) => {
+			setSnapshot((previous) => {
+				if (latest.current.key !== key) return previous;
+
+				const currentOptions = latest.current.options;
+				const value = previous.key === key ? previous.value : currentOptions.initialState();
+				const reconciled = currentOptions.normalize ? currentOptions.normalize(value) : value;
+				const next =
+					typeof update === "function" ? (update as (state: State) => State)(reconciled) : update;
+
+				return { key, value: next, loaded: previous.key === key && previous.loaded };
+			});
+		},
+		[key],
+	);
+
+	return [normalized, setState];
+}