@mapled/cli 0.14.2 → 0.14.4

package/dist/manifest.js

@@ -22,6 +22,7 @@ export const BINDING_TARGETS = [
     "form_field",
     "other",
 ];
+export const LOCALE_ROUTINGS = ["prefix", "prefix-except-default"];
 export const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/\[\]-]{0,119}$/;
 export const LIMITS = { bindings: 500, pages: 200, notes: 20 };
 /** Field types a target renders without a transform — the API's table
@@ -91,7 +92,8 @@ export function typeLabel(type) {
 }
 const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 const isText = (v, max, min = 1) => typeof v === "string" && v.length >= min && v.length <= max;
-const TOP_KEYS = new Set(["framework", "integrationMode", "pages", "bindings", "notes", "capabilities"]);
+const TOP_KEYS = new Set(["framework", "integrationMode", "pages", "bindings", "notes", "capabilities", "locales"]);
+const LOCALE_PARAM = /^[A-Za-z0-9_-]{1,60}$/;
 export const CAPABILITY_KEYS = ["realtime", "releaseRoute"];
 const BINDING_KEYS = new Set(["key", "page", "component", "file", "collection", "field", "target", "required"]);
 /** Parses the file's text into a manifest with only the known fields,
@@ -271,6 +273,31 @@ export function parseManifest(raw, file) {
                 manifest.capabilities = kept;
         }
     }
+    if (data.locales !== undefined) {
+        const loc = data.locales;
+        if (!isObject(loc)) {
+            error("locales", `"locales" must be an object — { routing, param }.`);
+        }
+        else {
+            let ok = true;
+            for (const key of Object.keys(loc)) {
+                if (key !== "routing" && key !== "param") {
+                    error(`locales.${key}`, `locales.${key} isn't part of the manifest — only routing and param; Mapled refuses the push.`);
+                    ok = false;
+                }
+            }
+            if (!LOCALE_ROUTINGS.includes(loc.routing)) {
+                error("locales.routing", `locales.routing must be "prefix" (every language under its own, /en/…) or "prefix-except-default" (the default language at the root).`);
+                ok = false;
+            }
+            if (loc.param !== undefined && !(typeof loc.param === "string" && LOCALE_PARAM.test(loc.param))) {
+                error("locales.param", `locales.param must name the dynamic segment that carries the language, e.g. "locale" for /[locale]/blog/[slug].`);
+                ok = false;
+            }
+            if (ok)
+                manifest.locales = { routing: loc.routing, ...(typeof loc.param === "string" ? { param: loc.param } : {}) };
+        }
+    }
     return { manifest, problems };
 }
 export function indexSchema(schema) {
@@ -302,6 +329,14 @@ export async function checkManifest(manifest, opts) {
     const warn = (p, message) => problems.push({ level: "warning", path: p, message });
     const index = opts.schema ? indexSchema(opts.schema) : null;
     const routes = new Set((manifest.pages ?? []).map((p) => p.route));
+    // routes by language (§28.4): a segment the manifest names must be on some page
+    if (manifest.locales?.param !== undefined) {
+        const marker = `[${manifest.locales.param}]`;
+        const all = [...routes, ...manifest.bindings.map((b) => b.page)];
+        if (all.length > 0 && !all.some((r) => r.split("?")[0].split("/").includes(marker))) {
+            warn("locales.param", `locales.param names "${marker}", but no page route has that segment — the language then goes nowhere; leave param out for Mapled to put the language before the page.`);
+        }
+    }
     for (const [i, p] of (manifest.pages ?? []).entries()) {
         if (p.file && !(await opts.fileExists(p.file))) {
             warn(`pages[${i}].file`, `pages[${i}] (${p.route}): ${p.file} doesn't exist in the repository.`);
@@ -381,8 +416,13 @@ export function orderManifest(manifest) {
         bindings: manifest.bindings.map(orderBinding),
         ...(manifest.notes && manifest.notes.length > 0 ? { notes: [...manifest.notes] } : {}),
         ...(manifest.capabilities ? { capabilities: orderCapabilities(manifest.capabilities) } : {}),
+        ...(manifest.locales ? { locales: { routing: manifest.locales.routing, ...(manifest.locales.param !== undefined ? { param: manifest.locales.param } : {}) } } : {}),
     };
 }
+/** Whether two manifests route languages the same way (missing on both is the same). */
+export function sameLocales(a, b) {
+    return (a?.routing ?? null) === (b?.routing ?? null) && (a?.param ?? null) === (b?.param ?? null);
+}
 function orderCapabilities(c) {
     return {
         ...(c.realtime !== undefined ? { realtime: c.realtime } : {}),
@@ -434,5 +474,6 @@ export function compareManifests(local, remote) {
         onlyRemote,
         changed,
         capabilitiesDiffer: !sameCapabilities(local.capabilities, remote.capabilities),
+        localesDiffer: !sameLocales(local.locales, remote.locales),
     };
 }

package/dist/pin.d.ts

@@ -1,4 +1,4 @@
-import { type Schema, type SchemaCollection } from "./schema.js";
+import { type Schema, type SchemaCollection, type SchemaComponentType } from "./schema.js";
 /** mapled/schema.json — the repository's pin of the schema it was last
     synced with (§21.5). `mapled schema diff` compares it with the live
     schema and says which changes a site that READS the content must
@@ -9,6 +9,8 @@ export type SchemaPin = {
     project: string;
     hash: string;
     collections: SchemaCollection[];
+    /** the component types (§45.4) — only when the project has some, so older pins read as before */
+    componentTypes?: SchemaComponentType[];
 };
 /** The schema reduced to what the pin keeps — the live answer of
     GET /v1/agent/schema without ids, positions and counters. */
@@ -22,7 +24,8 @@ export declare function writePin(dir: string, pin: SchemaPin): Promise<string>;
 export type Severity = "breaking" | "safe";
 export type ChangeOp = "added" | "removed" | "changed" | "renamed";
 export type SchemaChange = {
-    scope: "collection" | "field" | "subfield";
+    /** `component`: a component type (§45.4) — `collection` holds its key */
+    scope: "collection" | "field" | "subfield" | "component";
     collection: string;
     collectionName: string;
     /** The field key; "group.sub" for a sub-field. */
@@ -37,7 +40,10 @@ export type SchemaChange = {
     (§33.5) is safe while the old one is still an alias of the field —
     the site keeps reading it — and the rest of the field is compared
     under its new key; once the alias is removed it is a removed field. */
-export declare function diffSchema(before: SchemaCollection[], after: SchemaCollection[]): SchemaChange[];
+export declare function diffSchema(before: SchemaCollection[], after: SchemaCollection[], componentTypes?: {
+    before?: SchemaComponentType[];
+    after?: SchemaComponentType[];
+}): SchemaChange[];
 /** The diff as terminal lines: one heading per collection, one line per
     change, the severity in the last column. */
 export declare function formatChanges(changes: SchemaChange[], paint?: (severity: Severity, text: string) => string): string[];

package/dist/pin.js

@@ -50,6 +50,10 @@ function pinField(f) {
     // translation is part of the schema hash too (§28.2)
     if (f.localized === true)
         out.localized = true;
+    // and so are the component types a field allows (§45.4)
+    if (f.type === "components" && f.components) {
+        out.components = { allowed: [...f.components.allowed], min: f.components.min ?? null, max: f.components.max ?? null };
+    }
     if (f.aliases && f.aliases.length > 0)
         out.aliases = [...f.aliases];
     return out;
@@ -65,7 +69,10 @@ export function pinSchema(schema, project) {
         mode: c.mode,
         fields: c.fields.map(pinField),
     }));
-    return { project, hash: schemaHash({ collections }), collections };
+    const componentTypes = (schema.componentTypes ?? []).map((t) => ({ key: t.key, displayName: t.displayName, fields: t.fields.map(pinSubField) }));
+    if (componentTypes.length === 0)
+        return { project, hash: schemaHash({ collections }), collections };
+    return { project, hash: schemaHash({ collections, componentTypes }), collections, componentTypes };
 }
 export function parsePin(raw, file) {
     let data;
@@ -84,7 +91,8 @@ export function parsePin(raw, file) {
         collections.some((c) => !c || typeof c !== "object" || typeof c.key !== "string" || !Array.isArray(c.fields))) {
         throw new CliError(`${file} isn't a schema pin written by \`mapled schema pull\` — delete it and pull again.`);
     }
-    return pinSchema({ collections: collections }, obj.project);
+    const componentTypes = Array.isArray(obj.componentTypes) ? obj.componentTypes : undefined;
+    return pinSchema({ collections: collections, ...(componentTypes ? { componentTypes } : {}) }, obj.project);
 }
 export async function readPin(dir) {
     const file = path.join(dir, SCHEMA_FILE);
@@ -109,6 +117,9 @@ function describeType(f, names) {
         const target = names.get(f.relation.target) ?? f.relation.target;
         return `relation to ${target}${f.relation.cardinality === "many" ? " (many)" : ""}`;
     }
+    if (f.type === "components" && "components" in f && f.components) {
+        return `components of ${f.components.allowed.join(", ")}`;
+    }
     if (f.type === "group" && "group" in f && f.group) {
         return `group of ${f.group.fields.length} field${f.group.fields.length === 1 ? "" : "s"}${f.group.repeatable ? ", repeatable" : ""}`;
     }
@@ -155,7 +166,7 @@ function sameJson(a, b) {
     (§33.5) is safe while the old one is still an alias of the field —
     the site keeps reading it — and the rest of the field is compared
     under its new key; once the alias is removed it is a removed field. */
-export function diffSchema(before, after) {
+export function diffSchema(before, after, componentTypes = {}) {
     const changes = [];
     const names = new Map();
     for (const c of before)
@@ -252,6 +263,19 @@ export function diffSchema(before, after) {
                     });
                 }
             }
+            // §45.4: a type the list may no longer hold leaves the site's union; a new one is an item the site doesn't render yet
+            if (bf.type === "components" && af.type === "components" && bf.components && af.components) {
+                for (const k of bf.components.allowed)
+                    if (!af.components.allowed.includes(k))
+                        push("changed", `no longer holds ${q(k)} components`, "breaking");
+                for (const k of af.components.allowed)
+                    if (!bf.components.allowed.includes(k))
+                        push("changed", `may hold ${q(k)} components now`, "safe");
+                const limit = (lo, hi) => [lo ? `at least ${lo}` : null, hi ? `up to ${hi}` : null].filter((x) => x !== null).join(", ") || "no item limit";
+                if ((bf.components.min ?? null) !== (af.components.min ?? null) || (bf.components.max ?? null) !== (af.components.max ?? null)) {
+                    push("changed", `${limit(bf.components.min, bf.components.max)} → ${limit(af.components.min, af.components.max)} items`, "safe");
+                }
+            }
             if (!sameJson(bf.validation, af.validation))
                 push("changed", "validation changed", "safe");
             if (!sameJson(bf.defaultValue, af.defaultValue))
@@ -282,6 +306,48 @@ export function diffSchema(before, after) {
             severity: "safe",
         });
     }
+    // the component types (§45.4): an item of a type is typed by the type's sub-fields
+    const typesBefore = componentTypes.before ?? [];
+    const typesAfter = componentTypes.after ?? [];
+    const afterTypes = new Map(typesAfter.map((t) => [t.key, t]));
+    const beforeTypes = new Map(typesBefore.map((t) => [t.key, t]));
+    for (const bt of typesBefore) {
+        const at = afterTypes.get(bt.key);
+        const base = { collection: bt.key, collectionName: `${at?.displayName ?? bt.displayName} (component)` };
+        if (!at) {
+            changes.push({ ...base, scope: "component", op: "removed", detail: "component type removed", severity: "breaking" });
+            continue;
+        }
+        if (bt.displayName !== at.displayName)
+            changes.push({ ...base, scope: "component", op: "changed", detail: `name ${q(bt.displayName)} → ${q(at.displayName)}`, severity: "safe" });
+        const afterSubs = new Map(at.fields.map((s) => [s.key, s]));
+        const beforeSubs = new Map(bt.fields.map((s) => [s.key, s]));
+        for (const bs of bt.fields) {
+            const as = afterSubs.get(bs.key);
+            if (!as) {
+                changes.push({ ...base, scope: "component", field: bs.key, op: "removed", detail: `removed — ${describeType(bs, names)}`, severity: "breaking" });
+                continue;
+            }
+            diffCommon(bs, as, names, (op, detail, severity) => changes.push({ ...base, scope: "component", field: bs.key, op, detail, severity }));
+        }
+        for (const as of at.fields) {
+            if (beforeSubs.has(as.key))
+                continue;
+            changes.push({ ...base, scope: "component", field: as.key, op: "added", detail: `added — ${describeType(as, names)}, ${as.required ? "required" : "optional"}`, severity: "safe" });
+        }
+    }
+    for (const at of typesAfter) {
+        if (beforeTypes.has(at.key))
+            continue;
+        changes.push({
+            collection: at.key,
+            collectionName: `${at.displayName} (component)`,
+            scope: "component",
+            op: "added",
+            detail: `new component type — ${at.fields.length} field${at.fields.length === 1 ? "" : "s"}`,
+            severity: "safe",
+        });
+    }
     return changes;
 }
 const GLYPH = { added: "+", removed: "-", changed: "~", renamed: ">" };
@@ -303,14 +369,14 @@ export function formatChanges(changes, paint = (_, t) => t) {
     for (const key of order) {
         const list = byCollection.get(key);
         const name = list[0].collectionName;
-        const whole = list.find((c) => c.scope === "collection" && c.op !== "changed");
+        const whole = list.find((c) => (c.scope === "collection" || (c.scope === "component" && !c.field)) && c.op !== "changed");
         if (whole) {
             lines.push(`${GLYPH[whole.op]} ${name} (${key})  ${whole.detail.padEnd(detailWidth)}  ${paint(whole.severity, whole.severity)}`);
             continue;
         }
         lines.push(`${name} (${key})`);
         for (const c of list) {
-            const label = c.scope === "collection" ? "(collection)" : c.field;
+            const label = c.scope === "collection" ? "(collection)" : c.scope === "component" && !c.field ? "(component)" : c.field;
             lines.push(`  ${GLYPH[c.op]} ${label.padEnd(width)}  ${c.detail.padEnd(detailWidth)}  ${paint(c.severity, c.severity)}`);
         }
     }

package/dist/report.d.ts

@@ -114,6 +114,7 @@ export type PreviewAnswer = {
     url: string;
     expiresAt?: string;
     path: string | null;
+    locale?: string;
 } | {
     status: "not_deployed";
     origin: string;

package/dist/scan.d.ts

@@ -1,5 +1,5 @@
 import type * as TS from "typescript";
-import { type Manifest, type ManifestBinding, type ManifestCapabilities, type ManifestPage } from "./manifest.js";
+import { type Manifest, type ManifestBinding, type ManifestCapabilities, type ManifestLocales, type ManifestPage } from "./manifest.js";
 import type { Schema } from "./schema.js";
 /** `mapled scan` (§19.5, §21.4 — the standalone scanner of wave 2): reads
     the site's source and writes down what the code reads from Mapled —
@@ -39,7 +39,14 @@ export type ScanResult = {
     notes: string[];
     /** what the code says the site can do (live updates of a Next.js site); undefined keeps the manifest's */
     capabilities?: ManifestCapabilities;
+    /** how the routes carry the language (§28.4), when a leading dynamic segment names it; undefined keeps the manifest's */
+    locales?: ManifestLocales;
 };
+/** Routes by language from the file conventions (§28.4): a dynamic segment
+    named for the language at the front of a route (`/[locale]/…`,
+    `/[lang]/…`) — every language then lives under its own prefix, and
+    the segment is the manifest's `param`. Null when no route starts so. */
+export declare function detectLocales(routes: Iterable<string>): ManifestLocales | null;
 export declare const SDK_METHODS: Set<string>;
 /** The repository's TypeScript, when it has one; the CLI ships none. */
 export declare function loadTypeScript(dir: string): TypeScriptModule | null;
@@ -90,6 +97,8 @@ export type MergeResult = {
     dropped: string[];
     /** the scan changed what an existing manifest says the site can do */
     capabilitiesChanged: boolean;
+    /** the scan changed how an existing manifest routes languages */
+    localesChanged: boolean;
 };
 /** The scan's bindings replace the ones with the same key; bindings the
     scanner can't see (an agent's, hand-written) stay unless pruned. */

package/dist/scan.js

@@ -1,7 +1,22 @@
 import { createRequire } from "node:module";
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { sameCapabilities, targetFor } from "./manifest.js";
+import { sameCapabilities, sameLocales, targetFor } from "./manifest.js";
+/** The segment names a site gives the language at the front of its routes. */
+const LOCALE_SEGMENTS = new Set(["locale", "lang", "lng", "language"]);
+/** Routes by language from the file conventions (§28.4): a dynamic segment
+    named for the language at the front of a route (`/[locale]/…`,
+    `/[lang]/…`) — every language then lives under its own prefix, and
+    the segment is the manifest's `param`. Null when no route starts so. */
+export function detectLocales(routes) {
+    for (const route of routes) {
+        const first = route.split("/")[1];
+        const m = first ? /^\[([A-Za-z0-9_-]{1,60})\]$/.exec(first) : null;
+        if (m && LOCALE_SEGMENTS.has(m[1].toLowerCase()))
+            return { routing: "prefix", param: m[1] };
+    }
+    return null;
+}
 const SKIP_DIRS = new Set([
     "node_modules",
     ".git",
@@ -1398,6 +1413,7 @@ export async function scanRepository(dir, opts) {
     if (!opts.ts) {
         notes.push("TypeScript isn't installed in this repository, so fields weren't traced (collections only) — npm install -D typescript and scan again.");
     }
+    const locales = detectLocales(routes.pages.values());
     return {
         framework,
         parser: opts.ts ? "typescript" : "tokens",
@@ -1405,6 +1421,7 @@ export async function scanRepository(dir, opts) {
         pages: uniquePages,
         bindings: sortedBindings,
         notes,
+        ...(locales ? { locales } : {}),
     };
 }
 /** The scan's bindings replace the ones with the same key; bindings the
@@ -1451,7 +1468,10 @@ export function mergeManifest(existing, scan, opts) {
         bindings: out,
         ...(existing?.notes && existing.notes.length > 0 ? { notes: existing.notes } : {}),
         ...(scan.capabilities ? { capabilities: scan.capabilities } : existing?.capabilities ? { capabilities: existing.capabilities } : {}),
+        // the scan's routes by language, else the manifest's (written by hand or by the agent)
+        ...(scan.locales ? { locales: scan.locales } : existing?.locales ? { locales: existing.locales } : {}),
     };
     const capabilitiesChanged = existing !== null && !sameCapabilities(existing.capabilities, manifest.capabilities);
-    return { manifest, added, changed, unchanged, kept, dropped, capabilitiesChanged };
+    const localesChanged = existing !== null && !sameLocales(existing.locales, manifest.locales);
+    return { manifest, added, changed, unchanged, kept, dropped, capabilitiesChanged, localesChanged };
 }

package/dist/schema.d.ts

@@ -44,6 +44,20 @@ export type SchemaField = {
     /** Translated (§28.2): the field holds a value per language; the site
         reads the default language's. Absent on older servers. */
     localized?: boolean;
+    /** Components (§45.4): the component types the field allows (keys of
+        `componentTypes`) and how many items it takes. Only on a components field. */
+    components?: {
+        allowed: string[];
+        min?: number | null;
+        max?: number | null;
+    } | null;
+};
+/** A component type (§45.4): the key an item names in `_type`, the name,
+    the sub-fields in a group's shape. */
+export type SchemaComponentType = {
+    key: string;
+    displayName: string;
+    fields: SchemaSubField[];
 };
 export type SchemaCollection = {
     key: string;
@@ -55,6 +69,8 @@ export type SchemaCollection = {
 };
 export type Schema = {
     collections: SchemaCollection[];
+    /** the project's component types, in their order — absent on older servers */
+    componentTypes?: SchemaComponentType[];
 };
 /** Twelve hex characters over everything the generated types depend on. */
 export declare function schemaHash(schema: Schema): string;

package/dist/schema.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 /** Twelve hex characters over everything the generated types depend on. */
 export function schemaHash(schema) {
-    const projection = schema.collections.map((c) => ({
+    const collections = schema.collections.map((c) => ({
         key: c.key,
         displayName: c.displayName,
         kind: c.kind,
@@ -33,7 +33,31 @@ export function schemaHash(schema) {
             ...(f.type === "computed" && f.computed ? { computed: { expression: f.computed.expression, resultType: f.computed.resultType } } : {}),
             // present only for translated fields, so schemas without translations hash as before
             ...(f.localized === true ? { localized: true } : {}),
+            // present only for components fields (§45.4)
+            ...(f.type === "components" && f.components
+                ? { components: { allowed: [...f.components.allowed], min: f.components.min ?? null, max: f.components.max ?? null } }
+                : {}),
         })),
     }));
+    // the component types (§45.4) join the projection only when the project
+    // has some: the generated types name their sub-fields; a schema without
+    // them hashes as before
+    const projection = schema.componentTypes && schema.componentTypes.length > 0
+        ? {
+            collections,
+            componentTypes: schema.componentTypes.map((t) => ({
+                key: t.key,
+                displayName: t.displayName,
+                fields: t.fields.map((s) => ({
+                    key: s.key,
+                    displayName: s.displayName,
+                    type: s.type,
+                    required: s.required,
+                    options: s.options ?? null,
+                    sensitive: s.sensitive === true,
+                })),
+            })),
+        }
+        : collections;
     return createHash("sha256").update(JSON.stringify(projection)).digest("hex").slice(0, 12);
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { type Schema, type SchemaCollection } from "./schema.js";
+import { type Schema, type SchemaCollection, type SchemaComponentType } from "./schema.js";
 /** TypeScript types for the content a site reads through @mapled/next:
     one interface per collection and single, plus keyed maps. Sensitive
     fields never reach the site, so they are left out. */
@@ -16,9 +16,25 @@ export declare function singular(word: string): string;
 export declare function pascal(words: string[]): string;
 /** `blog-posts` → `BlogPost`; singles keep their name (`homepage` → `Homepage`). */
 export declare function typeName(key: string, kind: "collection" | "single"): string;
+/** The names the file declares itself — no collection or component type
+    may take one: `mapled-schemas` is a collection like any other, and a
+    component keyed `mapled` isn't the union of them all. */
+export declare const RESERVED_NAMES: readonly ["MapledAssetId", "MapledRecordId", "MapledJson", "MapledLocation", "MapledComponent", "MapledCollections", "MapledSingles", "MapledCollectionKey", "MapledSingleKey", "MapledSchema"];
+/** Every name the file declares, claimed once: the reserved ones first,
+    then the collections', the component types' and the group items' —
+    a name already claimed gets a numeric suffix, whoever asks second. */
+export declare class DeclaredNames {
+    private readonly taken;
+    claim(name: string): string;
+}
 /** Unique type names: the singular PascalCase of the key; the raw
-    PascalCase when two keys meet there; a numeric suffix as a last resort. */
-export declare function typeNames(collections: SchemaCollection[]): Map<string, string>;
+    PascalCase when two keys meet there; a numeric suffix as a last resort
+    — and when the name is one the file declares itself (`RESERVED_NAMES`). */
+export declare function typeNames(collections: SchemaCollection[], declared?: DeclaredNames): Map<string, string>;
+/** Unique names of the component types (§45.4): the PascalCase of the
+    key with `Component` after it, a numeric suffix when that is claimed
+    already — by a collection, another type or the file itself. */
+export declare function componentNames(types: SchemaComponentType[], declared: DeclaredNames): Map<string, string>;
 export declare function generateTypes(schema: Schema, opts?: {
     projectName?: string;
     sdk?: string;

package/dist/types.js

@@ -118,8 +118,8 @@ function renderSubField(sub) {
 /** The field's line, followed by one per previous key (§33.5): a
     renamed field is still delivered under them, typed as the field, and
     the editor strikes them through until the site stops reading them. */
-function renderField(field, owner, names, extras) {
-    const { required, rendered } = renderedField(field, owner, names, extras);
+function renderField(field, owner, names, extras, components, declared) {
+    const { required, rendered } = renderedField(field, owner, names, extras, components, declared);
     const lines = [fieldLine(field.key, field.displayName, required, rendered)];
     for (const alias of field.aliases ?? []) {
         lines.push(`  /** @deprecated Renamed to "${comment(field.key)}" — still delivered under this key until the alias is removed in Mapled. */\n` +
@@ -127,7 +127,7 @@ function renderField(field, owner, names, extras) {
     }
     return lines.join("\n");
 }
-function renderedField(field, owner, names, extras) {
+function renderedField(field, owner, names, extras, components = new Map(), declared = new DeclaredNames()) {
     if (field.type === "relation" && field.relation) {
         const target = names.get(field.relation.target) ?? field.relation.target;
         const many = field.relation.cardinality === "many";
@@ -137,7 +137,8 @@ function renderedField(field, owner, names, extras) {
         };
     }
     if (field.type === "group" && field.group) {
-        const itemName = `${owner}${pascal(wordsOf(field.key))}${field.group.repeatable ? "Item" : ""}`;
+        // the group's interface is a declared name like any other: a component or a collection may have taken it
+        const itemName = declared.claim(`${owner}${pascal(wordsOf(field.key))}${field.group.repeatable ? "Item" : ""}`);
         const kept = field.group.fields.filter((s) => s.sensitive !== true);
         const hidden = field.group.fields.filter((s) => s.sensitive === true).map((s) => s.key);
         const lines = kept.map(renderSubField);
@@ -153,38 +154,95 @@ function renderedField(field, owner, names, extras) {
     if (field.type === "computed" && field.computed) {
         return { required: false, rendered: computedType(field.computed.resultType) };
     }
+    // components (§45.4): a list of the types the field allows, told apart by `_type`
+    if (field.type === "components" && field.components) {
+        const allowed = field.components.allowed.map((k) => components.get(k)).filter((n) => n !== undefined);
+        const union = allowed.length === 0 ? "never" : allowed.length === 1 ? allowed[0] : `(${allowed.join(" | ")})`;
+        const limits = [
+            ...(field.components.min ? [`at least ${field.components.min}`] : []),
+            ...(field.components.max ? [`up to ${field.components.max}`] : []),
+        ];
+        const note = `components${limits.length > 0 ? `, ${limits.join(", ")} items` : ""}${field.localized === true ? ", translated" : ""}`;
+        return { required: field.required, rendered: { type: `${union}[]`, note } };
+    }
     const scalar = scalarType(field.type, field.options);
     // translated (§28.2): one language per read — `locale` on the read picks it
     return { required: field.required, rendered: field.localized === true ? { ...scalar, note: `${scalar.note}, translated` } : scalar };
 }
+/** The names the file declares itself — no collection or component type
+    may take one: `mapled-schemas` is a collection like any other, and a
+    component keyed `mapled` isn't the union of them all. */
+export const RESERVED_NAMES = [
+    "MapledAssetId",
+    "MapledRecordId",
+    "MapledJson",
+    "MapledLocation",
+    "MapledComponent",
+    "MapledCollections",
+    "MapledSingles",
+    "MapledCollectionKey",
+    "MapledSingleKey",
+    "MapledSchema",
+];
+/** Every name the file declares, claimed once: the reserved ones first,
+    then the collections', the component types' and the group items' —
+    a name already claimed gets a numeric suffix, whoever asks second. */
+export class DeclaredNames {
+    taken = new Set(RESERVED_NAMES);
+    claim(name) {
+        let unique = name;
+        for (let n = 2; this.taken.has(unique); n++)
+            unique = `${name}${n}`;
+        this.taken.add(unique);
+        return unique;
+    }
+}
 /** Unique type names: the singular PascalCase of the key; the raw
-    PascalCase when two keys meet there; a numeric suffix as a last resort. */
-export function typeNames(collections) {
+    PascalCase when two keys meet there; a numeric suffix as a last resort
+    — and when the name is one the file declares itself (`RESERVED_NAMES`). */
+export function typeNames(collections, declared = new DeclaredNames()) {
     const preferred = collections.map((c) => typeName(c.key, c.kind));
     const counts = new Map();
     for (const name of preferred)
         counts.set(name, (counts.get(name) ?? 0) + 1);
-    const taken = new Set();
     const out = new Map();
     collections.forEach((c, i) => {
         let name = preferred[i];
         if ((counts.get(name) ?? 0) > 1)
             name = pascal(wordsOf(c.key));
-        let unique = name;
-        for (let n = 2; taken.has(unique); n++)
-            unique = `${name}${n}`;
-        taken.add(unique);
-        out.set(c.key, unique);
+        out.set(c.key, declared.claim(name));
     });
     return out;
 }
+/** Unique names of the component types (§45.4): the PascalCase of the
+    key with `Component` after it, a numeric suffix when that is claimed
+    already — by a collection, another type or the file itself. */
+export function componentNames(types, declared) {
+    const out = new Map();
+    for (const t of types)
+        out.set(t.key, declared.claim(`${pascal(wordsOf(t.key))}Component`));
+    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) {
+    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),
+    ];
+    return `/** ${comment(type.displayName)} — a component (key "${comment(type.key)}") */\nexport interface ${name} {\n${lines.join("\n")}\n}`;
+}
 export function generateTypes(schema, opts = {}) {
     // the package the site reads through: "@mapled/next" unless the framework says otherwise
     const sdk = opts.sdk ?? "@mapled/next";
     // a React app's assetUrl comes from the client its hooks are built on; the HTML runtime has none to call
     const assets = sdk === "@mapled/react" || sdk === "@mapled/vanilla" ? "@mapled/client" : sdk;
     const hash = schemaHash(schema);
-    const names = typeNames(schema.collections);
+    const declared = new DeclaredNames();
+    const names = typeNames(schema.collections, declared);
+    const componentTypes = schema.componentTypes ?? [];
+    const components = componentNames(componentTypes, declared);
     const blocks = [];
     blocks.push([
         `// Types of the published content this site reads through ${sdk}.`,
@@ -198,12 +256,19 @@ export function generateTypes(schema, opts = {}) {
         "export type MapledJson = Record<string, unknown> | unknown[];",
         "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)));
+    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(" | ")};`);
+    }
     for (const c of schema.collections) {
         const name = names.get(c.key);
         const extras = [];
         const kept = c.fields.filter((f) => !f.sensitive);
         const hidden = c.fields.filter((f) => f.sensitive).map((f) => f.key);
-        const lines = kept.map((f) => renderField(f, name, names, extras));
+        const lines = kept.map((f) => renderField(f, name, names, extras, components, declared));
         if (hidden.length > 0)
             lines.push(`  // Sensitive, never delivered: ${comment(hidden.join(", "))}`);
         const traits = [

package/dist/vanillaDigests.js

@@ -11,4 +11,6 @@ export const VANILLA_DIGESTS = {
     "0.1.2": "sha384-bhIJoFuEGouAZtHbYeNZeN0m6fqFVWpQw+YkSMJhfk/7m5bUwS/qVWZ3xczw/1du",
     "0.2.0": "sha384-HJ5XG9AhAlbKe6jPRVaef3whiVup/5WhprMwqC6RwWhpq6Pb0OsRLzbLmLJ8WH0f",
     "0.2.1": "sha384-6apTHYxXrozzwFCqNU+70Z9pa/FDnhArNomcKQNWbeKRX4scjFiOc9d7wWKCOvTU",
+    "0.2.2": "sha384-lfhwQoPUtrbLcD2HXSLr2o1z+aUAjotB62i3LFMGxzBlK5lfCQPQPLOoWL+1DBMc",
+    "0.2.3": "sha384-SuKH/yk2hpNI+Ec2QGKpZ7jVxe+0Ep0x/fchL560g+XuzG5hnVCIhG9OKX6BKdpY",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/cli",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "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",