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

package/dist/shared/appDocuments.js

@@ -0,0 +1,131 @@
+/**
+ * Documents: a record put on paper — an invoice, a packing slip, a payslip, a
+ * quote.
+ *
+ * A document is an App page that says `document: { label, number, size,
+ * description }`. Its sections are the page sections a reader already knows
+ * (fields, related lists, notes), so its reads are a record page's: planned
+ * by the same route, asked through the same reads, under the same grants,
+ * row scope and tenant as the record's own page. Nothing is read for paper
+ * that the record's page could not read, and nothing new is served to make
+ * it: the browser's print engine is the renderer, and "Save as PDF" is the
+ * browser's.
+ *
+ * It is addressed under the record it is of, its key the last segment —
+ * `/atelier/orders/12/invoice` — the place a record's tab is said, so the
+ * address grammar (appAddress.ts) reads it unchanged. A document is never the
+ * page a record opens through, never a route of its own, and never in a menu:
+ * it is reached from its record, as a verb.
+ *
+ * Pure, and shared: the parser and the check here, the client's sheet and the
+ * server's address book read the same rules.
+ */
+import { allowKeys, isRecord } from './model.js';
+/** What a page's `document` takes. `label` names it (the verb on its record, its heading on paper); `description` is
+    the sender's lines under the letterhead's name. */
+export const DOCUMENT_KEYS = ['label', 'number', 'size', 'description'];
+/** Sheet sizes: ISO A4, or US Letter. */
+const DOCUMENT_SIZES = ['a4', 'letter'];
+/** What paper draws: the record's own fields, the rows that point at it, and the author's words. */
+const DOCUMENT_SECTION_KINDS = ['fields', 'list', 'note'];
+/** Every line is on paper, up to the most a related list reads at once; a page that would be longer says so. */
+const DOCUMENT_LINES = 500;
+/** A page's document, as one page body states it. */
+export function parseDocument(raw, at) {
+    const where = `${at}, "document"`;
+    if (!isRecord(raw))
+        throw new Error(`${where} is an object: { label: 'Invoice', number: 'invoice_no' }.`);
+    allowKeys(raw, DOCUMENT_KEYS, where);
+    if (typeof raw.label !== 'string' || !raw.label.trim())
+        throw new Error(`${where} has no "label": a document is named by what it is, "Invoice" or "Packing slip".`);
+    if (raw.number !== undefined &&
+        (typeof raw.number !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(raw.number)))
+        throw new Error(`${where}: "number" is a field of the record, "invoice_no" or "pay_run_id.reference".`);
+    if (raw.size !== undefined && !DOCUMENT_SIZES.includes(raw.size))
+        throw new Error(`${where}: "size" is ${DOCUMENT_SIZES.map((size) => `"${size}"`).join(' or ')}.`);
+    if (raw.description !== undefined && (typeof raw.description !== 'string' || !raw.description.trim()))
+        throw new Error(`${where}: "description" is text, the sender's lines under the name.`);
+    return {
+        label: raw.label.trim(),
+        ...(raw.number === undefined ? {} : { number: raw.number }),
+        ...(raw.size === undefined ? {} : { size: raw.size }),
+        ...(raw.description === undefined ? {} : { description: raw.description.trim() }),
+    };
+}
+/**
+ * What a document's sections may be, refused section by section: paper has no
+ * aside, no tabs and nothing to operate, and a list on it is every line — a
+ * table whose header repeats on each sheet — never a gallery, a card or a
+ * page of rows. Its lists read every line, up to DOCUMENT_LINES, unless the
+ * author says fewer.
+ */
+export function documentSections(sections, at) {
+    return sections.map((section, i) => {
+        const where = `${at}, section ${i + 1}`;
+        if (!DOCUMENT_SECTION_KINDS.includes(section.kind))
+            throw new Error(`${where} is a "${section.kind}" section; a document draws fields, related lists and notes on paper.`);
+        if (section.kind === 'fields' && (section.presentation === 'card' || section.presentation === 'header'))
+            throw new Error(`${where} is a "${section.presentation}"; on paper fields are a summary, properties, facts, a table or a headline.`);
+        if (section.region === 'aside')
+            throw new Error(`${where} is in the aside; a document is one sheet wide, so place sections side by side with "width".`);
+        if (section.tab !== undefined)
+            throw new Error(`${where} has a "tab"; paper has no tabs, so every section of a document is drawn.`);
+        if (section.kind === 'fields' && section.actions?.length)
+            throw new Error(`${where} has "actions"; paper has nothing to press.`);
+        if (section.kind !== 'list')
+            return section;
+        if (section.presentation !== undefined || section.create || section.rowActions)
+            throw new Error(`${where} is a list of the record's lines on paper: no presentation, create or row actions.`);
+        return section.limit === undefined ? { ...section, limit: DOCUMENT_LINES } : section;
+    });
+}
+/* Where Letter is the paper in the drawer: ISO 216 everywhere else. */
+const LETTER_REGIONS = new Set(['US', 'CA', 'MX', 'PH', 'PR', 'CL', 'CO', 'VE', 'GT', 'CR', 'PA', 'DO', 'SV', 'NI', 'HN', 'BZ']);
+/** The sheet a document is printed on: its own `size`, else the paper the App's (or tenant's) locale buys. */
+export function paperSize(document, locale) {
+    if (document.size)
+        return document.size;
+    let region;
+    try {
+        region = locale ? new Intl.Locale(locale).maximize().region : undefined;
+    }
+    catch {
+        region = undefined;
+    }
+    return region && LETTER_REGIONS.has(region) ? 'letter' : 'a4';
+}
+/** Whether a page is a document rather than a screen. */
+export const isDocument = (page) => page.document !== undefined;
+/**
+ * A document's key is the last segment of its record's address, where a record
+ * page's tab is said: `/orders/12/invoice`. A tab of the same word on a page
+ * over the same table would be two things at one address, and a record's page
+ * never opens through a document.
+ */
+export function documentProblems(pages, pageOf, tabWord, where) {
+    const problems = [];
+    const documents = pages.filter(isDocument);
+    for (const document of documents) {
+        for (const page of pages) {
+            if (isDocument(page) || page.base !== document.base)
+                continue;
+            const words = new Set();
+            for (const section of page.sections) {
+                if (section.tab)
+                    words.add(tabWord(`tab:${section.tab}`));
+                if (section.kind === 'list' && section.title)
+                    words.add(tabWord(`tab:${section.title}`));
+            }
+            if (words.has(document.id))
+                problems.push(`${where}: pages "${document.id}" is a document at /<record>/${document.id}, which the page "${page.id}" already answers to as a tab. Give the document another key.`);
+        }
+    }
+    for (const [resource, id] of Object.entries(pageOf)) {
+        const named = id === undefined ? undefined : documents.find((page) => page.id === id);
+        if (named)
+            problems.push(`${where}: resources "${resource}", "page" names "${named.id}", which is a document: a record opens on a page, and its documents are verbs on it.`);
+    }
+    return problems;
+}
+/** The share of a 12-column sheet a section's width takes, as the page's grid says it. */
+export const SHEET_SPAN = { full: 12, half: 6, third: 4, 'two-thirds': 8 };

package/dist/shared/appEmbeds.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Which views a dashboard embeds, and which of those only a dashboard opens.
+ * The client asks this to lay out its rooms on first paint; it is apart from
+ * appPayload.ts because that module builds the payload from the parsed App,
+ * and importing it took the manifest parser into the first script. It reads
+ * the views by their shape, so the shared client asks it without the App's
+ * model.
+ */
+import { type ServedNavNode } from './servedApp.js';
+/** The list views a dashboard section embeds, by key. */
+export declare function embedTargets(views: Readonly<Record<string, object>>): Set<string>;
+/**
+ * The views only a dashboard opens: embedded by one, and neither in nav
+ * nor among `homes`. Each has a room, where the embed's "open →" goes, and
+ * no menu lists it. The server passes every view a home rule names; the
+ * client, which knows only its own, the home it was served.
+ */
+export declare function embeddedOnlyViews(app: {
+    views: Readonly<Record<string, object>>;
+    nav: readonly ServedNavNode[];
+}, homes: Iterable<string>): Set<string>;

package/dist/shared/appEmbeds.js

@@ -0,0 +1,24 @@
+/**
+ * Which views a dashboard embeds, and which of those only a dashboard opens.
+ * The client asks this to lay out its rooms on first paint; it is apart from
+ * appPayload.ts because that module builds the payload from the parsed App,
+ * and importing it took the manifest parser into the first script. It reads
+ * the views by their shape, so the shared client asks it without the App's
+ * model.
+ */
+import { navViewKeys } from './servedApp.js';
+const embeds = (view) => Object.hasOwn(view, 'sections');
+/** The list views a dashboard section embeds, by key. */
+export function embedTargets(views) {
+    return new Set(Object.values(views).flatMap((view) => embeds(view) ? [...view.sections, ...(view.aside ?? [])].flatMap((section) => (section.view ? [section.view] : [])) : []));
+}
+/**
+ * The views only a dashboard opens: embedded by one, and neither in nav
+ * nor among `homes`. Each has a room, where the embed's "open →" goes, and
+ * no menu lists it. The server passes every view a home rule names; the
+ * client, which knows only its own, the home it was served.
+ */
+export function embeddedOnlyViews(app, homes) {
+    const listed = new Set([...navViewKeys(app.nav), ...homes]);
+    return new Set([...embedTargets(app.views)].filter((key) => !listed.has(key)));
+}

package/dist/shared/appIcons.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The icons an App may name, and the check that an authored name is one.
+ *
+ * A menu entry's icon is a word in the manifest (`icon: 'kanban'`), never a
+ * path or a component: a manifest is data, served to the browser and checked
+ * by the server, and a word is what both sides can agree on. The words are
+ * Phosphor's own names (https://phosphoricons.com, MIT, Phosphor Icons), so
+ * an author can look one up there and see exactly what they will get; the
+ * glyphs are drawn by `@phosphor-icons/react`, which the client already
+ * depends on (packages/kit/src/client/components/Icon.tsx imports each one by itself).
+ *
+ * The set is curated rather than the whole pack of ~1,500: the icons business
+ * Apps put in a menu — places, people, things, money, documents, time, state,
+ * and a clinic's, a school's, a workshop's — and the marks a value or a change
+ * wears (a display rule's `icons`, an activity feed's resources), and not the
+ * glyphs neither has a use for. A glyph costs an App nothing it does not use:
+ * the server sends the drawings of the icons an App names with its payload
+ * (packages/mistri/src/server/app/iconPayload.ts), and the client bundles none of the set. So
+ * the set grows by a word here and `node scripts/generate-icons.mjs`; the
+ * tests keep this list, the JSON schema's `appIcon` enum, packages/mistri/schema/app.d.ts's
+ * `AppIconName` and the generated glyphs the same.
+ */
+export declare const APP_ICONS: readonly ['house', 'tray', 'list', 'list-checks', 'kanban', 'table', 'calendar', 'calendar-check', 'clock', 'chart-bar', 'chart-line', 'chart-pie', 'gauge', 'target', 'flag', 'user', 'users', 'user-circle', 'address-book', 'handshake', 'buildings', 'storefront', 'briefcase', 'package', 'truck', 'car', 'shopping-cart', 'receipt', 'currency-dollar', 'credit-card', 'wallet', 'bank', 'file', 'file-text', 'folder', 'clipboard-text', 'note', 'archive', 'tag', 'ticket', 'star', 'bookmark-simple', 'bell', 'envelope', 'chat-circle', 'phone', 'headset', 'megaphone', 'globe', 'map-pin', 'magnifying-glass', 'gear', 'sliders', 'wrench', 'bug', 'shield-check', 'lock', 'key', 'database', 'stack', 'lightning', 'check-circle', 'warning', 'info', 'cell-signal-low', 'cell-signal-medium', 'cell-signal-high', 'cell-signal-full', 'fire', 'hourglass', 'circle-dashed', 'x-circle', 'plus-circle', 'pencil-simple', 'paper-plane-tilt', 'arrows-left-right', 'arrow-circle-down', 'arrow-circle-up', 'laptop', 'monitor', 'device-mobile', 'printer', 'stethoscope', 'heartbeat', 'heart', 'pill', 'syringe', 'first-aid-kit', 'thermometer', 'flask', 'test-tube', 'microscope', 'bed', 'hospital', 'ambulance', 'tooth', 'eyeglasses', 'wheelchair', 'baby', 'dna', 'brain', 'bandaids', 'hand-heart', 'graduation-cap', 'book-open', 'student', 'chalkboard-teacher', 'factory', 'warehouse', 'house-line', 'plant', 'leaf', 'sun', 'cloud', 'drop', 'airplane', 'bicycle', 'bus', 'train', 'boat', 'hammer', 'toolbox', 'plug', 'lightbulb', 'cube', 'camera', 'image', 'trophy', 'gift', 'coffee', 'fork-knife', 'shopping-bag', 'basket', 'barcode', 'qr-code', 'scales', 'gavel', 'certificate', 'identification-card', 'fingerprint', 'eye', 'link', 'paperclip', 'scissors', 'palette', 'code', 'terminal', 'users-three', 'user-plus'];
+export type AppIconName = (typeof APP_ICONS)[number];
+export declare const isAppIcon: (value: unknown) => value is AppIconName;
+/** An authored `icon`: one of APP_ICONS, or refused with the closest names and where the rest are listed.
+ * `key` is the key the author wrote it under — `ui.logo` takes an icon too, and a refusal naming "icon" sent people looking for a key they never wrote. */
+export declare function parseIcon(value: unknown, at: string, key?: string): AppIconName;

package/dist/shared/appIcons.js

@@ -0,0 +1,223 @@
+/**
+ * The icons an App may name, and the check that an authored name is one.
+ *
+ * A menu entry's icon is a word in the manifest (`icon: 'kanban'`), never a
+ * path or a component: a manifest is data, served to the browser and checked
+ * by the server, and a word is what both sides can agree on. The words are
+ * Phosphor's own names (https://phosphoricons.com, MIT, Phosphor Icons), so
+ * an author can look one up there and see exactly what they will get; the
+ * glyphs are drawn by `@phosphor-icons/react`, which the client already
+ * depends on (packages/kit/src/client/components/Icon.tsx imports each one by itself).
+ *
+ * The set is curated rather than the whole pack of ~1,500: the icons business
+ * Apps put in a menu — places, people, things, money, documents, time, state,
+ * and a clinic's, a school's, a workshop's — and the marks a value or a change
+ * wears (a display rule's `icons`, an activity feed's resources), and not the
+ * glyphs neither has a use for. A glyph costs an App nothing it does not use:
+ * the server sends the drawings of the icons an App names with its payload
+ * (packages/mistri/src/server/app/iconPayload.ts), and the client bundles none of the set. So
+ * the set grows by a word here and `node scripts/generate-icons.mjs`; the
+ * tests keep this list, the JSON schema's `appIcon` enum, packages/mistri/schema/app.d.ts's
+ * `AppIconName` and the generated glyphs the same.
+ */
+export const APP_ICONS = [
+    // Places and structure
+    'house',
+    'tray',
+    'list',
+    'list-checks',
+    'kanban',
+    'table',
+    'calendar',
+    'calendar-check',
+    'clock',
+    'chart-bar',
+    'chart-line',
+    'chart-pie',
+    'gauge',
+    'target',
+    'flag',
+    // People and organizations
+    'user',
+    'users',
+    'user-circle',
+    'address-book',
+    'handshake',
+    'buildings',
+    'storefront',
+    'briefcase',
+    // Things and logistics
+    'package',
+    'truck',
+    'car',
+    'shopping-cart',
+    // Money
+    'receipt',
+    'currency-dollar',
+    'credit-card',
+    'wallet',
+    'bank',
+    // Documents
+    'file',
+    'file-text',
+    'folder',
+    'clipboard-text',
+    'note',
+    'archive',
+    'tag',
+    'ticket',
+    'star',
+    'bookmark-simple',
+    // Communication
+    'bell',
+    'envelope',
+    'chat-circle',
+    'phone',
+    'headset',
+    'megaphone',
+    'globe',
+    'map-pin',
+    // Tools and state
+    'magnifying-glass',
+    'gear',
+    'sliders',
+    'wrench',
+    'bug',
+    'shield-check',
+    'lock',
+    'key',
+    'database',
+    'stack',
+    'lightning',
+    'check-circle',
+    'warning',
+    'info',
+    // Values: a priority's signal bars, a status's mark, what a change did
+    'cell-signal-low',
+    'cell-signal-medium',
+    'cell-signal-high',
+    'cell-signal-full',
+    'fire',
+    'hourglass',
+    'circle-dashed',
+    'x-circle',
+    'plus-circle',
+    'pencil-simple',
+    'paper-plane-tilt',
+    'arrows-left-right',
+    'arrow-circle-down',
+    'arrow-circle-up',
+    // Devices: what a service catalog orders and an asset list holds
+    'laptop',
+    'monitor',
+    'device-mobile',
+    'printer',
+    // Health and care: a clinic, a pharmacy, a lab
+    'stethoscope',
+    'heartbeat',
+    'heart',
+    'pill',
+    'syringe',
+    'first-aid-kit',
+    'thermometer',
+    'flask',
+    'test-tube',
+    'microscope',
+    'bed',
+    'hospital',
+    'ambulance',
+    'tooth',
+    'eyeglasses',
+    'wheelchair',
+    'baby',
+    'dna',
+    'brain',
+    'bandaids',
+    'hand-heart',
+    // Learning, land and buildings
+    'graduation-cap',
+    'book-open',
+    'student',
+    'chalkboard-teacher',
+    'factory',
+    'warehouse',
+    'house-line',
+    'plant',
+    'leaf',
+    'sun',
+    'cloud',
+    'drop',
+    // Travel
+    'airplane',
+    'bicycle',
+    'bus',
+    'train',
+    'boat',
+    // Things, tools and records
+    'hammer',
+    'toolbox',
+    'plug',
+    'lightbulb',
+    'cube',
+    'camera',
+    'image',
+    'trophy',
+    'gift',
+    'coffee',
+    'fork-knife',
+    'shopping-bag',
+    'basket',
+    'barcode',
+    'qr-code',
+    'scales',
+    'gavel',
+    'certificate',
+    'identification-card',
+    'fingerprint',
+    'eye',
+    'link',
+    'paperclip',
+    'scissors',
+    'palette',
+    'code',
+    'terminal',
+    'users-three',
+    'user-plus',
+];
+const KNOWN = new Set(APP_ICONS);
+export const isAppIcon = (value) => typeof value === 'string' && KNOWN.has(value);
+/* Edit distance, for "did you mean": a typo is a letter or two away, and a
+   near synonym usually shares its first word ("chart" → chart-bar). */
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let previous = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const kept = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+            previous = kept;
+        }
+    }
+    return row[b.length];
+}
+function nearest(name) {
+    const lower = name.toLowerCase();
+    const stem = lower.split('-')[0];
+    return APP_ICONS.map((icon) => ({ icon, d: icon.startsWith(stem) || icon.split('-').includes(stem) ? 0 : distance(lower, icon) }))
+        .filter((each) => each.d <= 3)
+        .sort((a, b) => a.d - b.d || a.icon.localeCompare(b.icon))
+        .slice(0, 3)
+        .map((each) => each.icon);
+}
+/** An authored `icon`: one of APP_ICONS, or refused with the closest names and where the rest are listed.
+ * `key` is the key the author wrote it under — `ui.logo` takes an icon too, and a refusal naming "icon" sent people looking for a key they never wrote. */
+export function parseIcon(value, at, key = 'icon') {
+    if (isAppIcon(value))
+        return value;
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`${at} has ${/^[aeiou]/.test(key) ? 'an' : 'a'} "${key}" that is not an icon's name.`);
+    const near = nearest(value.trim());
+    throw new Error(`${at} has "${key}": "${value}", which is not one of the App icons.` +
+        `${near.length ? ` Did you mean ${near.map((each) => `"${each}"`).join(', ')}?` : ''} The icons: ${APP_ICONS.join(', ')}.`);
+}

package/dist/shared/appLinks.d.ts

@@ -0,0 +1,17 @@
+/** Checked cross-App destinations are navigation intent, never authority. */
+import type { AppTarget } from '../../schema/model.js';
+export type { AppTarget, AppLinkValue, AppTenantIntent } from '../../schema/model.js';
+export type BoundAppTarget = AppTarget<string | number>;
+export type AppLinkAction = {
+    label: string;
+    to: AppTarget;
+} | {
+    label: string;
+    view: string;
+};
+/** Parse closed authoring data. Record bindings are opt-in at the source surface. */
+export declare function parseAppTarget(raw: unknown, at?: string, record?: boolean): AppTarget;
+export declare function parseAppLinkAction(raw: unknown, at: string, record?: boolean): AppLinkAction;
+export declare function appTargetFields(target: AppTarget): string[];
+/** Only bind values already served to this reader. Missing/hidden values refuse. */
+export declare function bindAppTarget(target: AppTarget, row: Readonly<Record<string, unknown>>, visibleFields: readonly string[]): BoundAppTarget;

package/dist/shared/appLinks.js

@@ -0,0 +1,124 @@
+function object(value, keys, at) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        throw new Error(`${at} must be a plain object.`);
+    const raw = value;
+    for (const key of Reflect.ownKeys(raw)) {
+        if (typeof key !== 'string' ||
+            !keys.includes(key) ||
+            !Object.getOwnPropertyDescriptor(raw, key)?.enumerable ||
+            !Object.hasOwn(Object.getOwnPropertyDescriptor(raw, key), 'value'))
+            throw new Error(`${at}: unsupported field "${String(key)}".`);
+    }
+    return raw;
+}
+function text(value, at) {
+    if (typeof value !== 'string' || !value.length || value.length > 1024 || /[\p{Cc}\p{Cs}]/u.test(value))
+        throw new Error(`${at} needs non-empty text.`);
+    return value;
+}
+function value(raw, at, record) {
+    if (typeof raw === 'number') {
+        if (!Number.isSafeInteger(raw))
+            throw new Error(`${at} needs a safe integer; use text for opaque or large keys.`);
+        return raw;
+    }
+    if (typeof raw === 'string')
+        return text(raw, at);
+    if (raw && typeof raw === 'object' && Object.hasOwn(raw, 'from'))
+        throw new Error(`${at} has "from", which is now "column": the field of this record the value is read from.`);
+    const bound = object(raw, ['column'], at);
+    if (!record)
+        throw new Error(`${at}: "column" bindings require a record surface.`);
+    const field = text(bound.column, `${at}.column`);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(field))
+        throw new Error(`${at}.column must name one visible field of this record.`);
+    return { column: field };
+}
+/** Parse closed authoring data. Record bindings are opt-in at the source surface. */
+export function parseAppTarget(raw, at = 'App link', record = false) {
+    const o = object(raw, ['app', 'kind', 'view', 'resource', 'key', 'tenant'], at);
+    const app = text(o.app, `${at}.app`);
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(app))
+        throw new Error(`${at}.app is not an App id.`);
+    const kind = o.kind;
+    if (kind !== 'home' && kind !== 'view' && kind !== 'record')
+        throw new Error(`${at}.kind must be home, view or record.`);
+    object(raw, ['app', 'kind', 'tenant', ...(kind === 'view' ? ['view'] : kind === 'record' ? ['resource', 'key'] : [])], at);
+    let tenant;
+    if (Object.hasOwn(o, 'tenant')) {
+        const t = object(o.tenant, ['kind', 'id'], `${at}.tenant`);
+        if (t.kind === 'choose' || t.kind === 'platform') {
+            object(t, ['kind'], `${at}.tenant`);
+            tenant = { kind: t.kind };
+        }
+        else if (t.kind === 'tenant') {
+            const id = value(t.id, `${at}.tenant.id`, record);
+            if (typeof id !== 'object' && (String(id).trim() !== String(id) || id === '@platform'))
+                throw new Error(`${at}.tenant.id is not a tenant selector.`);
+            tenant = { kind: 'tenant', id };
+        }
+        else
+            throw new Error(`${at}.tenant.kind must be choose, tenant or platform.`);
+    }
+    const base = { app, ...(tenant ? { tenant } : {}) };
+    if (kind === 'home')
+        return { ...base, kind };
+    if (kind === 'view') {
+        const view = text(o.view, `${at}.view`);
+        if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(view))
+            throw new Error(`${at}.view is not a view key.`);
+        return { ...base, kind, view };
+    }
+    const resource = text(o.resource, `${at}.resource`);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(resource))
+        throw new Error(`${at}.resource is not a resource name.`);
+    const keys = o.key && typeof o.key === 'object' ? Object.keys(o.key) : [];
+    const key = object(o.key, keys, `${at}.key`);
+    if (!keys.length || keys.some((column) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(column)))
+        throw new Error(`${at}.key needs primary-key columns.`);
+    return {
+        ...base,
+        kind,
+        resource,
+        key: Object.fromEntries(keys.map((column) => [column, value(key[column], `${at}.key.${column}`, record)])),
+    };
+}
+/** `to` is a view's key, or an App link (`appLink({ … })`): one key says where a link goes. */
+function parseLinkTo(to, at, record = false) {
+    if (typeof to === 'string') {
+        const view = to.trim();
+        if (!view || view.length > 1024 || /[\p{Cc}\p{Cs}]/u.test(view))
+            throw new Error(`${at} needs the key of a view, or an appLink().`);
+        return { view };
+    }
+    return { to: parseAppTarget(to, at, record) };
+}
+export function parseAppLinkAction(raw, at, record = false) {
+    const o = object(raw, ['label', 'to'], at);
+    if (typeof o.label !== 'string' || !o.label.trim())
+        throw new Error(`${at}.label needs non-empty text.`);
+    return { label: o.label.trim(), ...parseLinkTo(o.to, `${at}.to`, record) };
+}
+export function appTargetFields(target) {
+    const values = [
+        ...(target.kind === 'record' ? Object.values(target.key) : []),
+        ...(target.tenant?.kind === 'tenant' ? [target.tenant.id] : []),
+    ];
+    return [...new Set(values.flatMap((v) => (typeof v === 'object' ? [v.column] : [])))];
+}
+/** Only bind values already served to this reader. Missing/hidden values refuse. */
+export function bindAppTarget(target, row, visibleFields) {
+    const parsed = parseAppTarget(target, 'App link', true);
+    const bind = (v) => {
+        if (typeof v !== 'object')
+            return v;
+        if (!visibleFields.includes(v.column) || !Object.hasOwn(row, v.column))
+            throw new Error(`App link: unavailable source field "${v.column}".`);
+        return value(row[v.column], `App link source "${v.column}"`, false);
+    };
+    return parseAppTarget({
+        ...parsed,
+        ...(parsed.kind === 'record' ? { key: Object.fromEntries(Object.entries(parsed.key).map(([k, v]) => [k, bind(v)])) } : {}),
+        ...(parsed.tenant?.kind === 'tenant' ? { tenant: { kind: 'tenant', id: bind(parsed.tenant.id) } } : {}),
+    });
+}

package/dist/shared/appListColumns.d.ts

@@ -0,0 +1,3 @@
+import type { AppListPresentation } from './listPresentations.js';
+/** A split reads through its own show, and the columns of its rows when it chooses them. */
+export declare function listPresentationColumns(list: AppListPresentation): string[];

package/dist/shared/appListColumns.js

@@ -0,0 +1,66 @@
+/**
+ * The local columns a list presentation reads, so a list's query fetches
+ * them beside the keys. Its own module because the client needs it on first
+ * paint and app.ts is the manifest parser: a client that imported it from
+ * there took the whole parser — every key list, the page parser, the key
+ * homes it installs at load — into the first script it downloads.
+ */
+import { cardsColumns } from './appCards.js';
+/** A split reads through its own show, and the columns of its rows when it chooses them. */
+export function listPresentationColumns(list) {
+    if (list.kind === 'split') {
+        const { row } = list;
+        return row
+            ? [
+                ...new Set([
+                    row.primary,
+                    ...(row.badge ? [row.badge] : []),
+                    ...(row.avatar ? [row.avatar] : []),
+                    ...(row.lines ?? []),
+                    ...(row.facts ?? []),
+                ]),
+            ]
+            : [];
+    }
+    if (list.kind === 'custom')
+        return [...list.show];
+    if (list.kind === 'cards')
+        return cardsColumns(list);
+    if (list.kind === 'tree')
+        return [...new Set([list.parent, list.primary, ...(list.lines ?? [])])];
+    if (list.kind === 'gantt')
+        return [
+            ...new Set([
+                list.start,
+                list.end,
+                list.primary,
+                ...(list.by === undefined ? [] : [list.by]),
+                ...(list.progress === undefined ? [] : [list.progress]),
+            ]),
+        ];
+    const lines = list.lines ?? [];
+    return list.kind === 'checklist'
+        ? [list.primary, list.checked, ...lines]
+        : list.kind === 'queue'
+            ? [...new Set([list.primary, ...(list.badge === undefined ? [] : [list.badge]), ...lines, ...(list.facts ?? [])])]
+            : list.kind === 'calendar'
+                ? [
+                    ...new Set([
+                        list.date,
+                        ...(list.end === undefined ? [] : [list.end]),
+                        list.primary,
+                        ...lines,
+                        ...(list.badge === undefined ? [] : [list.badge]),
+                    ]),
+                ]
+                : // The place and the row are read with the card, so a lane can be drawn in its order and a row found.
+                    [
+                        list.by,
+                        list.primary,
+                        ...lines,
+                        ...(list.order === undefined ? [] : [list.order]),
+                        ...(list.swimlanes === undefined ? [] : [list.swimlanes]),
+                        ...(list.category === undefined ? [] : [list.category]),
+                        ...(list.footer ?? []).map((fact) => fact.column),
+                    ];
+}