@mapled/cli 0.16.0 → 0.17.1

package/dist/scanHtml.js

@@ -10,7 +10,7 @@ const MAX_DEPTH = MAX_OPEN;
     a page nests up to MAX_OPEN elements, deeper throws TooDeep; a
     numeric character reference parse5 can't read throws BadReference. */
 export function parseHtml(text) {
-    const root = { name: "#document", attrs: new Map(), children: [] };
+    const root = { name: "#document", html: true, attrs: new Map(), children: [] };
     const pending = [[parseDocument(text), root]];
     for (let at = 0; at < pending.length; at++) {
         const [node, into] = pending[at];
@@ -22,7 +22,7 @@ export function parseHtml(text) {
             for (const a of child.attrs ?? [])
                 if (!a.namespace)
                     attrs.set(a.name, a.value);
-            const el = { name: child.tagName, attrs, children: [] };
+            const el = { name: child.tagName, html: child.namespaceURI === HTML_NS, attrs, children: [] };
             into.children.push(el);
             const template = child.tagName === "template" && child.namespaceURI === HTML_NS;
             pending.push([template && child.content ? child.content : child, el]);
@@ -116,8 +116,49 @@ function segmentsOf(text) {
         return null;
     return segments.every((s) => SEGMENT.test(s)) ? segments : null;
 }
-/** The attributes the runtime fills (sinks.ts ATTRIBUTES). */
-const ATTRIBUTES = new Set(["href", "src", "alt", "title", "aria-label", "placeholder", "datetime"]);
+/** The attributes the runtime fills and the HTML elements each belongs
+    to, null — any (sinks.ts ATTRIBUTES, DOM rule 3). */
+const ATTRIBUTES = new Map([
+    ["href", ["a", "area"]],
+    ["src", ["img", "video", "audio", "source"]],
+    ["alt", ["img", "area"]],
+    ["title", null],
+    ["aria-label", null],
+    ["placeholder", ["input", "textarea"]],
+    ["datetime", ["time", "del", "ins"]],
+]);
+/** Never written into, by local name in any namespace (sinks.ts REFUSED, DOM rule 2). */
+const REFUSED = new Set(["script", "style", "iframe", "frame", "frameset", "object", "embed", "applet", "base", "link", "meta", "template", "noscript"]);
+/** Whether the runtime writes an element's text (sinks.ts writeText) — or,
+    `htmlOnly`, its picture, its Markdown or an attribute (writeImage,
+    writeMarkdown, writeAttribute), which it writes in HTML alone. */
+const writable = (el, htmlOnly) => !REFUSED.has(el.name.toLowerCase()) && (el.html || !htmlOnly);
+const MAX_EXPAND_DEPTH = 2;
+/** What an element names in `data-mapled-expand`, each as its steps (runtime.ts, listOf). */
+const expandOf = (el) => (el.attrs.get(`${P}expand`) ?? "")
+    .split(",")
+    .map((t) => t.trim())
+    .filter((t) => /^[a-z0-9][a-z0-9_.-]{0,127}$/.test(t))
+    .map((t) => t.split("."));
+/** What of an expand reaches past a step: past `sections`, `sections.picks` is `picks`. */
+const past = (expand, names) => expand.filter((e) => e.length > 1 && names(e[0])).map((e) => e.slice(1));
+/** The paths an element's own attributes read (runtime.ts, declaredOn and heads). */
+function declaredPaths(el) {
+    const out = [];
+    for (const [name, value] of el.attrs) {
+        if (!name.startsWith(P))
+            continue;
+        const attr = name.slice(P.length);
+        if (attr === "bind" || attr === "show" || attr === "hide")
+            out.push(value);
+        else if (attr.startsWith("bind-") && ATTRIBUTES.has(attr.slice(5)))
+            out.push(value);
+        else if (attr === "link")
+            for (const m of value.matchAll(/\{([^{}]*)\}/g))
+                out.push(m[1]);
+    }
+    return out;
+}
 /** Field types the runtime renders in a sink the API's table doesn't
     list for it (lib/bindings.ts COMPATIBLE): a yes or no becomes "true" or
     "false" (paths.ts asText); a link template takes a string or a number,
@@ -151,6 +192,16 @@ export async function scanHtml(dir, opts) {
     const tooDeep = [];
     const badReferences = [];
     const notGroups = [];
+    /** eaches over a relation the read doesn't expand */
+    const unexpanded = [];
+    /** templates with a type where the items have none: a list's records, a relation's, a group's items */
+    const typedUnused = [];
+    /** templates of a block type the components field doesn't take */
+    const foreignTypes = [];
+    /** block types the field takes that no template on the page shows */
+    const untemplated = [];
+    /** places the runtime doesn't write into: a code element, an attribute off its elements, SVG */
+    const refused = [];
     const seenRoutes = new Set();
     const pageKeys = new Set();
     for (const file of files) {
@@ -189,6 +240,24 @@ export async function scanHtml(dir, opts) {
         const routes = new Set();
         /** reads of each collection so far — a record with none inside still reads its collection */
         const reads = new Map();
+        /** What the runtime reads each single with (runtime.ts, heads): the
+            links `data-mapled-expand` names on the page's elements that read
+            it — outside lists, records and eaches — and on its eaches. */
+        const singleReads = new Map();
+        const readSingles = (el, root, depth) => {
+            if (depth > MAX_DEPTH || el.name === "template" || (!root && (el.attrs.has(`${P}list`) || el.attrs.has(`${P}record`))))
+                return;
+            // the document element's own attributes read as any element's; inside, an each reads its path
+            const each = root ? undefined : el.attrs.get(`${P}each`);
+            for (const p of each !== undefined ? [each] : declaredPaths(el)) {
+                const single = segmentsOf(p)?.[0];
+                if (single)
+                    singleReads.set(single, [...(singleReads.get(single) ?? []), ...expandOf(el)]);
+            }
+            if (each === undefined)
+                for (const c of el.children)
+                    readSingles(c, false, depth + 1);
+        };
         const add = (route, b) => {
             routes.add(route);
             reads.set(b.collection, (reads.get(b.collection) ?? 0) + 1);
@@ -208,8 +277,25 @@ export async function scanHtml(dir, opts) {
                 return;
             }
             if (scope.kind === "group") {
-                if (scope.fields && !scope.fields.has(segments[0]))
+                const sub = segments[0];
+                // the owners that hold it — or, when none does, each one: Mapled marks the reads outdated
+                const holding = scope.owners.filter((o) => o.subs.has(sub));
+                if (scope.fields && !scope.fields.has(sub))
                     unknown.push(at(path.trim()));
+                // an each repeats the items of a block's group sub-field: the runtime refuses a sub-field that holds no object with "type"
+                else if (sink === "each" && segments.length === 1 && holding.length > 0 && holding.every((o) => !["group", "json", "location", "relation"].includes(o.subs.get(sub).type)))
+                    notGroups.push(at(path.trim()));
+                for (const owner of holding.length > 0 ? holding : scope.owners) {
+                    const def = owner.subs.get(sub);
+                    add(route, {
+                        base: `${pageKey}:${scope.collection}.${owner.path}.${sub}`,
+                        collection: scope.collection,
+                        field: `${owner.path}.${sub}`,
+                        target: targetOf(sink, def, segments.length),
+                        natural: def ? targetFor(def.type) : "other",
+                        ...(sink === "presence" ? { presence: true } : {}),
+                    });
+                }
                 return;
             }
             let collection;
@@ -241,9 +327,24 @@ export async function scanHtml(dir, opts) {
             // a group's sub-field: the schema knows which there are
             else if (field?.group && rest.length > 1 && !field.group.fields.some((f) => f.key === rest[1]))
                 unknown.push(at(path.trim()));
-            // an each repeats a group's items: the runtime refuses anything else with "type"
-            else if (sink === "each" && field && rest.length === 1 && !field.group && !["json", "location"].includes(effectiveType(field)))
+            // an each repeats a group's items, a components field's blocks or the records a relation links to: the runtime refuses anything else with "type"
+            else if (sink === "each" && field && rest.length === 1 && !field.group && !["json", "location", "components", "relation"].includes(effectiveType(field)))
                 notGroups.push(at(path.trim()));
+            // a sub-field of a group that holds one item is read where it is: it binds
+            // as itself (`seo.title`); a list's items only through an each
+            const sub = field?.group && !field.group.repeatable && rest.length > 1 ? rest[1] : null;
+            if (sub !== null) {
+                const def = field.group.fields.find((f) => f.key === sub);
+                add(route, {
+                    base: `${pageKey}:${collectionKey}.${fieldKey}.${sub}`,
+                    collection: collectionKey,
+                    field: `${fieldKey}.${sub}`,
+                    target: targetOf(sink, def, rest.length - 1),
+                    natural: def ? targetFor(def.type) : "other",
+                    ...(sink === "presence" ? { presence: true } : {}),
+                });
+                return;
+            }
             add(route, {
                 base: `${pageKey}:${collectionKey}.${fieldKey}`,
                 collection: collectionKey,
@@ -253,17 +354,30 @@ export async function scanHtml(dir, opts) {
                 ...(sink === "presence" ? { presence: true } : {}),
             });
         };
-        /** The attributes an element declares for itself. */
+        /** The attributes an element declares for itself — bound only where
+            the runtime writes the value (sinks.ts); elsewhere the page keeps
+            its own HTML, and the scan says so. Shown or hidden works on any
+            element. */
         const own = (el, scope, route) => {
+            const refuse = (attr, value) => refused.push(at(`<${el.name} ${P}${attr}="${value.trim().slice(0, 40)}">`));
             const bind = el.attrs.get(`${P}bind`);
-            if (bind !== undefined)
-                use(scope, route, bind, bindSink(el));
+            if (bind !== undefined) {
+                if (writable(el, el.name === "img" || el.attrs.get(`${P}format`) === "markdown"))
+                    use(scope, route, bind, bindSink(el));
+                else
+                    refuse("bind", bind);
+            }
             for (const [name, value] of el.attrs) {
                 if (!name.startsWith(`${P}bind-`))
                     continue;
                 const attr = name.slice(P.length + 5);
-                if (ATTRIBUTES.has(attr))
+                const on = ATTRIBUTES.get(attr);
+                if (on === undefined)
+                    continue;
+                if (writable(el, true) && (on === null || on.includes(el.name)))
                     use(scope, route, value, attributeSink(el.name, attr));
+                else
+                    refuse(`bind-${attr}`, value);
             }
             for (const name of ["show", "hide"]) {
                 const value = el.attrs.get(`${P}${name}`);
@@ -271,21 +385,48 @@ export async function scanHtml(dir, opts) {
                     use(scope, route, value, "presence");
             }
             const link = el.attrs.get(`${P}link`);
-            if (link !== undefined)
+            if (link === undefined)
+                return;
+            if (el.html && (el.name === "a" || el.name === "area"))
                 for (const m of link.matchAll(/\{([^{}]*)\}/g))
                     use(scope, route, m[1], "template");
+            else
+                refuse("link", link);
+        };
+        /** The templates of a list or an each as the runtime reads them
+            (runtime.ts, templatesOf): the first one without a type, and the
+            first one of each type a block can name; a type outside the
+            grammar of keys is the author's typo. */
+        const templatesOf = (el) => {
+            let plain = null;
+            const typed = new Map();
+            for (const c of el.children) {
+                if (c.name !== "template")
+                    continue;
+                const type = c.attrs.get(`${P}type`);
+                if (type === undefined)
+                    plain ??= c;
+                else if (!KEY.test(type.trim()))
+                    badPaths.push(at(type.trim().slice(0, 40) || '""'));
+                else if (!typed.has(type.trim()))
+                    typed.set(type.trim(), c);
+            }
+            return { plain, typed };
         };
-        /** A list: the collection, and the fields of its first template. The
+        /** A list: the collection, and the fields of the template its records
+            take — a record has no type, so the first one without a type. The
             runtime reads every list of the page from the document, wherever
             it sits — the page's own route. */
         const readList = (el, collectionKey, depth) => {
             add(served, { base: `${pageKey}:${collectionKey}`, collection: collectionKey, target: "collection", natural: "collection" });
-            const template = el.children.find((c) => c.name === "template");
-            if (!template)
+            const { plain, typed } = templatesOf(el);
+            if (typed.size > 0)
+                typedUnused.push(at(collectionKey));
+            if (plain)
+                for (const c of plain.children)
+                    visit(c, { kind: "record", collection: collectionKey, expand: expandOf(el), level: 0 }, served, true, false, depth + 1);
+            else if (typed.size === 0)
                 noTemplate.push(at(collectionKey));
-            else
-                for (const c of template.children)
-                    visit(c, { kind: "record", collection: collectionKey }, served, true, false, depth + 1);
         };
         /** A record inside a record isn't read — but the lists inside it are:
             the runtime lifts them to the page (runtime.ts, compile). */
@@ -347,7 +488,7 @@ export async function scanHtml(dir, opts) {
                 const byQuery = param !== undefined && el.attrs.get(`${P}slug`) === undefined;
                 // the runtime reads the parameter by its exact name
                 const address = byQuery ? `${served}?${encodeURIComponent(param)}=[${slugField ?? "slug"}]` : served;
-                const inner = { kind: "record", collection: collectionKey };
+                const inner = { kind: "record", collection: collectionKey, expand: expandOf(el), level: 0 };
                 const before = reads.get(collectionKey) ?? 0;
                 own(el, inner, address);
                 for (const c of el.children)
@@ -363,35 +504,190 @@ export async function scanHtml(dir, opts) {
             }
             if (each !== undefined) {
                 use(scope, route, each, "each");
-                const template = el.children.find((c) => c.name === "template");
-                if (!template) {
+                const { plain, typed } = templatesOf(el);
+                if (!plain && typed.size === 0) {
                     noTemplate.push(at(each.trim()));
                     return;
                 }
-                const items = { kind: "group", fields: groupFields(scope, each) };
-                for (const c of template.children)
-                    visit(c, items, route, true, inRecord, depth + 1);
+                // the records a relation links to, when the read expands it (§45.4): records have no type, so
+                // they take the template without one — read at the page's own address, as a list inside a
+                // record is: a record's would lend them its [slug], which Preview fills with their own (lib/recordRoutes.ts)
+                const linked = linkedBy(scope, each);
+                if (linked) {
+                    if (!linked.expanded)
+                        unexpanded.push(at(each.trim()));
+                    else if (plain)
+                        for (const collection of linked.collections)
+                            for (const c of plain.children)
+                                visit(c, { kind: "record", collection, ...linked.reads }, served, true, inRecord, depth + 1);
+                    // blocks of other types may hold the sub-field as a group: its items take the same templates
+                    if (!linked.others) {
+                        if (typed.size > 0)
+                            typedUnused.push(at(each.trim()));
+                        return;
+                    }
+                }
+                const repeated = eachField(scope, each);
+                const filled = scope.kind === "group" ? filledByItems(scope, each.trim(), plain, typed) : filledBy(repeated, each.trim(), plain, typed);
+                // a block's relations come along as the read of its record or single expands them past the
+                // field — `sections.picks` → `picks`; a group's items hold none
+                let reads = { expand: [], level: scope.kind === "page" ? 0 : scope.level };
+                if (scope.kind !== "group" && repeated) {
+                    const of = collections.get(repeated.collection);
+                    reads = { expand: past(repeated.reads.expand, (step) => fieldOf(of, step) === repeated.field), level: repeated.reads.level };
+                }
+                for (const [template, fields, owners] of filled) {
+                    const inner = { kind: "group", fields, collection: scope.kind === "group" ? scope.collection : (repeated?.collection ?? ""), owners, ...reads };
+                    // a linked record's items are read at the page's own address, as its linked records are
+                    for (const c of template.children)
+                        visit(c, inner, repeated?.linked ? served : route, true, inRecord, depth + 1);
+                }
                 return;
             }
             own(el, scope, route);
             for (const c of el.children)
                 visit(c, scope, route, inTemplate, inRecord, depth + 1);
         };
-        /** The sub-fields of the group an each repeats, when the schema says. */
-        const groupFields = (scope, each) => {
+        /** The field an each repeats, when the schema says: its collection,
+            the key the page reads it by (a previous one too), the field and
+            what the read expands where it is — a field of the single or the
+            record, or of the one record a relation on the way links to, which
+            the runtime walks into when the read expands it (paths.ts, walk);
+            past ids or a list of records the path finds nothing. `linked`:
+            reached through such a relation. */
+        const eachField = (scope, each) => {
+            const segments = segmentsOf(each);
+            if (!segments || scope.kind === "group" || (scope.kind === "page" && segments.length < 2))
+                return undefined;
+            // on the page a path starts at a single, read with what the runtime reads it with
+            let collection = scope.kind === "page" ? segments[0] : scope.collection;
+            let reads = scope.kind === "page" ? { expand: singleReads.get(collection) ?? [], level: 0 } : { expand: scope.expand, level: scope.level };
+            const steps = scope.kind === "page" ? segments.slice(1) : segments;
+            for (const step of steps.slice(0, -1)) {
+                const of = collections.get(collection);
+                const via = fieldOf(of, step);
+                const names = (s) => fieldOf(of, s) === via;
+                if (!via?.relation || effectiveType(via) !== "relation" || via.relation.cardinality !== "one" || !reads.expand.some((e) => names(e[0])))
+                    return undefined;
+                const level = reads.level + 1;
+                collection = via.relation.target;
+                reads = { expand: level < MAX_EXPAND_DEPTH ? past(reads.expand, names) : [], level };
+            }
+            const key = steps[steps.length - 1];
+            const field = fieldOf(collections.get(collection), key);
+            return field ? { collection, key, field, reads, linked: steps.length > 1 } : undefined;
+        };
+        /** What an each repeats when it names a relation (§45.4) — a field of
+            the record or the single (or of a record linked on the way, as
+            eachField reads it), or a sub-field the blocks of some types
+            hold as one: the records it links to, of the collections the schema
+            knows — only when the read expands the relation (as the API keys
+            it: a field by any of its keys, a sub-field by its own), else the
+            ids, which the runtime doesn't repeat — and what the read expands
+            inside them. `others`: blocks of other types hold the sub-field as
+            something else, which repeats as it is. Null: no relation. */
+        const linkedBy = (scope, each) => {
             const segments = segmentsOf(each);
             if (!segments)
                 return null;
-            let field;
-            if (scope.kind === "page" && segments.length === 2)
-                field = fieldOf(collections.get(segments[0]), segments[1]);
-            else if (scope.kind === "record" && segments.length === 1)
-                field = fieldOf(collections.get(scope.collection), segments[0]);
-            return field?.group ? new Set(field.group.fields.map((f) => f.key)) : null;
+            let relations;
+            let outer;
+            let names;
+            let others = false;
+            if (scope.kind === "group") {
+                const sub = segments.length === 1 ? segments[0] : null;
+                const defs = sub === null ? [] : scope.owners.flatMap((o) => o.subs.get(sub) ?? []);
+                relations = defs.filter((d) => d.type === "relation");
+                if (relations.length === 0)
+                    return null;
+                others = relations.length < defs.length;
+                outer = scope;
+                names = (step) => step === sub;
+            }
+            else {
+                const repeated = eachField(scope, each);
+                if (!repeated || effectiveType(repeated.field) !== "relation")
+                    return null;
+                relations = [repeated.field];
+                outer = repeated.reads;
+                const of = collections.get(repeated.collection);
+                names = (step) => fieldOf(of, step) === repeated.field;
+            }
+            const level = outer.level + 1;
+            return {
+                collections: [...new Set(relations.flatMap((r) => (r.relation && collections.has(r.relation.target) ? [r.relation.target] : [])))],
+                expanded: outer.expand.some((e) => names(e[0])),
+                reads: { expand: level < MAX_EXPAND_DEPTH ? past(outer.expand, names) : [], level },
+                others,
+            };
+        };
+        /** The templates the runtime fills for an each, the fields their
+            paths can name (null: the schema doesn't say) and whose they are.
+            A group's items take the template without a type. A components
+            field's blocks take the template of their type, else that one — so
+            it names the fields of the types without a template of their own;
+            a type the field doesn't take is never filled. A JSON field's
+            objects pick like blocks when they name a `_type`, and the schema
+            doesn't say which do. */
+        const filledBy = (repeated, each, plain, typed) => {
+            const unknownShape = () => [...(plain ? [plain] : []), ...typed.values()].map((t) => [t, null, []]);
+            const field = repeated?.field;
+            // a JSON value's objects pick by their own _type, as blocks do — what they hold, the schema doesn't say
+            if (!repeated || !field || effectiveType(field) === "json")
+                return unknownShape();
+            const subsOf = (fields) => new Map(fields.map((f) => [f.key, f]));
+            if (effectiveType(field) !== "components") {
+                if (typed.size > 0)
+                    typedUnused.push(at(each));
+                if (!plain)
+                    return [];
+                return [field.group ? [plain, new Set(field.group.fields.map((f) => f.key)), [{ path: repeated.key, subs: subsOf(field.group.fields) }]] : [plain, null, []]];
+            }
+            const allowed = field.components?.allowed;
+            const types = opts.schema.componentTypes;
+            if (!allowed || !types)
+                return unknownShape();
+            const ownerOf = (type) => ({ path: `${repeated.key}[${type}]`, subs: subsOf(types.find((t) => t.key === type)?.fields ?? []) });
+            const out = [];
+            for (const [type, template] of typed) {
+                if (!allowed.includes(type)) {
+                    foreignTypes.push(at(`${each}: ${type}`));
+                    continue;
+                }
+                const owner = ownerOf(type);
+                out.push([template, new Set(owner.subs.keys()), [owner]]);
+            }
+            const rest = allowed.filter((type) => !typed.has(type));
+            if (rest.length > 0 && plain) {
+                const owners = rest.map(ownerOf);
+                out.push([plain, new Set(owners.flatMap((o) => [...o.subs.keys()])), owners]);
+            }
+            else if (rest.length > 0)
+                untemplated.push(at(`${each}: ${rest.join(", ")}`));
+            return out;
+        };
+        /** The templates an each inside a repeated template fills: the items
+            of a block's group sub-field (§45.4, `tiers` in a pricing block's
+            template) take the template without a type, and their paths name
+            its sub-fields under `sections[pricing].tiers`; what else repeats
+            there — a JSON value's objects — the schema doesn't say. */
+        const filledByItems = (scope, each, plain, typed) => {
+            const segments = segmentsOf(each);
+            const key = segments?.length === 1 ? segments[0] : null;
+            const owners = scope.owners.flatMap((o) => {
+                const def = key === null ? undefined : o.subs.get(key);
+                return def?.type === "group" && def.group ? [{ path: `${o.path}.${key}`, subs: new Map(def.group.fields.map((f) => [f.key, f])) }] : [];
+            });
+            if (owners.length === 0)
+                return [...(plain ? [plain] : []), ...typed.values()].map((t) => [t, null, []]);
+            if (typed.size > 0)
+                typedUnused.push(at(each));
+            return plain ? [[plain, new Set(owners.flatMap((o) => [...o.subs.keys()])), owners]] : [];
         };
         // the runtime's root is the document element: its own attributes, then what is inside
         const html = doc.children.find((c) => c.name === "html");
         if (html) {
+            readSingles(html, true, 1);
             own(html, { kind: "page" }, served);
             for (const c of html.children)
                 visit(c, { kind: "page" }, served, false, false, 1);
@@ -423,8 +719,19 @@ export async function scanHtml(dir, opts) {
         notes.push(`A list or a record inside a repeated template, or a record inside a record, isn't read: ${list(nested)}.`);
     if (notGroups.length > 0)
         notes.push(`An each repeats the items of a group — ${count(notGroups) === 1 ? "this field isn't one" : "these fields aren't"}: ${list(notGroups)}.`);
+    if (unexpanded.length > 0)
+        notes.push(`An each repeats a relation's records only when the read expands it — name it in data-mapled-expand (sections.picks for a block's), or the page keeps its own HTML there: ${list(unexpanded)}.`);
     if (noTemplate.length > 0)
         notes.push(`A list or an each without a <template> isn't filled: ${list(noTemplate)}.`);
+    if (typedUnused.length > 0)
+        notes.push(`A list's records, the records a relation links to and a group's items have no type, so a <template data-mapled-type> there is never filled — they take the <template> without one: ${list(typedUnused)}.`);
+    if (foreignTypes.length > 0)
+        notes.push(`A <template data-mapled-type> names a block type the field doesn't take, so it's never filled: ${list(foreignTypes)}.`);
+    if (untemplated.length > 0)
+        notes.push(`Blocks of these types have no <template> on the page and don't show — add one with data-mapled-type, or one without a type: ${list(untemplated)}.`);
+    if (refused.length > 0) {
+        notes.push(`Nothing is written into ${count(refused) === 1 ? "this place" : "these places"}, so the page keeps its own HTML there: ${list(refused)}. <script>, <style> and other code elements take nothing, inside <svg> only plain text goes in, and an attribute goes only onto the HTML elements it belongs to — href onto <a>, src onto <img> or media, data-mapled-link onto <a>.`);
+    }
     if (tooDeep.length > 0)
         notes.push(`Elements nest deeper than ${MAX_OPEN} levels, so the scan didn't read ${count(tooDeep) === 1 ? "this page" : "these pages"}: ${list(tooDeep)}.`);
     if (badReferences.length > 0)
@@ -506,9 +813,10 @@ function attributeSink(element, attr) {
             return "text";
     }
 }
-/** The binding's target: the sink, for a value read at the field itself.
-    Deeper paths (a group's sub-field, a linked record's field) and eaches
-    bind the field as a whole — Mapled grades those as it can't check. */
+/** The binding's target: the sink, for a value read at the field (or
+    the sub-field) itself. Deeper paths (a linked record's field, a key of
+    a JSON value) and eaches bind it as a whole — Mapled grades those as
+    it can't check. */
 function targetOf(sink, field, depth) {
     if (sink === "each" || depth > 1)
         return "other";

package/dist/schema.d.ts

@@ -9,6 +9,21 @@ export type SchemaSubField = {
     helpText?: string | null;
     options?: string[] | null;
     sensitive?: boolean;
+    /** A component type's group sub-field (§45.4): its own sub-fields, a
+        list of items. Absent on older servers. */
+    group?: {
+        fields: SchemaSubField[];
+        repeatable: boolean;
+        maxItems?: number;
+    } | null;
+    /** A component type's relation sub-field (§45.4): the collection its
+        items link into — ids of its records, as a relation field's. Absent
+        on older servers. */
+    relation?: {
+        target: string;
+        cardinality: "one" | "many";
+        onDelete?: string;
+    } | null;
 };
 export type SchemaField = {
     key: string;
@@ -53,7 +68,8 @@ export type SchemaField = {
     } | null;
 };
 /** A component type (§45.4): the key an item names in `_type`, the name,
-    the sub-fields in a group's shape. */
+    the sub-fields in a group's shape — one of them may be a group of its
+    own sub-fields. */
 export type SchemaComponentType = {
     key: string;
     displayName: string;

package/dist/schema.js

@@ -55,6 +55,26 @@ export function schemaHash(schema) {
                     required: s.required,
                     options: s.options ?? null,
                     sensitive: s.sensitive === true,
+                    // a group sub-field's own sub-fields (§45.4): present only for it,
+                    // so types without one hash as before
+                    ...(s.type === "group" && s.group
+                        ? {
+                            group: {
+                                repeatable: s.group.repeatable,
+                                maxItems: s.group.maxItems ?? null,
+                                fields: s.group.fields.map((r) => ({
+                                    key: r.key,
+                                    displayName: r.displayName,
+                                    type: r.type,
+                                    required: r.required,
+                                    options: r.options ?? null,
+                                    sensitive: r.sensitive === true,
+                                })),
+                            },
+                        }
+                        : {}),
+                    // a relation sub-field's collection (§45.4): present only for it
+                    ...(s.type === "relation" && s.relation ? { relation: { target: s.relation.target, cardinality: s.relation.cardinality } } : {}),
                 })),
             })),
         }

package/dist/types.js

@@ -84,6 +84,8 @@ function scalarType(type, options) {
             return { type: "MapledAssetId", note: "image" };
         case "file":
             return { type: "MapledAssetId", note: "file" };
+        case "gallery":
+            return { type: "MapledAssetId[]", note: "gallery, images in order" };
         case "enum":
             return { type: literalUnion(options), note: "choice" };
         case "json":
@@ -224,12 +226,27 @@ export function componentNames(types, declared) {
     return out;
 }
 /** One interface per component type: `_type` as its key, `_key` the
-    item's own id, then its sub-fields. */
-function renderComponent(type, name) {
+    item's own id, then its sub-fields — a group sub-field as a list of
+    its item interface, which goes to `extras` under a declared name; a
+    relation sub-field as the ids of the records it links, as a relation
+    field (`names`: the collections' type names). */
+function renderComponent(type, name, declared, extras, names) {
     const lines = [
         `  /** The component's type */\n  _type: ${JSON.stringify(type.key)};`,
         "  /** The item's own id — stays with it across saves */\n  _key: string;",
-        ...type.fields.map(renderSubField),
+        ...type.fields.map((sub) => {
+            if (sub.type === "relation" && sub.relation) {
+                const target = names.get(sub.relation.target) ?? sub.relation.target;
+                const many = sub.relation.cardinality === "many";
+                return fieldLine(sub.key, sub.displayName, sub.required, { type: many ? "MapledRecordId[]" : "MapledRecordId", note: `relation to ${comment(target)}${many ? " (many)" : ""}` });
+            }
+            if (sub.type !== "group" || !sub.group)
+                return renderSubField(sub);
+            const itemName = declared.claim(`${pascal(wordsOf(type.key))}${pascal(wordsOf(sub.key))}Item`);
+            extras.push(`/** ${comment(sub.displayName)} — an item of ${name} */\n` + `export interface ${itemName} {\n${sub.group.fields.map(renderSubField).join("\n")}\n}`);
+            const note = `group${sub.group.maxItems ? `, up to ${sub.group.maxItems} items` : ""}`;
+            return fieldLine(sub.key, sub.displayName, sub.required, { type: `${itemName}[]`, note });
+        }),
     ];
     return `/** ${comment(type.displayName)} — a component (key "${comment(type.key)}") */\nexport interface ${name} {\n${lines.join("\n")}\n}`;
 }
@@ -257,8 +274,11 @@ export function generateTypes(schema, opts = {}) {
         "export type MapledLocation = { lat: number; lng: number };",
     ].join("\n"));
     // the component types come first: a components field names them
-    for (const t of componentTypes)
-        blocks.push(renderComponent(t, components.get(t.key)));
+    for (const t of componentTypes) {
+        const extras = [];
+        const block = renderComponent(t, components.get(t.key), declared, extras, names);
+        blocks.push(...extras, block);
+    }
     if (componentTypes.length > 0) {
         blocks.push("/** Any component of the project — switch on `_type` to render an item of a components field. */\n" +
             `export type MapledComponent = ${componentTypes.map((t) => components.get(t.key)).join(" | ")};`);

package/dist/vanillaDigests.js

@@ -13,4 +13,5 @@ export const VANILLA_DIGESTS = {
     "0.2.1": "sha384-6apTHYxXrozzwFCqNU+70Z9pa/FDnhArNomcKQNWbeKRX4scjFiOc9d7wWKCOvTU",
     "0.2.2": "sha384-lfhwQoPUtrbLcD2HXSLr2o1z+aUAjotB62i3LFMGxzBlK5lfCQPQPLOoWL+1DBMc",
     "0.2.3": "sha384-SuKH/yk2hpNI+Ec2QGKpZ7jVxe+0Ep0x/fchL560g+XuzG5hnVCIhG9OKX6BKdpY",
+    "0.3.0": "sha384-evhHWpu15FOXqD3S7ZXIrtTTDv71hVrOE6l9eHWeeo2NzJh4o9eE3VUkQOnkMj/R",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/cli",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Mapled CLI — sign in, link a project, generate TypeScript types for its content, create forms, preview drafts and check the site's integration.",
   "license": "MIT",
   "homepage": "https://mapled.io",