@book.dev/sdk 1.60.0

package/dist/database.js

@@ -0,0 +1,1082 @@
+/**
+ * Full-featured databases — the second unit of storage layered over {@link
+ * StoredPage}. A **database** is a collection of pages (its *rows*) managed by
+ * typed *properties* and presented through one or more configurable *views*
+ * (table, board, gallery, calendar, list, or a bar/pie chart).
+ *
+ * Three ideas make OpenBook databases different from a plain spreadsheet:
+ *
+ *  1. **Rows are real pages.** Each row is an ordinary page in the `pages`
+ *     table with its own editable document — so a row can itself contain text,
+ *     reactive sliders, charts, even another database. Opening a row in the
+ *     split pane edits that page directly.
+ *
+ *  2. **Columns can be reactive.** A property of type `expr` reads a *named
+ *     exported cell* from the row page's reactive store (the `names`/`values`
+ *     pairs in its {@link PageSnapshot}). A "Total" column can therefore show
+ *     the live result of an expression block inside each row, and the table can
+ *     filter and sort on it.
+ *
+ *  3. **Columns can compute.** A property of type `formula` evaluates a small
+ *     expression over the row's *other* properties (`prop("Price") * prop("Qty")`)
+ *     via the pure evaluator in {@link ./formula}. Filters/sorts/charts read the
+ *     computed value just like any stored one.
+ *
+ * The host page (the page that *contains* the database) is itself a regular
+ * page with its own content; it merely points at the database. The database
+ * record — properties, views, filters — lives in its own `databases` table.
+ */
+import { evaluateFormula, FormulaError } from './formula';
+/** Whether each side of a relation cardinality holds a single row. `1:1` is
+ *  single both ways; `1:n` links many but each target points back to one; `n:n`
+ *  is many both ways. */
+export function relationSides(card) {
+    return { forwardSingle: card === '1:1', reverseSingle: card !== 'n:n' };
+}
+/** Read a `{lat, lng, …}` location value from a cell, or null when unresolvable. */
+export function asLocation(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const v = value;
+    const lat = typeof v.lat === 'number' ? v.lat : Number(v.lat);
+    const lng = typeof v.lng === 'number' ? v.lng : Number(v.lng);
+    if (!Number.isFinite(lat) || !Number.isFinite(lng))
+        return null;
+    return {
+        lat,
+        lng,
+        ...(typeof v.label === 'string' && v.label.trim() ? { label: v.label } : {}),
+        ...(typeof v.address === 'string' && v.address.trim() ? { address: v.address } : {}),
+    };
+}
+/** The value-less, relative-to-today date operators. */
+export const RELATIVE_DATE_OPS = [
+    'is_today',
+    'is_this_week',
+    'is_past_week',
+    'is_next_week',
+    'is_this_month',
+];
+/** True when a filter node is a group (vs. a leaf condition). */
+export function isFilterGroup(node) {
+    return node.conjunction !== undefined;
+}
+export function buildRowTree(rows) {
+    const byParent = new Map();
+    const ids = new Set(rows.map((r) => r.id));
+    for (const row of rows) {
+        const parent = row.parentId && ids.has(row.parentId) ? row.parentId : null;
+        const list = byParent.get(parent) ?? [];
+        list.push(row);
+        byParent.set(parent, list);
+    }
+    const build = (parent, depth) => (byParent.get(parent) ?? []).map((row) => ({ row, depth, children: build(row.id, depth + 1) }));
+    return build(null, 0);
+}
+/** Flatten a row tree to a list (depth-first), dropping the children of collapsed rows. */
+export function flattenRowTree(nodes, collapsed) {
+    const out = [];
+    const walk = (list) => {
+        for (const node of list) {
+            out.push(node);
+            if (node.children.length > 0 && !collapsed.has(node.row.id))
+                walk(node.children);
+        }
+    };
+    walk(nodes);
+    return out;
+}
+// ── Constants ────────────────────────────────────────────────────────────────
+/** Reserved property id addressing the row's page title in filters/sorts/views. */
+export const TITLE_PROPERTY_ID = 'title';
+/** Swatch tokens for `select` options; resolved to colors by the UI. */
+export const SELECT_COLORS = [
+    'gray',
+    'brown',
+    'orange',
+    'yellow',
+    'green',
+    'blue',
+    'purple',
+    'pink',
+    'red',
+];
+// ── Projection + view evaluation (shared by server and client) ───────────────
+/**
+ * Project a page snapshot's reactive store into a `{name: value}` map. This is
+ * how `expr` columns get their values without shipping the whole document: the
+ * `names` index maps each exported name to a cellId, and `values` holds the
+ * cellId → value pairs.
+ */
+export function projectExports(snapshot) {
+    const valueByCell = new Map(snapshot.values);
+    const out = {};
+    for (const [name, cellId] of snapshot.names) {
+        out[name] = valueByCell.get(cellId);
+    }
+    return out;
+}
+/** True when a URL looks like an image (by extension), for thumbnail rendering. */
+export function isImageUrl(url) {
+    return /\.(png|jpe?g|gif|webp|avif|svg|bmp)(\?.*)?$/i.test(url.trim());
+}
+/** The first image URL in a `files`/`url` cell value (a string or string[]), or null. */
+export function firstImageUrl(value) {
+    const urls = Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
+    for (const u of urls) {
+        if (typeof u === 'string' && isImageUrl(u))
+            return u;
+    }
+    return null;
+}
+/**
+ * The URL a gallery cover should try: the first extension-detected image, else
+ * the first http(s) URL — CDN/signed image URLs often carry no extension, and
+ * the property was explicitly chosen as the cover, so any URL in it is worth
+ * attempting (the UI falls back to the placeholder if it fails to load).
+ */
+export function coverImageUrl(value) {
+    const urls = Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
+    const strings = urls.filter((u) => typeof u === 'string');
+    return strings.find(isImageUrl) ?? strings.find((u) => /^https?:\/\//i.test(u.trim())) ?? null;
+}
+/**
+ * The friendly value a `formula` reads when it references another property by
+ * name: a `select` resolves to its option *label* (not the opaque id), a
+ * verification to its boolean flag, multi-selects/relations to a comma list. So
+ * `prop("Status")` in a formula sees `"Done"`, matching what the cell shows.
+ */
+function formulaFacingValue(row, property) {
+    switch (property.type) {
+        case 'select':
+        case 'status': {
+            const opt = property.options?.find((o) => o.id === row.properties[property.id]);
+            return opt ? opt.label : '';
+        }
+        case 'multi_select': {
+            const ids = Array.isArray(row.properties[property.id]) ? row.properties[property.id] : [];
+            return ids.map((id) => property.options?.find((o) => o.id === id)?.label ?? '').filter(Boolean).join(', ');
+        }
+        case 'checkbox':
+            return row.properties[property.id] === true;
+        case 'created_time':
+            return row.createdAt;
+        case 'last_edited_time':
+            return row.updatedAt;
+        case 'expr':
+            return row.exports[property.cellName ?? property.name];
+        case 'verification': {
+            const v = row.properties[property.id];
+            return !!(v && typeof v === 'object' && v.verified);
+        }
+        case 'date':
+            return dateStart(row.properties[property.id]) ?? '';
+        default:
+            return row.properties[property.id];
+    }
+}
+/**
+ * A {@link FormulaResolver} that looks a property up by name within one row and
+ * returns its formula-facing value. Resolves nested formulas recursively and
+ * guards against reference cycles (a cyclic ref yields a {@link FormulaError}).
+ * The reserved names `Name`/`Title` map to the row's page title.
+ */
+function rowFormulaResolver(row, properties, rows) {
+    const byName = new Map(properties.map((p) => [p.name.toLowerCase(), p]));
+    const visiting = new Set();
+    const resolve = (name) => {
+        const key = name.toLowerCase();
+        const property = byName.get(key);
+        if (!property) {
+            if (key === 'name' || key === 'title')
+                return row.name ?? '';
+            return null;
+        }
+        if (property.type === 'formula') {
+            if (visiting.has(property.id))
+                return new FormulaError('Circular formula');
+            visiting.add(property.id);
+            try {
+                return evaluateFormula(property.formula ?? '', resolve);
+            }
+            finally {
+                visiting.delete(property.id);
+            }
+        }
+        // A `rollup` resolves to its computed value so formulas can build on rollups.
+        if (property.type === 'rollup')
+            return rowValue(row, property, properties, rows);
+        return formulaFacingValue(row, property);
+    };
+    return resolve;
+}
+/**
+ * Resolve the value a row holds for a given property (title / manual / derived).
+ * `properties` is needed only to evaluate `formula` columns (which read other
+ * properties); pass it from any caller that has the schema (filters, sorts,
+ * cells). Without it, a formula resolves to `undefined`.
+ */
+export function rowValue(row, property, properties, rows) {
+    if (property === TITLE_PROPERTY_ID)
+        return row.name ?? '';
+    if (property.type === 'expr')
+        return row.exports[property.cellName ?? property.name];
+    if (property.type === 'formula') {
+        if (!properties)
+            return undefined;
+        return evaluateFormula(property.formula ?? '', rowFormulaResolver(row, properties, rows));
+    }
+    // A `rollup` folds a target property across the rows a relation points to.
+    if (property.type === 'rollup') {
+        if (!properties || !rows || !property.rollup)
+            return undefined;
+        return computeRollup(row, property.rollup, properties, rows);
+    }
+    // Timestamps are derived from the row page, not stored in `properties`.
+    if (property.type === 'created_time')
+        return row.createdAt;
+    if (property.type === 'last_edited_time')
+        return row.updatedAt;
+    // Verification filters/sorts on the boolean flag (so `is checked` works); the
+    // full {verified, by, at} object is read directly by the cell renderer.
+    if (property.type === 'verification') {
+        const v = row.properties[property.id];
+        return !!(v && typeof v === 'object' && v.verified);
+    }
+    // A `date` may hold a `{start, end}` range; filters/sorts compare the start.
+    if (property.type === 'date')
+        return dateStart(row.properties[property.id]) ?? '';
+    return row.properties[property.id];
+}
+/** Numeric folds shared by rollups, chart aggregates and summaries. */
+const numericFold = (nums, fn) => {
+    if (nums.length === 0)
+        return 0;
+    const sorted = [...nums].sort((a, b) => a - b);
+    switch (fn) {
+        case 'sum':
+            return sorted.reduce((a, b) => a + b, 0);
+        case 'avg':
+            return sorted.reduce((a, b) => a + b, 0) / sorted.length;
+        case 'min':
+            return sorted[0];
+        case 'max':
+            return sorted[sorted.length - 1];
+        case 'range':
+            return sorted[sorted.length - 1] - sorted[0];
+        case 'median': {
+            const mid = Math.floor(sorted.length / 2);
+            return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+        }
+    }
+};
+/** Compute a rollup value: gather the related rows, fold the target property. */
+function computeRollup(row, cfg, properties, rows) {
+    const relProp = properties.find((p) => p.id === cfg.relationPropertyId);
+    const raw = relProp ? row.properties[relProp.id] : undefined;
+    const ids = Array.isArray(raw) ? raw.filter((x) => typeof x === 'string') : [];
+    const byId = new Map(rows.map((r) => [r.id, r]));
+    const related = ids.map((id) => byId.get(id)).filter((r) => !!r);
+    if (cfg.function === 'count')
+        return related.length;
+    const target = cfg.targetPropertyId === TITLE_PROPERTY_ID ? TITLE_PROPERTY_ID : properties.find((p) => p.id === cfg.targetPropertyId);
+    if (!target)
+        return undefined;
+    const values = related.map((r) => rowValue(r, target, properties, rows));
+    switch (cfg.function) {
+        case 'show_original':
+            return values;
+        case 'count_values':
+            return values.filter((v) => !isEmpty(v)).length;
+        case 'count_unique':
+            return new Set(values.filter((v) => !isEmpty(v)).map((v) => (Array.isArray(v) ? JSON.stringify(v) : String(v)))).size;
+        case 'checked':
+            return values.filter((v) => v === true).length;
+        case 'percent_checked':
+            return values.length ? Math.round((values.filter((v) => v === true).length / values.length) * 100) : 0;
+        default: {
+            const nums = values.map(asNumber).filter((n) => !Number.isNaN(n));
+            return numericFold(nums, cfg.function);
+        }
+    }
+}
+// ── Dates & timeline spans ───────────────────────────────────────────────────
+/** The `start` day of a date value (a plain `YYYY-MM-DD` string or a {@link DateRange}). */
+export function dateStart(value) {
+    if (typeof value === 'string')
+        return value.trim() ? value : null;
+    if (value && typeof value === 'object') {
+        const s = value.start;
+        return typeof s === 'string' && s.trim() ? s : null;
+    }
+    return null;
+}
+/** The `end` day of a {@link DateRange} value (null for a single-day date). */
+export function dateEnd(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const e = value.end;
+        return typeof e === 'string' && e.trim() ? e : null;
+    }
+    return null;
+}
+/** Parse a `YYYY-MM-DD` (or any Date-parseable) string to a *local* midnight Date. */
+export function parseDay(value) {
+    if (!value)
+        return null;
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(value);
+    if (m)
+        return new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+/**
+ * The timeline bar span for a row: `[start, end]` resolved from the view's date
+ * configuration — a `dateRange` property (start+end in one), or a start date
+ * property plus an optional `endDatePropertyId`. Returns `null` when the row has
+ * no start date. A missing/earlier end collapses to a single-day bar.
+ */
+export function rowDateSpan(row, view, properties) {
+    const startProp = properties.find((p) => p.id === view.datePropertyId);
+    if (!startProp)
+        return null;
+    const raw = row.properties[startProp.id];
+    const start = parseDay(dateStart(raw));
+    if (!start)
+        return null;
+    const endProp = view.endDatePropertyId ? properties.find((p) => p.id === view.endDatePropertyId) : undefined;
+    const endStr = endProp ? dateStart(row.properties[endProp.id]) : dateEnd(raw);
+    const end = parseDay(endStr);
+    return { start, end: end && end >= start ? end : start };
+}
+/**
+ * The map marker location for a row: the resolved coords of the view's
+ * `geoPropertyId` location cell, or null when the row has no usable coords (an
+ * empty cell, or an address that hasn't been geocoded). Pure — drives the map
+ * view's placed/unplaced split and is unit-testable.
+ */
+export function rowLocation(row, view, properties) {
+    const geoProp = view.geoPropertyId ? properties.find((p) => p.id === view.geoPropertyId) : undefined;
+    if (!geoProp)
+        return null;
+    return asLocation(row.properties[geoProp.id]);
+}
+/**
+ * Lay a database's rows out as a dependency DAG: each row is a node, and its
+ * `dependency` property lists the predecessors it points back to (edge
+ * predecessor → dependent). Nodes are assigned a **layer** by longest path from a
+ * root (a row with no predecessors) so dependents always sit to the right of
+ * everything they depend on, and an **order** within the layer (stable, by row
+ * order). Pure and cycle-safe — a back-edge simply doesn't deepen the layer — so
+ * it can drive the graph view and be unit-tested directly.
+ */
+export function dependencyGraph(rows, dependencyPropertyId) {
+    const ids = new Set(rows.map((r) => r.id));
+    const predsOf = new Map();
+    for (const r of rows) {
+        const raw = dependencyPropertyId ? r.properties[dependencyPropertyId] : undefined;
+        const deps = Array.isArray(raw) ? raw.filter((d) => typeof d === 'string') : [];
+        predsOf.set(r.id, deps.filter((id) => ids.has(id) && id !== r.id));
+    }
+    const layerCache = new Map();
+    const computing = new Set();
+    const layerOf = (id) => {
+        const cached = layerCache.get(id);
+        if (cached !== undefined)
+            return cached;
+        if (computing.has(id))
+            return 0; // cycle — break without deepening
+        computing.add(id);
+        const preds = predsOf.get(id) ?? [];
+        const layer = preds.length === 0 ? 0 : Math.max(...preds.map(layerOf)) + 1;
+        computing.delete(id);
+        layerCache.set(id, layer);
+        return layer;
+    };
+    const perLayer = new Map();
+    const nodes = rows.map((r) => {
+        const layer = layerOf(r.id);
+        const order = perLayer.get(layer) ?? 0;
+        perLayer.set(layer, order + 1);
+        return { id: r.id, layer, order };
+    });
+    const edges = [];
+    for (const r of rows)
+        for (const p of predsOf.get(r.id) ?? [])
+            edges.push({ from: p, to: r.id });
+    return {
+        nodes,
+        edges,
+        layerCount: Math.max(0, ...nodes.map((n) => n.layer)) + 1,
+        maxLayerSize: Math.max(1, ...[...perLayer.values()]),
+    };
+}
+/**
+ * Compute the inverse-property writes for a two-way `dependency` change: when
+ * `rowId`'s links go from `oldIds` to `newIds`, each newly-added related row gains
+ * `rowId` in its `inversePropertyId`, and each removed one loses it. Pure — the
+ * hook applies the returned updates — so the sync logic is unit-tested directly.
+ */
+export function syncInverseUpdates(rowId, oldIds, newIds, relatedRows, inversePropertyId) {
+    const byId = new Map(relatedRows.map((r) => [r.id, r]));
+    const inverseOf = (r) => Array.isArray(r.properties[inversePropertyId]) ? r.properties[inversePropertyId] : [];
+    const updates = [];
+    for (const id of newIds.filter((x) => !oldIds.includes(x))) {
+        const r = byId.get(id);
+        if (r && !inverseOf(r).includes(rowId))
+            updates.push({ rowId: id, value: [...inverseOf(r), rowId] });
+    }
+    for (const id of oldIds.filter((x) => !newIds.includes(x))) {
+        const r = byId.get(id);
+        if (r && inverseOf(r).includes(rowId))
+            updates.push({ rowId: id, value: inverseOf(r).filter((x) => x !== rowId) });
+    }
+    return updates;
+}
+const isEmpty = (v) => v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0);
+const asNumber = (v) => {
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string' && v.trim() !== '')
+        return Number(v);
+    return NaN;
+};
+const startOfDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate());
+const shiftDays = (d, n) => new Date(d.getFullYear(), d.getMonth(), d.getDate() + n);
+/** Evaluate a relative-to-`now` date operator against a cell's day value. */
+function matchesRelativeDate(operator, cell, now) {
+    const day = parseDay(typeof cell === 'string' ? cell : '');
+    if (!day)
+        return false;
+    const today = startOfDay(now);
+    switch (operator) {
+        case 'is_today':
+            return day.getTime() === today.getTime();
+        case 'is_this_week': {
+            const start = shiftDays(today, -today.getDay()); // week starts Sunday
+            return day >= start && day < shiftDays(start, 7);
+        }
+        case 'is_past_week':
+            return day >= shiftDays(today, -7) && day <= today;
+        case 'is_next_week':
+            return day > today && day <= shiftDays(today, 7);
+        case 'is_this_month':
+            return day.getFullYear() === today.getFullYear() && day.getMonth() === today.getMonth();
+        default:
+            return false;
+    }
+}
+/**
+ * Evaluate a single filter against a resolved value. The optional `now`
+ * (defaulting to the current date) anchors the relative date operators
+ * (`is_today`, `is_this_week`, …) — pass it explicitly to keep tests deterministic.
+ */
+export function matchesFilter(operator, cell, target, now) {
+    if (RELATIVE_DATE_OPS.includes(operator))
+        return matchesRelativeDate(operator, cell, now ?? new Date());
+    // Array cells (multi-select / relation) test membership / emptiness.
+    if (Array.isArray(cell)) {
+        const needle = String(target ?? '').toLowerCase();
+        const has = cell.some((x) => String(x).toLowerCase().includes(needle));
+        switch (operator) {
+            case 'contains':
+                return has;
+            case 'not_contains':
+                return !has;
+            case 'is_empty':
+                return cell.length === 0;
+            case 'is_not_empty':
+                return cell.length > 0;
+            default:
+                return true;
+        }
+    }
+    switch (operator) {
+        case 'equals':
+            return String(cell ?? '') === String(target ?? '');
+        case 'not_equals':
+            return String(cell ?? '') !== String(target ?? '');
+        case 'contains':
+            return String(cell ?? '').toLowerCase().includes(String(target ?? '').toLowerCase());
+        case 'not_contains':
+            return !String(cell ?? '').toLowerCase().includes(String(target ?? '').toLowerCase());
+        case 'starts_with':
+            return String(cell ?? '').toLowerCase().startsWith(String(target ?? '').toLowerCase());
+        case 'ends_with':
+            return String(cell ?? '').toLowerCase().endsWith(String(target ?? '').toLowerCase());
+        case 'gt':
+            return asNumber(cell) > asNumber(target);
+        case 'lt':
+            return asNumber(cell) < asNumber(target);
+        case 'gte':
+            return asNumber(cell) >= asNumber(target);
+        case 'lte':
+            return asNumber(cell) <= asNumber(target);
+        case 'before':
+        case 'after':
+        case 'on_or_before':
+        case 'on_or_after': {
+            const c = parseDay(String(cell ?? ''));
+            const t = parseDay(String(target ?? ''));
+            if (!c || !t)
+                return false;
+            const d = c.getTime() - t.getTime();
+            return operator === 'before' ? d < 0 : operator === 'after' ? d > 0 : operator === 'on_or_before' ? d <= 0 : d >= 0;
+        }
+        case 'is_empty':
+            return isEmpty(cell);
+        case 'is_not_empty':
+            return !isEmpty(cell);
+        case 'is_checked':
+            return cell === true;
+        case 'is_unchecked':
+            return cell !== true;
+        default:
+            return true;
+    }
+}
+const propertyById = (properties, id) => id === TITLE_PROPERTY_ID ? TITLE_PROPERTY_ID : properties.find((p) => p.id === id);
+/** Compare two resolved cell values for sorting, numeric when both look numeric. */
+function compareValues(a, b) {
+    if (isEmpty(a) && isEmpty(b))
+        return 0;
+    if (isEmpty(a))
+        return 1; // empties sort last
+    if (isEmpty(b))
+        return -1;
+    const na = asNumber(a);
+    const nb = asNumber(b);
+    if (!Number.isNaN(na) && !Number.isNaN(nb))
+        return na - nb;
+    return String(a).localeCompare(String(b));
+}
+/**
+ * The effective filter tree for a view: its `filterRoot`, or a synthesised
+ * all-`and` group wrapping the legacy flat `filters`. Lets the UI always edit a
+ * single tree while old views keep working.
+ */
+export function viewFilterRoot(view) {
+    return view.filterRoot ?? { id: 'root', conjunction: 'and', filters: view.filters ?? [] };
+}
+/**
+ * Apply a view's filters and sorts to a row set, returning a new array. Filters
+ * are evaluated as a nested and/or tree ({@link viewFilterRoot}); sorts are
+ * applied in order (first sort is primary). Pure and side-effect free so it can
+ * run identically on the server or in the table UI.
+ */
+/**
+ * True when a single leaf condition holds for a row — the same per-row test
+ * {@link applyView} uses for filtering, exposed for conditional formatting
+ * (color rules). Returns false when the condition's property no longer exists.
+ */
+export function rowMatchesCondition(row, condition, properties, rows) {
+    const prop = properties.find((p) => p.id === condition.propertyId);
+    if (!prop)
+        return false;
+    return matchesFilter(condition.operator, rowValue(row, prop, properties, rows), condition.value);
+}
+export function applyView(rows, view, properties) {
+    const root = viewFilterRoot(view);
+    const evalNode = (node, row) => {
+        if (isFilterGroup(node)) {
+            if (node.filters.length === 0)
+                return true; // empty group matches everything
+            const results = node.filters.map((child) => evalNode(child, row));
+            return node.conjunction === 'or' ? results.some(Boolean) : results.every(Boolean);
+        }
+        const prop = propertyById(properties, node.propertyId);
+        if (!prop)
+            return true;
+        return matchesFilter(node.operator, rowValue(row, prop, properties, rows), node.value);
+    };
+    const filtered = rows.filter((row) => evalNode(root, row));
+    const sorts = view.sorts ?? [];
+    if (sorts.length === 0)
+        return filtered;
+    // Stable multi-key sort: index-tagged to keep equal rows in original order.
+    return filtered
+        .map((row, index) => ({ row, index }))
+        .sort((a, b) => {
+        for (const sort of sorts) {
+            const prop = propertyById(properties, sort.propertyId);
+            if (!prop)
+                continue;
+            const cmp = compareValues(rowValue(a.row, prop, properties, rows), rowValue(b.row, prop, properties, rows));
+            if (cmp !== 0)
+                return sort.direction === 'desc' ? -cmp : cmp;
+        }
+        return a.index - b.index;
+    })
+        .map((entry) => entry.row);
+}
+// ── Defaults ─────────────────────────────────────────────────────────────────
+let counter = 0;
+/** Short non-cryptographic id for properties/views/options/filters. */
+export const shortId = (prefix) => {
+    counter += 1;
+    const rand = typeof crypto !== 'undefined' && 'randomUUID' in crypto ? crypto.randomUUID().slice(0, 8) : `${counter}`;
+    return `${prefix}_${rand}`;
+};
+/**
+ * A sensible starting schema for a brand-new database: a couple of manual
+ * properties and both a table and a list view, so the view switcher has
+ * something to switch between out of the box.
+ */
+export function defaultDatabaseSchema() {
+    const status = {
+        id: shortId('prop'),
+        name: 'Status',
+        type: 'select',
+        options: [
+            { id: shortId('opt'), label: 'Todo', color: 'gray' },
+            { id: shortId('opt'), label: 'In progress', color: 'blue' },
+            { id: shortId('opt'), label: 'Done', color: 'green' },
+        ],
+    };
+    const notes = { id: shortId('prop'), name: 'Notes', type: 'text' };
+    return {
+        properties: [status, notes],
+        views: [
+            { id: shortId('view'), name: 'Table', type: 'table', filters: [], sorts: [] },
+            { id: shortId('view'), name: 'Board', type: 'board', filters: [], sorts: [], groupByPropertyId: status.id },
+            { id: shortId('view'), name: 'List', type: 'list', filters: [], sorts: [] },
+        ],
+    };
+}
+/** A fresh view of a given type with sensible defaults for its layout. */
+export function defaultView(type, name, properties) {
+    const view = { id: shortId('view'), name, type, filters: [], sorts: [] };
+    if (type === 'board' || type === 'bar' || type === 'pie') {
+        // Default the grouping to the first select/status property (kanban columns /
+        // chart categories read best off one), falling back to any property.
+        const select = properties.find((p) => p.type === 'select' || p.type === 'status');
+        view.groupByPropertyId = (select ?? properties[0])?.id;
+    }
+    if (type === 'calendar' || type === 'timeline') {
+        const date = properties.find((p) => p.type === 'date' || p.type === 'created_time' || p.type === 'last_edited_time');
+        view.datePropertyId = date?.id;
+    }
+    if (type === 'timeline') {
+        // A non-range start date pairs with a second date property for the bar end;
+        // a `dependency` property (if any) draws the arrows between bars.
+        const dates = properties.filter((p) => p.type === 'date');
+        if (dates.length >= 2 && !dates[0].dateRange)
+            view.endDatePropertyId = dates[1].id;
+        view.dependencyPropertyId = properties.find((p) => p.type === 'dependency')?.id;
+    }
+    if (type === 'graph') {
+        view.dependencyPropertyId = properties.find((p) => p.type === 'dependency')?.id;
+    }
+    if (type === 'map') {
+        // Place markers off the first location property; clustering on by default.
+        view.geoPropertyId = properties.find((p) => p.type === 'location')?.id;
+        view.mapClustered = true;
+    }
+    return view;
+}
+/** The starting options for a `status` property: one per lifecycle bucket. */
+export function defaultStatusOptions() {
+    return [
+        { id: shortId('opt'), label: 'Not started', color: 'gray', group: 'todo' },
+        { id: shortId('opt'), label: 'In progress', color: 'blue', group: 'in_progress' },
+        { id: shortId('opt'), label: 'Done', color: 'green', group: 'complete' },
+    ];
+}
+/** The lifecycle buckets a `status` property groups its options under, in order. */
+export const STATUS_GROUPS = [
+    { id: 'todo', label: 'To-do' },
+    { id: 'in_progress', label: 'In progress' },
+    { id: 'complete', label: 'Complete' },
+];
+/**
+ * Remove a property from a schema and scrub **every** dangling reference to it:
+ * each view's filters (flat list *and* the nested {@link filterRoot} tree),
+ * sorts, visible columns, summaries, and the group-by / date / cover config; plus
+ * any `rollup` on another property that aggregated through or over it. Pure —
+ * returns a fresh schema — so it can be unit-tested and shared by the delete
+ * action. (Renders already tolerate stale refs; this keeps the schema clean.)
+ */
+export function removeProperty(schema, propertyId) {
+    const pruneNode = (node) => {
+        if (isFilterGroup(node)) {
+            return { ...node, filters: node.filters.map(pruneNode).filter((n) => n !== null) };
+        }
+        return node.propertyId === propertyId ? null : node;
+    };
+    return {
+        ...schema,
+        properties: schema.properties
+            .filter((p) => p.id !== propertyId)
+            .map((p) => {
+            let next = p;
+            if (p.rollup && (p.rollup.relationPropertyId === propertyId || p.rollup.targetPropertyId === propertyId)) {
+                next = { ...next, rollup: undefined };
+            }
+            // Break a two-way dependency pairing when its partner is removed.
+            if (p.syncedPropertyId === propertyId)
+                next = { ...next, syncedPropertyId: undefined };
+            return next;
+        }),
+        views: schema.views.map((v) => {
+            const summaries = v.summaries
+                ? Object.fromEntries(Object.entries(v.summaries).filter(([k]) => k !== propertyId))
+                : undefined;
+            return {
+                ...v,
+                filters: (v.filters ?? []).filter((f) => f.propertyId !== propertyId),
+                filterRoot: v.filterRoot ? pruneNode(v.filterRoot) : undefined,
+                sorts: (v.sorts ?? []).filter((s) => s.propertyId !== propertyId),
+                visiblePropertyIds: v.visiblePropertyIds?.filter((id) => id !== propertyId),
+                summaries,
+                groupByPropertyId: v.groupByPropertyId === propertyId ? undefined : v.groupByPropertyId,
+                subGroupByPropertyId: v.subGroupByPropertyId === propertyId ? undefined : v.subGroupByPropertyId,
+                datePropertyId: v.datePropertyId === propertyId ? undefined : v.datePropertyId,
+                endDatePropertyId: v.endDatePropertyId === propertyId ? undefined : v.endDatePropertyId,
+                dependencyPropertyId: v.dependencyPropertyId === propertyId ? undefined : v.dependencyPropertyId,
+                coverPropertyId: v.coverPropertyId === propertyId ? undefined : v.coverPropertyId,
+                geoPropertyId: v.geoPropertyId === propertyId ? undefined : v.geoPropertyId,
+                addressPropertyId: v.addressPropertyId === propertyId ? undefined : v.addressPropertyId,
+            };
+        }),
+        // Drop the removed property's seed value from every row template.
+        templates: schema.templates?.map((t) => propertyId in t.properties
+            ? { ...t, properties: Object.fromEntries(Object.entries(t.properties).filter(([k]) => k !== propertyId)) }
+            : t),
+    };
+}
+// ── Number formatting ────────────────────────────────────────────────────────
+const FORMAT_PREFIX = { dollar: '$', euro: '€', pound: '£', rupee: '₹' };
+/** Format a numeric value for display per a {@link NumberFormat}. Non-numbers pass through as text. */
+export function formatNumber(value, format) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN;
+    if (Number.isNaN(n))
+        return value === undefined || value === null ? '' : String(value);
+    switch (format) {
+        case 'integer':
+            return Math.round(n).toLocaleString();
+        case 'decimal':
+            return n.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+        case 'percent':
+            return `${(n * 100).toLocaleString(undefined, { maximumFractionDigits: 2 })}%`;
+        case 'yen':
+            return `¥${Math.round(n).toLocaleString()}`; // yen is conventionally whole-number
+        case 'dollar':
+        case 'euro':
+        case 'pound':
+        case 'rupee':
+            return `${FORMAT_PREFIX[format]}${n.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+        default:
+            return Number.isInteger(n) ? String(n) : String(Number(n.toFixed(4)));
+    }
+}
+/**
+ * Format a `unique_id` value for display: an integer, optionally prefixed
+ * (`TASK` → `TASK-3`). Empty for unassigned (non-numeric) values. Pure.
+ */
+export function formatUniqueId(value, prefix) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return '';
+    const p = prefix?.trim();
+    return p ? `${p}-${value}` : String(value);
+}
+/**
+ * The clamped 0..1 fraction of a number cell relative to its `target` (the
+ * value that fills a `bar`/`ring`). Non-numbers and a non-positive target read
+ * as 0; the target defaults to 100. Pure — drives the bar/ring cell and tests.
+ */
+export function numberProgress(value, target) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN;
+    const max = typeof target === 'number' && target > 0 ? target : 100;
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(1, n / max));
+}
+// ── Grouping + aggregation (board columns, charts) ───────────────────────────
+/** The label shown for rows that have no value for the grouping property. */
+export const NO_VALUE_GROUP = 'No value';
+/** Display string for a row's value of a property (option labels, joined lists). */
+function displayValue(row, property, properties) {
+    const v = rowValue(row, property, properties);
+    if (property.type === 'select' || property.type === 'status') {
+        return property.options?.find((o) => o.id === row.properties[property.id])?.label ?? '';
+    }
+    if (v instanceof FormulaError)
+        return v.message;
+    if (property.type === 'location') {
+        const loc = asLocation(v);
+        return loc ? loc.label ?? loc.address ?? `${loc.lat.toFixed(4)}, ${loc.lng.toFixed(4)}` : '';
+    }
+    if (Array.isArray(v))
+        return v.map(String).join(', ');
+    if (v === undefined || v === null)
+        return '';
+    if (typeof v === 'boolean')
+        return v ? 'Checked' : 'Unchecked';
+    return String(v);
+}
+/**
+ * Group rows by a property for the board (kanban) layout. When the property is a
+ * `select`, columns follow the option order (including empty ones) so the board
+ * is stable as rows move; otherwise columns are the distinct displayed values.
+ * Rows with no value collect into a trailing {@link NO_VALUE_GROUP} column.
+ */
+export function groupRows(rows, property, properties) {
+    if (!property)
+        return [{ key: '__all__', label: 'All', rows }];
+    if (property.type === 'select' || property.type === 'status') {
+        const groups = (property.options ?? []).map((o) => ({ key: o.id, label: o.label, color: o.color, rows: [] }));
+        const byId = new Map(groups.map((g) => [g.key, g]));
+        const none = { key: '__none__', label: NO_VALUE_GROUP, rows: [] };
+        for (const row of rows) {
+            const id = row.properties[property.id];
+            const group = typeof id === 'string' ? byId.get(id) : undefined;
+            (group ?? none).rows.push(row);
+        }
+        return none.rows.length ? [...groups, none] : groups;
+    }
+    // Relation: one group per *linked page* (keyed by its row/page id), so a board
+    // or timeline grouped by a relation gets a column/band per related page. A row
+    // with several links appears in each; the UI resolves the key to a page
+    // title + icon. Rows with no link collect into the trailing "No value" group.
+    if (property.type === 'relation') {
+        const order = [];
+        const byId = new Map();
+        const none = { key: '__none__', label: NO_VALUE_GROUP, rows: [] };
+        for (const row of rows) {
+            const raw = row.properties[property.id];
+            const ids = Array.isArray(raw) ? raw.filter((x) => typeof x === 'string') : [];
+            if (ids.length === 0) {
+                none.rows.push(row);
+                continue;
+            }
+            for (const id of ids) {
+                let group = byId.get(id);
+                if (!group) {
+                    // Label is the page id; the UI swaps in the resolved title.
+                    group = { key: id, label: id, rows: [] };
+                    byId.set(id, group);
+                    order.push(id);
+                }
+                group.rows.push(row);
+            }
+        }
+        const groups = order.map((id) => byId.get(id));
+        return none.rows.length ? [...groups, none] : groups;
+    }
+    // Generic: bucket by displayed value, preserving first-seen order.
+    const order = [];
+    const byLabel = new Map();
+    for (const row of rows) {
+        const label = displayValue(row, property, properties) || NO_VALUE_GROUP;
+        let group = byLabel.get(label);
+        if (!group) {
+            group = { key: label, label, rows: [] };
+            byLabel.set(label, group);
+            order.push(label);
+        }
+        group.rows.push(row);
+    }
+    return order.map((label) => byLabel.get(label));
+}
+/**
+ * Sentinel `groupByPropertyId` meaning "group by parent item" (sub-items).
+ * Not a real property id — {@link groupRowsBy} dispatches on it.
+ */
+export const PARENT_GROUP_ID = '__parent__';
+/** The label of the trailing group for rows that are nobody's sub-item. */
+export const NO_PARENT_GROUP = 'No parent';
+/**
+ * Group rows by their parent row (sub-items): one group per row with at least
+ * one direct child in the set (key = the parent's row id, in row order), plus a
+ * trailing {@link NO_PARENT_GROUP} group for loose rows — rows that neither
+ * have a parent in the set nor children of their own. A row that is both a
+ * parent and a sub-item appears in its parent's group *and* heads its own.
+ * Parents outside the set (filtered out, or the host page) don't count.
+ */
+export function groupRowsByParent(rows) {
+    const ids = new Set(rows.map((r) => r.id));
+    const children = new Map();
+    for (const row of rows) {
+        if (row.parentId && ids.has(row.parentId)) {
+            const list = children.get(row.parentId);
+            if (list)
+                list.push(row);
+            else
+                children.set(row.parentId, [row]);
+        }
+    }
+    const groups = [];
+    const none = { key: '__none__', label: NO_PARENT_GROUP, rows: [] };
+    for (const row of rows) {
+        const kids = children.get(row.id);
+        if (kids)
+            groups.push({ key: row.id, label: row.name?.trim() || 'Untitled', rows: kids });
+        else if (!(row.parentId && ids.has(row.parentId)))
+            none.rows.push(row);
+    }
+    return none.rows.length ? [...groups, none] : groups;
+}
+/**
+ * Group rows by a view's `groupByPropertyId`: the {@link PARENT_GROUP_ID}
+ * sentinel groups by parent item ({@link groupRowsByParent}); anything else
+ * resolves to a property and falls through to {@link groupRows} (an unset or
+ * unknown id yields the single "All" group). The one dispatch shared by the
+ * board, table, list, gallery, and the chart aggregations.
+ */
+export function groupRowsBy(rows, groupByPropertyId, properties) {
+    if (groupByPropertyId === PARENT_GROUP_ID)
+        return groupRowsByParent(rows);
+    return groupRows(rows, properties.find((p) => p.id === groupByPropertyId), properties);
+}
+const foldAggregate = (rows, agg, properties) => {
+    if (agg.type === 'count' || !agg.propertyId)
+        return rows.length;
+    const prop = properties.find((p) => p.id === agg.propertyId);
+    if (!prop)
+        return rows.length;
+    const nums = rows
+        .map((r) => rowValue(r, prop, properties, rows))
+        .map((v) => (typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : NaN))
+        .filter((n) => !Number.isNaN(n));
+    if (nums.length === 0)
+        return 0;
+    switch (agg.type) {
+        case 'sum':
+            return nums.reduce((a, b) => a + b, 0);
+        case 'avg':
+            return nums.reduce((a, b) => a + b, 0) / nums.length;
+        case 'min':
+            return Math.min(...nums);
+        case 'max':
+            return Math.max(...nums);
+        default:
+            return rows.length;
+    }
+};
+/**
+ * Aggregate rows into chart data: one datum per group of the view's
+ * `groupByPropertyId`, with the bar/slice height computed by the view's
+ * `aggregate` (count by default, else sum/avg/min/max of a numeric property).
+ */
+export function aggregateRows(rows, view, properties) {
+    const agg = view.aggregate ?? { type: 'count' };
+    return groupRowsBy(rows, view.groupByPropertyId, properties).map((g) => ({
+        key: g.key,
+        label: g.label,
+        color: g.color,
+        value: foldAggregate(g.rows, agg, properties),
+    }));
+}
+/** Synthetic series used when a chart has no breakdown (a single full-height bar). */
+export const CHART_TOTAL_SERIES = '__total__';
+/**
+ * Aggregate rows into a {@link ChartMatrix}: one group per value of the view's
+ * `groupByPropertyId`, each split into segments by `breakdownPropertyId` (the
+ * second-level group). The series are derived once across all rows so every group
+ * shares the same ordered, coloured set — a group with no rows for a series gets a
+ * zero segment, keeping stacked bars aligned. Without a breakdown each group has a
+ * single {@link CHART_TOTAL_SERIES} segment equal to its total. Pure — drives the
+ * bar and pie charts and their drill-downs.
+ */
+export function aggregateMatrix(rows, view, properties) {
+    const agg = view.aggregate ?? { type: 'count' };
+    const groups = groupRowsBy(rows, view.groupByPropertyId, properties);
+    // A breakdown id is honoured when it differs from the primary grouping and
+    // resolves to something real (a property, or the parent-item sentinel).
+    const breakdownId = view.breakdownPropertyId &&
+        view.breakdownPropertyId !== view.groupByPropertyId &&
+        (view.breakdownPropertyId === PARENT_GROUP_ID || properties.some((p) => p.id === view.breakdownPropertyId))
+        ? view.breakdownPropertyId
+        : undefined;
+    if (!breakdownId) {
+        return {
+            series: [{ key: CHART_TOTAL_SERIES, label: '' }],
+            groups: groups.map((g) => {
+                const total = foldAggregate(g.rows, agg, properties);
+                return {
+                    key: g.key,
+                    label: g.label,
+                    color: g.color,
+                    total,
+                    rows: g.rows,
+                    segments: [{ seriesKey: CHART_TOTAL_SERIES, value: total, rows: g.rows }],
+                };
+            }),
+        };
+    }
+    // Derive the shared series from the breakdown across every row (stable order).
+    // Segments intersect a series' full-set rows with the group's rows rather than
+    // re-grouping the subset: for property breakdowns the two are equivalent, but a
+    // parent-item breakdown needs the full set (a subset loses the parents that
+    // anchor its groups).
+    const seriesGroups = groupRowsBy(rows, breakdownId, properties);
+    const series = seriesGroups.map((s) => ({ key: s.key, label: s.label, color: s.color }));
+    return {
+        series,
+        groups: groups.map((g) => {
+            const inGroup = new Set(g.rows.map((r) => r.id));
+            const segments = seriesGroups.map((s) => {
+                const segRows = s.rows.filter((r) => inGroup.has(r.id));
+                return { seriesKey: s.key, value: foldAggregate(segRows, agg, properties), rows: segRows };
+            });
+            return { key: g.key, label: g.label, color: g.color, total: foldAggregate(g.rows, agg, properties), rows: g.rows, segments };
+        }),
+    };
+}
+// ── Column summaries (table footers) ─────────────────────────────────────────
+const toNum = (v) => typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : NaN;
+/**
+ * Compute a column footer summary over a row set: counts (all / values / empty /
+ * filled / unique), percentages, or numeric folds (sum / avg / min / max / range
+ * / median). Returns a display string ('' for `none`). `property` is
+ * {@link TITLE_PROPERTY_ID} for the title column; numeric folds honour a
+ * property's `numberFormat`. Pure — shared by the table footer UI and tests.
+ */
+export function summarizeColumn(rows, property, type, properties) {
+    if (type === 'none')
+        return '';
+    if (type === 'count_all')
+        return String(rows.length);
+    const values = rows.map((r) => rowValue(r, property, properties, rows));
+    const filled = values.filter((v) => !isEmpty(v));
+    const total = rows.length || 1;
+    switch (type) {
+        case 'count_values':
+        case 'count_filled':
+            return String(filled.length);
+        case 'count_empty':
+            return String(values.length - filled.length);
+        case 'count_unique':
+            return String(new Set(filled.map((v) => (Array.isArray(v) ? JSON.stringify(v) : String(v)))).size);
+        case 'percent_empty':
+            return `${Math.round(((values.length - filled.length) / total) * 100)}%`;
+        case 'percent_filled':
+            return `${Math.round((filled.length / total) * 100)}%`;
+        default:
+            break;
+    }
+    // Numeric folds.
+    const nums = filled.map(toNum).filter((n) => !Number.isNaN(n)).sort((a, b) => a - b);
+    if (nums.length === 0)
+        return '—';
+    const format = property !== TITLE_PROPERTY_ID ? property.numberFormat : undefined;
+    const fmt = (n) => formatNumber(n, format);
+    switch (type) {
+        case 'sum':
+            return fmt(nums.reduce((a, b) => a + b, 0));
+        case 'avg':
+            return fmt(nums.reduce((a, b) => a + b, 0) / nums.length);
+        case 'min':
+            return fmt(nums[0]);
+        case 'max':
+            return fmt(nums[nums.length - 1]);
+        case 'range':
+            return fmt(nums[nums.length - 1] - nums[0]);
+        case 'median': {
+            const mid = Math.floor(nums.length / 2);
+            return fmt(nums.length % 2 ? nums[mid] : (nums[mid - 1] + nums[mid]) / 2);
+        }
+        default:
+            return '';
+    }
+}
+//# sourceMappingURL=database.js.map