@book.dev/sdk 1.60.0

package/dist/database.d.ts

@@ -0,0 +1,687 @@
+/**
+ * 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 type { PageSnapshot } from './types';
+/**
+ * The value kinds a property can hold. The manual kinds
+ * (`text`/`number`/`select`/`status`/`checkbox`/`date`/`person`/`verification`)
+ * store their value per row in `page.properties[id]`. `expr` projects a named
+ * reactive cell from the row page's document; `formula` computes from the row's
+ * *other* properties (`prop("Price") * prop("Qty")`); `rollup` folds a target
+ * property across the rows a `relation`/`dependency` points to; `backlinks` is
+ * computed from the link graph (never stored). The last three
+ * (`person`/`verification`/`backlinks`) double as the built-in page properties —
+ * see {@link ./pageProperties}.
+ */
+export type DatabasePropertyType = 'text' | 'number' | 'rating' | 'select' | 'multi_select' | 'status' | 'checkbox' | 'date' | 'url' | 'email' | 'phone' | 'location' | 'files' | 'relation' | 'dependency' | 'rollup' | 'created_time' | 'last_edited_time' | 'unique_id' | 'expr' | 'formula' | 'person' | 'verification' | 'backlinks';
+/** Display formatting for `number`/`formula`/`expr` numeric values. */
+export type NumberFormat = 'plain' | 'integer' | 'decimal' | 'percent' | 'dollar' | 'euro' | 'pound' | 'yen' | 'rupee';
+/** How a number cell is visualised: as text, a horizontal bar, or a ring. */
+export type NumberDisplay = 'number' | 'bar' | 'ring';
+/** The lifecycle bucket a `status` option belongs to. */
+export type StatusGroup = 'todo' | 'in_progress' | 'complete';
+/** One choice in a `select` / `multi_select` / `status` property. */
+export interface DatabaseSelectOption {
+    id: string;
+    label: string;
+    /** A token from the shared swatch palette (see `SELECT_COLORS`). */
+    color?: string;
+    /** For `status` options: which lifecycle bucket the option sits in. */
+    group?: StatusGroup;
+}
+/** How a {@link DatabaseProperty.rollup} folds the related rows' target values. */
+export type RollupFunction = 'show_original' | 'count' | 'count_values' | 'count_unique' | 'sum' | 'avg' | 'min' | 'max' | 'range' | 'median' | 'checked' | 'percent_checked';
+/** Rollup configuration: aggregate a related set's target property. */
+export interface RollupConfig {
+    /** A `relation` / `dependency` property on this row holding the related ids. */
+    relationPropertyId: string;
+    /** The property on the related rows to fold ({@link TITLE_PROPERTY_ID} for the title). */
+    targetPropertyId: string;
+    function: RollupFunction;
+}
+/**
+ * A column definition. Manual types (`text`/`number`/`select`/`checkbox`/
+ * `date`) store their value per row in `page.properties[id]`. The `expr` type
+ * stores nothing on the row — its value is projected live from the row page's
+ * exported cell named {@link cellName}.
+ */
+export interface DatabaseProperty {
+    id: string;
+    name: string;
+    type: DatabasePropertyType;
+    /** Choices, for `select` / `multi_select` properties. */
+    options?: DatabaseSelectOption[];
+    /** Name of the exported reactive cell to read, for `expr` properties. */
+    cellName?: string;
+    /** Expression source, for `formula` properties (references other props by name). */
+    formula?: string;
+    /** Numeric display format, for `number` / `formula` / `expr` properties. */
+    numberFormat?: NumberFormat;
+    /** How a `number` cell is visualised: plain text (default), a `bar`, or a `ring`. */
+    numberDisplay?: NumberDisplay;
+    /** The 100%-of-the-bar value for `bar`/`ring` display (defaults to 100). */
+    numberTarget?: number;
+    /** Optional prefix for a `unique_id` property, e.g. `TASK` → `TASK-1`. */
+    idPrefix?: string;
+    /**
+     * `date` only: when true the cell holds a `{start, end}` range (a `DateRange`)
+     * instead of a single `YYYY-MM-DD` string. Drives the timeline's bar length.
+     */
+    dateRange?: boolean;
+    /** `date` only: when true the cell stores a time too (`YYYY-MM-DDTHH:mm`). */
+    includeTime?: boolean;
+    /** `date` only: show dates relative to today ("Today", "In 3 days") near the present,
+     *  falling back to an absolute date further out. Defaults to absolute. */
+    dateDisplay?: 'absolute' | 'relative';
+    /** A short helper description, shown beneath the field in the page-view panel. */
+    description?: string;
+    /** The {@link PropertyGroup} this property belongs to (page-view organisation). */
+    groupId?: string;
+    /** Hidden in the page-view properties panel (still available as a table column). */
+    pageHidden?: boolean;
+    /** Rollup configuration, for `rollup` properties. */
+    rollup?: RollupConfig;
+    /**
+     * For a two-way `dependency`: the id of the paired inverse `dependency` property
+     * (same database). Linking A→B via this property also lists A on B's inverse.
+     */
+    syncedPropertyId?: string;
+    /**
+     * `relation` only: the id of the **target database** whose rows this column
+     * links to. A relation is database↔database — the cell picks rows from this
+     * database. (A legacy relation without it links arbitrary pages.)
+     */
+    relationDatabaseId?: string;
+    /**
+     * `relation` only: cap the cell at a single linked row (the "one" side of a
+     * 1:1 or 1:n relation). Many (the default) is the "n" side. Read by the cell
+     * editor on every relation property (forward and reverse).
+     */
+    relationSingle?: boolean;
+    /**
+     * `relation` (forward side) only: the chosen cardinality, kept for display and
+     * to derive the reverse property's multiplicity when pairing a two-way link.
+     */
+    relationCardinality?: RelationCardinality;
+    /**
+     * `relation` only: the id of the paired reverse `relation` property on the
+     * {@link relationDatabaseId target database} (a two-way link). Mirrors
+     * {@link syncedPropertyId} but across databases — setting A→B also lists A on
+     * B's reverse column.
+     */
+    reversePropertyId?: string;
+}
+/** Relation cardinality, from the perspective of the forward property: how many
+ *  rows this side links, and how many the reverse side links back. */
+export type RelationCardinality = '1:1' | '1:n' | 'n:n';
+/** 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 declare function relationSides(card: RelationCardinality): {
+    forwardSingle: boolean;
+    reverseSingle: boolean;
+};
+/** The stored value of a `date` property configured as a range. */
+export interface DateRange {
+    start: string | null;
+    end?: string | null;
+}
+/**
+ * The stored value of a `location` property: a geographic point with optional
+ * human label and source address. The shape mirrors the `location` **kit
+ * input** (see `blockeditor/kit/scope.ts`) so the two are interchangeable —
+ * `address` is added here for the database's geocoding round-trip (a text/address
+ * property geocoded into coords keeps the source string for re-display).
+ */
+export interface LocationValue {
+    lat: number;
+    lng: number;
+    label?: string;
+    address?: string;
+}
+/** Read a `{lat, lng, …}` location value from a cell, or null when unresolvable. */
+export declare function asLocation(value: unknown): LocationValue | null;
+/**
+ * A named, collapsible/toggleable cluster of properties in the **page-view
+ * properties panel** (open a database row → its fields, organised). Hiding a
+ * group hides all its properties at once; collapsing just folds them away.
+ */
+export interface PropertyGroup {
+    id: string;
+    name: string;
+    /** When true, the group's properties are hidden from the page-view panel. */
+    hidden?: boolean;
+    /** When true, the group renders folded (a header you can expand). */
+    collapsed?: boolean;
+}
+/**
+ * A reusable new-row preset: a named set of property values applied when a row
+ * is created "from template". Captured from an existing row and stored on the
+ * schema so every view can offer it from the New-row control.
+ */
+export interface RowTemplate {
+    id: string;
+    name: string;
+    /** Property values to seed onto the new row (keyed by property id). */
+    properties: Record<string, unknown>;
+}
+/**
+ * The presentations the database screen supports. `table`/`list` are the
+ * row-oriented layouts; `gallery` shows cards; `board` is a kanban grouped by a
+ * select property; `calendar` lays rows out on a month grid by a date property;
+ * `bar`/`pie` are charts that aggregate rows by a category property.
+ */
+export type DatabaseViewType = 'table' | 'list' | 'gallery' | 'board' | 'calendar' | 'timeline' | 'map' | 'graph' | 'bar' | 'pie';
+/** How a chart (or a board column footer) aggregates a group of rows. */
+export interface ChartAggregate {
+    /** `count` tallies rows; the others fold a numeric `propertyId`. */
+    type: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    /** Property to fold (ignored for `count`). */
+    propertyId?: string;
+}
+/** A per-column footer calculation (table summary aggregations). */
+export type SummaryType = 'none' | 'count_all' | 'count_values' | 'count_empty' | 'count_filled' | 'count_unique' | 'percent_empty' | 'percent_filled' | 'sum' | 'avg' | 'min' | 'max' | 'range' | 'median';
+/** Comparison used by a {@link DatabaseFilter}. */
+export type FilterOperator = 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'gt' | 'lt' | 'gte' | 'lte' | 'before' | 'after' | 'on_or_before' | 'on_or_after' | 'is_today' | 'is_this_week' | 'is_past_week' | 'is_next_week' | 'is_this_month' | 'is_empty' | 'is_not_empty' | 'is_checked' | 'is_unchecked';
+/** The value-less, relative-to-today date operators. */
+export declare const RELATIVE_DATE_OPS: FilterOperator[];
+export interface DatabaseFilter {
+    id: string;
+    /** Property to test. The reserved id {@link TITLE_PROPERTY_ID} targets the page name. */
+    propertyId: string;
+    operator: FilterOperator;
+    value?: unknown;
+}
+/** How a {@link DatabaseFilterGroup}'s children combine. */
+export type FilterConjunction = 'and' | 'or';
+/**
+ * A nested filter group: a set of conditions and/or sub-groups combined with a
+ * single conjunction (all `and`, or any `or`). This is the nested filter
+ * tree — `view.filterRoot` is the root group; an empty group matches everything.
+ */
+export interface DatabaseFilterGroup {
+    id: string;
+    conjunction: FilterConjunction;
+    filters: Array<DatabaseFilter | DatabaseFilterGroup>;
+}
+/** A filter node is either a leaf condition or a nested group. */
+export type FilterNode = DatabaseFilter | DatabaseFilterGroup;
+/** True when a filter node is a group (vs. a leaf condition). */
+export declare function isFilterGroup(node: FilterNode): node is DatabaseFilterGroup;
+export type SortDirection = 'asc' | 'desc';
+export interface DatabaseSort {
+    propertyId: string;
+    direction: SortDirection;
+}
+/** A conditional-formatting rule: when its condition holds for a row, the row's
+ *  edge is tinted `color`. The first matching rule wins. */
+export interface ColorRule {
+    id: string;
+    propertyId: string;
+    operator: FilterOperator;
+    value?: unknown;
+    /** A swatch palette token (see `SELECT_COLORS`). */
+    color: string;
+}
+/** A dashboard metric card: a single aggregate over the view's filtered rows. */
+export interface DatabaseMetric {
+    id: string;
+    /** Property to summarise; the reserved {@link TITLE_PROPERTY_ID} counts rows. */
+    propertyId: string;
+    type: SummaryType;
+    /** Optional custom label (defaults to "<property> · <summary>"). */
+    label?: string;
+    /** Optional goal — when set, the card shows a progress bar of value/target. */
+    target?: number;
+}
+/** A saved presentation of the database: a layout plus its filters and sorts. */
+export interface DatabaseView {
+    id: string;
+    name: string;
+    type: DatabaseViewType;
+    /** Legacy flat (all-AND) filters. Superseded by {@link filterRoot} when present. */
+    filters: DatabaseFilter[];
+    /** The nested filter tree (and/or groups). Falls back to ANDing {@link filters}. */
+    filterRoot?: DatabaseFilterGroup;
+    sorts: DatabaseSort[];
+    /**
+     * Property ids to show, in order. Empty/undefined shows every property. The
+     * title is always shown and is not listed here.
+     */
+    visiblePropertyIds?: string[];
+    /**
+     * Property to group rows by. Drives the kanban columns (`board`) and the
+     * category axis of a chart (`bar`/`pie`). Best paired with a `select`
+     * property, but any property works (rows group by their displayed value).
+     */
+    groupByPropertyId?: string;
+    /** Chart aggregation (`bar`/`pie`). Defaults to counting rows per group. */
+    aggregate?: ChartAggregate;
+    /**
+     * Chart second-level group (`bar`/`pie`). Splits each `groupByPropertyId`
+     * category into stacked bar segments (or a breakdown ring on the pie). Ignored
+     * when unset or equal to `groupByPropertyId`.
+     */
+    breakdownPropertyId?: string;
+    /** Bar chart with a breakdown: stretch every bar to 100% and show each segment
+     *  as its share of the group total (proportions rather than absolute lengths). */
+    chartStacked100?: boolean;
+    /** Date property positioning rows on the month grid (`calendar`) or the bar
+     *  start on the `timeline`. A `dateRange` property supplies both ends at once. */
+    datePropertyId?: string;
+    /** Timeline only: the property giving each bar's end (when not a range date). */
+    endDatePropertyId?: string;
+    /** Timeline only: the `dependency` property whose links draw arrows between bars. */
+    dependencyPropertyId?: string;
+    /** Gallery only: a `files`/`url` property whose first image is the card cover. */
+    coverPropertyId?: string;
+    /** Gallery only: card preview size. Defaults to `medium`. */
+    cardSize?: 'small' | 'medium' | 'large';
+    /** Gallery/board: a `select`/`status` property whose option colour tints each card's edge. */
+    cardColorPropertyId?: string;
+    /** Conditional formatting: rules that tint a row/card edge when their condition holds. */
+    colorRules?: ColorRule[];
+    /** Per-column footer summaries (table), keyed by property id (or {@link TITLE_PROPERTY_ID}). */
+    summaries?: Record<string, SummaryType>;
+    /** Dashboard metric cards shown above the view (count/sum/avg/… over the filtered rows). */
+    metrics?: DatabaseMetric[];
+    /** Board only: the per-column footer calculation (a property + summary). Defaults
+     *  to summing the first numeric property, or counting rows. */
+    boardSummary?: {
+        propertyId: string;
+        type: SummaryType;
+    };
+    /** When grouped, collapse (fold) groups/columns/bands that currently have no rows
+     *  rather than removing them — they stay visible but folded. On unless set false. */
+    collapseEmptyGroups?: boolean;
+    /**
+     * Board/timeline only: a **second** grouping dimension. The board renders one
+     * horizontal swimlane per value of this property (columns stay the primary
+     * {@link groupByPropertyId}, the Notion model); the timeline already groups by
+     * {@link groupByPropertyId}. Distinct from the chart {@link breakdownPropertyId}
+     * (different semantics — keep the menus unambiguous).
+     */
+    subGroupByPropertyId?: string;
+    /** Map only: the `location` property whose coords place each row's marker. */
+    geoPropertyId?: string;
+    /** Map only: an optional text/address property the user can opt to geocode into
+     *  the {@link geoPropertyId} coords (no silent network calls — explicit action). */
+    addressPropertyId?: string;
+    /** Map only: cluster nearby markers at low zoom (default on for dense data). */
+    mapClustered?: boolean;
+}
+/** The full editable definition of a database: its columns, views, and the
+ *  page-view property groups. */
+export interface DatabaseSchema {
+    properties: DatabaseProperty[];
+    views: DatabaseView[];
+    /** Named groups organising the properties in the page-view panel. */
+    propertyGroups?: PropertyGroup[];
+    /** Reusable new-row presets offered by the New-row control. */
+    templates?: RowTemplate[];
+}
+/** A database as returned by the store. */
+export interface StoredDatabase {
+    id: string;
+    /** The host page that contains this database. */
+    pageId: string;
+    name: string | null;
+    schema: DatabaseSchema;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Payload for creating a database (always tied to an existing host page). */
+export interface DatabaseInput {
+    id?: string;
+    pageId: string;
+    name?: string | null;
+    schema?: DatabaseSchema;
+}
+/** Payload for editing a database's name and/or schema in place. */
+export interface DatabaseUpdate {
+    name?: string | null;
+    schema?: DatabaseSchema;
+}
+/**
+ * A single row, projected for list/table rendering. Lightweight on purpose: it
+ * carries the manual `properties` and the projected `exports` (named reactive
+ * values) but not the row page's full document — that is fetched only when the
+ * row is opened in the split pane.
+ */
+export interface DatabaseRow {
+    /** The row's page id. */
+    id: string;
+    /** The row's page title. */
+    name: string | null;
+    /** Manual property values, keyed by property id. */
+    properties: Record<string, unknown>;
+    /** Exported reactive cell values, keyed by cell name. */
+    exports: Record<string, unknown>;
+    /** The row this row is a *sub-item* of (another row of the same database), or null. */
+    parentId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Payload for creating a row (a new page inside the database). */
+export interface RowInput {
+    name?: string | null;
+    properties?: Record<string, unknown>;
+    data?: PageSnapshot;
+    /** Nest the new row under this row as a sub-item (same database). */
+    parentId?: string | null;
+}
+/**
+ * Arrange a flat row list into a parent→children forest by `parentId` (rows
+ * whose parent isn't in the set become roots), preserving the input order within
+ * each sibling group. Used to render sub-items as an expandable tree.
+ */
+export interface RowTreeNode {
+    row: DatabaseRow;
+    depth: number;
+    children: RowTreeNode[];
+}
+export declare function buildRowTree(rows: DatabaseRow[]): RowTreeNode[];
+/** Flatten a row tree to a list (depth-first), dropping the children of collapsed rows. */
+export declare function flattenRowTree(nodes: RowTreeNode[], collapsed: Set<string>): RowTreeNode[];
+/** Payload for editing a row's title and/or manual property values. */
+export interface RowUpdate {
+    name?: string | null;
+    properties?: Record<string, unknown>;
+}
+/** Reserved property id addressing the row's page title in filters/sorts/views. */
+export declare const TITLE_PROPERTY_ID = "title";
+/** Swatch tokens for `select` options; resolved to colors by the UI. */
+export declare const SELECT_COLORS: readonly ["gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red"];
+/**
+ * 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 declare function projectExports(snapshot: Pick<PageSnapshot, 'values' | 'names'>): Record<string, unknown>;
+/** True when a URL looks like an image (by extension), for thumbnail rendering. */
+export declare function isImageUrl(url: string): boolean;
+/** The first image URL in a `files`/`url` cell value (a string or string[]), or null. */
+export declare function firstImageUrl(value: unknown): string | 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 declare function coverImageUrl(value: unknown): string | null;
+/**
+ * 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 declare function rowValue(row: DatabaseRow, property: DatabaseProperty | typeof TITLE_PROPERTY_ID, properties?: DatabaseProperty[], rows?: DatabaseRow[]): unknown;
+/** The `start` day of a date value (a plain `YYYY-MM-DD` string or a {@link DateRange}). */
+export declare function dateStart(value: unknown): string | null;
+/** The `end` day of a {@link DateRange} value (null for a single-day date). */
+export declare function dateEnd(value: unknown): string | null;
+/** Parse a `YYYY-MM-DD` (or any Date-parseable) string to a *local* midnight Date. */
+export declare function parseDay(value: string | null | undefined): Date | null;
+/** An inclusive day span for a timeline bar. */
+export interface DateSpan {
+    start: Date;
+    end: Date;
+}
+/**
+ * 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 declare function rowDateSpan(row: DatabaseRow, view: DatabaseView, properties: DatabaseProperty[]): DateSpan | null;
+/**
+ * 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 declare function rowLocation(row: DatabaseRow, view: DatabaseView, properties: DatabaseProperty[]): LocationValue | null;
+/** A node in the dependency graph, placed in a layer (column) at an order (row). */
+export interface GraphNode {
+    id: string;
+    /** Longest-path depth from a root (a row with no predecessors). */
+    layer: number;
+    /** Position within the layer (stable: source-row order). */
+    order: number;
+}
+/** A directed edge `from` a predecessor `to` the row that depends on it. */
+export interface GraphEdge {
+    from: string;
+    to: string;
+}
+export interface DependencyGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    /** Number of layers (the graph's depth); at least 1. */
+    layerCount: number;
+    /** The most nodes in any one layer (the graph's height). */
+    maxLayerSize: number;
+}
+/**
+ * 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 declare function dependencyGraph(rows: DatabaseRow[], dependencyPropertyId: string | undefined): DependencyGraph;
+/** A related row's inverse-property value to write when syncing a two-way link. */
+export interface InverseUpdate {
+    rowId: string;
+    value: string[];
+}
+/**
+ * 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 declare function syncInverseUpdates(rowId: string, oldIds: string[], newIds: string[], relatedRows: DatabaseRow[], inversePropertyId: string): InverseUpdate[];
+/**
+ * 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 declare function matchesFilter(operator: FilterOperator, cell: unknown, target: unknown, now?: Date): boolean;
+/**
+ * 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 declare function viewFilterRoot(view: DatabaseView): DatabaseFilterGroup;
+/**
+ * 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 declare function rowMatchesCondition(row: DatabaseRow, condition: {
+    propertyId: string;
+    operator: FilterOperator;
+    value?: unknown;
+}, properties: DatabaseProperty[], rows?: DatabaseRow[]): boolean;
+export declare function applyView(rows: DatabaseRow[], view: DatabaseView, properties: DatabaseProperty[]): DatabaseRow[];
+/** Short non-cryptographic id for properties/views/options/filters. */
+export declare const shortId: (prefix: string) => string;
+/**
+ * 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 declare function defaultDatabaseSchema(): DatabaseSchema;
+/** A fresh view of a given type with sensible defaults for its layout. */
+export declare function defaultView(type: DatabaseViewType, name: string, properties: DatabaseProperty[]): DatabaseView;
+/** The starting options for a `status` property: one per lifecycle bucket. */
+export declare function defaultStatusOptions(): DatabaseSelectOption[];
+/** The lifecycle buckets a `status` property groups its options under, in order. */
+export declare const STATUS_GROUPS: {
+    id: StatusGroup;
+    label: string;
+}[];
+/**
+ * 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 declare function removeProperty(schema: DatabaseSchema, propertyId: string): DatabaseSchema;
+/** Format a numeric value for display per a {@link NumberFormat}. Non-numbers pass through as text. */
+export declare function formatNumber(value: unknown, format: NumberFormat | undefined): string;
+/**
+ * Format a `unique_id` value for display: an integer, optionally prefixed
+ * (`TASK` → `TASK-3`). Empty for unassigned (non-numeric) values. Pure.
+ */
+export declare function formatUniqueId(value: unknown, prefix?: string): string;
+/**
+ * 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 declare function numberProgress(value: unknown, target?: number): number;
+/** The label shown for rows that have no value for the grouping property. */
+export declare const NO_VALUE_GROUP = "No value";
+/** One group of rows sharing a value of the grouping property. */
+export interface RowGroup {
+    /** Stable key for the group (option id, or the displayed string). */
+    key: string;
+    /** Human label (option label, or the value itself). */
+    label: string;
+    /** Swatch color, when the group corresponds to a select option. */
+    color?: string;
+    rows: DatabaseRow[];
+}
+/**
+ * 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 declare function groupRows(rows: DatabaseRow[], property: DatabaseProperty | undefined, properties: DatabaseProperty[]): RowGroup[];
+/**
+ * Sentinel `groupByPropertyId` meaning "group by parent item" (sub-items).
+ * Not a real property id — {@link groupRowsBy} dispatches on it.
+ */
+export declare const PARENT_GROUP_ID = "__parent__";
+/** The label of the trailing group for rows that are nobody's sub-item. */
+export declare 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 declare function groupRowsByParent(rows: DatabaseRow[]): RowGroup[];
+/**
+ * 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 declare function groupRowsBy(rows: DatabaseRow[], groupByPropertyId: string | undefined, properties: DatabaseProperty[]): RowGroup[];
+/** One category of a chart: a label, its aggregated value, and an optional color. */
+export interface ChartDatum {
+    key: string;
+    label: string;
+    value: number;
+    color?: string;
+}
+/**
+ * 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 declare function aggregateRows(rows: DatabaseRow[], view: DatabaseView, properties: DatabaseProperty[]): ChartDatum[];
+/** Synthetic series used when a chart has no breakdown (a single full-height bar). */
+export declare const CHART_TOTAL_SERIES = "__total__";
+/** A breakdown series — the second-level group shared across every chart group. */
+export interface ChartSeries {
+    /** Stable key (breakdown option id, or its displayed value). */
+    key: string;
+    label: string;
+    /** Swatch color when the series is a select option. */
+    color?: string;
+}
+/** One series' slice of a {@link ChartGroup}: its rows and aggregated value. */
+export interface ChartSegment {
+    seriesKey: string;
+    value: number;
+    /** The rows behind this segment (powers click-to-drill). */
+    rows: DatabaseRow[];
+}
+/** One primary chart category, split across the shared {@link ChartMatrix.series}. */
+export interface ChartGroup {
+    key: string;
+    label: string;
+    color?: string;
+    /** The group's bar height / slice size (sum of its segment values). */
+    total: number;
+    /** Per-series contributions, in {@link ChartMatrix.series} order (zero-filled). */
+    segments: ChartSegment[];
+    rows: DatabaseRow[];
+}
+/** A chart's full data: primary groups, each split across a shared series set. */
+export interface ChartMatrix {
+    groups: ChartGroup[];
+    series: ChartSeries[];
+}
+/**
+ * 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 declare function aggregateMatrix(rows: DatabaseRow[], view: DatabaseView, properties: DatabaseProperty[]): ChartMatrix;
+/**
+ * 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 declare function summarizeColumn(rows: DatabaseRow[], property: DatabaseProperty | typeof TITLE_PROPERTY_ID, type: SummaryType, properties: DatabaseProperty[]): string;