caracms 0.0.0-stage → 0.2.0

package/src/editor/client/collections/CollectionTable.tsx

@@ -0,0 +1,406 @@
+/**
+ * A flat collection as a table over the stage (pre-M7 polish; Rich's "table over the
+ * stage"): at a collection's level (Case studies, the Journal, Shared blocks) the
+ * stage shows its documents full width in place of the preview, which stays behind it.
+ *
+ * The head: the collection's name and count, a find box, a filter for each select,
+ * toggle or reference column, and **+ New**. The table: the title, then the columns the
+ * config picks (collections/table.ts). A column's header sorts by it (again: the other
+ * way); `aria-sort` says which. A list of references doesn't sort, so its header is a
+ * plain label (posts and tags, Decision 13). The view opens in the config's `sort`. A row opens its document in the editor (the row, or its
+ * title's button from the keyboard), and keeps the marks a sidebar row has: a file
+ * that can't be opened (it says why, and doesn't open), and in live mode the merge
+ * mark, someone's lock, presence and the waiting dot (live/marks.tsx). The open
+ * document's row is a wash with a ring, as the sidebar's (no side rails).
+ *
+ * The find, filters and order are one view with the sidebar's list (tableViewFor),
+ * so the two never disagree. Nothing loads: the rows are the listing the editor
+ * already has, field values included (entry.columns).
+ *
+ * M6c (G5): a collection whose documents can hold an image (its `view`, Decision 13)
+ * gets a List / Grid switch at the end of the tools row; Grid shows the same view's
+ * documents as cards (CollectionGrid.tsx), with an order select in place of the
+ * headers. The choice is the editor's, per collection, in the UI cookie (Decision 18;
+ * the config's `view.default` until they pick), so the view is right the moment it's drawn.
+ */
+import { Fragment, useMemo, type KeyboardEvent, type MouseEvent } from 'react';
+import { useEditor, useStore } from '../context.tsx';
+import type { Editor } from '../editor.ts';
+import { createStore, type Store } from '../state/store.ts';
+import { Icon } from '../shell/Icons.tsx';
+import { docIcon } from '../nav/DocRow.tsx';
+import { DocMarksView } from '../live/marks.tsx';
+import { when } from '../live/format.ts';
+import { openDialog } from '../documents/dialogs.tsx';
+import { PAGELESS_SUB, singular } from '../documents/actions.ts';
+import { usedOnLine } from '../block-list/summary.ts';
+import { docId, type EditorAnyCollection, type ListedDocument } from '../../types.ts';
+import { captionColumns, cellText, cellValue, defaultView, filterable, MISSING, nextSort, orderOptions, orderValue, refIndex, refParts, sortable, tableColumns, viewRows, type FilterValue, type RefIndex, type TableColumn, type TableView } from './table.ts';
+import { useCollection } from '../fields/ReferenceField.tsx';
+import { CollectionGrid } from './CollectionGrid.tsx';
+import { viewModeOf } from '../../ui-state.ts';
+import type { ViewMode } from '../../types.ts';
+
+const views = new WeakMap<Editor, Store<Record<string, TableView>>>();
+
+/** The editor's table views, one per collection: kept while the editor runs, so going back finds it as left. */
+export function tableViewsFor(editor: Editor): Store<Record<string, TableView>> {
+	let store = views.get(editor);
+	if (!store) views.set(editor, (store = createStore<Record<string, TableView>>({})));
+	return store;
+}
+
+/** One collection's view, and a way to change it. It opens in the config's `sort` (Decision 13), else the title A to Z. */
+export function useTableView(name: string): [TableView, (patch: Partial<TableView>) => void] {
+	const editor = useEditor();
+	const store = tableViewsFor(editor);
+	const sort = editor.site.collections.find((c) => c.name === name)?.sort;
+	const view = useStore(store, (all) => all[name]) ?? defaultView(sort);
+	const update = (patch: Partial<TableView>) => store.set((all) => ({ ...all, [name]: { ...(all[name] ?? defaultView(sort)), ...patch } }));
+	return [view, update];
+}
+
+/** Every listed document by collection and path, for reference columns (table.ts → refIndex). */
+export function useRefIndex(): RefIndex {
+	const editor = useEditor();
+	const documents = useStore(editor.documents);
+	return useMemo(() => refIndex(documents), [documents]);
+}
+
+/** The collection's table, when the stage shows one: a flat collection at its own level. */
+export function useTableCollection(): EditorAnyCollection | null {
+	const editor = useEditor();
+	const name = useStore(editor.view, (v) => (v.level === 'collection' ? v.collection : null));
+	const collection = name ? editor.site.collections.find((c) => c.name === name) : undefined;
+	return collection && !collection.nested ? collection : null;
+}
+
+/** M6c (G5): the view a collection shows, list or grid; always list without the switch (Decision 13). */
+export function useViewMode(collection: EditorAnyCollection): ViewMode {
+	const editor = useEditor();
+	const view = collection.kind === 'shared' ? null : collection.view;
+	return useStore(editor.ui, (ui) => (view ? viewModeOf(ui, collection.name, view.default) : 'list'));
+}
+
+const openDoc = (editor: Editor, doc: ListedDocument) => {
+	if (doc.warning) {
+		editor.announce(`${doc.label} can't be opened. ${doc.warning.message}`);
+		return;
+	}
+	void editor.openDocument({ collection: doc.collection, path: doc.path });
+};
+
+export function CollectionTable({ collection }: { collection: EditorAnyCollection }) {
+	const editor = useEditor();
+	const documents = useStore(editor.documents);
+	const currentId = useStore(editor.doc.state, (s) => docId(s.ref));
+	const readOnly = useStore(editor.access, (a) => !!a.signedOut);
+	const [view, update] = useTableView(collection.name);
+	const columns = tableColumns(collection);
+	const refs = useRefIndex();
+	const docs = documents.filter((d) => d.collection === collection.name);
+	const rows = viewRows(docs, columns, view, refs);
+	const shared = collection.kind === 'shared';
+	const one = singular(collection);
+	const create = () => openDialog(editor, shared ? { kind: 'new-shared' } : { kind: 'new', collection: collection.name });
+	const now = new Date().toISOString();
+	const zone = editor.timeZone();
+	const edited = (ms: number) => when(new Date(ms).toISOString(), zone, now);
+	const filters = filterable(columns);
+	const filtered = view.query.trim() !== '' || Object.keys(view.filters).length > 0;
+	const mode = useViewMode(collection);
+	const switches = !!collection.view && !shared;
+	const grid = mode === 'grid';
+	const orders = grid ? orderOptions(columns, view.sort) : [];
+
+	const setFilter = (key: string, value: FilterValue | null) => {
+		const next = { ...view.filters };
+		if (value === null) delete next[key];
+		else next[key] = value;
+		update({ filters: next });
+	};
+
+	return (
+		<div className="ctable" role="region" aria-label={`${collection.label}, as ${grid ? 'a grid' : 'a table'}`} data-collection-table={collection.name} data-view={mode}>
+			<div className="ct-head">
+				<div className="ct-title">
+					<Icon name={docIcon(collection)} />
+					<h2>{collection.label}</h2>
+					<span className="n-chip">{filtered ? `${rows.length} of ${docs.length}` : docs.length}</span>
+					{shared ? null : collection.urlBase === null ? <span className="ct-sub">{PAGELESS_SUB}</span> : <span className="ct-sub mono">{`${editor.site.host}${collection.urlBase}…`}</span>}
+				</div>
+				<button type="button" className="btn sm" data-act="table-new" disabled={readOnly} onClick={create}>
+					<Icon name="plus" size="sm" />
+					{shared ? 'New shared block' : `New ${one}`}
+				</button>
+				{docs.length > 0 ? (
+					<div className="ct-tools">
+						<div className="find">
+							<Icon name="search" />
+							<input
+								className="input"
+								type="search"
+								placeholder={shared ? 'Find a shared block' : `Find in ${collection.label}`}
+								aria-label={shared ? 'Find a shared block' : `Find in ${collection.label}`}
+								data-filter="table"
+								autoComplete="off"
+								spellCheck={false}
+								value={view.query}
+								onChange={(e) => update({ query: e.target.value })}
+								onKeyDown={(e) => {
+									if (e.key === 'Escape' && view.query) {
+										e.preventDefault();
+										update({ query: '' });
+									}
+								}}
+							/>
+						</div>
+						{filters.map((c) => (
+							<FilterSelect key={c.key} column={c} value={view.filters[c.key]} onChange={(v) => setFilter(c.key, v)} />
+						))}
+						{grid ? (
+							<select
+								className="input ct-filter ct-order"
+								aria-label="Order"
+								data-order=""
+								value={orderValue(view.sort)}
+								onChange={(e) => {
+									const picked = orders.find((o) => o.value === e.target.value);
+									if (picked) update({ sort: picked.sort });
+								}}
+							>
+								{orders.map((o) => (
+									<option key={o.value} value={o.value}>
+										Order: {o.label}
+									</option>
+								))}
+							</select>
+						) : null}
+						{switches ? (
+							<div className="mini-seg ct-view" role="radiogroup" aria-label="Show as">
+								{(['list', 'grid'] as const).map((m) => (
+									<button
+										key={m}
+										type="button"
+										role="radio"
+										aria-checked={mode === m}
+										data-view-mode={m}
+										onClick={() => editor.setViewMode(collection.name, m)}
+									>
+										<Icon name={m} size="sm" />
+										{m === 'list' ? 'List' : 'Grid'}
+									</button>
+								))}
+							</div>
+						) : null}
+					</div>
+				) : null}
+			</div>
+			{docs.length === 0 ? (
+				<div className="empty ct-empty" data-empty="collection-table">
+					<b>{shared ? 'No shared blocks yet' : `Nothing in ${collection.label} yet`}</b>
+					{!shared && collection.urlBase === null ? <span>No pages of their own.</span> : null}
+				</div>
+			) : (
+				<div className="ct-scroll">
+					{grid ? (
+						rows.length > 0 ? <CollectionGrid collection={collection} rows={rows} captions={captionColumns(collection, columns)} currentId={currentId} edited={edited} refs={refs} open={(d) => openDoc(editor, d)} /> : null
+					) : (
+						<table className="ct">
+							<thead>
+								<tr>
+									{columns.map((c) => {
+										const on = view.sort.key === c.key;
+										if (!sortable(c)) {
+											return (
+												<th key={c.key} scope="col" className={`ct-${c.kind}`}>
+													<span className="ct-sort ct-label">{c.label}</span>
+												</th>
+											);
+										}
+										return (
+											<th key={c.key} scope="col" className={`ct-${c.kind}`} aria-sort={on ? (view.sort.dir === 'asc' ? 'ascending' : 'descending') : undefined}>
+												<button type="button" className={`ct-sort${on ? ' on' : ''}`} onClick={() => update({ sort: nextSort(view.sort, c.key) })}>
+													<span>{c.label}</span>
+													<Icon name={on && view.sort.dir === 'desc' ? 'down' : 'up'} size="xs" />
+												</button>
+											</th>
+										);
+									})}
+								</tr>
+							</thead>
+							<tbody>
+								{rows.map((d) => (
+									<Row key={d.path} doc={d} columns={columns} current={docId(d) === currentId} edited={edited} refs={refs} extra={shared ? usedOnLine(d) : null} />
+								))}
+							</tbody>
+						</table>
+					)}
+					{rows.length === 0 ? (
+						<p className="no-hits ct-none" role="status">
+							<b>Nothing in {collection.label} matches</b>
+							<button type="button" className="linkbtn" onClick={() => update({ query: '', filters: {} })}>
+								Show all {docs.length}
+							</button>
+						</p>
+					) : null}
+				</div>
+			)}
+		</div>
+	);
+}
+
+function FilterSelect({ column, value, onChange }: { column: TableColumn; value: FilterValue | undefined; onChange: (value: FilterValue | null) => void }) {
+	if (column.kind === 'reference' || column.kind === 'references') return <RefFilterSelect column={column} value={value} onChange={onChange} />;
+	const field = column.field;
+	const options: { value: string; label: string }[] =
+		field?.kind === 'select'
+			? [{ value: '', label: `Any ${column.label.toLowerCase()}` }, ...field.options.map((o) => ({ value: `s:${o.value}`, label: o.label }))]
+			: [
+					{ value: '', label: `${column.label}: any` },
+					{ value: 'b:1', label: `${column.label}: on` },
+					{ value: 'b:0', label: `${column.label}: off` },
+				];
+	const current = value === undefined ? '' : typeof value === 'boolean' ? (value ? 'b:1' : 'b:0') : `s:${value}`;
+	return (
+		<select
+			className={`input ct-filter${value === undefined ? '' : ' is-set'}`}
+			aria-label={`Filter by ${column.label.toLowerCase()}`}
+			data-filter-key={column.key}
+			value={current}
+			onChange={(e) => {
+				const v = e.target.value;
+				onChange(v === '' ? null : v.startsWith('b:') ? v === 'b:1' : v.slice(2));
+			}}
+		>
+			{options.map((o) => (
+				<option key={o.value} value={o.value}>
+					{o.label}
+				</option>
+			))}
+		</select>
+	);
+}
+
+/**
+ * A reference column's filter (Decision 13): one referenced document, by title ("Tag:
+ * Print", the column's label as one of them), keeping the rows that point at it (for a list, among others). The options are
+ * the referenced collection's documents, in its listing order; a filter on one that's
+ * since gone stays listed, as Missing, so the select never lies.
+ */
+function RefFilterSelect({ column, value, onChange }: { column: TableColumn; value: FilterValue | undefined; onChange: (value: FilterValue | null) => void }) {
+	const { documents } = useCollection(column.to ?? '');
+	// "Tag: Print" for a list called Tags; a single reference by its own label ("Author: Ada").
+	const one = column.kind === 'references' ? singularLabel(column.label) : column.label;
+	const options = [{ value: '', label: `Any ${one.toLowerCase()}` }, ...documents.map((d) => ({ value: `r:${d.path}`, label: `${one}: ${d.label || d.title}` }))];
+	const current = value === undefined ? '' : `r:${String(value)}`;
+	if (value !== undefined && !options.some((o) => o.value === current)) options.push({ value: current, label: `${one}: ${MISSING}` });
+	return (
+		<select
+			className={`input ct-filter${value === undefined ? '' : ' is-set'}`}
+			aria-label={`Filter by ${one.toLowerCase()}`}
+			data-filter-key={column.key}
+			value={current}
+			onChange={(e) => onChange(e.target.value === '' ? null : e.target.value.slice(2))}
+		>
+			{options.map((o) => (
+				<option key={o.value} value={o.value}>
+					{o.label}
+				</option>
+			))}
+		</select>
+	);
+}
+
+/** A list's label as one of its items: "Tags" → "Tag", "Categories" → "Category". */
+const singularLabel = (label: string) => (/ies$/i.test(label) ? label.replace(/ies$/i, 'y') : /[^s]s$/i.test(label) ? label.slice(0, -1) : label);
+
+/** A reference cell (Decision 13): the title, or each of a list's joined by commas; one that's gone is "Missing", in the warning colour. */
+function RefCell({ doc, column, refs }: { doc: ListedDocument; column: TableColumn; refs: RefIndex }) {
+	const parts = refParts(doc, column, refs);
+	if (parts.length === 0) {
+		return (
+			<td className={`ct-${column.kind}`}>
+				<span className="ct-nil" aria-label="None">–</span>
+			</td>
+		);
+	}
+	return (
+		<td className={`ct-${column.kind}`} title={cellText(doc, column, () => '', refs)}>
+			{parts.map((p, i) => (
+				<Fragment key={`${i}:${p.path}`}>
+					{i > 0 ? ', ' : null}
+					{p.title === null ? (
+						<span className="ct-missing" data-missing={p.path}>
+							{MISSING}
+						</span>
+					) : (
+						p.title
+					)}
+				</Fragment>
+			))}
+		</td>
+	);
+}
+
+function Row(props: { doc: ListedDocument; columns: readonly TableColumn[]; current: boolean; edited: (ms: number) => string; refs: RefIndex; extra: string | null }) {
+	const editor = useEditor();
+	const { doc } = props;
+	const open = () => openDoc(editor, doc);
+	const onClick = (event: MouseEvent) => {
+		// The title's own button handles its click; a selection being made isn't a click on the row.
+		if ((event.target as Element).closest('button') || String(window.getSelection() ?? '') !== '') return;
+		open();
+	};
+	const onKeyDown = (event: KeyboardEvent) => {
+		if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+			const row = (event.currentTarget as HTMLElement).closest('tr');
+			const next = (event.key === 'ArrowDown' ? row?.nextElementSibling : row?.previousElementSibling)?.querySelector<HTMLElement>('.ct-open');
+			if (next) {
+				event.preventDefault();
+				next.focus();
+			}
+		}
+	};
+	return (
+		<tr className={[props.current ? 'is-current' : '', doc.warning ? 'is-warned' : ''].filter(Boolean).join(' ') || undefined} data-doc={docId(doc)} onClick={onClick}>
+			{props.columns.map((c) => {
+				if (c.kind === 'title') {
+					return (
+						<th key={c.key} scope="row" className="ct-title-cell">
+							<button type="button" className="ct-open" aria-current={props.current ? 'page' : undefined} title={doc.warning?.message} onClick={open} onKeyDown={onKeyDown}>
+								<span className="nm">{doc.label}</span>
+							</button>
+							<span className="meta">
+								{doc.warning ? (
+									<span className="wmark" data-warning={doc.warning.code} title={doc.warning.message}>
+										<Icon name="warn" size="xs" />
+										<span className="sr">, can't be opened: {doc.warning.message}</span>
+									</span>
+								) : null}
+								{editor.mode === 'live' ? <DocMarksView file={doc.file} /> : <span data-slot="presence" hidden />}
+							</span>
+							{props.extra ? <span className="ct-extra">{props.extra}</span> : null}
+						</th>
+					);
+				}
+				if (c.kind === 'toggle') {
+					const on = cellValue(doc, c) === true;
+					return (
+						<td key={c.key} className="ct-toggle">
+							{on ? <Icon name="check" size="sm" /> : null}
+							<span className="sr">{on ? 'Yes' : 'No'}</span>
+						</td>
+					);
+				}
+				if (c.kind === 'reference' || c.kind === 'references') return <RefCell key={c.key} doc={doc} column={c} refs={props.refs} />;
+				const text = cellText(doc, c, props.edited);
+				return (
+					<td key={c.key} className={`ct-${c.kind}`}>
+						{text ? text : <span className="ct-nil" aria-label="None">–</span>}
+					</td>
+				);
+			})}
+		</tr>
+	);
+}

package/src/editor/client/collections/table.ts

@@ -0,0 +1,270 @@
+/**
+ * The collections table's rows and columns (pre-M7 polish: a flat collection's
+ * documents as a table over the stage). Pure, so the sidebar's list and the table
+ * read one view: the same find, filters and order.
+ *
+ * Columns: the title always, then what the collection's config names in `columns`
+ * (its fields, by key, and the two built-ins `address` and `edited`); without
+ * `columns`, the address and when it was last edited. A field column's values ride
+ * on each listed document (`entry.columns`, content.ts), so the table draws at once.
+ *
+ * Posts and tags (Decision 13): a section builder's page fields can be columns too,
+ * and two more kinds, for both collection kinds: a reference, shown as the referenced
+ * document's title ("Missing" when it's gone), and a list of references, its titles
+ * joined by commas. Titles come from the editor's listing of every collection (`RefIndex`).
+ *
+ * Filters: one per select, toggle, reference or list-of-references column, an exact
+ * match on its value (a reference's: the document's path; a list's: one of them).
+ * Sorting: by any column but a list of references, either way; documents without a
+ * value go last whichever way. The view starts in the config's `sort`, else the title A to Z.
+ */
+import type { Field, Fields } from '../../../fields.ts';
+import { titleCase } from '../../../fields.ts';
+import type { EditorAnyCollection, ListedDocument } from '../../types.ts';
+import { formatDay } from '../fields/date.ts';
+import { filterCollection } from '../nav/search.ts';
+import { DEFAULT_COLUMNS, columnKindOf, type SortConfig } from '../../../columns.ts';
+
+export type ColumnKind = 'title' | 'address' | 'edited' | 'text' | 'select' | 'toggle' | 'date' | 'number' | 'reference' | 'references';
+
+export interface TableColumn {
+	key: string;
+	label: string;
+	kind: ColumnKind;
+	field?: Field;
+	/** A reference or list-of-references column's: the collection its documents are in. */
+	to?: string;
+}
+
+/** The listed documents a reference can point at, by `collection` and `path` (refIndex). */
+export type RefIndex = ReadonlyMap<string, ListedDocument>;
+const refKey = (collection: string, path: string) => `${collection}:${path}`;
+
+/** Every listed document by collection and path, for reference columns' titles. */
+export function refIndex(documents: readonly ListedDocument[]): RefIndex {
+	return new Map(documents.map((d) => [refKey(d.collection, d.path), d]));
+}
+
+const NO_REFS: RefIndex = new Map();
+
+/** A reference column's paths for a document: one (a reference), or each of a list's; empty for none. */
+export function refPaths(doc: ListedDocument, column: TableColumn): string[] {
+	const v = doc.columns?.[column.key];
+	const paths = column.kind === 'reference' ? [v] : column.kind === 'references' && Array.isArray(v) ? v : [];
+	return paths.filter((p): p is string => typeof p === 'string' && p.trim() !== '').map((p) => p.trim());
+}
+
+/** One referenced document's title, or null when it's missing (gone from its collection). */
+export function refTitle(refs: RefIndex, column: TableColumn, path: string): string | null {
+	const doc = column.to ? refs.get(refKey(column.to, path)) : undefined;
+	return doc ? doc.label || doc.title : null;
+}
+
+/** A reference cell's parts, in order: each referenced document's title, or `missing`. */
+export function refParts(doc: ListedDocument, column: TableColumn, refs: RefIndex): { path: string; title: string | null }[] {
+	return refPaths(doc, column).map((path) => ({ path, title: refTitle(refs, column, path) }));
+}
+
+/** What a reference that's gone shows (in the warning colour). */
+export const MISSING = 'Missing';
+
+export type SortDir = 'asc' | 'desc';
+
+/** A filter's value: a select's option value, or a toggle's on/off. */
+export type FilterValue = string | boolean;
+
+export interface TableView {
+	query: string;
+	sort: { key: string; dir: SortDir };
+	filters: Record<string, FilterValue>;
+}
+
+/** A view as it opens: the config's sort (Decision 13), else the title A to Z. */
+export const defaultView = (sort?: SortConfig | null): TableView => ({ query: '', sort: sort ? { key: sort.column, dir: sort.order } : { key: 'title', dir: 'asc' }, filters: {} });
+
+export function tableColumns(collection: Pick<EditorAnyCollection, 'fields' | 'columns'> & { urlBase?: string | null }): TableColumn[] {
+	const fields: Fields = collection.fields ?? {};
+	const named = collection.columns ?? DEFAULT_COLUMNS;
+	const columns: TableColumn[] = [{ key: 'title', label: 'Title', kind: 'title' }];
+	for (const key of named) {
+		// Shared blocks have no address (no page of their own): no column for it.
+		if (key === 'address') {
+			if (collection.urlBase !== null) columns.push({ key, label: 'Address', kind: 'address' });
+		}
+		else if (key === 'edited') columns.push({ key, label: 'Last edited', kind: 'edited' });
+		else {
+			const field = fields[key];
+			const kind = field ? columnKindOf(field) : null;
+			if (!field || !kind) continue;
+			const to = field.kind === 'reference' ? field.to : field.kind === 'list' && field.item?.kind === 'reference' ? field.item.to : undefined;
+			columns.push({ key, label: field.label ?? titleCase(key), kind, field, ...(to ? { to } : {}) });
+		}
+	}
+	return columns;
+}
+
+/** A field column's stored value for a document (undefined when it has none). */
+const raw = (doc: ListedDocument, key: string): unknown => doc.columns?.[key];
+
+/**
+ * The value a column sorts and filters by: a string, number or boolean, or null (none).
+ * A reference's is its document's title (a missing one has none, so it sorts last); a
+ * list of references' is its titles joined (it doesn't sort, and filters by refPaths).
+ */
+export function cellValue(doc: ListedDocument, column: TableColumn, refs: RefIndex = NO_REFS): string | number | boolean | null {
+	switch (column.kind) {
+		case 'reference':
+		case 'references': {
+			const titles = refParts(doc, column, refs).flatMap((p) => (p.title === null ? [] : [p.title]));
+			return titles.length ? titles.join(', ') : null;
+		}
+		case 'title':
+			return doc.label;
+		case 'address':
+			return doc.url;
+		case 'edited':
+			return doc.mtimeMs;
+		case 'toggle': {
+			const v = raw(doc, column.key);
+			return typeof v === 'boolean' ? v : column.field?.kind === 'toggle' ? column.field.default : null;
+		}
+		case 'number': {
+			const v = raw(doc, column.key);
+			return typeof v === 'number' && Number.isFinite(v) ? v : null;
+		}
+		default: {
+			const v = raw(doc, column.key);
+			return typeof v === 'string' && v.trim() !== '' ? v : null;
+		}
+	}
+}
+
+/**
+ * What a cell shows, as text ('' for nothing). A toggle's is "Yes" or ''; the table
+ * draws it as a mark. `edited` writes a time (the editor's absolute times, live/format.ts → when).
+ */
+export function cellText(doc: ListedDocument, column: TableColumn, edited: (ms: number) => string, refs: RefIndex = NO_REFS): string {
+	if (column.kind === 'reference' || column.kind === 'references') return refParts(doc, column, refs).map((p) => p.title ?? MISSING).join(', ');
+	const v = cellValue(doc, column);
+	if (v === null) return '';
+	switch (column.kind) {
+		case 'select': {
+			const field = column.field;
+			return field?.kind === 'select' ? (field.options.find((o) => o.value === v)?.label ?? String(v)) : String(v);
+		}
+		case 'date':
+			return formatDay(v);
+		case 'toggle':
+			return v ? 'Yes' : '';
+		case 'edited':
+			return edited(v as number);
+		default:
+			return String(v);
+	}
+}
+
+const collator = new Intl.Collator('en', { numeric: true, sensitivity: 'base' });
+
+function compare(a: string | number | boolean, b: string | number | boolean): number {
+	if (typeof a === 'string' && typeof b === 'string') return collator.compare(a, b);
+	if (typeof a === 'boolean' && typeof b === 'boolean') return a === b ? 0 : a ? -1 : 1; // on first
+	return Number(a) - Number(b);
+}
+
+/** The documents in the view's order: by its column either way, the title breaking ties; no value last. */
+export function sortRows(docs: readonly ListedDocument[], columns: readonly TableColumn[], sort: TableView['sort'], refs: RefIndex = NO_REFS): ListedDocument[] {
+	// A list of references doesn't order (Decision 13): the title does instead.
+	const column = columns.find((c) => c.key === sort.key && sortable(c)) ?? columns[0]!;
+	const title = columns[0]!;
+	const sign = sort.dir === 'asc' ? 1 : -1;
+	return [...docs].sort((x, y) => {
+		const a = cellValue(x, column, refs);
+		const b = cellValue(y, column, refs);
+		if (a === null || b === null) {
+			if (a !== b) return a === null ? 1 : -1;
+		} else {
+			const c = compare(a, b);
+			if (c !== 0) return sign * c;
+		}
+		return collator.compare(String(cellValue(x, title)), String(cellValue(y, title)));
+	});
+}
+
+/** Whether a column's header sorts: every column but a list of references. */
+export const sortable = (column: TableColumn) => column.kind !== 'references';
+
+const isFilterable = (c: TableColumn) => c.kind === 'select' || c.kind === 'toggle' || c.kind === 'reference' || c.kind === 'references';
+
+/** The columns a filter can be set on: select, toggle, reference and list-of-references columns. */
+export const filterable = (columns: readonly TableColumn[]) => columns.filter(isFilterable);
+
+/** Whether a document passes a column's filter: its value, or for a reference column, one of its paths. */
+function matches(doc: ListedDocument, column: TableColumn, want: FilterValue): boolean {
+	if (column.kind === 'reference' || column.kind === 'references') return refPaths(doc, column).includes(String(want));
+	return cellValue(doc, column) === want;
+}
+
+/** The view's documents: found (filterCollection), filtered, in order. */
+export function viewRows(docs: readonly ListedDocument[], columns: readonly TableColumn[], view: TableView, refs: RefIndex = NO_REFS): ListedDocument[] {
+	const byFilter = Object.entries(view.filters).flatMap(([key, want]) => {
+		const column = columns.find((c) => c.key === key && isFilterable(c));
+		return column ? [[column, want] as const] : [];
+	});
+	const found = filterCollection(view.query, docs).filter((d) => byFilter.every(([column, want]) => matches(d, column, want)));
+	return sortRows(found, columns, view.sort, refs);
+}
+
+/** The next sort for a click on a column's header: that column ascending, or the other way when it's already the sort. */
+export const nextSort = (sort: TableView['sort'], key: string): TableView['sort'] => (sort.key === key ? { key, dir: sort.dir === 'asc' ? 'desc' : 'asc' } : { key, dir: 'asc' });
+
+// ── M6c (G5): the grid view ───────────────────────────────────────────────────
+
+export interface OrderOption {
+	value: string;
+	label: string;
+	sort: TableView['sort'];
+}
+
+/** A sort's `<option>` value: `<key>:<dir>`. */
+export const orderValue = (sort: TableView['sort']) => `${sort.key}:${sort.dir}`;
+
+/**
+ * Grid's order select (it has no headers to click, Decision 16): the title either way,
+ * then each column in the words its kind reads in (dates newest or oldest first,
+ * numbers lowest or highest, text and choices A to Z). A toggle doesn't order a grid.
+ * The view's sort is always one of them, set from List's headers or not, so the select
+ * never lies about the order.
+ */
+export function orderOptions(columns: readonly TableColumn[], current: TableView['sort']): OrderOption[] {
+	const out: OrderOption[] = [];
+	const add = (column: TableColumn, dir: SortDir, words: string) => out.push({ value: orderValue({ key: column.key, dir }), label: `${column.label}, ${words}`, sort: { key: column.key, dir } });
+	for (const c of columns) {
+		if (c.kind === 'toggle' || c.kind === 'references') continue;
+		if (c.kind === 'title') {
+			add(c, 'asc', 'A to Z');
+			add(c, 'desc', 'Z to A');
+		} else if (c.kind === 'date' || c.kind === 'edited') {
+			add(c, 'desc', 'newest first');
+			add(c, 'asc', 'oldest first');
+		} else if (c.kind === 'number') {
+			add(c, 'asc', 'lowest first');
+			add(c, 'desc', 'highest first');
+		} else add(c, 'asc', 'A to Z');
+	}
+	if (!out.some((o) => o.value === orderValue(current))) {
+		const column = columns.find((c) => c.key === current.key);
+		if (column) out.push({ value: orderValue(current), label: `${column.label}, ${current.dir === 'asc' ? 'A to Z' : 'Z to A'}`, sort: current });
+	}
+	return out;
+}
+
+/**
+ * A card's captions (Decision 16): up to two of the configured columns after the
+ * title, as the table formats them; a toggle has no words, so it's skipped. A section
+ * builder whose columns are the built-ins: its card says when it was last edited. One
+ * whose columns name page fields (posts and tags, Decision 13) captions as a list of fields does.
+ */
+export function captionColumns(collection: Pick<EditorAnyCollection, 'kind'>, columns: readonly TableColumn[]): TableColumn[] {
+	if (collection.kind === 'sections' && !columns.some((c) => c.field)) return [columns.find((c) => c.kind === 'edited') ?? { key: 'edited', label: 'Last edited', kind: 'edited' }];
+	return columns.filter((c) => c.kind !== 'title' && c.kind !== 'toggle').slice(0, 2);
+}