@orkestrel/table 0.0.8 → 0.0.10

package/dist/src/browser/index.js

@@ -0,0 +1,1058 @@
+import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isInstance, isRecord, isString, parseJSON, parseNumber, readArrayEntries, recordOf } from "@orkestrel/contract";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/browser/errors.ts
+/** Represents a native table binding failure with a machine-readable code. */
+var TableBindingError = class extends Error {
+	code;
+	/** Creates a binding failure.
+	* @param code - The failed boundary.
+	* @param message - The explanation.
+	*/
+	constructor(code, message) {
+		super(message);
+		this.name = "TableBindingError";
+		this.code = code;
+	}
+};
+/** Checks whether a caught value is a native table binding error.
+* @param value - The caught value.
+* @returns Whether the value is a binding error.
+*/
+function isTableBindingError(value) {
+	return isInstance(value, TableBindingError);
+}
+//#endregion
+//#region src/core/errors.ts
+/**
+* Represents an error raised by the table domain — a machine-readable `code` and optional
+* structured `context`.
+*/
+var TableError = class extends Error {
+	/** Holds the machine-readable reason for this failure. */
+	code;
+	/** Holds structured values that locate or explain this failure. */
+	context;
+	/**
+	* Creates a table error.
+	*
+	* @param code - The machine-readable reason.
+	* @param message - The human-readable failure text.
+	* @param context - Optional structured failure details.
+	*/
+	constructor(code, message, context) {
+		super(message);
+		this.name = "TableError";
+		this.code = code;
+		if (context !== void 0) this.context = context;
+	}
+};
+//#endregion
+//#region src/core/cloners.ts
+/**
+* Clones one row into an owned frozen snapshot.
+*
+* @param row - The row to own.
+* @returns A frozen copy of the row's cells.
+*/
+function cloneRow(row) {
+	return Object.freeze({ ...row });
+}
+//#endregion
+//#region src/core/constants.ts
+/** Lists every column cell, in the order declared by the public contract. */
+var COLUMN_CELLS = Object.freeze([
+	"text",
+	"number",
+	"flag",
+	"choice"
+]);
+/** Names the maximum number of choices one `choice` column may offer: 1024. */
+var CHOICE_LIMIT = 1024;
+/** Names the maximum length of any single retained string: 65536 UTF-16 code units. */
+var STRING_LIMIT = 65536;
+/**
+* Names the maximum total length of every string one schema retains: 1048576 UTF-16 code units.
+*/
+var TEXT_LIMIT = 1048576;
+/** Names the maximum total number of records, arrays, and leaves one schema retains: 16384. */
+var NODE_LIMIT = 16384;
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Finds one column by key; `undefined` when the schema declares no such column.
+*
+* @param schema - The schema whose columns to search.
+* @param key - The column key to find.
+* @returns The declared column, or `undefined` when no column has that key.
+*/
+function extractColumn(schema, key) {
+	return schema.columns.find((column) => column.key === key);
+}
+/**
+* Reads one row's declared identity; `undefined` when its key cell is missing, empty, or not a
+* string.
+*
+* @param schema - The schema that names the identity column.
+* @param row - The row whose identity to read.
+* @returns The non-empty string identity, or `undefined` when it is unusable.
+*/
+function extractKey(schema, row) {
+	if (!Object.hasOwn(row, schema.key)) return void 0;
+	const key = row[schema.key];
+	return isString(key) && key.length > 0 ? key : void 0;
+}
+/**
+* Checks whether one column can hold a value — the shape gate every write and every seed passes
+* through.
+*
+* @param column - The column that owns the cell.
+* @param value - The unknown value to inspect.
+* @returns True if the column can hold the value; false otherwise.
+*/
+function matchesCell(column, value) {
+	if (isString(value) && value.length > 65536) return false;
+	switch (column.cell) {
+		case "text": return isString(value);
+		case "number": return isFiniteNumber(value);
+		case "flag": return isBoolean(value);
+		case "choice": return isString(value) && column.choices.some((choice) => choice.value === value);
+	}
+}
+/**
+* Audits a structurally valid schema for domain faults and budget breaches, returning human
+* diagnostics.
+*
+* @param schema - The table schema to audit.
+* @returns Frozen human-readable diagnostics, or an empty list when the schema is sound.
+*/
+function auditTable(schema) {
+	const faults = [];
+	const columns = /* @__PURE__ */ new Set();
+	let choiceExceeded;
+	let nameExceeded = schema.name !== void 0 && schema.name.length > 128;
+	if (schema.columns.length > 256) faults.push(`schema declares more than 256 columns`);
+	const columnCount = Math.min(schema.columns.length, 257);
+	for (let index = 0; index < columnCount; index += 1) {
+		const column = schema.columns[index];
+		if (column === void 0) continue;
+		if (column.key.length > 128) nameExceeded = true;
+		if (choiceExceeded === void 0 && column.cell === "choice" && column.choices.length > 1024) choiceExceeded = column.key;
+	}
+	if (choiceExceeded !== void 0) faults.push(`column "${choiceExceeded}" offers more than ${CHOICE_LIMIT} choices`);
+	if (nameExceeded) faults.push(`schema contains a name longer than 128`);
+	const pending = [schema];
+	const metadata = [false];
+	let position = 0;
+	let stringExceeded = false;
+	let textExceeded = false;
+	let nodeExceeded = false;
+	let text = 0;
+	while (position < pending.length) {
+		const node = pending[position];
+		const inMeta = metadata[position] === true;
+		position += 1;
+		if (isString(node)) {
+			if (node.length > 65536) stringExceeded = true;
+			text = Math.min(TEXT_LIMIT + 1, text + node.length);
+			if (text > 1048576) textExceeded = true;
+			continue;
+		}
+		if (isArray(node)) {
+			const read = readArrayEntries(node);
+			if (!read.success || !read.value.dense) continue;
+			for (const entry of read.value.entries) {
+				if (pending.length >= 16384) {
+					nodeExceeded = true;
+					continue;
+				}
+				pending.push(entry);
+				metadata.push(inMeta);
+			}
+			continue;
+		}
+		if (!isRecord(node)) continue;
+		const keys = attempt(() => Object.keys(node));
+		if (!keys.success) continue;
+		for (const key of keys.value) {
+			if (inMeta) {
+				if (key.length > 65536) stringExceeded = true;
+				text = Math.min(TEXT_LIMIT + 1, text + key.length);
+				if (text > 1048576) textExceeded = true;
+			}
+			const value = attempt(() => node[key]);
+			if (!value.success || value.value === void 0) continue;
+			if (pending.length >= 16384) {
+				nodeExceeded = true;
+				continue;
+			}
+			pending.push(value.value);
+			metadata.push(inMeta || key === "meta");
+		}
+	}
+	if (stringExceeded) faults.push(`schema contains a string longer than ${STRING_LIMIT}`);
+	if (textExceeded) faults.push(`schema retains more than ${TEXT_LIMIT} string code units`);
+	if (nodeExceeded) faults.push(`schema retains more than ${NODE_LIMIT} nodes`);
+	for (let index = 0; index < columnCount; index += 1) {
+		const column = schema.columns[index];
+		if (column === void 0) continue;
+		if (!nodeExceeded && column.meta !== void 0) {
+			if (!attempt(() => cloneJSONRecord(column.meta)).success) faults.push(`column "${column.key}" has metadata that cannot be owned`);
+		}
+		if (column.key.length === 0) faults.push("column \"\" has an empty key");
+		if (columns.has(column.key)) faults.push(`column "${column.key}" is declared more than once`);
+		columns.add(column.key);
+		if (column.cell === "choice") {
+			const choices = /* @__PURE__ */ new Set();
+			const choiceCount = Math.min(column.choices.length, CHOICE_LIMIT + 1);
+			for (let choiceIndex = 0; choiceIndex < choiceCount; choiceIndex += 1) {
+				const choice = column.choices[choiceIndex];
+				if (choice === void 0) continue;
+				if (choices.has(choice.value)) faults.push(`column "${column.key}" offers choice "${choice.value}" more than once`);
+				choices.add(choice.value);
+			}
+			if (column.choices.length === 0) faults.push(`column "${column.key}" offers no choices`);
+		}
+	}
+	const key = extractColumn(schema, schema.key);
+	if (key === void 0) faults.push(`schema key "${schema.key}" names no declared column`);
+	else if (key.cell === "number" || key.cell === "flag") faults.push(`schema key "${schema.key}" names a ${key.cell} column, which holds no identity`);
+	return Object.freeze(faults);
+}
+/**
+* Projects a schema into JSON in declaration order, dropping every absent member; raises `SCHEMA`
+* for a `meta` it cannot own.
+*
+* @param schema - The schema to project.
+* @returns A deeply owned JSON record with absent members omitted.
+* @throws A {@link TableError} coded `SCHEMA` when metadata cannot be owned.
+*/
+function serializeTable(schema) {
+	const output = {};
+	if (schema.name !== void 0) output.name = schema.name;
+	if (schema.label !== void 0) output.label = schema.label;
+	if (schema.help !== void 0) output.help = schema.help;
+	output.key = schema.key;
+	output.columns = schema.columns.map((column) => {
+		const entry = {
+			cell: column.cell,
+			key: column.key
+		};
+		if (column.label !== void 0) entry.label = column.label;
+		if (column.help !== void 0) entry.help = column.help;
+		if (column.hidden !== void 0) entry.hidden = column.hidden;
+		if (column.meta !== void 0) entry.meta = column.meta;
+		if (column.cell === "choice") entry.choices = column.choices.map((choice) => {
+			const option = {
+				value: choice.value,
+				label: choice.label
+			};
+			if (choice.help !== void 0) option.help = choice.help;
+			return option;
+		});
+		return entry;
+	});
+	try {
+		return cloneJSONRecord(output);
+	} catch (error) {
+		if (!isContractError(error)) throw error;
+		throw new TableError("SCHEMA", "schema contains metadata that cannot be owned");
+	}
+}
+/** Compares complete row values independently of their snapshot identities.
+* @param left - The previous row, if present.
+* @param right - The next row.
+* @returns Whether both rows carry exactly the same cells.
+*/
+function matchesTableRow(left, right) {
+	return left !== void 0 && Object.keys(left).length === Object.keys(right).length && Object.keys(right).every((key) => Object.hasOwn(left, key) && left[key] === right[key]);
+}
+//#endregion
+//#region src/core/validators.ts
+/**
+* Determines whether an unknown value is a declared column cell.
+*
+* @param input - The value to inspect.
+* @returns True if the value is a declared column cell; false otherwise.
+*/
+function isColumnCell(input) {
+	return COLUMN_CELLS.some((cell) => cell === input);
+}
+/**
+* Determines whether an unknown value is one exact {@link ColumnChoice} record; an unknown member
+* refuses it.
+*
+* @param input - The value to inspect.
+* @returns True if the value is a column choice; false otherwise.
+*/
+function isColumnChoice(input) {
+	const outcome = attempt(() => {
+		if (!isRecord(input) || !Reflect.ownKeys(input).every((key) => isString(key))) return false;
+		return recordOf({
+			value: isString,
+			label: isString,
+			help: isString
+		}, ["help"])(input);
+	});
+	return outcome.success && outcome.value;
+}
+/**
+* Determines whether an unknown value is one exact discriminated {@link TableColumn}, checked
+* against its cell's own options.
+*
+* @param input - The value to inspect.
+* @returns True if the value is a structurally valid table column; false otherwise.
+*/
+function isTableColumn(input) {
+	const outcome = attempt(() => {
+		if (!isRecord(input) || !Object.hasOwn(input, "cell") || !Object.hasOwn(input, "key")) return false;
+		const cell = input.cell;
+		if (!isColumnCell(cell)) return false;
+		if (!Reflect.ownKeys(input).every((key) => {
+			if (!isString(key)) return false;
+			if ([
+				"cell",
+				"key",
+				"label",
+				"help",
+				"hidden",
+				"meta"
+			].includes(key)) return true;
+			return cell === "choice" && key === "choices";
+		})) return false;
+		const key = input.key;
+		const hasLabel = Object.hasOwn(input, "label");
+		const label = hasLabel ? input.label : void 0;
+		const hasHelp = Object.hasOwn(input, "help");
+		const help = hasHelp ? input.help : void 0;
+		const hasHidden = Object.hasOwn(input, "hidden");
+		const hidden = hasHidden ? input.hidden : void 0;
+		const hasMeta = Object.hasOwn(input, "meta");
+		const meta = hasMeta ? input.meta : void 0;
+		if (hasMeta) {
+			if (!isBoundedJSONRecord(meta)) return false;
+			if (!attempt(() => cloneJSONRecord(meta)).success) return false;
+		}
+		if (!isString(key) || hasLabel && !isString(label) || hasHelp && !isString(help) || hasHidden && !isBoolean(hidden)) return false;
+		if (cell !== "choice") return !Object.hasOwn(input, "choices");
+		return Object.hasOwn(input, "choices") && arrayOf(isColumnChoice)(input.choices);
+	});
+	return outcome.success && outcome.value;
+}
+/**
+* Determines whether an unknown value has the exact shape of a {@link TableSchema} — the shape
+* alone, with no domain check.
+*
+* @param input - The value to inspect.
+* @returns True if the value has the exact structure of a table schema; false otherwise.
+*/
+function isStructuralTableSchema(input) {
+	const outcome = attempt(() => {
+		if (!isRecord(input) || !Reflect.ownKeys(input).every((key) => isString(key))) return false;
+		return recordOf({
+			name: isString,
+			label: isString,
+			help: isString,
+			key: isString,
+			columns: arrayOf(isTableColumn)
+		}, [
+			"name",
+			"label",
+			"help"
+		])(input);
+	});
+	return outcome.success && outcome.value;
+}
+/**
+* Determines whether an unknown value is a {@link TableSchema} a table can be opened against —
+* the exact shape, and an audit that finds nothing.
+*
+* @param input - The value to inspect.
+* @returns True if the value has valid structure, domain relationships, and
+*   budgets; false otherwise.
+*/
+function isTableSchema(input) {
+	const outcome = attempt(() => isStructuralTableSchema(input) && auditTable(input).length === 0);
+	return outcome.success && outcome.value;
+}
+//#endregion
+//#region src/core/parsers.ts
+/**
+* Parses unknown wire data into an owned, structurally valid, semantically sound table schema.
+*
+* @param input - The unknown schema value to parse.
+* @returns An owned table schema, or `undefined` on refusal.
+*/
+function parseTable(input) {
+	const outcome = attempt(() => {
+		if (!isTableSchema(input)) return void 0;
+		const projected = serializeTable(input);
+		return isTableSchema(projected) ? projected : void 0;
+	});
+	return outcome.success ? outcome.value : void 0;
+}
+/**
+* Parses unknown wire data into owned rows against one table schema, coercing a numeric string
+* and `'true'` / `'false'`.
+*
+* @param schema - The schema that declares the accepted keys and cell shapes.
+* @param input - The unknown row-list value to parse.
+* @returns Frozen owned rows, or `undefined` when any row is refused.
+*/
+function parseRows(schema, input) {
+	const outcome = attempt(() => {
+		if (!isTableSchema(schema) || !isArray(input)) return;
+		const read = readArrayEntries(input);
+		if (!read.success || !read.value.dense) return void 0;
+		const keys = /* @__PURE__ */ new Set();
+		const rows = [];
+		for (const candidate of read.value.entries) {
+			if (!isRecord(candidate)) return void 0;
+			const row = {};
+			for (const key of Reflect.ownKeys(candidate)) {
+				if (!isString(key) || !Object.hasOwn(candidate, key)) return void 0;
+				const column = extractColumn(schema, key);
+				if (column === void 0) return void 0;
+				const inputCell = candidate[key];
+				let cell = inputCell;
+				if (column.cell === "number" && isString(inputCell)) {
+					if (inputCell.length > 65536) return void 0;
+					cell = parseNumber(inputCell);
+				} else if (column.cell === "flag" && inputCell === "true") cell = true;
+				else if (column.cell === "flag" && inputCell === "false") cell = false;
+				if (!matchesCell(column, cell)) return void 0;
+				Object.defineProperty(row, key, {
+					value: cell,
+					enumerable: true,
+					configurable: true,
+					writable: true
+				});
+			}
+			const owned = cloneRow(row);
+			const key = extractKey(schema, owned);
+			if (key === void 0 || keys.has(key)) return void 0;
+			keys.add(key);
+			rows.push(owned);
+		}
+		return Object.freeze(rows);
+	});
+	return outcome.success ? outcome.value : void 0;
+}
+//#endregion
+//#region src/browser/helpers.ts
+/** Reads declared header metadata and explicit row keys into a validated core projection.
+* @param element - A native table with data-table-key naming its identity column.
+* @returns The schema and rows, validated together before any mutation.
+* @throws A binding error when metadata, identities, or cells are malformed.
+* @example
+* ```ts
+* import { createTable } from '@orkestrel/table'
+* import { readTable } from '@orkestrel/table/browser'
+* const element = document.createElement('table')
+* element.setAttribute('data-table-key', 'id')
+* element.innerHTML = '<thead><tr><th data-table-column="id" data-table-cell="text">Reference</th></tr></thead><tbody></tbody>'
+* const projection = readTable(element)
+* const table = createTable(projection.schema, { rows: projection.rows })
+* ```
+*/
+function readTable(element) {
+	const schema = readTableSchema(element);
+	return {
+		schema,
+		rows: readTableRows(schema, Array.from(element.tBodies[0]?.rows ?? []))
+	};
+}
+/** Reads and validates explicit native header metadata.
+* @param element - The table declaring its identity column and cell kinds.
+* @returns The core schema described by the native headers.
+*/
+function readTableSchema(element) {
+	const columns = Array.from(element.tHead?.querySelectorAll("th[data-table-column]") ?? []).filter((header) => header.closest("table") === element).map((header) => ({
+		key: header.getAttribute("data-table-column"),
+		cell: header.getAttribute("data-table-cell"),
+		label: header.textContent?.trim() ?? "",
+		...header.hasAttribute("data-table-choices") ? { choices: parseJSON(header.getAttribute("data-table-choices") ?? "") } : {}
+	}));
+	const schema = parseTable({
+		key: element.getAttribute("data-table-key"),
+		columns
+	});
+	if (schema === void 0 || element.tBodies.length !== 1) throw new TableBindingError("STRUCTURE", "Declare one body, an identity column, and valid header metadata");
+	return schema;
+}
+/** Reads explicit keys and declared direct cells against a core schema.
+* @param schema - The declared columns and identity column.
+* @param elements - Data rows belonging to one table, including retained detached rows.
+* @returns Validated rows in the supplied order.
+* @throws A binding error for duplicate keys, undeclared cells, or malformed values.
+*/
+function readTableRows(schema, elements) {
+	const rows = parseRows(schema, elements.map((element) => {
+		const cells = { [schema.key]: element.getAttribute("data-table-key") };
+		const seen = /* @__PURE__ */ new Set();
+		for (const cell of element.cells) {
+			const column = cell.getAttribute("data-table-column");
+			if (column === null) continue;
+			if (seen.has(column)) throw new TableBindingError("STRUCTURE", "A row repeats a declared cell");
+			seen.add(column);
+			const value = cell.querySelector("data[value], time[datetime]");
+			const text = value?.closest("table") === element.closest("table") ? value?.getAttribute("value") ?? value?.getAttribute("datetime") ?? "" : cell.textContent ?? "";
+			if (column === schema.key && text !== cells[schema.key]) throw new TableBindingError("STRUCTURE", "The identity cell disagrees with its row key");
+			Object.defineProperty(cells, column, {
+				value: text,
+				enumerable: true,
+				configurable: true
+			});
+		}
+		return cells;
+	}));
+	if (rows === void 0) throw new TableBindingError("STRUCTURE", "Native row keys or cells are invalid");
+	return rows;
+}
+//#endregion
+//#region src/browser/TableBinding.ts
+/** Retains keyed native rows while projecting every core table manager. */
+var TableBinding = class {
+	#element;
+	#document;
+	#options;
+	#body;
+	#scope;
+	#emitter;
+	#lifetime = new AbortController();
+	#observer;
+	#rows = /* @__PURE__ */ new Map();
+	#values = /* @__PURE__ */ new Map();
+	#details = /* @__PURE__ */ new Map();
+	#detailValues = /* @__PURE__ */ new Map();
+	#visible = /* @__PURE__ */ new Set();
+	#attributes = /* @__PURE__ */ new Map();
+	#checks = /* @__PURE__ */ new Map();
+	#controlValues = /* @__PURE__ */ new Map();
+	#schedule = this.#enqueue.bind(this);
+	#subscriptions = [];
+	#pending;
+	#announcement;
+	#range;
+	#rendering = false;
+	#requesting = false;
+	#records = [];
+	/** Creates a native binding over a borrowed document.
+	* @param element - The table whose body the binding owns.
+	* @param document - The core document retained by the caller.
+	* @param options - Row ownership, detail renderer, controls, and listeners.
+	*/
+	constructor(element, document, options = {}) {
+		if (element.tBodies.length !== 1 || document.destroyed) throw new TableBindingError("STRUCTURE", "Bind one table body to a live document");
+		const body = element.tBodies[0];
+		if (body === void 0) throw new TableBindingError("STRUCTURE", "The table has no body");
+		this.#element = element;
+		this.#document = document;
+		this.#options = { ...options };
+		this.#body = body;
+		this.#scope = options.scope ?? element;
+		if (!this.#scope.contains(element)) throw new TableBindingError("STRUCTURE", "The scope must contain the table");
+		this.#emitter = new Emitter({
+			...options.on === void 0 ? {} : { on: options.on },
+			...options.error === void 0 ? {} : { error: options.error }
+		});
+		this.#observer = new MutationObserver((records) => {
+			this.#records.push(...records);
+			this.#enqueue();
+		});
+		if (options.row === void 0) {
+			this.#validateSchema();
+			const elements = Array.from(body.rows);
+			const rows = readTableRows(document.schema, elements);
+			if (rows.length !== document.rows.rows().length || rows.some((row) => {
+				const key = extractKey(document.schema, row);
+				return key === void 0 || !matchesTableRow(document.rows.row(key), row);
+			})) throw new TableBindingError("STRUCTURE", "Authored rows must match the supplied document");
+			for (const [index, row] of rows.entries()) {
+				const key = extractKey(document.schema, row);
+				const node = elements[index];
+				if (key !== void 0 && node !== void 0) this.#rows.set(key, node);
+			}
+		} else if (body.rows.length > 0) throw new TableBindingError("STRUCTURE", "Model rendering requires an empty body");
+		for (const event of [
+			"write",
+			"remove",
+			"sort",
+			"filter",
+			"select",
+			"expand",
+			"paginate",
+			"clear"
+		]) {
+			document.emitter.on(event, this.#schedule);
+			this.#subscriptions.push(() => document.emitter.off(event, this.#schedule));
+		}
+		this.#scope.addEventListener("click", (event) => this.#click(event), { signal: this.#lifetime.signal });
+		this.#scope.addEventListener("change", (event) => this.#change(event), { signal: this.#lifetime.signal });
+		this.#observe();
+		this.refresh();
+	}
+	get element() {
+		return this.#element;
+	}
+	get document() {
+		return this.#document;
+	}
+	get destroyed() {
+		return this.#lifetime.signal.aborted;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	/** Reconciles native input and retries rendering against the current document. */
+	refresh() {
+		if (this.destroyed) return;
+		if (this.#rendering) {
+			this.#enqueue();
+			return;
+		}
+		if (this.#pending !== void 0) clearTimeout(this.#pending);
+		this.#pending = void 0;
+		this.#rendering = true;
+		const outcome = attempt(() => {
+			this.#records.push(...this.#observer.takeRecords());
+			if (this.#options.row === void 0 && this.#records.length > 0) this.#reconcile();
+			if (!this.destroyed) this.#render();
+		});
+		if (!outcome.success && !this.destroyed) this.#emitter.emit("error", outcome.error);
+		else if (!this.destroyed) this.#emitter.emit("render");
+		this.#rendering = false;
+	}
+	/** Releases native resources and restores authored state while retaining the core document. */
+	destroy() {
+		if (this.destroyed) return;
+		const active = this.#element.ownerDocument.activeElement;
+		const focused = active instanceof HTMLElement && [...this.#rows.values()].some((row) => row.contains(active)) ? active : void 0;
+		this.#lifetime.abort();
+		if (this.#pending !== void 0) clearTimeout(this.#pending);
+		this.#pending = void 0;
+		this.#observer.disconnect();
+		if (this.#announcement !== void 0) clearTimeout(this.#announcement);
+		this.#announcement = void 0;
+		for (const unsubscribe of this.#subscriptions) unsubscribe();
+		this.#subscriptions.length = 0;
+		for (const detail of this.#details.values()) detail.remove();
+		if (this.#options.row === void 0) for (const row of this.#document.rows.rows()) {
+			const key = extractKey(this.#document.schema, row);
+			const node = key === void 0 ? void 0 : this.#rows.get(key);
+			if (node !== void 0) this.#place(node, null);
+		}
+		for (const element of this.#attributes.keys()) this.#release(element);
+		for (const input of this.#checks.keys()) this.#release(input);
+		for (const [control, state] of this.#controlValues) if (control.value === state.value) control.value = state.original;
+		this.#restoreFocus(focused);
+		this.#rows.clear();
+		this.#values.clear();
+		this.#details.clear();
+		this.#detailValues.clear();
+		this.#attributes.clear();
+		this.#checks.clear();
+		this.#controlValues.clear();
+		this.#visible.clear();
+		this.#records = [];
+		this.#emitter.destroy();
+	}
+	#enqueue() {
+		if (this.destroyed || this.#pending !== void 0) return;
+		this.#pending = setTimeout(() => {
+			this.#pending = void 0;
+			this.refresh();
+		}, 0);
+	}
+	#observe() {
+		if (this.destroyed || this.#options.row !== void 0) return;
+		this.#records.push(...this.#observer.takeRecords());
+		this.#observer.disconnect();
+		this.#observer.observe(this.#element, {
+			childList: true,
+			characterData: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: [
+				"data-table-key",
+				"data-table-column",
+				"data-table-cell",
+				"data-table-choices",
+				"value",
+				"datetime"
+			]
+		});
+		for (const node of this.#rows.values()) if (node.parentElement !== this.#body) this.#observer.observe(node, {
+			childList: true,
+			characterData: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: [
+				"data-table-key",
+				"data-table-column",
+				"value",
+				"datetime"
+			]
+		});
+	}
+	#validateSchema() {
+		const schema = readTableSchema(this.#element);
+		if (schema.key !== this.#document.schema.key || schema.columns.length !== this.#document.schema.columns.length || schema.columns.some((column, index) => {
+			const declared = this.#document.schema.columns[index];
+			return declared?.key !== column.key || declared.cell !== column.cell || column.cell === "choice" && declared.cell === "choice" && JSON.stringify(column.choices) !== JSON.stringify(declared.choices);
+		})) throw new TableBindingError("STRUCTURE", "Header metadata must match the supplied schema");
+	}
+	#reconcile() {
+		this.#validateSchema();
+		const elements = Array.from(this.#rows).filter(([, node]) => !this.#visible.has(node) || node.parentElement === this.#body).map(([, node]) => node);
+		for (const node of this.#body.rows) if (!elements.includes(node) && !Array.from(this.#details.values()).includes(node)) elements.push(node);
+		const rows = readTableRows(this.#document.schema, elements);
+		this.#records = [];
+		const keys = new Set(this.#keys(rows));
+		const additions = [];
+		const replacements = [];
+		for (const row of rows) {
+			const key = extractKey(this.#document.schema, row);
+			if (key !== void 0 && this.#document.rows.row(key) === void 0) additions.push(row);
+			else replacements.push(row);
+		}
+		this.#document.rows.replace(replacements);
+		if (this.destroyed) return;
+		this.#document.rows.add(additions);
+		if (this.destroyed) return;
+		for (const key of this.#rows.keys()) if (!keys.has(key)) {
+			this.#document.rows.remove(key);
+			if (this.destroyed) return;
+		}
+		for (const [index, row] of rows.entries()) {
+			const key = extractKey(this.#document.schema, row);
+			const node = elements[index];
+			if (key !== void 0 && node !== void 0) this.#rows.set(key, node);
+		}
+	}
+	#render() {
+		const active = this.#element.ownerDocument.activeElement;
+		const focused = active instanceof HTMLElement && [...this.#rows.values(), ...this.#details.values()].some((row) => row.contains(active)) ? active : void 0;
+		const stored = this.#document.rows.rows();
+		const keys = new Set(this.#keys(stored));
+		for (const [key, node] of this.#rows) if (!keys.has(key)) {
+			this.#place(node);
+			this.#release(node);
+			const detail = this.#details.get(key);
+			if (detail !== void 0) this.#place(detail);
+			this.#rows.delete(key);
+			this.#values.delete(key);
+			this.#details.delete(key);
+			this.#detailValues.delete(key);
+		}
+		const view = this.#document.view;
+		const ordered = [];
+		for (const row of view) {
+			const key = extractKey(this.#document.schema, row);
+			if (key === void 0) continue;
+			let node = this.#rows.get(key);
+			if (node === void 0) {
+				if (this.#options.row === void 0) throw new TableBindingError("STRUCTURE", "An authored document row has no native row");
+				node = this.#element.ownerDocument.createElement("tr");
+				node.setAttribute("data-table-key", key);
+				this.#rows.set(key, node);
+			}
+			if (this.#options.row !== void 0 && !matchesTableRow(this.#values.get(key), row)) {
+				this.#options.row(node, row);
+				if (this.destroyed) return;
+				this.#values.set(key, row);
+			}
+			ordered.push(node);
+			const detail = this.#detail(key, row);
+			if (this.destroyed) return;
+			if (detail !== void 0) ordered.push(detail);
+			this.#controls(node, key, detail);
+		}
+		for (const node of [...this.#rows.values(), ...this.#details.values()]) if (!ordered.includes(node) && node.parentElement === this.#body) this.#place(node);
+		for (const [index, node] of ordered.entries()) if (this.#body.rows[index] !== node) this.#place(node, this.#body.rows[index] ?? null);
+		this.#visible.clear();
+		for (const node of this.#rows.values()) if (node.parentElement === this.#body) this.#visible.add(node);
+		this.#headers();
+		if (this.destroyed) return;
+		this.#pages(view);
+		if (this.destroyed) return;
+		this.#pager();
+		if (this.destroyed) return;
+		this.#restoreFocus(focused, true);
+		this.#observe();
+		if (this.#records.length > 0) this.#enqueue();
+	}
+	#restoreFocus(focused, hidden = false) {
+		if (focused !== void 0 && this.#element.ownerDocument.activeElement !== focused && (this.#element.ownerDocument.activeElement === this.#element.ownerDocument.body || this.#element.ownerDocument.activeElement === null)) {
+			if (focused.isConnected) focused.focus({ preventScroll: true });
+			else if (hidden) this.#focusTable();
+		}
+	}
+	#focusTable() {
+		this.#attribute(this.#element, "tabindex", "-1");
+		if (!this.#element.hasAttribute("aria-label") && !this.#element.hasAttribute("aria-labelledby") && this.#element.caption === null) this.#attribute(this.#element, "aria-label", this.#document.schema.label ?? "Table");
+		this.#element.focus({ preventScroll: true });
+	}
+	#detail(key, row) {
+		if (this.#options.detail === void 0 || !this.#document.expansion.keys.has(key)) return void 0;
+		let detail = this.#details.get(key);
+		if (detail === void 0) {
+			detail = this.#element.ownerDocument.createElement("tr");
+			detail.id = `table-detail-${crypto.randomUUID()}`;
+			detail.insertCell().colSpan = Math.max(1, this.#rows.get(key)?.cells.length ?? this.#document.schema.columns.length);
+			this.#details.set(key, detail);
+		}
+		if (!matchesTableRow(this.#detailValues.get(key), row)) {
+			this.#options.detail(detail, row);
+			if (!this.destroyed) this.#detailValues.set(key, row);
+		}
+		return detail;
+	}
+	#place(node, before) {
+		this.#records.push(...this.#observer.takeRecords());
+		this.#observer.disconnect();
+		if (before === void 0) node.remove();
+		else if (typeof this.#body.moveBefore === "function" && node.isConnected && this.#body.isConnected) this.#body.moveBefore(node, before);
+		else this.#body.insertBefore(node, before);
+		this.#observe();
+	}
+	#attribute(element, name, value) {
+		let attributes = this.#attributes.get(element);
+		if (attributes === void 0) {
+			attributes = /* @__PURE__ */ new Map();
+			this.#attributes.set(element, attributes);
+		}
+		const entry = attributes.get(name);
+		if (entry === void 0) attributes.set(name, {
+			original: element.getAttribute(name),
+			value
+		});
+		else entry.value = value;
+		if (value === null) element.removeAttribute(name);
+		else if (element.getAttribute(name) !== value) element.setAttribute(name, value);
+	}
+	#release(root) {
+		for (const [element, attributes] of this.#attributes) if (root.contains(element)) {
+			for (const [name, entry] of attributes) if (element.getAttribute(name) === entry.value) {
+				if (entry.original === null) element.removeAttribute(name);
+				else element.setAttribute(name, entry.original);
+			}
+			this.#attributes.delete(element);
+		}
+		for (const [input, state] of this.#checks) if (root.contains(input)) {
+			if (input.checked === state.value) input.checked = state.checked;
+			if (input.indeterminate === state.mixed) input.indeterminate = state.indeterminate;
+			this.#checks.delete(input);
+		}
+	}
+	#check(input, value, mixed) {
+		const state = this.#checks.get(input);
+		if (state === void 0) this.#checks.set(input, {
+			checked: input.checked,
+			indeterminate: input.indeterminate,
+			value,
+			mixed
+		});
+		else {
+			state.value = value;
+			state.mixed = mixed;
+		}
+		input.checked = value;
+		input.indeterminate = mixed;
+	}
+	#controls(node, key, detail) {
+		const table = node.closest("table");
+		for (const input of node.querySelectorAll("input[type=\"checkbox\"][data-table-select]")) if (input instanceof HTMLInputElement && input.closest("table") === table) this.#check(input, this.#document.selection.keys.has(key), false);
+		for (const button of node.querySelectorAll("button[data-table-expand]:not([data-table-expand=\"page\"])")) if (button.closest("table") === table) {
+			this.#attribute(button, "aria-expanded", String(this.#document.expansion.keys.has(key)));
+			this.#attribute(button, "aria-controls", detail?.id ?? null);
+		}
+	}
+	#headers() {
+		const orders = this.#document.sort.orders();
+		for (const button of this.#element.tHead?.querySelectorAll("button[data-table-sort]") ?? []) {
+			if (button.closest("table") !== this.#element) continue;
+			const header = button.closest("th");
+			if (header === null) continue;
+			const column = button.getAttribute("data-table-sort");
+			const index = orders.findIndex((order) => order.column === column);
+			const order = orders[index];
+			const description = order === void 0 ? null : this.#options.describe?.sort?.({
+				column: order.column,
+				direction: order.direction,
+				priority: index + 1,
+				count: orders.length
+			}) ?? `Sort priority ${index + 1} of ${orders.length}, ${order.direction}`;
+			if (this.destroyed) return;
+			this.#attribute(header, "aria-sort", index === 0 && order !== void 0 ? order.direction : null);
+			this.#attribute(button, "aria-description", description);
+		}
+	}
+	#pages(view) {
+		const keys = this.#keys(view);
+		for (const button of this.#scoped("button[data-table-expand=\"page\"]")) {
+			this.#attribute(button, "aria-expanded", String(keys.length > 0 && keys.every((key) => this.#document.expansion.keys.has(key))));
+			if (button instanceof HTMLButtonElement) this.#disable(button, keys.length === 0);
+			if (this.destroyed) return;
+		}
+		const selected = view.filter((row) => {
+			const key = extractKey(this.#document.schema, row);
+			return key !== void 0 && this.#document.selection.keys.has(key);
+		}).length;
+		for (const input of this.#scope.querySelectorAll("input[type=\"checkbox\"][data-table-page]")) if (input instanceof HTMLInputElement && (input.closest("table") === null || input.closest("table") === this.#element)) this.#check(input, view.length > 0 && selected === view.length, selected > 0 && selected < view.length);
+	}
+	#scoped(selector) {
+		return Array.from(this.#scope.querySelectorAll(selector)).filter((control) => {
+			const table = control.closest("table");
+			return table === null || table === this.#element;
+		});
+	}
+	#disable(button, disabled, sibling) {
+		if (disabled && this.#element.ownerDocument.activeElement === button) {
+			if (sibling !== void 0) sibling.focus({ preventScroll: true });
+			else this.#focusTable();
+		}
+		if (!this.destroyed) this.#attribute(button, "disabled", disabled ? "" : null);
+	}
+	#value(control, value) {
+		const state = this.#controlValues.get(control);
+		if (state === void 0) this.#controlValues.set(control, {
+			original: control.value,
+			value
+		});
+		else state.value = value;
+		if (control.value !== value) control.value = value;
+	}
+	#readRange() {
+		const pagination = this.#document.pagination;
+		const length = this.#document.view.length;
+		return {
+			first: length === 0 ? 0 : pagination.offset + 1,
+			last: length === 0 ? 0 : pagination.offset + length,
+			count: this.#document.count,
+			page: pagination.page,
+			pages: pagination.count,
+			limit: pagination.limit
+		};
+	}
+	#pager() {
+		const range = this.#readRange();
+		const buttons = this.#scoped("button[data-table-move=\"previous\"], button[data-table-move=\"next\"]").filter((button) => button instanceof HTMLButtonElement);
+		const enabled = buttons.filter((button) => button.getAttribute("data-table-move") === "previous" ? range.page > 1 : range.page < range.pages);
+		for (const button of enabled) this.#disable(button, false);
+		for (const button of buttons) {
+			if (!enabled.includes(button)) this.#disable(button, true, enabled.find((sibling) => sibling.getAttribute("data-table-move") !== button.getAttribute("data-table-move")));
+			if (this.destroyed) return;
+		}
+		for (const select of this.#scoped("select[data-table-limit]")) if (select instanceof HTMLSelectElement) this.#value(select, range.limit === void 0 ? "" : String(range.limit));
+		const signature = JSON.stringify(range);
+		if (signature === this.#range) return;
+		const outputs = this.#scoped("output[data-table-range]").filter((output) => output instanceof HTMLOutputElement);
+		const description = this.#options.describe?.range?.(range) ?? `${range.first} to ${range.last} of ${range.count}`;
+		if (this.destroyed) return;
+		if (signature !== JSON.stringify(this.#readRange())) {
+			this.#enqueue();
+			return;
+		}
+		this.#range = signature;
+		if (this.#announcement !== void 0) clearTimeout(this.#announcement);
+		for (const output of outputs) this.#value(output, "");
+		this.#announcement = setTimeout(() => {
+			this.#announcement = void 0;
+			if (this.destroyed) return;
+			if (signature !== JSON.stringify(this.#readRange())) {
+				this.#range = void 0;
+				this.#enqueue();
+				return;
+			}
+			for (const output of outputs) if (this.#scoped("output[data-table-range]").includes(output)) this.#value(output, description);
+		}, 0);
+	}
+	#click(event) {
+		if (!(event.target instanceof Element) || this.destroyed || this.#requesting) return;
+		const button = event.target.closest("button");
+		if (!(button instanceof HTMLButtonElement) || button.disabled || button.closest("table") !== null && button.closest("table") !== this.#element) return;
+		const outcome = attempt(() => {
+			const move = button.getAttribute("data-table-move");
+			if (move === "previous" || move === "next") this.#document.pagination.move(this.#document.pagination.page + (move === "previous" ? -1 : 1));
+			else if (button.getAttribute("data-table-expand") === "page") {
+				const keys = this.#keys(this.#document.view);
+				if (keys.length > 0 && keys.every((key) => this.#document.expansion.keys.has(key))) this.#document.expansion.clear(keys);
+				else this.#document.expansion.expand(keys);
+			} else if (button.hasAttribute("data-table-sort") && this.#element.tHead?.contains(button)) {
+				const column = button.getAttribute("data-table-sort");
+				if (column === null || !this.#document.schema.columns.some((entry) => entry.key === column)) throw new TableBindingError("STRUCTURE", "The sort button names no column");
+				const direction = this.#document.sort.order(column)?.direction;
+				const orders = direction === "descending" ? [] : [{
+					column,
+					direction: direction === void 0 ? "ascending" : "descending"
+				}];
+				const request = new CustomEvent("table-sort", {
+					cancelable: true,
+					detail: orders
+				});
+				this.#requesting = true;
+				this.#emitter.emit("sort", request);
+				this.#requesting = false;
+				if (request.defaultPrevented || this.destroyed) return;
+				this.#document.sort.remove();
+				if (!this.destroyed) this.#document.sort.set(orders);
+			} else if (button.hasAttribute("data-table-expand")) {
+				const row = button.closest("tr");
+				const key = Array.from(this.#rows).find(([, node]) => node === row)?.[0];
+				if (key !== void 0) this.#document.expansion.toggle(key);
+			}
+		});
+		if (!outcome.success) this.#emitter.emit("error", outcome.error);
+	}
+	#change(event) {
+		const input = event.target;
+		if (input instanceof HTMLSelectElement && input.hasAttribute("data-table-limit")) {
+			if (input.disabled || this.destroyed || !this.#scoped("select[data-table-limit]").includes(input)) return;
+			const outcome = attempt(() => {
+				const limit = input.value === "" ? void 0 : parseNumber(input.value);
+				if (input.value !== "" && (limit === void 0 || limit <= 0 || !Number.isInteger(limit))) throw new TableBindingError("STRUCTURE", "The page limit must be a positive integer or empty");
+				this.#document.pagination.resize(limit);
+			});
+			if (!outcome.success) this.#emitter.emit("error", outcome.error);
+			return;
+		}
+		if (!(input instanceof HTMLInputElement) || input.type !== "checkbox" || input.disabled || this.destroyed) return;
+		const table = input.closest("table");
+		if (table !== null && table !== this.#element) return;
+		const outcome = attempt(() => {
+			if (input.hasAttribute("data-table-page")) {
+				const keys = this.#keys(this.#document.view);
+				if (input.checked) this.#document.selection.select(keys);
+				else this.#document.selection.clear(keys);
+			} else if (input.hasAttribute("data-table-select") && table === this.#element) {
+				const key = Array.from(this.#rows).find(([, node]) => node === input.closest("tr"))?.[0];
+				if (key !== void 0) {
+					if (input.checked) this.#document.selection.select(key);
+					else this.#document.selection.clear(key);
+				}
+			}
+		});
+		if (!outcome.success) this.#emitter.emit("error", outcome.error);
+	}
+	#keys(rows) {
+		return rows.flatMap((row) => {
+			const key = extractKey(this.#document.schema, row);
+			return key === void 0 ? [] : [key];
+		});
+	}
+};
+//#endregion
+//#region src/browser/factories.ts
+/** Creates a native table binding with one retained row owner.
+* @param element - The native table to bind.
+* @param document - The borrowed core document.
+* @param options - Renderers, scoped controls, and listeners.
+* @returns The native binding.
+*/
+function createTableBinding(element, document, options) {
+	return new TableBinding(element, document, options);
+}
+//#endregion
+export { TableBinding, TableBindingError, createTableBinding, isTableBindingError, readTable, readTableRows, readTableSchema };
+
+//# sourceMappingURL=index.js.map