@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/shared/keysetPage.js

@@ -0,0 +1,161 @@
+/**
+ * Paging by key: the next page is the rows after the last one shown, in the
+ * list's own order, rather than the rows after skipping every earlier page.
+ *
+ * An offset makes the database walk and throw away every row before the
+ * page — page 40,000 of a sorted list was fifteen seconds on SQLite with the
+ * server's one handle held throughout — and the HTTP routes refuse one past
+ * 10,000 (MAX_PAGE_OFFSET). A page after a boundary costs what the first
+ * page costs, however deep: the boundary is the last row's sort values and
+ * key, and the continuation is "after it in this order", which an index on
+ * the sort column reads as a range.
+ *
+ * The continuation is a filter like any other, so every layer that checks a
+ * filter — a reader's grants, hidden columns, a row scope — checks it: it is
+ * only ever an additional AND on columns the reader already sorts by. Where a
+ * boundary cannot be exact the list pages by offset as before: no primary
+ * key (the order is not total), a sort through a reference, or a column whose
+ * value does not come back as it is stored (JSON, bytes, money, a float
+ * read back rounded).
+ *
+ * NULL sorts last ascending on PostgreSQL and first on SQLite, and
+ * no statement here says NULLS FIRST/LAST, so each engine's own placement is
+ * the one the continuation follows.
+ */
+import { columnKind, declaredOrder, primaryKey } from './schema.js';
+/* The types whose value comes back as the engine compares it. */
+const UNFAITHFUL = /json|xml|money|bytea|blob|binary|interval|array|\[\]/i;
+/** Whether this order pages by key on this engine: total, and every column exact. */
+export function keysetOrder(table, order, dialect) {
+    if (dialect !== 'postgres' && dialect !== 'sqlite')
+        return false;
+    const key = primaryKey(table);
+    if (!key.length || !key.every((column) => order.some((o) => o.column === column)))
+        return false;
+    return order.every((o) => {
+        const column = table.columns.find((c) => c.name === o.column);
+        if (!column || UNFAITHFUL.test(column.type))
+            return false;
+        const kind = columnKind(column.type);
+        if (kind === 'other')
+            return false;
+        return true;
+    });
+}
+/** The body fields a step is said in: a route that names the fields its body may carry names these too. */
+export const PAGE_STEP_FIELDS = ['after', 'before', 'end'];
+/** Read a step from a request body: absent, one of the three, or malformed. */
+export function readPageStep(body) {
+    const given = PAGE_STEP_FIELDS.filter((key) => body[key] !== undefined);
+    if (!given.length)
+        return undefined;
+    if (given.length > 1)
+        return 'invalid';
+    if (given[0] === 'end')
+        return body.end === true ? { end: true } : 'invalid';
+    const raw = body[given[0]];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || Object.keys(raw).length > 64)
+        return 'invalid';
+    for (const value of Object.values(raw)) {
+        if (value !== null && typeof value !== 'string' && typeof value !== 'boolean' && !(typeof value === 'number' && Number.isFinite(value)))
+            return 'invalid';
+    }
+    return given[0] === 'after' ? { after: raw } : { before: raw };
+}
+/** The same order read the other way: the page before a row, or the list's end. */
+export function reversedOrder(order) {
+    return order.map((o) => ({ column: o.column, direction: o.direction === 'asc' ? 'desc' : 'asc' }));
+}
+/**
+ * The rows after `boundary` in `order`, as OR-of-AND groups over its
+ * columns; undefined when the boundary does not name a value for every one,
+ * or names null for a column that cannot hold it. A strict comparison at one
+ * position, equality at every earlier one; the first column's bound (`>=`,
+ * `<=`) rides in each branch that compares it, which buildWhere says once so
+ * an index on it reads a range.
+ */
+export function keysetAfter(table, order, boundary, dialect) {
+    const nullsHigh = dialect === 'postgres';
+    const columns = order.map((o) => table.columns.find((c) => c.name === o.column));
+    if (columns.some((c) => !c))
+        return undefined;
+    for (const [at, o] of order.entries()) {
+        if (!Object.hasOwn(boundary, o.column))
+            return undefined;
+        if (boundary[o.column] === null && !columns[at].nullable)
+            return undefined;
+    }
+    const equal = (column) => boundary[column] === null ? { column, op: 'isNull' } : { column, op: '=', value: boundary[column] };
+    /* A vocabulary sorts as declared (schema.ts declaredOrder), NULL after
+       its last value on every engine: the rows past a value are the values
+       after it in the list, named, which an index reads as well as a range. */
+    const declared = columns.map((column) => declaredOrder(column));
+    for (const [at, o] of order.entries()) {
+        const value = boundary[o.column];
+        if (declared[at] && value !== null && !declared[at].includes(String(value)))
+            return undefined;
+    }
+    const pastDeclared = (o, values, nullable) => {
+        const value = boundary[o.column], up = o.direction === 'asc';
+        if (value === null)
+            return up ? [] : [{ column: o.column, op: 'isNotNull' }];
+        const rank = values.indexOf(String(value));
+        const after = up ? values.slice(rank + 1) : values.slice(0, rank);
+        return [
+            ...(after.length ? [{ column: o.column, op: 'in', value: [...after] }] : []),
+            ...(up && nullable ? [{ column: o.column, op: 'isNull' }] : []),
+        ];
+    };
+    /* Where the rows past a value lie: above it ascending, below descending,
+       and NULL is on whichever side the engine sorts it. */
+    const past = (o, nullable, at) => {
+        if (declared[at])
+            return pastDeclared(o, declared[at], nullable);
+        const value = boundary[o.column], up = o.direction === 'asc';
+        if (value === null)
+            return up === nullsHigh ? [] : [{ column: o.column, op: 'isNotNull' }];
+        const strict = { column: o.column, op: up ? '>' : '<', value };
+        return nullable && up === nullsHigh ? [strict, { column: o.column, op: 'isNull' }] : [strict];
+    };
+    const first = order[0], lead = boundary[first.column];
+    const bound = lead === null || declared[0] ? undefined : { column: first.column, op: first.direction === 'asc' ? '>=' : '<=', value: lead };
+    const groups = [];
+    for (const [at, o] of order.entries()) {
+        const prefix = order.slice(0, at).map((p) => equal(p.column));
+        for (const term of past(o, columns[at].nullable, at)) {
+            const branch = [...prefix, term];
+            // The bound holds wherever the first column is compared with a value; a NULL branch has none.
+            const compared = branch[0].op !== 'isNull' && branch[0].op !== 'isNotNull';
+            groups.push(bound && compared ? [bound, ...branch] : branch);
+        }
+    }
+    return groups;
+}
+/** A filter's groups, each continued by every branch: the rows it matches past the boundary. */
+export function continueGroups(base, tail) {
+    const starting = base?.filter((group) => group.length).length ? base.filter((group) => group.length) : [[]];
+    return starting.flatMap((group) => tail.map((branch) => [...group, ...branch]));
+}
+/** The boundaries of a page's first and last rows, where every order column came back with them. */
+export function pageBounds(order, rows, name = (column) => column) {
+    if (!rows.length)
+        return undefined;
+    const read = (row) => {
+        const boundary = {};
+        for (const o of order) {
+            const key = name(o.column);
+            if (!Object.hasOwn(row, key))
+                return undefined;
+            const value = row[key];
+            if (value !== null &&
+                typeof value !== 'string' &&
+                typeof value !== 'boolean' &&
+                !(typeof value === 'number' && Number.isFinite(value)))
+                return undefined;
+            boundary[o.column] = value;
+        }
+        return boundary;
+    };
+    const first = read(rows[0]), last = read(rows[rows.length - 1]);
+    return first && last ? { first, last } : undefined;
+}

package/dist/shared/like.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The pattern behind `contains`, `starts with` and `ends with`.
+ *
+ * A user typing `contains 50%` means a literal percent sign. Interpolated
+ * straight into a LIKE pattern it becomes a wildcard, so the search matches
+ * every row and the tool reports a hit on data that does not contain the
+ * value — the worst shape of wrong answer, because nothing about it looks
+ * like a failure. `a_c` matching `abc` is the same bug, quieter.
+ *
+ * So the value is escaped and the statement declares an escape character.
+ * `#` rather than the conventional backslash: engines differ on backslash escapes
+ * inside string literals, which would make the `ESCAPE` clause itself
+ * dialect-specific text.
+ *
+ * Lives in shared/ because the SQL the adapters compile and the SQL the query
+ * bar *shows* you have to agree — a preview that promises a wildcard the
+ * compiler escapes is a lie in the one place the tool is teaching.
+ */
+export declare const LIKE_ESCAPE = "#";
+export declare function likePattern(value: unknown, op: 'contains' | 'startsWith' | 'endsWith'): string;

package/dist/shared/like.js

@@ -0,0 +1,29 @@
+/**
+ * The pattern behind `contains`, `starts with` and `ends with`.
+ *
+ * A user typing `contains 50%` means a literal percent sign. Interpolated
+ * straight into a LIKE pattern it becomes a wildcard, so the search matches
+ * every row and the tool reports a hit on data that does not contain the
+ * value — the worst shape of wrong answer, because nothing about it looks
+ * like a failure. `a_c` matching `abc` is the same bug, quieter.
+ *
+ * So the value is escaped and the statement declares an escape character.
+ * `#` rather than the conventional backslash: engines differ on backslash escapes
+ * inside string literals, which would make the `ESCAPE` clause itself
+ * dialect-specific text.
+ *
+ * Lives in shared/ because the SQL the adapters compile and the SQL the query
+ * bar *shows* you have to agree — a preview that promises a wildcard the
+ * compiler escapes is a lie in the one place the tool is teaching.
+ */
+export const LIKE_ESCAPE = '#';
+/** The wildcards, plus the escape character itself, which must escape too. */
+const SPECIAL = /[#%_]/g;
+export function likePattern(value, op) {
+    const literal = String(value ?? '').replace(SPECIAL, (ch) => `${LIKE_ESCAPE}${ch}`);
+    if (op === 'startsWith')
+        return `${literal}%`;
+    if (op === 'endsWith')
+        return `%${literal}`;
+    return `%${literal}%`;
+}

package/dist/shared/listEmpty.d.ts

@@ -0,0 +1,12 @@
+import type { AppListEmpty } from './listPresentations.js';
+/** Read the shared empty-list copy used by list views and related sections. */
+export declare function parseListEmpty(raw: unknown, at: string): AppListEmpty;
+/** The authored shape again, for a definition written back out. */
+export declare function listEmptyConfig(empty: AppListEmpty): {
+    title: string;
+    description?: string | undefined;
+    action?: {
+        label: string;
+        to: string;
+    } | undefined;
+};

package/dist/shared/listEmpty.js

@@ -0,0 +1,36 @@
+/**
+ * Shared list-empty contract and projection.
+ *
+ * Ownership: the App DSL owns validation and authored copy; clients consume
+ * the resulting AppListEmpty shape for list and related-list rendering.
+ */
+import { allowKeys, isRecord } from './model.js';
+import { parseCaption } from './appMessages.js';
+/** Read the shared empty-list copy used by list views and related sections. */
+export function parseListEmpty(raw, at) {
+    const here = `${at}, "empty"`;
+    if (!isRecord(raw))
+        throw new Error(`${here} must be an object with a "title".`);
+    allowKeys(raw, ['title', 'description', 'action'], here, { message: 'is now "description": the sentence under the title' });
+    const title = parseCaption(raw.title, `${here} needs a non-empty "title"`);
+    const description = raw.description === undefined ? undefined : parseCaption(raw.description, `${here}, "description"`);
+    const result = { title, ...(description === undefined ? {} : { description }) };
+    if (raw.action === undefined)
+        return result;
+    if (!isRecord(raw.action))
+        throw new Error(`${here}, "action" must be an object with "label" and "to".`);
+    const actionAt = `${here}, "action"`;
+    allowKeys(raw.action, ['label', 'to'], actionAt);
+    const label = parseCaption(raw.action.label, `${actionAt} needs a non-empty "label"`);
+    if (typeof raw.action.to !== 'string' || !raw.action.to.trim())
+        throw new Error(`${actionAt} needs a non-empty "to": the key of a list, a dashboard or a signed-in form view.`);
+    return { ...result, action: { label, view: raw.action.to.trim() } };
+}
+/** The authored shape again, for a definition written back out. */
+export function listEmptyConfig(empty) {
+    return {
+        title: empty.title,
+        ...(empty.description === undefined ? {} : { description: empty.description }),
+        ...(empty.action ? { action: { label: empty.action.label, to: empty.action.view } } : {}),
+    };
+}

package/dist/shared/listFilters.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A list's filter as authored, as the key it is held under: a column or a
+ * path as written, a `has` filter as the words of its condition. Throws with
+ * the fix for a shape no list reads.
+ */
+export declare function listFilterKey(raw: unknown, at: string): string;
+/** A `has` filter's key read back: the child table as written, the reference where it names one, and what it asks. */
+export interface HasFilterKey {
+    child: string;
+    via?: string;
+    asks: string;
+}
+/** The `has` filter a key is, or undefined for a column or a path. */
+export declare function hasFilterOf(key: string): HasFilterKey | undefined;
+/**
+ * The word an address names a filter by: a column or a path as it is
+ * (`?account_id.industry_id=3`), the rows that point at the record as
+ * `has.` their table, the reference where the filter names one, and what
+ * it asks (`?has.opportunity.stage=won`). No column is called `has.…`.
+ */
+export declare function filterAddressWord(key: string): string;
+/**
+ * What a filter across a reference is called on its list: the record it
+ * reaches says it ("Industry"), unless another of the list's filters or
+ * columns is called that too, when the reference it crosses says whose it is
+ * ("Account industry"). Any other filter is called by its caption.
+ */
+export declare function filterLabel(name: string, caption: (path: string) => string, near: readonly string[]): string;

package/dist/shared/listFilters.js

@@ -0,0 +1,84 @@
+/**
+ * A list's filters across its related tables: a path up a reference
+ * (`'account_id.industry_id'`) and the rows that point at the record
+ * (`{ has: 'opportunity', filter: 'stage' }`).
+ *
+ * A filter is held as the words its condition starts with, as every filter
+ * always was — a column's name, a path, or `any opportunity where stage` — so
+ * the rail and the bar fold a tail onto it (`in (won, lost)`) by the rule
+ * they fold one onto a column (conditions.js), the question is a chip, a URL
+ * and a tab refinement like any other, and the language (`any …`, view.ts)
+ * is what reads it. The address names it by a word of its own.
+ */
+import { ANY_CONDITION } from './query.js';
+const WORD = /^[A-Za-z_][\w$]*$/;
+const KEY_WORD = /^[A-Za-z_][\w$]*(?:\+[A-Za-z_][\w$]*)*$/;
+const PATH = /^[A-Za-z_][\w$]*(?:\.[A-Za-z_][\w$]*)*$/;
+const HAS_KEYS = new Set(['has', 'filter', 'segment', 'whose']);
+/**
+ * A list's filter as authored, as the key it is held under: a column or a
+ * path as written, a `has` filter as the words of its condition. Throws with
+ * the fix for a shape no list reads.
+ */
+export function listFilterKey(raw, at) {
+    if (typeof raw === 'string' && raw.trim())
+        return raw.trim();
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`${at} has "filters" that are not a list of column names, paths, or { has } filters.`);
+    }
+    const o = raw;
+    /* The reference is `whose`, as a rollup's and a related list's is; `via` stays the query language's own word (renamed before 1.0). */
+    if (o.via !== undefined)
+        throw new Error(`${at} has a filter with "via", which is now "whose": the column of ${String(o.has)} that points at this record.`);
+    const stray = Object.keys(o).find((key) => !HAS_KEYS.has(key));
+    if (stray !== undefined)
+        throw new Error(`${at} has a filter with "${stray}": a { has } filter takes has, filter or segment, and whose.`);
+    const word = (key, shape) => typeof o[key] === 'string' && shape.test(o[key].trim()) ? o[key].trim() : undefined;
+    const has = word('has', /^[A-Za-z_][\w$]*(?:\.[A-Za-z_][\w$]*)?$/);
+    if (!has)
+        throw new Error(`${at} has a filter without the table it asks about: { has: 'opportunity', filter: 'stage' }.`);
+    if ((o.filter === undefined) === (o.segment === undefined)) {
+        throw new Error(`${at}: the filter { has: '${has}' } names a "filter" (a column of ${has}, or a path up from it) or a "segment" of ${has} — one of them.`);
+    }
+    const asks = o.filter === undefined ? word('segment', WORD) : word('filter', PATH);
+    if (!asks) {
+        throw new Error(`${at}: the filter { has: '${has}' } has a "${o.filter === undefined ? 'segment' : 'filter'}" that is not ${o.filter === undefined ? "a segment's name" : 'a column or a path'}.`);
+    }
+    if (o.whose !== undefined && !word('whose', KEY_WORD)) {
+        throw new Error(`${at}: the filter { has: '${has}' } has a "whose" that is not a column of ${has}.`);
+    }
+    const whose = word('whose', KEY_WORD);
+    return `any ${has}${whose ? ` via ${whose}` : ''} where ${asks}`;
+}
+/** The `has` filter a key is, or undefined for a column or a path. */
+export function hasFilterOf(key) {
+    const m = ANY_CONDITION.exec(key.trim());
+    if (!m || m[1].toLowerCase() !== 'any' || m[4] === undefined || !PATH.test(m[4].trim()))
+        return undefined;
+    return { child: m[2], ...(m[3] ? { via: m[3] } : {}), asks: m[4].trim() };
+}
+/**
+ * The word an address names a filter by: a column or a path as it is
+ * (`?account_id.industry_id=3`), the rows that point at the record as
+ * `has.` their table, the reference where the filter names one, and what
+ * it asks (`?has.opportunity.stage=won`). No column is called `has.…`.
+ */
+export function filterAddressWord(key) {
+    const has = hasFilterOf(key);
+    return has ? ['has', has.child, ...(has.via ? [has.via] : []), has.asks].join('.') : key;
+}
+/**
+ * What a filter across a reference is called on its list: the record it
+ * reaches says it ("Industry"), unless another of the list's filters or
+ * columns is called that too, when the reference it crosses says whose it is
+ * ("Account industry"). Any other filter is called by its caption.
+ */
+export function filterLabel(name, caption, near) {
+    const said = caption(name);
+    if (!name.includes('.') || hasFilterOf(name))
+        return said;
+    if (!near.some((other) => other !== name && caption(other) === said))
+        return said;
+    const whose = caption(name.split('.')[0]);
+    return `${whose} ${/^[A-Z][a-z]/.test(said) ? said.charAt(0).toLowerCase() + said.slice(1) : said}`;
+}

package/dist/shared/listPresentations.d.ts

@@ -0,0 +1,199 @@
+/**
+ * How a list draws its rows, beside the plain grid: the presentations
+ * (`presentation: { kind: … }` — a board, a calendar, cards, a split, …), a
+ * list's tabs and its empty state. The rules both a page's related list and
+ * an App's list view read (listQuestion.ts, dashboardAsks.ts, appListColumns.ts);
+ * the list view that holds them is the App's (appModel.ts AppListView).
+ */
+import type { AppCardsList } from './appCards.js';
+import type { AppIconName } from './appIcons.js';
+import type { CustomListPresentation } from './appComponents.js';
+import { DISPLAY_TONES } from './model.js';
+/**
+ * One filter tab on a list page. The query is written in the ordinary
+ * query-bar language, without the leading table name — the list supplies
+ * it. No query means every row.
+ */
+export interface AppListTab {
+    label: string;
+    query?: string;
+    /** Internal: the tab's word in an address, from the App's own language, where a reader's label says
+        another (server/app/apps.ts `localizedApp`). Addresses stay one per thing in every locale. A segment's
+        tab is its segment's name. */
+    slug?: string;
+    /** The resource's segment the tab names (appSegments.ts): its `query` is that word, written out where it is read. */
+    segment?: string;
+}
+/**
+ * Data only: the renderer supplies the list and detail nodes. One of the
+ * list presentations, so a view says how its rows are drawn in exactly
+ * one place — `presentation: { kind: 'split', … }` beside the checklist, the
+ * queue and the board — rather than through a second key that had to be read
+ * before the first. The list is the view's own — its show, query, tabs and
+ * filter bar — so the split says only what is its: the detail's fields and
+ * the list's page size. The detail is headed by the resource's noun.
+ */
+export interface AppSplitListDetail {
+    kind: 'split';
+    /** The picked record's fields, in order: columns or label paths. Absent, its fields as the schema has them. */
+    detail?: string[];
+    /** The list's page size, 1 to 200: the view's, written into its question. */
+    limit?: number;
+    /** How a row reads in the pane beside the record: the queue's vocabulary, with an avatar. Absent, the plain grid. */
+    row?: {
+        primary: string;
+        lines?: string[];
+        facts?: string[];
+        badge?: string;
+        avatar?: string;
+    };
+}
+/** Local readable columns; presentation never grants permission to toggle. */
+export interface AppChecklist {
+    kind: 'checklist';
+    primary: string;
+    checked: string;
+    /** At most one line beneath the primary. */
+    lines?: string[];
+}
+/**
+ * A keyboard-first selection queue: the rows as a listbox, and the view's
+ * `bulk` actions offered for exactly the selected keys. Its title and lines may
+ * be local columns or one-hop reference label paths. Selection is a set of
+ * loaded records, never "everything matching". A fixed update writes each
+ * record on its own through the ordinary update route, so its result is per
+ * record; a `targets: 'many'` command sends one request, all or nothing.
+ */
+export interface AppQueueList {
+    kind: 'queue';
+    /** A local text column or one-hop reference label path. */
+    primary: string;
+    /** At most two local columns or one-hop label paths beneath the primary. */
+    lines?: string[];
+    /** Up to six values with captions, each a local column or one-hop label path. */
+    facts?: string[];
+    /** An optional status or other compact value shown as a reusable badge above the title. */
+    badge?: string;
+    /** The row-opening call to action; omitted uses "Open". */
+    openLabel?: string;
+}
+/**
+ * Lanes of cards by one local column's values. A card moves only through an
+ * action of the view whose `set` is exactly that column, judged by its own
+ * `when`; the board never writes a lane the app did not spell out. Where `by`
+ * references another table (a cycle, a sprint), the lanes are that table's
+ * rows, led by one for none, and a card moves by an ordinary update of the
+ * reference — unless the resource's transitions give it to its actions.
+ */
+export interface AppBoardList {
+    kind: 'board';
+    by: string;
+    /** Ordered subset of exact lane values (a reference's keys); omit to use the column's vocabulary, the
+        referenced rows, or the values seen. */
+    lanes?: readonly string[];
+    /** A numeric local column holding each card's place in its lane: the lanes read in its order, and a reader
+        who may edit it moves a card into place. Never a column the resource's transitions give to its actions. */
+    order?: string;
+    /** A local column whose values are rows across the lanes, one per value plus one for none; a card changes
+        row by an ordinary update of it where the reader may edit it, and keeps its row, told why, where not. */
+    swimlanes?: string;
+    /** A lane's work-in-progress limit, by lane value: its head says "count / limit" and warns past it. Shown,
+        never enforced. */
+    limits?: Readonly<Record<string, number>>;
+    primary: string;
+    /** At most one line beneath the primary. */
+    lines?: string[];
+    /** A local column whose value is the card's kind: a chip over the title in the color its display rule's `colors`
+        gives the value (else one fixed by its text), and the card's stripe where the look draws one. */
+    category?: string;
+    /** Up to four facts along the card's foot, each a local column with an optional App icon before it; a person
+        (an `avatar` or `avatars` column) stands at the right end. */
+    footer?: readonly AppBoardFact[];
+    /** A local numeric column summed in each lane's head beside its count. Absent, the first money column the card
+        shows (a line, a fact) is summed; a card and a lane say money short ($240K), whole in the title. */
+    sum?: string;
+    /** Lane values drawn folded until a reader opens one — a closed stage, won or lost: a narrow strip with its name,
+        count and sum. The reader's choice is remembered in their browser, per board. */
+    folded?: readonly string[];
+}
+/** One fact on a board card's foot. */
+export interface AppBoardFact {
+    column: string;
+    icon?: AppIconName;
+}
+/** A month of records by one date column, each on its day — or, with `end`, across the days from one date
+    column to another; a phone reads it as an agenda. */
+export interface AppCalendarList {
+    kind: 'calendar';
+    /** The date (or timestamp) column a record sits on, or starts on when it has an `end`. */
+    date: string;
+    /** A local date column holding a record's last day: the record is drawn across every day between. */
+    end?: string;
+    /** A local text column or one-hop reference label path. */
+    primary: string;
+    /** At most one local column or one-hop label path beneath the primary. */
+    lines?: string[];
+    /** A status said as its tone (a dot and its word), from the column's display map. */
+    badge?: string;
+    /** Shaded spans behind the days, read from other resources (a blackout window), each labeled. */
+    backdrop?: AppCalendarBackdrop[];
+}
+/** One kind of shaded span on a calendar: another resource's rows, from one date column to another, each labeled. */
+export interface AppCalendarBackdrop {
+    /** The resource the spans are rows of: by the App's name as authored, its table's id once resolved. */
+    from: string;
+    /** Its date (or timestamp) column where a span starts. */
+    start: string;
+    /** Its date (or timestamp) column holding a span's last day. */
+    end: string;
+    /** Its column whose value names a span. */
+    labelColumn: string;
+    /** The span's shade, in a display tone; absent, the quiet neutral. */
+    tone?: (typeof DISPLAY_TONES)[number];
+}
+/** How many kinds of span one calendar shades. */
+export declare const CALENDAR_BACKDROPS_MAX = 4;
+/** Records as the tree their parent column makes: a root per record with no parent, its children folded under it. */
+export interface AppTreeList {
+    kind: 'tree';
+    /** A local column that references this table: the record above, empty at a root. */
+    parent: string;
+    /** A local text column or one-hop reference label path. */
+    primary: string;
+    /** At most one local column or one-hop label path beside the primary. */
+    lines?: string[];
+}
+/** Records as bars along time, from one date column to another, in a row per group: a Gantt chart. */
+export interface AppGanttList {
+    kind: 'gantt';
+    /** The date (or timestamp) column a bar starts on. */
+    start: string;
+    /** The date column it ends on; a record with none is a mark on its start. */
+    end: string;
+    /** A local text column or one-hop reference label path. */
+    primary: string;
+    /** A local column or one-hop label path whose value names a bar's row ("owner_id.name"); absent, a row per record. */
+    by?: string;
+    /** A percent column (0–100) drawn as the bar's filled share. */
+    progress?: string;
+}
+export type AppListPresentation = AppTreeList | AppGanttList | AppChecklist | AppQueueList | AppBoardList | AppCalendarList | AppCardsList | AppSplitListDetail | CustomListPresentation;
+/** An optional empty-list action opens another App list or dashboard, or a signed-in form (the one that makes the first row). */
+export interface AppListEmpty {
+    title: string;
+    description?: string;
+    action?: {
+        label: string;
+        view: string;
+    };
+}
+/** Whether the Export menu is offered for a table, here and not beside the payload that sets `exportableTables`, since a list's first paint asks it and appPayload.ts imports the manifest parser: `ui.export` is the App's switch, and `exportableTables` (present in an App that grants by role) the person's. */
+export declare const exportOffered: (app: {
+    ui: {
+        export?: boolean;
+    };
+    exportableTables?: string[];
+} | null | undefined, table: string | undefined) => boolean;
+/** Where a list's filters sit: a bar above the rows, a rail of facets beside them, or none. */
+export declare const FILTER_BARS: readonly ['bar', 'rail', 'none'];
+export type FilterBar = (typeof FILTER_BARS)[number];

package/dist/shared/listPresentations.js

@@ -0,0 +1,7 @@
+import { DISPLAY_TONES } from './model.js';
+/** How many kinds of span one calendar shades. */
+export const CALENDAR_BACKDROPS_MAX = 4;
+/** Whether the Export menu is offered for a table, here and not beside the payload that sets `exportableTables`, since a list's first paint asks it and appPayload.ts imports the manifest parser: `ui.export` is the App's switch, and `exportableTables` (present in an App that grants by role) the person's. */
+export const exportOffered = (app, table) => app?.ui.export !== false && (!app?.exportableTables || (table !== undefined && app.exportableTables.includes(table)));
+/** Where a list's filters sit: a bar above the rows, a rail of facets beside them, or none. */
+export const FILTER_BARS = ['bar', 'rail', 'none'];

package/dist/shared/listQuestion.d.ts

@@ -0,0 +1,52 @@
+import { type DatabaseSchema } from './schema.js';
+import type { ServedResource } from './servedApp.js';
+import type { AppListPresentation } from './listPresentations.js';
+/** What a list's question is read over: the schema, and the App's resources — their record labels and display rules. */
+export interface ListRules {
+    readonly schema: DatabaseSchema;
+    readonly resources: Readonly<Record<string, Pick<ServedResource, 'recordLabel' | 'display'>>>;
+}
+/** One of a list's tabs: its label and the condition it adds. */
+export interface ListTab {
+    label: string;
+    query?: string;
+    /** Its word in an address where the label is said in another language (addressParams.ts `tabKey`). */
+    slug?: string;
+}
+/** What of a list view its question is made from. */
+export interface ListQuestionSpec {
+    table: string;
+    query?: string;
+    tabs?: ListTab[];
+    show?: string[];
+    presentation?: AppListPresentation;
+    sort?: string;
+    order?: string;
+    limit?: number;
+    editable?: true | string[];
+    /** The reference column whose record a row opens (a view's `opens`): fetched, as the row's key is, to open it. */
+    opens?: string;
+}
+/**
+ * The references among a list's columns, each with the path its record's
+ * name is read from: `partner_id` → `partner_id.code` where the partner's
+ * resource says `recordLabel: 'code'`, else the name the record page would
+ * give it. A target with nothing better than its key keeps the key.
+ */
+export declare function referenceNames(rules: ListRules, tableId: string, names: readonly string[]): Record<string, string>;
+/** The columns a shown column's second line reads: fetched with the row, drawn under it. */
+export declare function subtitleColumns(rules: ListRules, tableId: string, shown: readonly string[]): string[];
+/** The references an editable list shows by name (`owner_id.name`): their keys ride along
+    with the row, so a cell edits the reference and says what it replaces. */
+export declare function editedReferences(rules: ListRules, spec: Pick<ListQuestionSpec, 'table' | 'show' | 'editable' | 'presentation'>): string[];
+/** The references a list draws — its `show`, its presentation's columns, or every column — by the path each is named from (referenceNames). */
+export declare function listReferenceNames(rules: ListRules, spec: Pick<ListQuestionSpec, 'table' | 'show' | 'presentation'>): Record<string, string>;
+/** The show clause that fetches the app's columns plus the keys a row needs to open.
+    A presentation names the columns it draws, so a view of cards needs no `show`. */
+export declare function showClause(rules: ListRules, spec: ListQuestionSpec): string;
+export declare const limitClause: (spec: Pick<ListQuestionSpec, 'limit'>) => string;
+export declare const orderClause: (spec: Pick<ListQuestionSpec, 'order' | 'sort'>) => string;
+export declare function withOrder(spec: Pick<ListQuestionSpec, 'table' | 'order' | 'sort'>, question: string): string;
+/** The full query text one of the app's tabs stands for. A module's
+    standing conditions come first; a tab refines on top of them. */
+export declare function appListQuery(rules: ListRules, spec: ListQuestionSpec, index?: number): string;