@moloodev/table-sdk 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@moloodev/table-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@moloodev/editor-sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "@moloodev/typescript-config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test 'src/**/*.test.ts'"
+  }
 }

package/src/asset.ts

@@ -0,0 +1,40 @@
+import { isAssetColumnType } from "./types";
+import type { AssetRef, Table } from "./types";
+
+export function isAssetRef(value: unknown): value is AssetRef {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const ref = value as Record<string, unknown>;
+  return (
+    typeof ref.id === "string" &&
+    ref.id !== "" &&
+    typeof ref.name === "string"
+  );
+}
+
+export function assetRef(id: string, name = ""): AssetRef {
+  return { id, name };
+}
+
+export function refreshAssetNames(
+  document: Table,
+  names: ReadonlyMap<string, string>,
+): Table {
+  let changed = false;
+  const rows = document.rows.map((row) => {
+    let next = row;
+    for (const column of document.columns) {
+      if (!isAssetColumnType(column.type)) continue;
+      const cell = row.cells[column.id];
+      if (!isAssetRef(cell)) continue;
+      const name = names.get(cell.id);
+      if (name == null || cell.name === name) continue;
+      if (next === row) next = { ...row, cells: { ...row.cells } };
+      next.cells[column.id] = assetRef(cell.id, name);
+      changed = true;
+    }
+    return next;
+  });
+  return changed ? { ...document, rows } : document;
+}

package/src/bind.ts

@@ -0,0 +1,306 @@
+import {
+  createArray,
+  createDoc,
+  createMap,
+  isArray,
+  isMap,
+  rootMap,
+  stopCapturing,
+  transact,
+  writeJson,
+  type Doc,
+  type SharedArray,
+  type SharedMap,
+} from "@moloodev/editor-sdk/crdt";
+import { cellsEqual } from "./coerce";
+import { createBlank, parse } from "./parse";
+import {
+  INDEX_SORT_ASC,
+  normalizeSorting,
+  type ColumnSort,
+  type SortingState,
+} from "./sort";
+import {
+  TABLE_VERSION,
+  type CellValue,
+  type Table,
+  type TableColumn,
+  type TableRow,
+} from "./types";
+
+/** CRDT-only rank. Shared types cannot move; project sorts by this. */
+const ORDER_KEY = "#ord";
+const SORT_KEY = "#sort";
+const PRIMARY_KEY = "primaryKeyColumnId";
+
+export function projectTable(doc: Doc): Table {
+  const root = rootMap(doc).toJSON() as Record<string, unknown>;
+  // An unseeded document is editable; other malformed documents must stay intact.
+  if (Object.keys(root).every((key) => key === SORT_KEY)) return createBlank();
+  return parse({
+    ...root,
+    version: root.version === undefined ? TABLE_VERSION : root.version,
+    columns: Array.isArray(root.columns) ? listed(root.columns) : root.columns,
+    rows: Array.isArray(root.rows) ? listed(root.rows) : root.rows,
+  });
+}
+
+function listed(raw: unknown): unknown[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((item, index) => ({ item, index, key: orderKey(item, index) }))
+    .sort((left, right) => left.key - right.key || left.index - right.index)
+    .map((entry) => entry.item);
+}
+
+function orderKey(item: unknown, fallback: number): number {
+  if (!item || typeof item !== "object" || Array.isArray(item)) return fallback;
+  const value = (item as Record<string, unknown>)[ORDER_KEY];
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+export function projectSorting(
+  doc: Doc,
+  columnIds: readonly string[],
+): SortingState {
+  const raw = (rootMap(doc).toJSON() as Record<string, unknown>)[SORT_KEY];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return [INDEX_SORT_ASC];
+  }
+  const id = (raw as Record<string, unknown>).id;
+  const desc = (raw as Record<string, unknown>).desc;
+  if (typeof id !== "string") return [INDEX_SORT_ASC];
+  return normalizeSorting([{ id, desc: Boolean(desc) }], columnIds);
+}
+
+export function applySortingChange(
+  doc: Doc,
+  sorting: SortingState,
+  columnIds: readonly string[],
+): SortingState {
+  projectTable(doc);
+  const next = normalizeSorting(sorting, columnIds);
+  const current = projectSorting(doc, columnIds);
+  if (current[0]?.id === next[0]?.id && current[0]?.desc === next[0]?.desc) {
+    return next;
+  }
+  transact(doc, () => {
+    writeSorting(rootMap(doc), next[0] ?? INDEX_SORT_ASC);
+  });
+  stopCapturing(doc);
+  return next;
+}
+
+function writePrimaryKey(root: SharedMap, columnId: string | undefined): void {
+  if (columnId == null) {
+    if (root.has(PRIMARY_KEY)) root.delete(PRIMARY_KEY);
+    return;
+  }
+  if (root.get(PRIMARY_KEY) !== columnId) root.set(PRIMARY_KEY, columnId);
+}
+
+function writeSorting(root: SharedMap, sort: ColumnSort): void {
+  let map = root.get(SORT_KEY);
+  if (!isMap(map)) {
+    map = createMap();
+    root.set(SORT_KEY, map);
+  }
+  const sortMap = map as SharedMap;
+  if (sortMap.get("id") !== sort.id) sortMap.set("id", sort.id);
+  if (sortMap.get("desc") !== sort.desc) sortMap.set("desc", sort.desc);
+}
+
+export function seedTable(doc: Doc, table: Table): void {
+  projectTable(doc);
+  writeJson(doc, parse(table) as unknown as Record<string, unknown>);
+}
+
+export function tableDoc(table: Table): Doc {
+  const doc = createDoc();
+  seedTable(doc, table);
+  return doc;
+}
+
+function ensureArray(root: SharedMap, key: string): SharedArray {
+  const existing = root.get(key);
+  if (isArray(existing)) return existing;
+  const next = createArray();
+  root.set(key, next);
+  return next;
+}
+
+function asMap(value: unknown): SharedMap | null {
+  return isMap(value) ? value : null;
+}
+
+function writeColumn(
+  map: SharedMap,
+  column: TableColumn,
+  before?: TableColumn,
+): void {
+  for (const key of ["id", "type", "width"] as const) {
+    if (before && before[key] === column[key]) continue;
+    if (column[key] === undefined) map.delete(key);
+    else setIfChanged(map, key, column[key]);
+  }
+}
+
+function writeRow(map: SharedMap, row: TableRow, before?: TableRow): void {
+  if (!before) setIfChanged(map, "id", row.id);
+  let cells = map.get("cells");
+  if (!isMap(cells)) {
+    cells = createMap();
+    map.set("cells", cells);
+  }
+  const cellMap = cells as SharedMap;
+  // Only keys visible in the before state can express an intentional deletion.
+  for (const key of Object.keys(before?.cells ?? {})) {
+    if (!Object.hasOwn(row.cells, key)) cellMap.delete(key);
+  }
+  for (const [key, value] of Object.entries(row.cells)) {
+    if (
+      before &&
+      Object.hasOwn(before.cells, key) &&
+      cellsEqual(before.cells[key]!, value)
+    )
+      continue;
+    setIfChanged(cellMap, key, value);
+  }
+}
+
+function setIfChanged(map: SharedMap, key: string, value: unknown): void {
+  const current = map.get(key);
+  if (current === value) return;
+  if (
+    isMap(current) &&
+    cellsEqual(current.toJSON() as CellValue, value as CellValue)
+  ) {
+    return;
+  }
+  if (cellsEqual(current as CellValue, value as CellValue)) return;
+  map.set(key, value);
+}
+
+function idOf(value: unknown): string | null {
+  const map = asMap(value);
+  const id = map?.get("id");
+  return typeof id === "string" ? id : null;
+}
+
+function reconcile<T extends { id: string }>(
+  arr: SharedArray,
+  before: readonly T[],
+  next: readonly T[],
+  write: (map: SharedMap, item: T, before?: T) => void,
+): void {
+  const byId = new Map<string, SharedMap>();
+  for (let i = 0; i < arr.length; i += 1) {
+    const id = idOf(arr.get(i));
+    const map = asMap(arr.get(i));
+    if (id && map) byId.set(id, map);
+  }
+
+  const previous = new Map(before.map((item) => [item.id, item]));
+  const orderChanged =
+    before.length !== next.length ||
+    before.some((item, index) => item.id !== next[index]?.id);
+  const keep = new Set(next.map((item) => item.id));
+  for (let i = arr.length - 1; i >= 0; i -= 1) {
+    const id = idOf(arr.get(i));
+    if (id && previous.has(id) && !keep.has(id)) arr.delete(i, 1);
+  }
+
+  for (let i = 0; i < next.length; i += 1) {
+    const item = next[i]!;
+    let map = byId.get(item.id);
+    if (!map && previous.has(item.id)) continue;
+    if (!map) {
+      map = createMap();
+      arr.push([map]);
+      byId.set(item.id, map);
+    }
+    write(map, item, previous.get(item.id));
+    if (orderChanged && map.get(ORDER_KEY) !== i) map.set(ORDER_KEY, i);
+  }
+}
+
+function writeTablePatch(
+  doc: Doc,
+  before: Table,
+  next: Table,
+  sorting?: SortingState,
+): void {
+  const root = rootMap(doc);
+  if (!root.has("version")) root.set("version", TABLE_VERSION);
+  const columns = ensureArray(root, "columns");
+  reconcile(columns, before.columns, next.columns, writeColumn);
+  const liveColumnIds = new Set<string>();
+  for (let index = 0; index < columns.length; index += 1) {
+    const id = idOf(columns.get(index));
+    if (id) liveColumnIds.add(id);
+  }
+  const nextColumnIds = new Set(next.columns.map((column) => column.id));
+  reconcile(
+    ensureArray(root, "rows"),
+    before.rows,
+    next.rows,
+    (map, row, previous) => {
+      // A stale cell edit must not resurrect a column another replica removed.
+      const cells = Object.fromEntries(
+        Object.entries(row.cells).filter(([id]) => liveColumnIds.has(id)),
+      );
+      const previousRow = previous
+        ? {
+            ...previous,
+            cells: Object.fromEntries(
+              Object.entries(previous.cells).filter(
+                ([id]) => liveColumnIds.has(id) || !nextColumnIds.has(id),
+              ),
+            ),
+          }
+        : undefined;
+      writeRow(map, { ...row, cells }, previousRow);
+    },
+  );
+  if (before.primaryKeyColumnId !== next.primaryKeyColumnId) {
+    if (
+      next.primaryKeyColumnId === undefined ||
+      liveColumnIds.has(next.primaryKeyColumnId)
+    ) {
+      writePrimaryKey(root, next.primaryKeyColumnId);
+    }
+  }
+  if (sorting) {
+    writeSorting(
+      root,
+      normalizeSorting(sorting, [...liveColumnIds])[0] ?? INDEX_SORT_ASC,
+    );
+  }
+}
+
+/** Apply intent computed from a rendered snapshot to the current shared document. */
+export function applyTablePatch(
+  doc: Doc,
+  before: Table,
+  after: Table,
+  sorting?: SortingState,
+): Table {
+  projectTable(doc);
+  parse(before);
+  parse(after);
+  transact(doc, () => writeTablePatch(doc, before, after, sorting));
+  stopCapturing(doc);
+  return projectTable(doc);
+}
+
+export function applyTableChange(
+  doc: Doc,
+  compute: (table: Table) => Table,
+  sorting?: SortingState,
+): Table {
+  const fresh = projectTable(doc);
+  // Keep an independent baseline even if the callback mutates its argument.
+  const before = structuredClone(fresh);
+  const next = compute(fresh);
+  return applyTablePatch(doc, before, next, sorting);
+}

package/src/coerce.ts

@@ -0,0 +1,113 @@
+import { assetRef } from "./asset";
+import { coerceDate, coerceTime, coerceTimestamp } from "./timestamp";
+import { isAssetColumnType } from "./types";
+import type { AssetRef, CellValue, ColumnType, JsonValue } from "./types";
+
+export function coerceCell(type: ColumnType, value: unknown): CellValue {
+  if (value === null || value === undefined) return null;
+  if (isAssetColumnType(type)) return coerceAsset(value);
+  switch (type) {
+    case "text":
+      if (typeof value === "string") return value;
+      if (typeof value === "number" && Number.isFinite(value)) return String(value);
+      if (typeof value === "boolean") return value ? "true" : "false";
+      if (isJsonValue(value)) return stringifyJson(value);
+      return null;
+    case "integer":
+      return coerceInteger(value);
+    case "float":
+      return coerceFloat(value);
+    case "boolean":
+      if (typeof value === "boolean") return value;
+      if (value === "true" || value === 1) return true;
+      if (value === "false" || value === 0) return false;
+      return null;
+    case "json":
+      return coerceJson(value);
+    case "date":
+      return coerceDate(value);
+    case "time":
+      return coerceTime(value);
+    case "timestamp":
+      return coerceTimestamp(value);
+  }
+}
+
+export function cellsEqual(left: CellValue, right: CellValue): boolean {
+  if (left === right) return true;
+  if (left == null || right == null) return false;
+  if (typeof left !== "object" || typeof right !== "object") return false;
+  return stringifyJson(left) === stringifyJson(right);
+}
+
+export function stringifyJson(value: JsonValue): string {
+  return JSON.stringify(value);
+}
+
+function coerceInteger(value: unknown): number | null {
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "number" && Number.isFinite(value)) return Math.floor(value);
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? Math.floor(parsed) : null;
+  }
+  return null;
+}
+
+function coerceFloat(value: unknown): number | null {
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+function coerceAsset(value: unknown): AssetRef | null {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed === "") return null;
+    if (trimmed.startsWith("{")) {
+      try {
+        return coerceAsset(JSON.parse(trimmed));
+      } catch {
+        return assetRef(trimmed);
+      }
+    }
+    return assetRef(trimmed);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const raw = value as Record<string, unknown>;
+  const id = typeof raw.id === "string" ? raw.id.trim() : "";
+  if (id === "") return null;
+  return assetRef(id, typeof raw.name === "string" ? raw.name : "");
+}
+
+function coerceJson(value: unknown): CellValue {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed === "") return null;
+    try {
+      return cloneJson(JSON.parse(trimmed));
+    } catch {
+      return null;
+    }
+  }
+  if (isJsonValue(value)) return cloneJson(value);
+  return null;
+}
+
+function cloneJson(value: JsonValue): JsonValue {
+  return JSON.parse(JSON.stringify(value)) as JsonValue;
+}
+
+function isJsonValue(value: unknown): value is JsonValue {
+  if (typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isJsonValue);
+  if (value !== null && typeof value === "object") {
+    return Object.values(value).every(isJsonValue);
+  }
+  return false;
+}

package/src/contract.ts

@@ -0,0 +1,177 @@
+import { isAssetRef } from "./asset";
+import { coerceDate, coerceTime, coerceTimestamp } from "./timestamp";
+import {
+  assetKind,
+  isAssetColumnType,
+  isColumnType,
+  TABLE_VERSION,
+  type ColumnType,
+} from "./types";
+import { MAX_COLUMN_WIDTH, MIN_COLUMN_WIDTH } from "./width";
+
+function record(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function json(value: unknown, ancestors = new Set<object>()): boolean {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (!Array.isArray(value) && !record(value)) return false;
+  if (ancestors.has(value)) return false;
+  ancestors.add(value);
+  const valid = Object.values(value).every((entry) => json(entry, ancestors));
+  ancestors.delete(value);
+  return valid;
+}
+
+function validCell(type: ColumnType, value: unknown): boolean {
+  if (value === null) return true;
+  if (isAssetColumnType(type)) return record(value) && isAssetRef(value);
+  switch (type) {
+    case "text":
+      return typeof value === "string";
+    case "integer":
+      return (
+        typeof value === "number" &&
+        Number.isFinite(value) &&
+        Number.isInteger(value)
+      );
+    case "float":
+      return typeof value === "number" && Number.isFinite(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "json":
+      return json(value);
+    case "date":
+      return typeof value === "string" && coerceDate(value) === value;
+    case "time":
+      return typeof value === "string" && coerceTime(value) === value;
+    case "timestamp":
+      return typeof value === "string" && coerceTimestamp(value) === value;
+  }
+}
+
+/** Inspects stored v1 content without applying the editor's permissive coercions. */
+export const tableFormat = {
+  currentSchemaVersion: TABLE_VERSION,
+  inspect(input: unknown) {
+    const issues: { severity: "warning" | "error"; code: string; path: (string | number)[] }[] = [];
+    const references: { assetId: string; assetType: string; path: (string | number)[] }[] = [];
+    const issue = (
+      code: string,
+      path: (string | number)[],
+      severity: "warning" | "error" = "error",
+    ) => {
+      issues.push({ severity, code, path });
+    };
+    if (!record(input)) {
+      issue("invalid_document", []);
+      return { schemaVersion: null, issues, references };
+    }
+    const schemaVersion =
+      typeof input.version === "number" &&
+      Number.isInteger(input.version) &&
+      input.version > 0
+        ? input.version
+        : null;
+    if (input.version !== TABLE_VERSION) {
+      issue(
+        schemaVersion === null
+          ? "invalid_schema_version"
+          : "unsupported_schema",
+        ["version"],
+      );
+      return { schemaVersion, issues, references };
+    }
+    const columns = new Map<string, ColumnType>();
+    const ids = new Set<string>();
+    if (!Array.isArray(input.columns)) issue("invalid_columns", ["columns"]);
+    else
+      input.columns.forEach((column, index) => {
+        const path = ["columns", index];
+        if (!record(column)) {
+          issue("invalid_column", path);
+          return;
+        }
+        const validId = typeof column.id === "string" && column.id.length > 0;
+        if (!validId) issue("invalid_column_id", [...path, "id"]);
+        else if (ids.has(column.id as string))
+          issue("duplicate_column_id", [...path, "id"]);
+        const validType =
+          typeof column.type === "string" && isColumnType(column.type);
+        if (!validType) issue("invalid_column_type", [...path, "type"]);
+        if (validId) {
+          if (validType && !ids.has(column.id as string))
+            columns.set(column.id as string, column.type as ColumnType);
+          ids.add(column.id as string);
+        }
+        if (Object.hasOwn(column, "width")) {
+          if (
+            typeof column.width !== "number" ||
+            !Number.isFinite(column.width)
+          )
+            issue("invalid_column_width", [...path, "width"]);
+          else if (
+            !Number.isInteger(column.width) ||
+            column.width < MIN_COLUMN_WIDTH ||
+            column.width > MAX_COLUMN_WIDTH
+          )
+            issue("noncanonical_column_width", [...path, "width"], "warning");
+        }
+      });
+    if (
+      Object.hasOwn(input, "primaryKeyColumnId") &&
+      (typeof input.primaryKeyColumnId !== "string" ||
+        !ids.has(input.primaryKeyColumnId))
+    ) {
+      issue("invalid_primary_key_column", ["primaryKeyColumnId"]);
+    }
+    const rowIds = new Set<string>();
+    if (!Array.isArray(input.rows)) issue("invalid_rows", ["rows"]);
+    else
+      input.rows.forEach((row, index) => {
+        const path = ["rows", index];
+        if (!record(row)) {
+          issue("invalid_row", path);
+          return;
+        }
+        if (typeof row.id !== "string" || row.id.length === 0)
+          issue("invalid_row_id", [...path, "id"]);
+        else {
+          if (rowIds.has(row.id)) issue("duplicate_row_id", [...path, "id"]);
+          rowIds.add(row.id);
+        }
+        if (!record(row.cells)) {
+          issue("invalid_cells", [...path, "cells"]);
+          return;
+        }
+        for (const [id, type] of columns) {
+          const cellPath = [...path, "cells", id];
+          if (!Object.hasOwn(row.cells, id)) {
+            issue("missing_cell", cellPath, "warning");
+            continue;
+          }
+          const cell = row.cells[id];
+          if (!validCell(type, cell)) {
+            issue(
+              isAssetColumnType(type)
+                ? "invalid_asset_reference"
+                : "invalid_cell",
+              cellPath,
+            );
+          } else if (isAssetColumnType(type) && isAssetRef(cell)) {
+            references.push({
+              assetId: cell.id,
+              assetType: assetKind(type),
+              path: cellPath,
+            });
+          }
+        }
+      });
+    return { schemaVersion, issues, references };
+  },
+};

package/src/index.ts

@@ -0,0 +1,54 @@
+export {
+  COLUMN_TYPES,
+  TABLE_VERSION,
+  ParseError,
+  assetColumnType,
+  assetKind,
+  isAssetColumnType,
+  isColumnType,
+  type AssetRef,
+  type CellValue,
+  type ColumnType,
+  type JsonValue,
+  type ScalarColumnType,
+  type Table,
+  type TableColumn,
+  type TableRow,
+} from "./types";
+export { cellsEqual, coerceCell, stringifyJson } from "./coerce";
+export { assetRef, isAssetRef, refreshAssetNames } from "./asset";
+export {
+  addDateUnit,
+  addTimeUnit,
+  addTimestampUnit,
+  coerceDate,
+  coerceTime,
+  coerceTimestamp,
+  formatDateLocal,
+  formatIsoUtc,
+  formatTimeLocal,
+  setDateUnit,
+  setTimeUnit,
+  setTimestampUnit,
+  timestampParts,
+  type TimestampUnit,
+} from "./timestamp";
+export { createBlank, parse } from "./parse";
+export {
+  applySortingChange,
+  applyTableChange,
+  applyTablePatch,
+  projectSorting,
+  projectTable,
+  tableDoc,
+} from "./bind";
+export {
+  canApplyViewOrder,
+  INDEX_SORT_ASC,
+  INDEX_SORT_ID,
+  isIndexSort,
+  normalizeSorting,
+  type SortingState,
+} from "./sort";
+export { clampColumnWidth, columnWidth, displayColumnWidth } from "./width";
+export { tableFormat } from "./contract";

package/src/parse.ts

@@ -0,0 +1,116 @@
+import { coerceCell } from "./coerce";
+import {
+  TABLE_VERSION,
+  ParseError,
+  isColumnType,
+  type TableColumn,
+  type Table,
+  type TableRow,
+} from "./types";
+import { clampColumnWidth } from "./width";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseColumn(raw: unknown, index: number, seen: Set<string>): TableColumn {
+  if (!isPlainObject(raw)) {
+    throw new ParseError(`columns[${index}] must be an object`);
+  }
+  const id = raw.id;
+  if (typeof id !== "string" || id.length === 0) {
+    throw new ParseError(
+      `columns[${index}].id must be a non-empty string`,
+    );
+  }
+  if (seen.has(id)) {
+    throw new ParseError(`duplicate column id "${id}"`);
+  }
+  seen.add(id);
+  const type = raw.type;
+  if (typeof type !== "string" || !isColumnType(type)) {
+    throw new ParseError(
+      `columns[${index}].type must be text, integer, float, boolean, json, timestamp, date, time, or asset/<kind>`,
+    );
+  }
+  const width =
+    typeof raw.width === "number" && Number.isFinite(raw.width)
+      ? clampColumnWidth(raw.width)
+      : undefined;
+  return width == null ? { id, type } : { id, type, width };
+}
+
+function parseRow(
+  raw: unknown,
+  index: number,
+  columns: readonly TableColumn[],
+  seen: Set<string>,
+): TableRow {
+  if (!isPlainObject(raw)) {
+    throw new ParseError(`rows[${index}] must be an object`);
+  }
+  const id = raw.id;
+  if (typeof id !== "string" || id.length === 0) {
+    throw new ParseError(
+      `rows[${index}].id must be a non-empty string`,
+    );
+  }
+  if (seen.has(id)) {
+    throw new ParseError(`duplicate row id "${id}"`);
+  }
+  seen.add(id);
+  if (!isPlainObject(raw.cells)) {
+    throw new ParseError(`rows[${index}].cells must be an object`);
+  }
+  const cells: TableRow["cells"] = {};
+  for (const column of columns) {
+    cells[column.id] = Object.hasOwn(raw.cells, column.id)
+      ? coerceCell(column.type, raw.cells[column.id])
+      : null;
+  }
+  return { id, cells };
+}
+
+export function createBlank(): Table {
+  return { version: TABLE_VERSION, columns: [], rows: [] };
+}
+
+export function parse(input: unknown): Table {
+  if (!isPlainObject(input)) {
+    throw new ParseError("document must be an object");
+  }
+  if (input.version !== TABLE_VERSION) {
+    throw new ParseError(
+      `version must be ${TABLE_VERSION}`,
+    );
+  }
+  if (!Array.isArray(input.columns)) {
+    throw new ParseError("columns must be an array");
+  }
+  if (!Array.isArray(input.rows)) {
+    throw new ParseError("rows must be an array");
+  }
+  const seenColumns = new Set<string>();
+  const columns = input.columns.map((column, index) =>
+    parseColumn(column, index, seenColumns),
+  );
+  const seenRows = new Set<string>();
+  const rows = input.rows.map((row, index) =>
+    parseRow(row, index, columns, seenRows),
+  );
+  const primaryKeyColumnId = parsePrimaryKeyColumnId(
+    input.primaryKeyColumnId,
+    columns,
+  );
+  return primaryKeyColumnId
+    ? { version: TABLE_VERSION, primaryKeyColumnId, columns, rows }
+    : { version: TABLE_VERSION, columns, rows };
+}
+
+function parsePrimaryKeyColumnId(
+  raw: unknown,
+  columns: readonly TableColumn[],
+): string | undefined {
+  if (typeof raw !== "string" || raw.length === 0) return undefined;
+  return columns.some((column) => column.id === raw) ? raw : undefined;
+}

package/src/sort.ts

@@ -0,0 +1,34 @@
+export const INDEX_SORT_ID = "#index";
+
+export type ColumnSort = {
+  id: string;
+  desc: boolean;
+};
+
+export type SortingState = ColumnSort[];
+
+export const INDEX_SORT_ASC: ColumnSort = { id: INDEX_SORT_ID, desc: false };
+
+export function normalizeSorting(
+  sorting: SortingState,
+  columnIds: readonly string[],
+): SortingState {
+  const sort = sorting[0];
+  if (!sort) return [INDEX_SORT_ASC];
+  if (sort.id === INDEX_SORT_ID) return [{ id: INDEX_SORT_ID, desc: sort.desc }];
+  if (columnIds.includes(sort.id)) return [{ id: sort.id, desc: sort.desc }];
+  return [INDEX_SORT_ASC];
+}
+
+export function isIndexSort(sorting: SortingState): boolean {
+  return (sorting[0] ?? INDEX_SORT_ASC).id === INDEX_SORT_ID;
+}
+
+function isIndexSortAsc(sorting: SortingState): boolean {
+  const sort = sorting[0] ?? INDEX_SORT_ASC;
+  return sort.id === INDEX_SORT_ID && !sort.desc;
+}
+
+export function canApplyViewOrder(sorting: SortingState): boolean {
+  return !isIndexSortAsc(sorting);
+}

package/src/timestamp.ts

@@ -0,0 +1,328 @@
+const TIMESTAMP_UNITS = [
+  "year",
+  "month",
+  "day",
+  "hour",
+  "minute",
+  "second",
+] as const;
+
+export type TimestampUnit = (typeof TIMESTAMP_UNITS)[number];
+
+type TimestampParts = {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+};
+
+export function formatIsoUtc(date: Date): string | null {
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function formatDateUtc(date: Date): string | null {
+  if (Number.isNaN(date.getTime())) return null;
+  const year = String(date.getUTCFullYear()).padStart(4, "0");
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function formatTimeUtc(date: Date): string | null {
+  if (Number.isNaN(date.getTime())) return null;
+  const hour = String(date.getUTCHours()).padStart(2, "0");
+  const minute = String(date.getUTCMinutes()).padStart(2, "0");
+  const second = String(date.getUTCSeconds()).padStart(2, "0");
+  return `${hour}:${minute}:${second}`;
+}
+
+export function formatDateLocal(date: Date): string | null {
+  if (Number.isNaN(date.getTime())) return null;
+  return formatDateUtc(
+    new Date(
+      Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()),
+    ),
+  );
+}
+
+export function formatTimeLocal(date: Date): string | null {
+  if (Number.isNaN(date.getTime())) return null;
+  return formatTimeUtc(
+    new Date(
+      Date.UTC(
+        1970,
+        0,
+        1,
+        date.getHours(),
+        date.getMinutes(),
+        date.getSeconds(),
+      ),
+    ),
+  );
+}
+
+export function coerceTimestamp(value: unknown): string | null {
+  if (value == null || value === "") return null;
+  if (value instanceof Date) return formatIsoUtc(value);
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return formatIsoUtc(new Date(value));
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    return formatIsoUtc(new Date(value));
+  }
+  return null;
+}
+
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const TIME_RE = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;
+
+export function coerceDate(value: unknown): string | null {
+  if (value == null || value === "") return null;
+  if (value instanceof Date) return formatDateUtc(value);
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return formatDateUtc(new Date(value));
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const text = value.trim();
+    const civil = text.includes("T") ? text.slice(0, text.indexOf("T")) : text;
+    if (DATE_RE.test(civil)) {
+      const date = new Date(`${civil}T00:00:00Z`);
+      return Number.isNaN(date.getTime()) ? null : formatDateUtc(date);
+    }
+    return formatDateUtc(new Date(text));
+  }
+  return null;
+}
+
+export function coerceTime(value: unknown): string | null {
+  if (value == null || value === "") return null;
+  if (value instanceof Date) return formatTimeUtc(value);
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return formatTimeUtc(new Date(value));
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const text = value.trim();
+    const clock = text.includes("T")
+      ? text.slice(text.indexOf("T") + 1).replace(/[Zz]|[+-]\d{2}:?\d{2}$/, "")
+      : text;
+    const match = TIME_RE.exec(clock);
+    if (match) {
+      return formatTimeUtc(
+        new Date(
+          Date.UTC(
+            1970,
+            0,
+            1,
+            Number(match[1]),
+            Number(match[2]),
+            Number(match[3] ?? 0),
+          ),
+        ),
+      );
+    }
+    const parsed = new Date(text);
+    return Number.isNaN(parsed.getTime()) ? null : formatTimeUtc(parsed);
+  }
+  return null;
+}
+
+export function timestampParts(iso: string): TimestampParts | null {
+  const date = parseUtc(iso);
+  if (!date) return null;
+  return {
+    year: date.getUTCFullYear(),
+    month: date.getUTCMonth() + 1,
+    day: date.getUTCDate(),
+    hour: date.getUTCHours(),
+    minute: date.getUTCMinutes(),
+    second: date.getUTCSeconds(),
+  };
+}
+
+export function addTimestampUnit(
+  iso: string | null,
+  unit: TimestampUnit,
+  delta: number,
+  fallback: Date = new Date(0),
+): string | null {
+  const date = dateFromIso(iso, fallback);
+  switch (unit) {
+    case "year":
+      date.setUTCFullYear(date.getUTCFullYear() + delta);
+      break;
+    case "month":
+      date.setUTCMonth(date.getUTCMonth() + delta);
+      break;
+    case "day":
+      date.setUTCDate(date.getUTCDate() + delta);
+      break;
+    case "hour":
+      date.setUTCHours(date.getUTCHours() + delta);
+      break;
+    case "minute":
+      date.setUTCMinutes(date.getUTCMinutes() + delta);
+      break;
+    case "second":
+      date.setUTCSeconds(date.getUTCSeconds() + delta);
+      break;
+  }
+  return formatIsoUtc(date);
+}
+
+export function setTimestampUnit(
+  iso: string | null,
+  unit: TimestampUnit,
+  value: number,
+  fallback: Date = new Date(0),
+): string | null {
+  if (!Number.isFinite(value)) {
+    return iso ? formatIsoUtc(new Date(iso)) : null;
+  }
+  const date = dateFromIso(iso, fallback);
+  const next = Math.trunc(value);
+  switch (unit) {
+    case "year":
+      date.setUTCFullYear(next);
+      break;
+    case "month":
+      date.setUTCMonth(next - 1);
+      break;
+    case "day":
+      date.setUTCDate(next);
+      break;
+    case "hour":
+      date.setUTCHours(next);
+      break;
+    case "minute":
+      date.setUTCMinutes(next);
+      break;
+    case "second":
+      date.setUTCSeconds(next);
+      break;
+  }
+  return formatIsoUtc(date);
+}
+
+export function addDateUnit(
+  value: string | null,
+  unit: TimestampUnit,
+  delta: number,
+  fallback: Date = new Date(Date.UTC(1970, 0, 1)),
+): string | null {
+  return formatDateUtc(shiftUnit(dateFromCivilDate(value, fallback), unit, delta));
+}
+
+export function setDateUnit(
+  value: string | null,
+  unit: TimestampUnit,
+  next: number,
+  fallback: Date = new Date(Date.UTC(1970, 0, 1)),
+): string | null {
+  if (!Number.isFinite(next)) return coerceDate(value);
+  return formatDateUtc(
+    writeUnit(dateFromCivilDate(value, fallback), unit, Math.trunc(next)),
+  );
+}
+
+export function addTimeUnit(
+  value: string | null,
+  unit: TimestampUnit,
+  delta: number,
+  fallback: Date = new Date(Date.UTC(1970, 0, 1)),
+): string | null {
+  return formatTimeUtc(shiftUnit(dateFromCivilTime(value, fallback), unit, delta));
+}
+
+export function setTimeUnit(
+  value: string | null,
+  unit: TimestampUnit,
+  next: number,
+  fallback: Date = new Date(Date.UTC(1970, 0, 1)),
+): string | null {
+  if (!Number.isFinite(next)) return coerceTime(value);
+  return formatTimeUtc(
+    writeUnit(dateFromCivilTime(value, fallback), unit, Math.trunc(next)),
+  );
+}
+
+function shiftUnit(date: Date, unit: TimestampUnit, delta: number): Date {
+  switch (unit) {
+    case "year":
+      date.setUTCFullYear(date.getUTCFullYear() + delta);
+      break;
+    case "month":
+      date.setUTCMonth(date.getUTCMonth() + delta);
+      break;
+    case "day":
+      date.setUTCDate(date.getUTCDate() + delta);
+      break;
+    case "hour":
+      date.setUTCHours(date.getUTCHours() + delta);
+      break;
+    case "minute":
+      date.setUTCMinutes(date.getUTCMinutes() + delta);
+      break;
+    case "second":
+      date.setUTCSeconds(date.getUTCSeconds() + delta);
+      break;
+  }
+  return date;
+}
+
+function writeUnit(date: Date, unit: TimestampUnit, next: number): Date {
+  switch (unit) {
+    case "year":
+      date.setUTCFullYear(next);
+      break;
+    case "month":
+      date.setUTCMonth(next - 1);
+      break;
+    case "day":
+      date.setUTCDate(next);
+      break;
+    case "hour":
+      date.setUTCHours(next);
+      break;
+    case "minute":
+      date.setUTCMinutes(next);
+      break;
+    case "second":
+      date.setUTCSeconds(next);
+      break;
+  }
+  return date;
+}
+
+function dateFromCivilDate(value: string | null, fallback: Date): Date {
+  const civil = value ? coerceDate(value) : null;
+  if (civil) {
+    const date = new Date(`${civil}T00:00:00Z`);
+    if (!Number.isNaN(date.getTime())) return date;
+  }
+  return new Date(fallback.getTime());
+}
+
+function dateFromCivilTime(value: string | null, fallback: Date): Date {
+  const clock = value ? coerceTime(value) : null;
+  if (clock) {
+    const date = new Date(`1970-01-01T${clock}Z`);
+    if (!Number.isNaN(date.getTime())) return date;
+  }
+  return new Date(fallback.getTime());
+}
+
+function parseUtc(iso: string): Date | null {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function dateFromIso(iso: string | null, fallback: Date): Date {
+  if (iso) {
+    const date = parseUtc(iso);
+    if (date) return date;
+  }
+  return new Date(fallback.getTime());
+}

package/src/types.ts

@@ -0,0 +1,78 @@
+export const TABLE_VERSION = 1 as const;
+
+export const COLUMN_TYPES = [
+  "text",
+  "integer",
+  "float",
+  "boolean",
+  "json",
+  "timestamp",
+  "date",
+  "time",
+] as const;
+
+export type ScalarColumnType = (typeof COLUMN_TYPES)[number];
+type AssetColumnType = `asset/${string}`;
+export type ColumnType = ScalarColumnType | AssetColumnType;
+
+const ASSET_PREFIX = "asset/";
+
+export function isAssetColumnType(
+  value: string,
+): value is AssetColumnType {
+  return value.startsWith(ASSET_PREFIX) && value.length > ASSET_PREFIX.length;
+}
+
+export function assetKind(type: AssetColumnType): string {
+  return type.slice(ASSET_PREFIX.length);
+}
+
+export function assetColumnType(kind: string): AssetColumnType {
+  return `${ASSET_PREFIX}${kind}`;
+}
+
+export type TableColumn = {
+  id: string;
+  type: ColumnType;
+  width?: number;
+};
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type AssetRef = {
+  id: string;
+  name: string;
+};
+
+export type CellValue = JsonValue | null;
+
+export type TableRow = {
+  id: string;
+  cells: Record<string, CellValue>;
+};
+
+export type Table = {
+  version: typeof TABLE_VERSION;
+  primaryKeyColumnId?: string;
+  columns: TableColumn[];
+  rows: TableRow[];
+};
+
+export class ParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ParseError";
+  }
+}
+
+export function isColumnType(value: string): value is ColumnType {
+  return (
+    (COLUMN_TYPES as readonly string[]).includes(value) ||
+    isAssetColumnType(value)
+  );
+}

package/src/width.ts

@@ -0,0 +1,30 @@
+import type { TableColumn } from "./types";
+
+const DEFAULT_COLUMN_WIDTH = 160;
+export const MIN_COLUMN_WIDTH = 72;
+export const MAX_COLUMN_WIDTH = 2000;
+
+export function clampColumnWidth(px: number): number {
+  return Math.min(
+    MAX_COLUMN_WIDTH,
+    Math.max(MIN_COLUMN_WIDTH, Math.round(px)),
+  );
+}
+
+export function columnWidth(column: TableColumn): number {
+  return column.width == null
+    ? DEFAULT_COLUMN_WIDTH
+    : clampColumnWidth(column.width);
+}
+
+/** Live drag, then session overlay, then the stored column. */
+export function displayColumnWidth(
+  column: TableColumn,
+  overrides: Readonly<Record<string, number>>,
+  live?: { id: string; width: number } | null,
+): number {
+  if (live?.id === column.id) return live.width;
+  const override = overrides[column.id];
+  if (override != null) return clampColumnWidth(override);
+  return columnWidth(column);
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.