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

package/dist/shared/computedValue.d.ts

@@ -0,0 +1,47 @@
+/**
+ * An expression's value, worked out in JavaScript (computed.ts parses it and
+ * writes its SQL). A module of its own so the evaluator loads only with what
+ * uses it — a form saying its live values (formLines.ts), a fixed action's
+ * stamp on the server (appStamps.ts) — and never with a page's first paint.
+ */
+import { type ComputedNode, type ComputedValue } from './computed.js';
+/**
+ * An expression's value, worked out in JavaScript with the statement's
+ * semantics (compileComputed), so the browser and the server say one thing:
+ * where a fixed action's `set` writes a constant (appStamps on the server),
+ * and where a form says its live values as someone types (formLines.ts).
+ * `read` supplies each path's value, typed — a number, a yes-or-no, text, a
+ * day — or null for none; an expression that reads no column needs none.
+ *
+ * As SQL does: anything with no value in it has none (`price * qty` with no
+ * price), a number over zero has none, a comparison with nothing is unknown,
+ * and `and`, `or` and `not` keep unknown as SQL's three-valued logic does. A
+ * yes-or-no that comes out unknown is no, as a computed flag is (the CASE in
+ * compileComputed): a task with no due date is not overdue. Dates move as the
+ * statement moves them: days and weeks by count, months and years by the
+ * calendar, a day past a month's end landing on its last, an instant by hours
+ * and minutes.
+ */
+export declare function evaluateComputed(node: ComputedNode, values: {
+    today: string;
+    now: Date;
+    me: string | null;
+}, read?: (path: string) => ComputedValue): ComputedValue;
+/**
+ * A constant expression's value, worked out where a fixed action's `set`
+ * writes it (appStamps on the server): `today + 14 days`, `now + 1 week`,
+ * `3 * 7`. It reads no column, which loading the App made sure of; the
+ * constants are this request's — the App's day, the instant, the
+ * signed-in person.
+ */
+export declare function evaluateConstant(node: ComputedNode, values: {
+    today: string;
+    now: Date;
+    me: string | null;
+}): ComputedValue;
+/**
+ * Two values compared as the statement compares them (`qty < reorder_at`, `paid < owed`): a number with a number,
+ * a day with a day or an instant; a comparison with nothing is no. Where a guard reads both sides in one transaction
+ * rather than writing the comparison into a single-table read, which never compares two columns (filter.ts).
+ */
+export declare function compares(op: string, left: ComputedValue, right: ComputedValue): boolean;

package/dist/shared/computedValue.js

@@ -0,0 +1,191 @@
+/**
+ * An expression's value, worked out in JavaScript (computed.ts parses it and
+ * writes its SQL). A module of its own so the evaluator loads only with what
+ * uses it — a form saying its live values (formLines.ts), a fixed action's
+ * stamp on the server (appStamps.ts) — and never with a page's first paint.
+ */
+import { ComputedError } from './computed.js';
+const DAY_MS = 86_400_000;
+const dayOf = (date) => date.toISOString().slice(0, 10);
+const COMPARISONS = new Set(['=', '!=', '<', '<=', '>', '>=']);
+/* A figure to `places`, a half away from zero, as the engines round a numeric: moved by its places and said to 15
+   digits first (as PostgreSQL casts a double to a numeric, and computed.ts has SQLite do), so 1.005 is 1.01 as it is
+   written rather than 1.00 as the double nearest it would say. */
+function roundAway(figure, places) {
+    const scale = 10 ** places;
+    const moved = Number((Math.abs(figure) * scale).toPrecision(15));
+    const rounded = Math.round(moved) / scale;
+    return rounded === 0 ? 0 : Math.sign(figure) * rounded;
+}
+/** Whether an expression is a yes-or-no at its top: a comparison, `and`, `or`, `not`, `is empty`, or `true`/`false`. */
+const isCondition = (node) => node.k === 'not' ||
+    node.k === 'empty' ||
+    node.k === 'bool' ||
+    (node.k === 'op' && (node.op === 'and' || node.op === 'or' || COMPARISONS.has(node.op)));
+/**
+ * An expression's value, worked out in JavaScript with the statement's
+ * semantics (compileComputed), so the browser and the server say one thing:
+ * where a fixed action's `set` writes a constant (appStamps on the server),
+ * and where a form says its live values as someone types (formLines.ts).
+ * `read` supplies each path's value, typed — a number, a yes-or-no, text, a
+ * day — or null for none; an expression that reads no column needs none.
+ *
+ * As SQL does: anything with no value in it has none (`price * qty` with no
+ * price), a number over zero has none, a comparison with nothing is unknown,
+ * and `and`, `or` and `not` keep unknown as SQL's three-valued logic does. A
+ * yes-or-no that comes out unknown is no, as a computed flag is (the CASE in
+ * compileComputed): a task with no due date is not overdue. Dates move as the
+ * statement moves them: days and weeks by count, months and years by the
+ * calendar, a day past a month's end landing on its last, an instant by hours
+ * and minutes.
+ */
+export function evaluateComputed(node, values, read = (path) => {
+    throw new ComputedError(`"${path}" is a column, and this expression reads none.`, 0);
+}) {
+    const span = (n) => ({ count: Number(value(n.of)), unit: n.unit });
+    const move = (at, by, sign) => {
+        const base = 'day' in at ? new Date(`${at.day}T00:00:00Z`) : new Date(at.instant);
+        const count = by.count * sign;
+        if (by.unit === 'hour' || by.unit === 'minute')
+            return { instant: new Date(base.getTime() + count * (by.unit === 'hour' ? 3_600_000 : 60_000)) };
+        if (by.unit === 'day' || by.unit === 'week')
+            base.setTime(base.getTime() + count * (by.unit === 'week' ? 7 : 1) * DAY_MS);
+        else {
+            const months = by.unit === 'year' ? count * 12 : count, day = base.getUTCDate();
+            base.setUTCDate(1);
+            base.setUTCMonth(base.getUTCMonth() + months);
+            const last = new Date(Date.UTC(base.getUTCFullYear(), base.getUTCMonth() + 1, 0)).getUTCDate();
+            base.setUTCDate(Math.min(day, last));
+        }
+        return 'day' in at ? { day: dayOf(base) } : { instant: base };
+    };
+    const isDate = (v) => typeof v === 'object' && v !== null;
+    const ms = (v) => ('day' in v ? Date.parse(`${v.day}T00:00:00Z`) : v.instant.getTime());
+    const comparable = (v) => (isDate(v) ? ms(v) : v);
+    /* SQL's truth: yes, no, or unknown (null). */
+    const truth = (v) => (v === null ? null : Boolean(v));
+    const value = (n) => {
+        switch (n.k) {
+            case 'number':
+                return n.value;
+            case 'text':
+                return n.value;
+            case 'bool':
+                return n.value;
+            case 'today':
+                return { day: values.today };
+            case 'date':
+                return { day: n.value };
+            case 'now':
+                return { instant: values.now };
+            case 'instant':
+                return { instant: new Date(n.value) };
+            case 'me':
+                return values.me;
+            case 'nobody':
+                return null;
+            case 'not': {
+                const v = truth(value(n.of));
+                return v === null ? null : !v;
+            }
+            case 'neg': {
+                const v = value(n.of);
+                return v === null ? null : -Number(v);
+            }
+            case 'empty': {
+                const v = value(n.of);
+                return (v === null || v === '') !== n.negate;
+            }
+            case 'span':
+                return Number(value(n.of));
+            case 'call': {
+                const args = n.args.map(value);
+                if (n.fn === 'coalesce')
+                    return args.find((each) => each !== null) ?? null;
+                if (args.some((each) => each === null))
+                    return null;
+                if (n.fn === 'abs')
+                    return Math.abs(Number(args[0]));
+                if (n.fn === 'round')
+                    return roundAway(Number(args[0]), args[1] === undefined ? 0 : Number(args[1]));
+                let kept = args[0];
+                for (const each of args.slice(1)) {
+                    const [a, b] = [comparable(each), comparable(kept)];
+                    if (n.fn === 'min' ? a < b : a > b)
+                        kept = each;
+                }
+                return kept;
+            }
+            case 'path': {
+                const v = read(n.path);
+                return v === undefined || v === '' ? null : v;
+            }
+            case 'op': {
+                if (n.op === 'and' || n.op === 'or') {
+                    const l = truth(value(n.left)), r = truth(value(n.right));
+                    if (n.op === 'and')
+                        return l === false || r === false ? false : l === null || r === null ? null : true;
+                    return l === true || r === true ? true : l === null || r === null ? null : false;
+                }
+                const l = value(n.left), r = value(n.right);
+                if (COMPARISONS.has(n.op)) {
+                    if (l === null || r === null)
+                        return null;
+                    const a = comparable(l), b = comparable(r);
+                    switch (n.op) {
+                        case '=':
+                            return a === b;
+                        case '!=':
+                            return a !== b;
+                        case '<':
+                            return a < b;
+                        case '<=':
+                            return a <= b;
+                        case '>':
+                            return a > b;
+                        default:
+                            return a >= b;
+                    }
+                }
+                if (l === null || r === null)
+                    return null;
+                if (n.op === '+' || n.op === '-') {
+                    const sign = n.op === '+' ? 1 : -1;
+                    if (isDate(l) && isDate(r) && n.op === '-')
+                        return Math.round((ms(l) - ms(r)) / DAY_MS);
+                    if (isDate(l) && !isDate(r))
+                        return move(l, n.right.k === 'span' ? span(n.right) : { count: Number(r), unit: 'day' }, sign);
+                    if (isDate(r) && !isDate(l) && n.op === '+')
+                        return move(r, n.left.k === 'span' ? span(n.left) : { count: Number(l), unit: 'day' }, 1);
+                    return Number(l) + sign * Number(r);
+                }
+                if (n.op === '*')
+                    return Number(l) * Number(r);
+                return Number(r) === 0 ? null : Number(l) / Number(r);
+            }
+        }
+    };
+    const result = value(node);
+    return result === null && isCondition(node) ? false : result;
+}
+/**
+ * A constant expression's value, worked out where a fixed action's `set`
+ * writes it (appStamps on the server): `today + 14 days`, `now + 1 week`,
+ * `3 * 7`. It reads no column, which loading the App made sure of; the
+ * constants are this request's — the App's day, the instant, the
+ * signed-in person.
+ */
+export function evaluateConstant(node, values) {
+    return evaluateComputed(node, values);
+}
+/**
+ * Two values compared as the statement compares them (`qty < reorder_at`, `paid < owed`): a number with a number,
+ * a day with a day or an instant; a comparison with nothing is no. Where a guard reads both sides in one transaction
+ * rather than writing the comparison into a single-table read, which never compares two columns (filter.ts).
+ */
+export function compares(op, left, right) {
+    if (!COMPARISONS.has(op))
+        return false;
+    const node = { k: 'op', op, left: { k: 'path', path: 'l' }, right: { k: 'path', path: 'r' } };
+    return evaluateComputed(node, { today: '', now: new Date(0), me: null }, (path) => (path === 'l' ? left : right)) === true;
+}

package/dist/shared/connection.d.ts

@@ -0,0 +1,30 @@
+/** Public metadata only. Connection URLs and credentials remain server-side. */
+export type SecretSource = 'none' | 'inline' | 'environment' | 'keychain' | 'file';
+/** Routing and write capability, without database administration metadata. */
+export interface AppSource {
+    id: string;
+    name: string;
+    writable: boolean;
+    rows?: boolean;
+    /** Some columns are never served over it (`"hidden"`), so it runs no raw SQL. */
+    hidesColumns?: true;
+}
+export type RuntimeMetadata = {
+    appConfigured: false;
+} | {
+    appConfigured: true;
+    active: string | null;
+    apps: AppSource[];
+};
+export interface PublicConnection extends AppSource {
+    dialect: string;
+    /** Host and database, or a file name. Never a password. */
+    detail: string;
+    source: 'argument' | 'config' | 'session';
+    connected: boolean;
+    tables?: number;
+    error?: string;
+    secret?: SecretSource;
+    warning?: string;
+    schemas?: string[];
+}

package/dist/shared/connection.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/csv.d.ts

@@ -0,0 +1,20 @@
+export declare const CRLF = "\r\n";
+/**
+ * One CSV field.
+ *
+ * null and undefined emit nothing at all, while an empty string emits `""`.
+ * That asymmetry is the whole point: `a,,b` and `a,"",b` are different
+ * documents, and collapsing them means an export cannot tell you whether a
+ * column was never set or set to blank — often the exact question the export
+ * was taken to answer.
+ */
+export declare function csvField(value: unknown): string;
+/** One CSV record: the fields of `row` in `columns` order, without its line break. */
+export declare function csvRecord(columns: readonly string[], row: Record<string, unknown> | undefined): string;
+/**
+ * One record as an export's JSON writes it: rebuilt from `columns` rather
+ * than emitted as-is so the shape matches the CSV exactly — including a key
+ * whose value is missing, which `JSON.stringify` would silently drop and
+ * leave the two formats disagreeing about the row.
+ */
+export declare function jsonRecord(columns: readonly string[], row: Record<string, unknown> | undefined): Record<string, unknown>;

package/dist/shared/csv.js

@@ -0,0 +1,63 @@
+/*
+ * One CSV field and one JSON record, as an export writes them — shared, so
+ * the file the browser writes from rows in hand and the file the server
+ * streams (exportRoute.ts) are the same file, byte for byte.
+ */
+/* RFC 4180 §2.6: a field containing a comma, a quote or a line break must be
+   quoted. CR and LF are listed separately because a lone CR inside a value is
+   just as capable of splitting a record as a full CRLF. */
+const NEEDS_QUOTES = /[",\r\n]/;
+/* Excel, Sheets and LibreOffice all treat a cell beginning with one of these
+   as a formula to evaluate rather than text to show — so a value like
+   `=HYPERLINK(...)` or `@SUM(A1)` out of a database column becomes code the
+   moment someone opens the file. Prefixing a single quote is the standard
+   mitigation: spreadsheets show the rest as literal text.
+   Tab and CR are included because they are skipped before the parse, which
+   makes `\t=cmd` a formula too. */
+const FORMULA_LEAD = /^[=+\-@\t\r]/;
+/* ...but `-5` and `+1.5e3` are numbers, not formulas, and prefixing them
+   would corrupt every negative amount in the export to buy nothing. Only a
+   leading sign that is *not* part of a plain number is dangerous. */
+const PLAIN_NUMBER = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
+export const CRLF = '\r\n';
+/**
+ * One CSV field.
+ *
+ * null and undefined emit nothing at all, while an empty string emits `""`.
+ * That asymmetry is the whole point: `a,,b` and `a,"",b` are different
+ * documents, and collapsing them means an export cannot tell you whether a
+ * column was never set or set to blank — often the exact question the export
+ * was taken to answer.
+ */
+export function csvField(value) {
+    if (value === null || value === undefined)
+        return '';
+    // A JSON/JSONB column arrives as a parsed object; `String(obj)` would write
+    // "[object Object]" into every row of it.
+    const text = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    const safe = FORMULA_LEAD.test(text) && !PLAIN_NUMBER.test(text) ? `'${text}` : text;
+    if (safe === '' || NEEDS_QUOTES.test(safe))
+        return `"${safe.replace(/"/g, '""')}"`;
+    return safe;
+}
+/* A row's own value for a column, never one it inherits: an export's column
+   list is the caller's, and `constructor` or `__proto__` named there would
+   otherwise write out Object's own members as if they were data. */
+const own = (row, name) => (row && Object.hasOwn(row, name) ? row[name] : undefined);
+/** One CSV record: the fields of `row` in `columns` order, without its line break. */
+export function csvRecord(columns, row) {
+    return columns.map((name) => csvField(own(row, name))).join(',');
+}
+/**
+ * One record as an export's JSON writes it: rebuilt from `columns` rather
+ * than emitted as-is so the shape matches the CSV exactly — including a key
+ * whose value is missing, which `JSON.stringify` would silently drop and
+ * leave the two formats disagreeing about the row.
+ */
+export function jsonRecord(columns, row) {
+    /* No prototype, so a column called `__proto__` is a key like any other. */
+    const out = Object.create(null);
+    for (const name of columns)
+        out[name] = own(row, name) ?? null;
+    return out;
+}

package/dist/shared/dashLayout.d.ts

@@ -0,0 +1,30 @@
+/** A template as cells: `grid[row][column]` is an area's name or `.`. */
+export type LayoutGrid = string[][];
+/** Whether a word may name an area. */
+export declare const isAreaName: (word: string) => boolean;
+/** The rows of a template as cells. Ragged rows stay ragged: `layoutProblems` is what says so. */
+export declare function layoutGrid(layout: readonly string[]): LayoutGrid;
+/** The areas a template names, in reading order: row by row, each at its first cell. */
+export declare function layoutAreas(grid: LayoutGrid): string[];
+/** An area's box: where it starts, and how many rows and columns it spans. Absent when the template does not name it. */
+export declare function areaBox(grid: LayoutGrid, name: string): {
+    row: number;
+    column: number;
+    rows: number;
+    columns: number;
+} | undefined;
+/**
+ * Everything wrong with a template, in words, one pass: a template is judged whole so one run names every refusal.
+ * `at` is the dashboard, as the other refusals name it.
+ */
+export declare function layoutProblems(layout: unknown, at: string): string[];
+/**
+ * The areas a layout leaves for a reader when `hidden` ones have nothing to draw: a hidden area's cells go to its left
+ * neighbour in that row (the right one when it is first), and a row left with no area in it is dropped. A neighbour that
+ * would stop being a rectangle by it is not given the cells, which stand empty. Pure: a template in, a template out.
+ */
+export declare function reflowLayout(grid: LayoutGrid, hidden: ReadonlySet<string>): LayoutGrid;
+/** The template as the strings a CSS `grid-template-areas` takes: one quoted row each. */
+export declare const gridTemplateAreas: (grid: LayoutGrid) => string;
+/** An area that no section is placed in, or a section placed in none: the nearest name for a slip. */
+export declare function nearestArea(name: string, areas: readonly string[]): string | undefined;

package/dist/shared/dashLayout.js

@@ -0,0 +1,132 @@
+/**
+ * A dashboard's `areas`: sections placed in named areas of a grid of equal columns.
+ *
+ * One reading on both sides — the parser that refuses a template (appViews.ts), the lint that judges an area's
+ * width (designLint.ts) and the client that draws it (components/Dashboard.tsx) — so a template means the same
+ * thing wherever it is read. Pure data in, data out.
+ */
+import { nearest } from './suggest.js';
+/** An area's name: a lowercase word that is also a CSS identifier, since the client names the grid area with it. */
+const AREA_NAME = /^[a-z][a-z0-9-]{0,23}$/;
+/** Words CSS reads before an area name: `grid-area: span` or `auto` is not a name. */
+const CSS_WORDS = new Set(['auto', 'span', 'initial', 'inherit', 'unset', 'revert', 'default']);
+const LAYOUT_MAX_ROWS = 8;
+const LAYOUT_MAX_COLUMNS = 4;
+/** The cell that holds no area. */
+const EMPTY_CELL = '.';
+/** Whether a word may name an area. */
+export const isAreaName = (word) => AREA_NAME.test(word) && !CSS_WORDS.has(word);
+/** The rows of a template as cells. Ragged rows stay ragged: `layoutProblems` is what says so. */
+export function layoutGrid(layout) {
+    return layout.map((row) => row.trim().split(/\s+/).filter(Boolean));
+}
+/** The areas a template names, in reading order: row by row, each at its first cell. */
+export function layoutAreas(grid) {
+    const seen = [];
+    for (const row of grid)
+        for (const cell of row)
+            if (cell !== EMPTY_CELL && !seen.includes(cell))
+                seen.push(cell);
+    return seen;
+}
+/** The cells an area covers, 0-based, in reading order. */
+function cellsOf(grid, name) {
+    const cells = [];
+    grid.forEach((row, r) => row.forEach((cell, c) => cell === name && cells.push({ row: r, column: c })));
+    return cells;
+}
+/** An area's box: where it starts, and how many rows and columns it spans. Absent when the template does not name it. */
+export function areaBox(grid, name) {
+    const cells = cellsOf(grid, name);
+    if (!cells.length)
+        return undefined;
+    const rows = cells.map((cell) => cell.row);
+    const columns = cells.map((cell) => cell.column);
+    const row = Math.min(...rows);
+    const column = Math.min(...columns);
+    return { row, column, rows: Math.max(...rows) - row + 1, columns: Math.max(...columns) - column + 1 };
+}
+const place = (cell) => `row ${cell.row + 1} column ${cell.column + 1}`;
+/** "a, b and c". */
+const said = (words) => words.length < 2 ? (words[0] ?? '') : `${words.slice(0, -1).join(', ')} and ${words[words.length - 1]}`;
+/** Whether an area's cells fill their box exactly. */
+function isRectangle(grid, name) {
+    const box = areaBox(grid, name);
+    return !box || cellsOf(grid, name).length === box.rows * box.columns;
+}
+/**
+ * Everything wrong with a template, in words, one pass: a template is judged whole so one run names every refusal.
+ * `at` is the dashboard, as the other refusals name it.
+ */
+export function layoutProblems(layout, at) {
+    const here = `${at}, "areas"`;
+    if (!Array.isArray(layout) || !layout.length || layout.some((row) => typeof row !== 'string')) {
+        return [`${here} is not a list of rows, each a string of area names: ['kpis kpis', 'trend side'].`];
+    }
+    const problems = [];
+    if (layout.length > LAYOUT_MAX_ROWS)
+        problems.push(`${here} has ${layout.length} rows. At most ${LAYOUT_MAX_ROWS}.`);
+    const grid = layoutGrid(layout);
+    const widest = Math.max(...grid.map((row) => row.length));
+    if (grid.some((row) => !row.length))
+        problems.push(`${here} has an empty row. Write . for a cell with nothing in it.`);
+    if (widest > LAYOUT_MAX_COLUMNS)
+        problems.push(`${here} has ${widest} columns in a row. At most ${LAYOUT_MAX_COLUMNS}: wider than that, a column is too narrow to read.`);
+    const counts = new Set(grid.filter((row) => row.length).map((row) => row.length));
+    if (counts.size > 1) {
+        problems.push(`${here} has rows of different lengths (${grid.map((row, i) => `row ${i + 1} has ${row.length}`).join(', ')}). Every row has the same number of cells; write . for one with nothing in it.`);
+    }
+    for (const word of new Set(grid.flat())) {
+        if (word !== EMPTY_CELL && !isAreaName(word)) {
+            problems.push(`${here} has "${word}", which is not an area name. An area is a lowercase word (letters, digits and hyphens, at most 24, starting with a letter, and not ${[...CSS_WORDS].join(' or ')}); . is a cell with nothing in it.`);
+        }
+    }
+    if (problems.length)
+        return problems;
+    for (const name of layoutAreas(grid)) {
+        if (isRectangle(grid, name))
+            continue;
+        problems.push(`${here}: "${name}" is not a rectangle: it covers ${said(cellsOf(grid, name).map(place))}. An area is one block of cells; give each separate block its own name.`);
+    }
+    return problems;
+}
+/**
+ * The areas a layout leaves for a reader when `hidden` ones have nothing to draw: a hidden area's cells go to its left
+ * neighbour in that row (the right one when it is first), and a row left with no area in it is dropped. A neighbour that
+ * would stop being a rectangle by it is not given the cells, which stand empty. Pure: a template in, a template out.
+ */
+export function reflowLayout(grid, hidden) {
+    let next = grid.map((row) => [...row]);
+    for (const name of layoutAreas(grid)) {
+        if (!hidden.has(name))
+            continue;
+        const trial = next.map((row) => [...row]);
+        const touched = new Set();
+        next.forEach((row, r) => {
+            const first = row.indexOf(name);
+            if (first < 0)
+                return;
+            const last = row.lastIndexOf(name);
+            const neighbour = first > 0 ? row[first - 1] : (row[last + 1] ?? EMPTY_CELL);
+            for (let c = first; c <= last; c++)
+                trial[r][c] = neighbour;
+            touched.add(neighbour);
+        });
+        for (const other of touched) {
+            if (other !== EMPTY_CELL && !isRectangle(trial, other)) {
+                trial.forEach((row, r) => row.forEach((cell, c) => {
+                    if (cell === other && next[r][c] === name)
+                        row[c] = EMPTY_CELL;
+                }));
+            }
+        }
+        next = trial;
+    }
+    return next.filter((row) => row.some((cell) => cell !== EMPTY_CELL));
+}
+/** The template as the strings a CSS `grid-template-areas` takes: one quoted row each. */
+export const gridTemplateAreas = (grid) => grid.map((row) => `"${row.join(' ')}"`).join(' ');
+/** An area that no section is placed in, or a section placed in none: the nearest name for a slip. */
+export function nearestArea(name, areas) {
+    return nearest(name, areas);
+}

package/dist/shared/dashboardAsks.d.ts

@@ -0,0 +1,93 @@
+import { type ForeignKey, type TableMeta } from './schema.js';
+import type { AppListPresentation } from './listPresentations.js';
+/**
+ * How the asks read the schema: the client through the walk's own helpers
+ * (core.js), the server over the schema it answered with (listQuestion.ts
+ * `referenceNames` names the references either way).
+ */
+export interface AskLookups {
+    table(id: string): TableMeta | undefined;
+    references(id: string): readonly ForeignKey[];
+    referenceNames(tableId: string, names: readonly string[]): Record<string, string>;
+    /** Where a table's records are named, as a view path (schema.ts labelPath, by the App's record label). */
+    naming(table: TableMeta): string | undefined;
+}
+/** What of a section its asks are made from. */
+export interface AskedSection {
+    kind: string;
+    table?: string;
+    query?: string;
+    measure?: string;
+    /** A scatter's second measure, which places its dots across. */
+    x?: string;
+    by?: string;
+    lanes?: string[];
+    limit?: number;
+    over?: string;
+    compare?: string;
+    windowBase?: string;
+    /** The reader's window, where one stands in the author's (`windowed`): the window a metric's trend is drawn over. */
+    windowPhrase?: string;
+    comparePeriod?: boolean;
+    spark?: boolean;
+    shape?: string;
+    show?: string[];
+    sort?: string;
+    view?: string;
+    windows?: string[];
+    windowKey?: string;
+    /** A goal: a number, or read from data — per group where it names a `by` (a breakdown's, G76). */
+    target?: number | {
+        table: string;
+        query?: string;
+        measure: string;
+        by?: string;
+        over?: string;
+        windowBase?: string;
+    };
+    /** The target is the whole this metric is a share of, not a goal (it follows the metric's window and picks). */
+    targetWhole?: true;
+    error?: string;
+}
+/** A breakdown's goals, a row per group: the target table's measure by its own `by`, within its query. */
+export declare function targetText(section: Pick<AskedSection, 'target' | 'limit'>): string | null;
+/** The breakdown a section asks for: its measure by its key, within its query. */
+export declare function breakdownText(section: Pick<AskedSection, 'table' | 'query' | 'measure' | 'by' | 'x'>, limit?: number | string): string;
+/**
+ * A section with the reader's window in place of the author's. The server
+ * hands sections whose query already windows the `over` column a
+ * `windowBase` without that phrase, so the reader's phrase stands where
+ * the author's did rather than intersecting it. A compare derived from
+ * "previous period" is re-derived against the reader's window — `last 30
+ * days` picked compares against `previous 30 days`; a hand-written compare,
+ * or a window phrase with no "previous" (this month), hides the delta rather
+ * than compare the reader's window to the author's.
+ */
+export declare function windowed<S extends AskedSection>(section: S, windowNow: string | null): S;
+/** The period a section with windows of its own is over: the reader's pick, else its first. */
+export declare const sectionPeriod: (section: Pick<AskedSection, 'windows' | 'windowKey'>, periods: Readonly<Record<string, string>>) => string | null;
+/** A metric's figure over `query` — its own, or its compare window's. */
+export declare const measureText: (section: Pick<AskedSection, 'table' | 'measure'>, query: string | undefined) => string;
+export declare const groupsAskedFor: (section: Pick<AskedSection, 'limit'>) => number;
+/** The groups a chart asks for: stacked bars cross two keys, and bars and a donut order their groups themselves. */
+export declare function chartLimit(section: Pick<AskedSection, 'shape' | 'limit' | 'by'>): number | undefined;
+/** A board's lane counts. */
+export declare const boardCountText: (section: Pick<AskedSection, 'table' | 'query' | 'by'>) => string;
+/**
+ * A dashboard list's question: its rows with the columns it draws, the names
+ * its references are read by and the keys a row opens by, kept out of sight,
+ * up to its limit. `presentation` is the embedded view's, whose dress reads
+ * columns of its own.
+ */
+export declare function dashboardListQuery(lookups: AskLookups, section: Pick<AskedSection, 'table' | 'query' | 'sort' | 'show' | 'limit'>, presentation?: AppListPresentation): {
+    query: string;
+    keys: string[];
+    named: string[];
+    referenceLabels: Record<string, string>;
+};
+/**
+ * A pick's choices, where its column is a whole single-column reference: the
+ * records it points at, by name, fifty at most. Null where the column is a
+ * vocabulary (its values are the choices) or no section's table has it.
+ */
+export declare function pickQuery(lookups: AskLookups, sections: readonly Pick<AskedSection, 'table'>[], column: string): string | null;