@fieldia/core 0.23.0 → 0.25.0

package/src/lib/format/references.mjs

@@ -7,13 +7,20 @@ import { BROWSER_HOTKEYS, hotkeyWords } from './hotkeys.mjs';
 import { checkButtonParts, checkHead } from './head-checks.mjs';
 import { checkSectionTracks } from './section-checks.mjs';
 import { fieldPattern } from './pattern.mjs';
+import { BULK_KINDS, bulkSettable } from './bulk-edit.mjs';
+import { DUPLICATE_KINDS } from './duplicate-kinds.mjs';
+import { IMPORT_KINDS, importable } from './import-fields.mjs';
+import { isTimeZone } from '../record/zones.mjs';
 import { fill, MESSAGES } from '../record/messages.mjs';
+import { autofillGroupProblem } from './autofill-group.mjs';
 const has = (record, key) => Object.prototype.hasOwnProperty.call(record, key);
 /** The kinds of field an expression can give a value to: the rest hold records, lines or files. */
 const EXPRESSIBLE = new Set(['char', 'text', 'html', 'integer', 'float', 'monetary', 'boolean', 'date', 'datetime', 'selection', 'json']);
 const EXPRESSIBLE_WORDS = 'text, numbers, yes or no, dates, choices and json can';
 /** The kinds of field a list's filter bar can list the values of. */
 const LISTS_ITS_VALUES = new Set(['selection', 'many2one', 'many2many', 'boolean', 'char', 'integer']);
+/** Kinds of field a list's card shows as its picture: a picture held, or text holding a picture's address. */
+const PICTURES = new Set(['image', 'binary', 'char']);
 /** What a calendar's start and end can be: a day, or a day and a time. */
 const CALENDAR_TIMES = new Set(['date', 'datetime']);
 /** What a record's words on a calendar can be. */
@@ -38,11 +45,15 @@ export class ReferenceCheck {
     /** The ids of the tabs and wizard steps a step can go to, and where each goTo and show names one. */
     places = new Set();
     goingTo = [];
+    /** The names of the slots the layout places. */
+    slots = new Set();
     constructor(page, line) {
         this.page = page;
         this.line = line;
     }
     run() {
+        if (this.page.timeZone !== undefined)
+            this.checkZone(this.page.timeZone, 'timeZone');
         this.checkFields(this.page.fields, 'fields', this.line?.name, this.line?.parent);
         this.walkRoot(this.page.layout, 'layout');
         checkHead(this.page.layout, 'layout', {
@@ -58,9 +69,46 @@ export class ReferenceCheck {
         });
         if (this.page.on)
             this.checkEvents(this.page.on, 'on');
+        if (this.page.botCheck !== undefined && !this.line)
+            this.checkBotCheck(this.page);
+        if (this.page.duplicates !== undefined && !this.line)
+            this.checkDuplicates(this.page);
         this.checkGoingTo();
         return this.issues;
     }
+    /** A bot check: on a page of responses, its captcha drawn in a slot the page places. */
+    checkBotCheck(page) {
+        const check = page.botCheck;
+        if (page.data.kind !== 'responses')
+            return this.report('botCheck', 'a bot check is for a page of responses that anyone may send; a record’s page is behind the app’s own sign-in');
+        const captcha = check?.captcha;
+        if (typeof captcha === 'string' && !this.slots.has(captcha))
+            this.report('botCheck.captcha', `no slot "${captcha}" on this page to draw the captcha in: place { "type": "slot", "id": "${captcha}", "name": "${captcha}" } where it goes`);
+    }
+    /** Possible duplicates: asked of a record's own page, by fields records can be compared by, each named once. */
+    checkDuplicates(page) {
+        const given = page.duplicates?.fields;
+        const named = Array.isArray(given) ? given : [];
+        if (!named.length)
+            this.report('duplicates.fields', 'name the fields records are compared by: ["phone", "email"]');
+        if (page.data.kind !== 'record')
+            this.report('duplicates', 'duplicates are asked of records like the one typed: a page of responses keeps none to compare it with');
+        else if (page.layout.type === 'list')
+            this.report('duplicates', 'duplicates are asked as a record is typed, on its own page, not on a list of records');
+        named.forEach((name, i) => {
+            const at = `duplicates.fields[${i}]`;
+            if (named.indexOf(name) !== i)
+                return this.report(at, `"${name}" is named twice`);
+            const def = this.need(name, at);
+            if (def && !DUPLICATE_KINDS.has(def.type))
+                this.report(at, `"${name}" is a ${def.type}; records are compared by words, a number, a date, a choice or a link`);
+        });
+    }
+    /** A time zone the browser knows, by its IANA name: a page's dates and times are never drawn on a clock it cannot read. */
+    checkZone(zone, path) {
+        if (!isTimeZone(zone))
+            this.report(path, `${JSON.stringify(zone)} is not a time zone this browser knows: name one as the IANA does, such as "Africa/Cairo"`);
+    }
     /** Each step's goTo and show names a tab or a wizard step of this page. */
     checkGoingTo() {
         for (const { target, path } of this.goingTo) {
@@ -392,6 +440,14 @@ export class ReferenceCheck {
                 if (pattern instanceof Error)
                     this.report(`${path}.pattern`, fill(MESSAGES.en.patternBroken, { label: def.label, problem: pattern.message }));
             }
+            if (def.type === 'datetime' && def.timeZone !== undefined)
+                this.checkZone(def.timeZone, `${path}.timeZone`);
+            // A linked record's date and time, in a table of the records a many2many links to.
+            if (def.type === 'many2many' && def.fields) {
+                for (const [column, linked] of Object.entries(def.fields))
+                    if (linked.type === 'datetime' && linked.timeZone !== undefined)
+                        this.checkZone(linked.timeZone, `${path}.fields.${column}.timeZone`);
+            }
             if (def.type === 'selection')
                 def.optionsFrom?.dependsOn?.forEach((other, i) => this.need(other, `${path}.optionsFrom.dependsOn[${i}]`, fields));
             if (def.type === 'properties')
@@ -490,9 +546,7 @@ export class ReferenceCheck {
     walkList(list, path) {
         if (this.page.data.kind !== 'record')
             this.report('data', 'a list shows records: its data needs kind "record" and a model');
-        list.columns.forEach((name, i) => this.need(name, `${path}.columns[${i}]`));
-        list.sort?.forEach((order, i) => this.need(order.field, `${path}.sort[${i}].field`));
-        list.searchFields?.forEach((name, i) => this.need(name, `${path}.searchFields[${i}]`));
+        this.checkListed(list, this.page.fields, path);
         list.groupBy?.forEach((name, i) => this.need(name, `${path}.groupBy[${i}]`));
         // A list's filters are about its own records: their fields are the page's, and there is no record to take a value from.
         const walk = (item, at) => {
@@ -508,7 +562,11 @@ export class ReferenceCheck {
         list.filters?.forEach((filter, i) => {
             this.claim(filter.id, `${path}.filters[${i}]`);
             named.add(filter.id);
-            filter.filter.forEach((item, j) => walk(item, `${path}.filters[${i}].filter[${j}]`));
+            filter.filter?.forEach((item, j) => walk(item, `${path}.filters[${i}].filter[${j}]`));
+            // A period is of a date, or a date and time.
+            const dated = filter.period ? this.need(filter.period.field, `${path}.filters[${i}].period.field`) : undefined;
+            if (dated && dated.type !== 'date' && dated.type !== 'datetime')
+                this.report(`${path}.filters[${i}].period.field`, `"${filter.period?.field}" is a ${dated.type}; a period is of a date, or a date and time`);
         });
         list.defaultFilters?.forEach((id, i) => {
             if (!named.has(id))
@@ -523,6 +581,54 @@ export class ReferenceCheck {
         if (list.calendar)
             this.walkListCalendar(list, `${path}.calendar`);
         this.checkListCells(list, path);
+        this.checkListRows(list, path);
+    }
+    /**
+     * A list's cards, gallery, columns people choose and rows' own rules: a
+     * card's fields the page's, its picture one that can hold a picture; the
+     * optional columns among the columns; a row's tones, bold and buttons
+     * reading the list's record (its fields, `id`, `user`); and the list
+     * opening on one thing.
+     */
+    checkListRows(list, path) {
+        if (list.card)
+            this.checkListCard(list.card, `${path}.card`, this.page.fields);
+        for (const column of Object.keys(list.optionalColumns ?? {})) {
+            if (!list.columns.includes(column))
+                this.report(`${path}.optionalColumns.${column}`, `"${column}" is no column of this list: a person shows or hides its columns`);
+        }
+        // A column a person may hide, every one hidden at first: the list would open with no column but its own.
+        if (list.optionalColumns && list.columns.every((column) => list.optionalColumns?.[column] === 'hide'))
+            this.report(`${path}.optionalColumns`, 'every column starts hidden: show one at least, as the list opens');
+        if (list.gallery?.opens === 'gallery') {
+            if (list.map?.view && list.map.view !== 'list')
+                this.report(`${path}.gallery.opens`, 'the list opens on its map (map.view) and on its gallery: say one');
+            if (list.calendar?.opens === 'calendar')
+                this.report(`${path}.gallery.opens`, 'the list opens on its calendar and on its gallery: say one');
+        }
+        list.rowTones?.forEach((tone, i) => this.checkModifiers(tone, `${path}.rowTones[${i}]`, ['when']));
+        this.checkModifiers(list, path, ['rowBold']);
+        list.rowButtons?.forEach((button, i) => {
+            this.claim(button.id, `${path}.rowButtons[${i}]`);
+            this.checkPress(button, `${path}.rowButtons[${i}]`);
+            // Shown by a condition on each row's record.
+            this.checkModifiers(button, `${path}.rowButtons[${i}]`, ['invisible']);
+        });
+    }
+    /**
+     * What a list's card shows — a list page's, or a related list's of its own records' fields: its title, subtitle,
+     * status and lines each a field, its picture one that can hold a picture.
+     */
+    checkListCard(card, at, fields) {
+        for (const key of ['title', 'subtitle', 'status'])
+            if (card[key] !== undefined)
+                this.need(card[key], `${at}.${key}`, fields);
+        if (card.image !== undefined) {
+            const def = this.need(card.image, `${at}.image`, fields);
+            if (def && !PICTURES.has(def.type))
+                this.report(`${at}.image`, `"${card.image}" is a ${def.type}; a card's picture is an image or binary field, or text holding a picture's address`);
+        }
+        card.fields?.forEach((line, i) => (Array.isArray(line) ? line : [line]).forEach((part, j) => this.need(typeof part === 'string' ? part : part.field, `${at}.fields[${i}]${Array.isArray(line) ? `[${j}]` : ''}${typeof part === 'string' ? '' : '.field'}`, fields)));
     }
     /**
      * A list's calendar: when each record starts (a date, or a date and time)
@@ -567,22 +673,6 @@ export class ReferenceCheck {
      * the rows chosen need a box to choose one.
      */
     checkListCells(list, path) {
-        for (const [column, cell] of Object.entries(list.cells ?? {})) {
-            const at = `${path}.cells.${column}`;
-            if (!list.columns.includes(column)) {
-                this.report(at, `"${column}" is no column of this list: its cells are for its columns`);
-                continue;
-            }
-            if (!cell.lead)
-                continue;
-            const def = this.need(cell.lead.field, `${at}.lead.field`);
-            if (def?.type !== 'selection')
-                continue;
-            const values = new Set(def.options.map((option) => String(option.value)));
-            for (const value of Object.keys(cell.lead.looks))
-                if (!values.has(value))
-                    this.report(`${at}.lead.looks.${value}`, `"${value}" is no value of "${cell.lead.field}"`);
-        }
         if (list.filterFields && list.search !== 'fields')
             this.report(`${path}.filterFields`, 'the filter fields are for the "fields" search: add "search": "fields"');
         list.filterFields?.forEach((name, i) => {
@@ -604,6 +694,86 @@ export class ReferenceCheck {
         }
         if (list.choose === false && list.actions?.length)
             this.report(`${path}.actions`, 'a list’s buttons act on the rows chosen: with "choose": false there is no way to choose one');
+        this.checkBulkEdit(list, path);
+        this.checkImport(list, path);
+    }
+    /**
+     * What a list shows of its records — a list page's, or a related list's of its own records' fields: its columns, its
+     * order and the fields its search looks in, each a field; each column's cells for a column of it, a sum, an average,
+     * the lowest and the highest of a number column (any column's count), a lead's icon by a field's values.
+     */
+    checkListed(list, fields, path) {
+        list.columns.forEach((name, i) => this.need(name, `${path}.columns[${i}]`, fields));
+        list.sort?.forEach((order, i) => this.need(order.field, `${path}.sort[${i}].field`, fields));
+        list.searchFields?.forEach((name, i) => this.need(name, `${path}.searchFields[${i}]`, fields));
+        for (const [column, cell] of Object.entries(list.cells ?? {})) {
+            const at = `${path}.cells.${column}`;
+            if (!list.columns.includes(column)) {
+                this.report(at, `"${column}" is no column of this list: its cells are for its columns`);
+                continue;
+            }
+            const kind = has(fields, column) ? fields[column].type : undefined;
+            if (cell.total && cell.total !== 'count' && kind && kind !== 'integer' && kind !== 'float' && kind !== 'monetary') {
+                this.report(`${at}.total`, `"${column}" is a ${kind}; its total "${cell.total}" is of numbers — an integer, a float or an amount — and any column's is "count"`);
+            }
+            if (!cell.lead)
+                continue;
+            const def = this.need(cell.lead.field, `${at}.lead.field`, fields);
+            if (def?.type !== 'selection')
+                continue;
+            const values = new Set(def.options.map((option) => String(option.value)));
+            for (const value of Object.keys(cell.lead.looks))
+                if (!values.has(value))
+                    this.report(`${at}.lead.looks.${value}`, `"${value}" is no value of "${cell.lead.field}"`);
+        }
+    }
+    /** A list's Edit: each field it names one value can set in many records, and rows to choose to set it on. */
+    checkBulkEdit(list, path) {
+        if (!list.bulkEdit)
+            return;
+        if (list.choose === false)
+            this.report(`${path}.bulkEdit`, 'Edit changes the rows chosen: with "choose": false there is no way to choose one');
+        if (list.bulkEdit === true) {
+            if (!list.columns.some((name) => bulkSettable(this.page.fields[name])))
+                this.report(`${path}.bulkEdit`, 'Edit offers the columns one value can set, and none of these can: name the fields it offers');
+            return;
+        }
+        const named = list.bulkEdit;
+        named.forEach((name, i) => {
+            const at = `${path}.bulkEdit[${i}]`;
+            if (named.indexOf(name) !== i)
+                this.report(at, `"${name}" is offered twice`);
+            const def = this.need(name, at);
+            if (!def)
+                return;
+            if (!BULK_KINDS.has(def.type))
+                this.report(at, `"${name}" is a ${def.type}; one value set in many records is words, a number, money, a yes or no, a date, a choice or a link`);
+            else if (def.readonly === true || def.compute)
+                this.report(at, `"${name}" is ${def.compute ? 'worked out from other fields' : 'read-only'}; Edit sets a field people can change`);
+        });
+    }
+    /** A list's Import: each field it names one a file's cell can fill, and at least one such field on the page. */
+    checkImport(list, path) {
+        if (!list.import)
+            return;
+        if (list.import === true) {
+            if (!Object.values(this.page.fields).some((def) => importable(def)))
+                this.report(`${path}.import`, 'Import fills the fields a file’s cell can, and this page has none: words, a number, money, yes or no, a date, a choice or a link people can change');
+            return;
+        }
+        const named = list.import;
+        named.forEach((name, i) => {
+            const at = `${path}.import[${i}]`;
+            if (named.indexOf(name) !== i)
+                this.report(at, `"${name}" is offered twice`);
+            const def = this.need(name, at);
+            if (!def)
+                return;
+            if (!IMPORT_KINDS.has(def.type))
+                this.report(at, `"${name}" is a ${def.type}; a file's cell fills words, a number, money, a yes or no, a date, a choice, or a link or links by name`);
+            else if (def.readonly === true || def.compute)
+                this.report(at, `"${name}" is ${def.compute ? 'worked out from other fields' : 'read-only'}; Import fills a field people can change`);
+        });
     }
     /** A list's map: where each record is, and the fields its pin and its card show, each of a type that can. */
     walkListMap(map, path) {
@@ -799,6 +969,11 @@ export class ReferenceCheck {
                 return this.checkValuesIn(node.text, `${path}.text`);
             case 'map':
                 return this.walkMap(node, path);
+            case 'related':
+                return this.checkRelated(node, path);
+            case 'slot':
+                this.slots.add(node.name);
+                return;
             default:
                 return;
         }
@@ -820,6 +995,48 @@ export class ReferenceCheck {
         else
             this.formNames.set(node.name, path);
     }
+    /**
+     * A related list: on a record's page, its columns, order, search, cells, card and rows' rules of its own records'
+     * fields, its link to this record a link of theirs to this model where its fields name it, and its filter's
+     * `valueFrom` this record's.
+     */
+    checkRelated(node, path) {
+        // The quick check reads no shapes: a part with nothing to go by is said here.
+        if (typeof node.model !== 'string' || typeof node.field !== 'string' || !Array.isArray(node.columns) || !node.fields || typeof node.fields !== 'object') {
+            return this.report(path, 'a related list needs the model of its records, their link to this record (field), their fields and its columns');
+        }
+        const model = this.page.data.kind === 'record' ? this.page.data.model : null;
+        if (!model || this.line)
+            this.report(path, 'a related list shows the records that point at a record: it belongs on a record’s page');
+        const fields = node.fields;
+        this.checkListed(node, fields, path);
+        // On a phone its rows are cards, as a list's: of its own records' fields.
+        if (node.card)
+            this.checkListCard(node.card, `${path}.card`, fields);
+        // Its rows' own rules, as a list's, each read on the row's record: its own fields, its id, the person, the context.
+        const row = { fields };
+        node.rowTones?.forEach((tone, i) => this.checkModifiers(tone, `${path}.rowTones[${i}]`, ['when'], row));
+        this.checkModifiers(node, path, ['rowBold'], row);
+        node.rowButtons?.forEach((button, i) => {
+            this.claim(button.id, `${path}.rowButtons[${i}]`);
+            this.checkPress(button, `${path}.rowButtons[${i}]`);
+            this.checkModifiers(button, `${path}.rowButtons[${i}]`, ['invisible'], row);
+        });
+        const link = has(fields, node.field) ? fields[node.field] : undefined;
+        if (link && model && (link.type !== 'many2one' || link.relation !== model)) {
+            this.report(`${path}.field`, `"${node.field}" ${link.type === 'many2one' ? `links to ${link.relation}` : `is a ${link.type}`}; the records listed point at this one by a many2one to ${model}`);
+        }
+        for (const [name, def] of Object.entries(fields)) {
+            if (def.type === 'monetary' && def.currencyField !== undefined)
+                this.checkCurrency(def.currencyField, `${path}.fields.${name}.currencyField`, fields, undefined, fields);
+            if (def.type === 'datetime' && def.timeZone !== undefined)
+                this.checkZone(def.timeZone, `${path}.fields.${name}.timeZone`);
+        }
+        // Its filter is about its records, by their fields; what it compares with may be read from this record.
+        node.filter?.forEach((item, i) => this.checkFilterItem(item, `${path}.filter[${i}]`, this.here()));
+        if (node.viewAll && node.viewAll.page === this.page.id)
+            this.report(`${path}.viewAll.page`, 'View all opens a list of the records related: this page is the record they point at');
+    }
     walkTabs(node, path) {
         node.children.forEach((tab, i) => {
             const tabPath = `${path}.children[${i}]`;
@@ -956,6 +1173,23 @@ export class ReferenceCheck {
         if (parts && parts !== 'json')
             this.report(`${path}.options.partsField`, `"${options['partsField']}" is a ${parts}; an address's parts are kept in a json field`);
     }
+    /** Booking slots: on a date and time, its end written in another, asked again as the fields it depends on change. */
+    checkSlots(node, def, path) {
+        const options = node.options ?? {};
+        if (def && def.type !== 'datetime')
+            this.report(`${path}.widget`, `slots is for a datetime field; "${node.field}" is a ${def.type}`);
+        const end = options['endField'];
+        if (typeof end === 'string' && has(this.page.fields, end)) {
+            const type = this.page.fields[end].type;
+            if (end === node.field)
+                this.report(`${path}.options.endField`, 'a booking ends in another field than the one it starts in');
+            else if (type !== 'datetime')
+                this.report(`${path}.options.endField`, `"${end}" is a ${type}; a booking's end is kept in a datetime field`);
+        }
+        const on = options['dependsOn'];
+        if (Array.isArray(on))
+            on.forEach((name, i) => typeof name === 'string' && this.need(name, `${path}.options.dependsOn[${i}]`));
+    }
     /** A picker's own settings, on the kind of field each is for: a path on a link, Fieldia's own list on a choice, a button adding tags, a colour for each state. */
     checkPicker(node, def, path) {
         const options = node.options ?? {};
@@ -1001,6 +1235,13 @@ export class ReferenceCheck {
         node.tones?.forEach((tone, i) => this.checkModifiers(tone, `${path}.tones[${i}]`, ['when']));
         node.placeholderWhen?.forEach((item, i) => this.checkModifiers(item, `${path}.placeholderWhen[${i}]`, ['when']));
         this.checkModifiers(node, path, ['bold']);
+        // What the browser fills its box in with: a box names what it holds, an address in parts only whose it is. (That
+        // it is a purpose the standard lists is the format's check, `validatePage`, as other shapes are.)
+        if (typeof node.autocomplete === 'string') {
+            const problem = autofillGroupProblem(node.autocomplete, node.widget === 'address');
+            if (problem)
+                this.report(`${path}.autocomplete`, problem);
+        }
         if (def && node.totals) {
             if (def.type !== 'one2many') {
                 this.report(`${path}.totals`, `totals only apply to one2many fields; "${node.field}" is a ${def.type}`);
@@ -1023,6 +1264,8 @@ export class ReferenceCheck {
         }
         if (node.widget === 'address-search')
             this.checkAddressSearch(node, def, path);
+        if (node.widget === 'slots')
+            this.checkSlots(node, def, path);
         if (def)
             this.checkPicker(node, def, path);
         // The order lines load in: fields of its lines.