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

package/dist/shared/page.d.ts

@@ -0,0 +1,135 @@
+import { type DatabaseSchema } from './schema.js';
+import { type BreakdownDef, type BreakdownKey } from './breakdown.js';
+import type { AuthoredPage, AuthoredSection } from '../../schema/model.js';
+import { type PageCustomTotal } from './appComponents.js';
+import { type PageBreakdown, type PageChart, type PageSection, type PageTimeline, type PageDef } from './pageModel.js';
+import { type OfKeys } from './pagePaths.js';
+export { type SectionWidth, WIDTHS, type SectionOffset, OFFSETS, type SectionRegion, SECTION_REGIONS, FIELD_COLUMNS, type ResolvedWorkflowStatus, type PageFields, type PageMetric, type PageList, type PageBreakdown, type PageChart, type TimelineStream, type PageTimeline, type PageSection, type PageDef, timelineMarkColumns, DEFAULT_PAGE_LIST_LIMIT, MAX_PAGE_SECTIONS, } from './pageModel.js';
+export { resolvePath, rootFilter, resolveOf, type OfKeys, listView, sectionQuery, metricView, defaultColumns, customReadView, } from './pagePaths.js';
+export { parsePagesConfig, PAGE_KEYS, PAGE_SECTION_KEYS, STREAM_KEYS, parsePageBody } from './pageConfig.js';
+/**
+ * Check a page against a real schema, and say what is wrong with it.
+ *
+ * Returns the page with an `error` rather than throwing, because a page that
+ * names a table this connection does not have is still a page — it belongs
+ * in the list, greyed, with its reason. A config file shared by a team will
+ * always describe some connection someone is not on.
+ */
+export declare function validatePage(schema: DatabaseSchema, page: PageDef): PageDef;
+/**
+ * Which rows of each timeline stream are the other party's: the condition each stream is asked, with `record.` reached
+ * by the stream's way back to the record, or undefined for a stream that has no far side. A stream's own `side` is its
+ * condition and must read over its table. The section's `side` is every other stream's, where it reads there: a stream
+ * whose table lacks a column it names (a time entry beside the replies, with no author) is never on the far side. A
+ * section's `side` no stream can read is refused, so a misspelt column is still named. `error` follows the section's
+ * own place, as `, stream "reply": "side": …`.
+ */
+export declare function timelineSides(schema: DatabaseSchema, section: Pick<PageTimeline, 'streams' | 'side'>): {
+    sides: (string | undefined)[];
+    error?: string;
+};
+/**
+ * What a breakdown section needs to run, as a structured BreakdownDef.
+ *
+ * It borrows the list machinery for everything except the grouping: the
+ * `of` resolution, the join back to the record's key, the extra filter
+ * text — a breakdown asks the same question a list does, about the same
+ * rows, and answers with groups instead of rows. Building the filter twice
+ * would be two implementations of "these rows belong to that record" to
+ * keep honest.
+ */
+export declare function breakdownPlan(schema: DatabaseSchema, page: PageDef, section: PageBreakdown, key: Record<string, string | number>, index: number, now?: Date, ofKeys?: OfKeys): {
+    def?: BreakdownDef;
+    empty?: boolean;
+    error?: string;
+};
+/**
+ * A chart's `by`, in the breakdown grammar's words: one or two keys, each a
+ * path and optionally a period to cut a date into — "month issued_on",
+ * "status", "month issued_on, status".
+ */
+export declare function chartKeys(by: string): {
+    keys: BreakdownKey[];
+} | {
+    error: string;
+};
+/**
+ * What a chart section needs to run: the breakdown section's plan — the same
+ * rows, anchored on the record the same way — with the chart's keys, its
+ * measure, and the order its shape reads in. A line reads along time, so it
+ * is ordered by its key; a donut and stacked bars are ordered on the client
+ * (dashboardModel.ts, orderGroups), as a dashboard's are.
+ */
+export declare function chartPlan(schema: DatabaseSchema, page: PageDef, section: PageChart, key: Record<string, string | number>, index: number, now?: Date, ofKeys?: OfKeys): {
+    def?: BreakdownDef;
+    empty?: boolean;
+    error?: string;
+};
+/**
+ * What one aggregate read of a custom section needs to run: a breakdown, built from the same pieces a metric and a
+ * chart on a page are — `whose` anchors it on the record as a related list is, a query narrows it as a list's does —
+ * so the figure counts every row the reader may see, not the page of rows a component happened to load, and the
+ * reader's grants, row policy and tenant scope narrow it as they narrow every breakdown. With a `by`, one row for
+ * each group (`key_1`, `value`); without, one row (`value`).
+ */
+export declare function customTotalPlan(schema: DatabaseSchema, page: PageDef, name: string, total: PageCustomTotal, key: Record<string, string | number>, index: number, now?: Date): {
+    def?: BreakdownDef;
+    empty?: boolean;
+    error?: string;
+};
+export declare function sectionConfig(s: PageSection): AuthoredSection;
+/** A Workbench page (tablewalk.json) also names the one connection it is for; an App's page has its App's. */
+type WorkbenchPage = Omit<AuthoredPage, 'sections'> & {
+    label?: string;
+    sections?: readonly AuthoredSection[];
+    connection?: string;
+};
+/** A whole page in the authored spelling, ready to write to a pages/ file. */
+export declare function pageConfig(p: PageDef): WorkbenchPage;
+/**
+ * A page for a table nobody has written one for: the record, a count of each
+ * thing that points at it, and the two biggest of those as lists.
+ */
+export declare function suggestPage(schema: DatabaseSchema, baseId: string): PageDef | null;
+/** One thing a section could be built from, ready to put in a menu. */
+export interface Relation {
+    /** The table a section would list or count. */
+    from: string;
+    /** How a row of it names the root. */
+    path: string;
+    /** What to call it, already disambiguated. */
+    label: string;
+    /** How many references away, for grouping "direct" from "further out". */
+    hops: number;
+    /** The foreign keys followed, so a builder can explain the route. */
+    via: string[];
+    /**
+     * Every spelling of this path that resolves to it.
+     *
+     * A hop can be named by its constraint or by its column, and both are
+     * legal — `resolvePath` accepts either. So the path in a hand-written
+     * config (`customer_id`) and the path this function generates
+     * (`invoice_fk_2`) are different strings for the same relationship, and
+     * anything matching on the string alone decides they are different
+     * relationships. The builder does exactly that when it looks up the
+     * relation a section came from.
+     */
+    aliases: string[];
+}
+/**
+ * Every way a table could reach this root, within a couple of hops.
+ *
+ * The one field nobody guesses when writing a page by hand is the path —
+ * `invoice_id.customer_id` is obvious only once you already know it. So it is
+ * not typed: the schema is asked what actually points here, directly and one
+ * table further out, and each answer comes back with the path already
+ * written.
+ *
+ * Two hops rather than the full depth limit. Three is a real relationship and
+ * a list nobody can read: on a schema of this size it runs to hundreds of
+ * entries, most of them routes no one would choose, and a menu that long is a
+ * menu people close.
+ */
+export declare function relationsTo(schema: DatabaseSchema, baseId: string, maxHops?: number): Relation[];
+/** Columns of a table that a metric could summarise. `count` needs none. */
+export declare function metricColumns(schema: DatabaseSchema, tableId: string): string[];