@seamlet/astro 0.2.0 → 0.3.0

package/README.md

@@ -90,6 +90,8 @@ The site's pages take their published content with `site.loadPublishedContent()`
 | `toggle({ label })`                       | `true` or `false`                                                       | `false`          |
 | `choice({ label, options })`              | the `value` of one option                                               | `null`           |
 | `choices({ label, options })`             | the `value`s of any number of options                                   | `[]`             |
+| `reference({ label, collection })`        | the `id` of a record of a collection of the schema                      | `null`           |
+| `references({ label, collection })`       | the `id`s of any number of such records                                 | `[]`             |
 | `group({ label, fields })`                | named fields shown together                                             | each field empty |
 | `collection({ label, item, itemTitle? })` | a list of records of the same fields                                    | `[]`             |
 
@@ -113,6 +115,33 @@ item: { name: text({ label: "Название" }), isHidden: toggle({ label: "С
 // content.practices.filter((practice) => !practice.isHidden)
 ```
 
+## Records and references
+
+Every record of a collection has an `id` of its own, which never changes when records move, so a record has no field named `id`. The CMS gives ids to records that have none (`withRecordIds`), so a site's initial content may leave them out, unless something refers to those records.
+
+A reference points at a record of another collection by its id: the teacher of a practice is chosen from the teachers, so renaming the teacher changes every practice at once. `collection` is where the collection is, its name or a path through groups:
+
+```ts
+const schema = defineSchema({
+  teachers: collection({
+    label: "Преподаватели",
+    itemTitle: "name",
+    item: { name: text({ label: "Имя" }) },
+  }),
+  practices: collection({
+    label: "Практики",
+    itemTitle: "name",
+    item: {
+      name: text({ label: "Название" }),
+      teacher: reference({ label: "Ведёт", collection: "teachers" }),
+    },
+  }),
+});
+// findRecord(content.teachers, practice.teacher)?.name
+```
+
+A reference to a record removed since is kept, with the issue `missing-record`: the content is not saved until the person picks another one or clears it.
+
 ## What the page hides
 
 A field is edited where it is seen, so the editor opens what hides it when a person chooses it in the list of fields. A native `<details>` needs nothing: a click on its summary opens it in the editor too. A part the site hides and shows by itself (its own accordion, a step of a quiz, a dialog, a tab) gets the attribute `data-cms-reveal` (`REVEAL_ATTRIBUTE`). When a field inside it is chosen, the bridge sets `data-cms-revealed` on it and sends it the event `cms:reveal`, which bubbles; the site shows the part with CSS or with its own script:

package/dist/bridge.d.ts

@@ -1,6 +1,6 @@
-import { F as Fields } from './content-CD5TXi4R.js';
-import { P as PageMessage, E as EditorMessage } from './messages-BQSbv5YE.js';
-import './parse-content-CVoASb5i.js';
+import { F as Fields } from './content-GL5k9Mch.js';
+import { P as PageMessage, E as EditorMessage } from './messages-CJ8vKPs9.js';
+import './parse-content-CVU-pHrH.js';
 
 interface BridgeOptions {
     /** The origin of the CMS whose editor may frame the page, such as `https://cms.example.com`. */

package/dist/bridge.js

@@ -5,13 +5,13 @@ import {
   imageFieldAt,
   readEditorMessage,
   shortcutOf
-} from "./chunk-LADJH7RU.js";
+} from "./chunk-N2UE3EQU.js";
 import {
   FIELD_PATH_ATTRIBUTE,
   REVEALED_ATTRIBUTE,
   REVEAL_ATTRIBUTE,
   REVEAL_EVENT
-} from "./chunk-2MRY5Z6U.js";
+} from "./chunk-AFTVM755.js";
 
 // src/bridge/page-markers.ts
 var MARKER_SELECTOR = `[${FIELD_PATH_ATTRIBUTE}]`;

package/dist/{chunk-2MRY5Z6U.js → chunk-AFTVM755.js}

@@ -32,6 +32,12 @@ function url(options) {
 function time(options) {
   return { kind: "time", ...options };
 }
+function reference(options) {
+  return { kind: "reference", ...options };
+}
+function references(options) {
+  return { kind: "references", ...options };
+}
 function group(options) {
   return { kind: "group", ...options };
 }
@@ -47,6 +53,7 @@ function defaultValue(field) {
     case "toggle":
       return false;
     case "choices":
+    case "references":
       return [];
     case "number":
     case "date":
@@ -55,6 +62,7 @@ function defaultValue(field) {
     case "choice":
     case "url":
     case "time":
+    case "reference":
       return null;
     case "group":
       return defaultContent(field.fields);
@@ -139,6 +147,132 @@ function withoutPrefix(address, prefix) {
   return hasPrefix ? address.slice(prefix.length) : void 0;
 }
 
+// src/schema/record-ids.ts
+var RECORD_ID_KEY = "id";
+var RECORD_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/u;
+function isRecordId(value) {
+  return typeof value === "string" && RECORD_ID_PATTERN.test(value);
+}
+function newRecord(collection2, id) {
+  return { ...defaultContent(collection2.item), [RECORD_ID_KEY]: id };
+}
+function withRecordIds(schema, content, newId) {
+  return withIdsInFields(schema, content, newId);
+}
+var COLLECTION_PATH_SEPARATOR = ".";
+function collectionAt(schema, content, path) {
+  return collectionIn(schema, content, path.split(COLLECTION_PATH_SEPARATOR));
+}
+function collectionIn(fields, content, names) {
+  const [name, ...rest] = names;
+  const field = name !== void 0 && Object.hasOwn(fields, name) ? fields[name] : void 0;
+  if (name === void 0 || field === void 0) return void 0;
+  const value = content[name];
+  if (rest.length === 0 && field.kind === "collection") {
+    const records = Array.isArray(value) ? value.filter(isContent) : [];
+    return { collection: field, records };
+  }
+  if (rest.length > 0 && field.kind === "group" && isContent(value)) {
+    return collectionIn(field.fields, value, rest);
+  }
+  return void 0;
+}
+function findRecord(records, id) {
+  if (id === null) return void 0;
+  return records.find((record) => record.id === id);
+}
+function withIdsInFields(fields, content, newId) {
+  const entries = Object.entries(content).map(([name, value]) => {
+    const field = Object.hasOwn(fields, name) ? fields[name] : void 0;
+    return [name, field === void 0 ? value : withIdsIn(field, value, newId)];
+  });
+  return Object.fromEntries(entries);
+}
+function withIdsIn(field, value, newId) {
+  if (field.kind === "group" && isContent(value)) {
+    return withIdsInFields(field.fields, value, newId);
+  }
+  if (field.kind === "collection" && Array.isArray(value)) {
+    return withIdsInRecords(field, value.filter(isContent), newId);
+  }
+  return value;
+}
+function withIdsInRecords(collection2, records, newId) {
+  const taken = /* @__PURE__ */ new Set();
+  return records.map((record) => {
+    const own = record[RECORD_ID_KEY];
+    const isOwnFree = isRecordId(own) && !taken.has(own);
+    const id = isOwnFree ? own : newId();
+    taken.add(id);
+    const fields = withIdsInFields(collection2.item, record, newId);
+    return { ...fields, [RECORD_ID_KEY]: id };
+  });
+}
+function isContent(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/schema/reference-checks.ts
+function missingRecordIssues(schema, content) {
+  const idsOf = (collection2) => recordIdsAt(schema, content, collection2);
+  return issuesInFields(schema, content, [], idsOf);
+}
+function issuesInFields(fields, content, path, idsOf) {
+  return Object.entries(fields).flatMap(
+    ([name, field]) => issuesInField(field, content[name], [...path, name], idsOf)
+  );
+}
+function issuesInField(field, value, path, idsOf) {
+  switch (field.kind) {
+    case "reference":
+      return missingIds(
+        typeof value === "string" ? [value] : [],
+        field,
+        path,
+        idsOf
+      );
+    case "references":
+      return missingIds(stringsOf(value), field, path, idsOf);
+    case "group":
+      return isContent2(value) ? issuesInFields(field.fields, value, path, idsOf) : [];
+    case "collection":
+      return recordsOf(value).flatMap(
+        (record, index) => issuesInFields(field.item, record, [...path, index], idsOf)
+      );
+    case "text":
+    case "number":
+    case "date":
+    case "image":
+    case "link":
+    case "toggle":
+    case "choice":
+    case "choices":
+    case "url":
+    case "time":
+      return [];
+  }
+}
+function missingIds(ids, field, path, idsOf) {
+  const known = idsOf(field.collection);
+  const missing = ids.filter((id) => !known.has(id));
+  return missing.map((id) => ({ path, code: "missing-record", id }));
+}
+function recordIdsAt(schema, content, path) {
+  const records = collectionAt(schema, content, path)?.records ?? [];
+  const ids = records.map((record) => record[RECORD_ID_KEY]);
+  return new Set(ids.filter((id) => typeof id === "string"));
+}
+function recordsOf(value) {
+  return Array.isArray(value) ? value.filter(isContent2) : [];
+}
+function stringsOf(value) {
+  const list = Array.isArray(value) ? value : [];
+  return list.filter((id) => typeof id === "string");
+}
+function isContent2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/schema/parse-content.ts
 var DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
 var TIME_PATTERN = /^(?:[01]\d|2[0-3]):[0-5]\d$/u;
@@ -151,7 +285,11 @@ function countCharacters(text2) {
 }
 function parseContent(schema, input) {
   const parsed = parseFields(schema, input, []);
-  return { content: parsed.value, issues: parsed.issues };
+  const missingRecords = missingRecordIssues(schema, parsed.value);
+  return {
+    content: parsed.value,
+    issues: [...parsed.issues, ...missingRecords]
+  };
 }
 function parseFields(fields, input, path) {
   if (!isRecord(input)) {
@@ -192,6 +330,10 @@ function parseField(field, input, path) {
       return parseUrl(field, input, path);
     case "time":
       return parseTime(field, input, path);
+    case "reference":
+      return parseReference(field, input, path);
+    case "references":
+      return parseReferences(field, input, path);
     case "group":
       return parseFields(field.fields, input, path);
     case "collection":
@@ -346,13 +488,39 @@ function parseCollection(field, input, path) {
   }
   const records = input;
   const parsedRecords = records.map(
-    (record, index) => parseFields(field.item, record, [...path, index])
+    (record, index) => parseRecord(field, record, [...path, index])
   );
   return {
     value: parsedRecords.map((parsed) => parsed.value),
     issues: parsedRecords.flatMap((parsed) => parsed.issues)
   };
 }
+function parseRecord(field, input, path) {
+  const parsed = parseFields(field.item, input, path);
+  const id = isRecord(input) ? input[RECORD_ID_KEY] : void 0;
+  if (!isRecordId(id)) return parsed;
+  return {
+    value: { ...parsed.value, [RECORD_ID_KEY]: id },
+    issues: parsed.issues
+  };
+}
+function parseReference(field, input, path) {
+  if (input === null) {
+    return valid(null);
+  }
+  if (!isRecordId(input)) {
+    return invalidType(defaultValue(field), path);
+  }
+  return valid(input);
+}
+function parseReferences(field, input, path) {
+  const isListOfIds = Array.isArray(input) && input.every((id) => isRecordId(id));
+  if (!isListOfIds) {
+    return invalidType(defaultValue(field), path);
+  }
+  const ids = [...new Set(input)];
+  return valid(ids);
+}
 function isCalendarDate(value) {
   if (!DATE_PATTERN.test(value)) {
     return false;
@@ -432,12 +600,20 @@ export {
   choices,
   url,
   time,
+  reference,
+  references,
   group,
   collection,
   defaultValue,
   defaultContent,
   linkTargetOf,
   hrefOf,
+  RECORD_ID_KEY,
+  isRecordId,
+  newRecord,
+  withRecordIds,
+  collectionAt,
+  findRecord,
   formatFieldPath,
   countCharacters,
   parseContent,

package/dist/{chunk-LADJH7RU.js → chunk-N2UE3EQU.js}

@@ -1,7 +1,7 @@
 import {
   formatFieldPath,
   resolveFieldPath
-} from "./chunk-2MRY5Z6U.js";
+} from "./chunk-AFTVM755.js";
 
 // src/bridge/editor-shortcuts.ts
 function shortcutOf(event) {

package/dist/{content-CD5TXi4R.d.ts → content-GL5k9Mch.d.ts}

@@ -64,26 +64,48 @@ interface TimeField {
     readonly kind: "time";
     readonly label: string;
 }
+/**
+ * A record of a collection of the schema, by its id: the teacher of a practice. `collection` is
+ * where that collection is, its name or a path through groups: "teachers", "studio.teachers".
+ */
+interface ReferenceField {
+    readonly kind: "reference";
+    readonly label: string;
+    readonly collection: string;
+}
+/** Any number of records of a collection of the schema, by their ids: the practices a teacher leads. */
+interface ReferencesField {
+    readonly kind: "references";
+    readonly label: string;
+    readonly collection: string;
+}
 /** Named fields shown and stored together, for example the first screen of a page. */
 interface GroupField<F extends Fields = Fields> {
     readonly kind: "group";
     readonly label: string;
     readonly fields: F;
 }
-/** A list of records of the same shape, for example the items of a menu. */
-interface CollectionField<F extends Fields = Fields> {
+/**
+ * A list of records of the same shape, for example the items of a menu. Every record also has an
+ * `id` of its own, which never changes (see withRecordIds), so a record has no field named `id`.
+ */
+interface CollectionField<F extends RecordFields = RecordFields> {
     readonly kind: "collection";
     readonly label: string;
     readonly item: F;
     /** The field of a record that names it in the editor: a text field, or a link by its text. */
     readonly itemTitle?: keyof F & string;
 }
-type Field = TextField | NumberField | DateField | ImageField | LinkField | ToggleField | ChoiceField | ChoicesField | UrlField | TimeField | GroupField | CollectionField;
+type Field = TextField | NumberField | DateField | ImageField | LinkField | ToggleField | ChoiceField | ChoicesField | UrlField | TimeField | ReferenceField | ReferencesField | GroupField | CollectionField;
 type FieldKind = Field["kind"];
 /** Field names to fields; the order of the keys is the order of the form. */
 interface Fields {
     readonly [name: string]: Field;
 }
+/** The fields of a record of a collection: any fields but `id`, which is the record's own. */
+type RecordFields = Fields & {
+    readonly id?: never;
+};
 type FieldOptions<F extends Field> = Omit<F, "kind">;
 /** The root of a site's schema. Only checks the shape and keeps the literal types. */
 declare function defineSchema<F extends Fields>(fields: F): F;
@@ -98,8 +120,10 @@ declare function choice<const O extends readonly ChoiceOption[]>(options: FieldO
 declare function choices<const O extends readonly ChoiceOption[]>(options: FieldOptions<ChoicesField<O>>): ChoicesField<O>;
 declare function url(options: FieldOptions<UrlField>): UrlField;
 declare function time(options: FieldOptions<TimeField>): TimeField;
+declare function reference(options: FieldOptions<ReferenceField>): ReferenceField;
+declare function references(options: FieldOptions<ReferencesField>): ReferencesField;
 declare function group<F extends Fields>(options: FieldOptions<GroupField<F>>): GroupField<F>;
-declare function collection<F extends Fields>(options: FieldOptions<CollectionField<F>>): CollectionField<F>;
+declare function collection<F extends RecordFields>(options: FieldOptions<CollectionField<F>>): CollectionField<F>;
 
 interface ImageValue {
     readonly src: string;
@@ -114,7 +138,14 @@ interface LinkValue {
  * The value of each field. A text can be empty (""), the other scalar fields can be unset (null):
  * content is filled in by people, so a site must be ready for a missing price or date.
  */
-type ValueOf<F extends Field> = F extends TextField ? string : F extends NumberField ? number | null : F extends DateField ? string | null : F extends ImageField ? ImageValue | null : F extends LinkField ? LinkValue | null : F extends ToggleField ? boolean : F extends ChoiceField<infer Options> ? OptionValue<Options> | null : F extends ChoicesField<infer Options> ? readonly OptionValue<Options>[] : F extends UrlField ? string | null : F extends TimeField ? string | null : F extends GroupField<infer Group> ? ContentOf<Group> : F extends CollectionField<infer Item> ? readonly ContentOf<Item>[] : never;
+type ValueOf<F extends Field> = F extends TextField ? string : F extends NumberField ? number | null : F extends DateField ? string | null : F extends ImageField ? ImageValue | null : F extends LinkField ? LinkValue | null : F extends ToggleField ? boolean : F extends ChoiceField<infer Options> ? OptionValue<Options> | null : F extends ChoicesField<infer Options> ? readonly OptionValue<Options>[] : F extends UrlField ? string | null : F extends TimeField ? string | null : F extends ReferenceField ? string | null : F extends ReferencesField ? readonly string[] : F extends GroupField<infer Group> ? ContentOf<Group> : F extends CollectionField<infer Item> ? readonly RecordOf<Item>[] : never;
+/**
+ * A record of a collection: its fields and its id. The id is missing only in content no editor has
+ * saved yet, such as a site's initial content (see withRecordIds).
+ */
+type RecordOf<F extends RecordFields> = ContentOf<F> & {
+    readonly id?: string;
+};
 /** The values a list of options stores: `"soft" | "active"` for options with those values. */
 type OptionValue<O extends readonly ChoiceOption[]> = O[number]["value"];
 /** The content a schema describes: `ContentOf<typeof schema>` is the type a site renders. */
@@ -129,4 +160,4 @@ type FieldValue = string | number | boolean | null | readonly string[] | ImageVa
 declare function defaultValue(field: Field): FieldValue;
 declare function defaultContent(fields: Fields): Content;
 
-export { url as A, type ContentOf as C, type DateField as D, type Fields as F, type GroupField as G, type ImageField as I, type LinkValue as L, type NumberField as N, type OptionValue as O, type TextField as T, type UrlField as U, type ValueOf as V, type Content as a, type ImageValue as b, type Field as c, type CollectionField as d, type ChoiceField as e, type ChoiceOption as f, type ChoicesField as g, type FieldKind as h, type FieldValue as i, type LinkField as j, type TimeField as k, type ToggleField as l, choice as m, choices as n, collection as o, date as p, defaultContent as q, defaultValue as r, defineSchema as s, group as t, image as u, link as v, number as w, text as x, time as y, toggle as z };
+export { reference as A, references as B, type ContentOf as C, type DateField as D, text as E, type Fields as F, type GroupField as G, time as H, type ImageField as I, toggle as J, url as K, type LinkValue as L, type NumberField as N, type OptionValue as O, type RecordFields as R, type TextField as T, type UrlField as U, type ValueOf as V, type Content as a, type ImageValue as b, type Field as c, type CollectionField as d, type ChoiceField as e, type ChoiceOption as f, type ChoicesField as g, type FieldKind as h, type FieldValue as i, type LinkField as j, type RecordOf as k, type ReferenceField as l, type ReferencesField as m, type TimeField as n, type ToggleField as o, choice as p, choices as q, collection as r, date as s, defaultContent as t, defaultValue as u, defineSchema as v, group as w, image as x, link as y, number as z };

package/dist/{messages-BQSbv5YE.d.ts → messages-CJ8vKPs9.d.ts}

@@ -1,5 +1,5 @@
-import { F as Fields, a as Content } from './content-CD5TXi4R.js';
-import { F as FieldPath } from './parse-content-CVoASb5i.js';
+import { F as Fields, a as Content } from './content-GL5k9Mch.js';
+import { F as FieldPath } from './parse-content-CVU-pHrH.js';
 
 interface Box {
     readonly top: number;

package/dist/{parse-content-CVoASb5i.d.ts → parse-content-CVU-pHrH.d.ts}

@@ -1,4 +1,4 @@
-import { F as Fields, C as ContentOf } from './content-CD5TXi4R.js';
+import { F as Fields, C as ContentOf } from './content-GL5k9Mch.js';
 
 /** Where a value lives in the content: field names and, inside a collection, record indexes. */
 type FieldPath = readonly (string | number)[];
@@ -39,6 +39,10 @@ type ContentIssue = {
     readonly path: FieldPath;
     readonly code: "unknown-choice";
     readonly value: string;
+} | {
+    readonly path: FieldPath;
+    readonly code: "missing-record";
+    readonly id: string;
 };
 interface ParsedContent<C> {
     readonly content: C;
@@ -56,7 +60,8 @@ declare function countCharacters(text: string): number;
  * - a value of the wrong type or format gets the default too, and an issue;
  * - a value of the right type that breaks a rule of its field (too long, below the minimum) is
  *   kept, with an issue: nothing a person typed is lost;
- * - keys the schema does not know are dropped.
+ * - keys the schema does not know are dropped; a record keeps its id (see withRecordIds);
+ * - a reference to a record its collection does not have (removed since) is kept, with an issue.
  * Content with issues is valid to show and edit, but not to save.
  */
 declare function parseContent<F extends Fields>(schema: F, input: unknown): ParsedContent<ContentOf<F>>;

package/dist/protocol.d.ts

@@ -1,6 +1,6 @@
-export { B as Box, a as EditorKey, E as EditorMessage, I as InlineEditingOutcome, L as LinkBox, M as MarkerBox, b as PROTOCOL_VERSION, c as PageLayout, P as PageMessage, d as Point, S as Shortcut, V as Viewport, r as readEditorMessage, e as readPageMessage, s as shortcutOf } from './messages-BQSbv5YE.js';
-import { F as Fields, I as ImageField } from './content-CD5TXi4R.js';
-import { F as FieldPath } from './parse-content-CVoASb5i.js';
+export { B as Box, a as EditorKey, E as EditorMessage, I as InlineEditingOutcome, L as LinkBox, M as MarkerBox, b as PROTOCOL_VERSION, c as PageLayout, P as PageMessage, d as Point, S as Shortcut, V as Viewport, r as readEditorMessage, e as readPageMessage, s as shortcutOf } from './messages-CJ8vKPs9.js';
+import { F as Fields, I as ImageField } from './content-GL5k9Mch.js';
+import { F as FieldPath } from './parse-content-CVU-pHrH.js';
 
 declare function carriesFiles(event: DragEvent): boolean;
 

package/dist/protocol.js

@@ -6,8 +6,8 @@ import {
   readEditorMessage,
   readPageMessage,
   shortcutOf
-} from "./chunk-LADJH7RU.js";
-import "./chunk-2MRY5Z6U.js";
+} from "./chunk-N2UE3EQU.js";
+import "./chunk-AFTVM755.js";
 export {
   PROTOCOL_VERSION,
   carriesFiles,

package/dist/schema.d.ts

@@ -1,17 +1,18 @@
-import { b as ImageValue, L as LinkValue, c as Field, d as CollectionField, F as Fields } from './content-CD5TXi4R.js';
-export { e as ChoiceField, f as ChoiceOption, g as ChoicesField, a as Content, C as ContentOf, D as DateField, h as FieldKind, i as FieldValue, G as GroupField, I as ImageField, j as LinkField, N as NumberField, O as OptionValue, T as TextField, k as TimeField, l as ToggleField, U as UrlField, V as ValueOf, m as choice, n as choices, o as collection, p as date, q as defaultContent, r as defaultValue, s as defineSchema, t as group, u as image, v as link, w as number, x as text, y as time, z as toggle, A as url } from './content-CD5TXi4R.js';
-import { F as FieldPath } from './parse-content-CVoASb5i.js';
-export { C as ContentIssue, P as ParsedContent, c as countCharacters, f as formatFieldPath, p as parseContent } from './parse-content-CVoASb5i.js';
+import { b as ImageValue, L as LinkValue, c as Field, d as CollectionField, F as Fields, a as Content, R as RecordFields, C as ContentOf } from './content-GL5k9Mch.js';
+export { e as ChoiceField, f as ChoiceOption, g as ChoicesField, D as DateField, h as FieldKind, i as FieldValue, G as GroupField, I as ImageField, j as LinkField, N as NumberField, O as OptionValue, k as RecordOf, l as ReferenceField, m as ReferencesField, T as TextField, n as TimeField, o as ToggleField, U as UrlField, V as ValueOf, p as choice, q as choices, r as collection, s as date, t as defaultContent, u as defaultValue, v as defineSchema, w as group, x as image, y as link, z as number, A as reference, B as references, E as text, H as time, J as toggle, K as url } from './content-GL5k9Mch.js';
+import { F as FieldPath } from './parse-content-CVU-pHrH.js';
+export { C as ContentIssue, P as ParsedContent, c as countCharacters, f as formatFieldPath, p as parseContent } from './parse-content-CVU-pHrH.js';
 
 declare const FIELD_PATH_ATTRIBUTE = "data-cms-path";
 interface FieldMarker {
     readonly [FIELD_PATH_ATTRIBUTE]: string;
 }
+type Leaf = string | number | boolean | null | ImageValue | LinkValue | readonly string[];
 /**
  * Every path in content of type C, as a tuple: ["hero"], ["hero", "title"], ["menu", 2],
  * ["menu", 2, "price"]. Scalars, images and links are leaves: an image is one field, not two.
  */
-type ContentPath<C> = C extends readonly (infer Record)[] ? [number] | [number, ...ContentPath<Record>] : C extends string | number | null | ImageValue | LinkValue ? never : {
+type ContentPath<C> = C extends Leaf ? never : C extends readonly (infer Record)[] ? [number] | [number, ...ContentPath<Record>] : {
     [Name in keyof C & string]: [Name] | [Name, ...ContentPath<C[Name]>];
 }[keyof C & string];
 /**
@@ -39,6 +40,29 @@ type FieldTarget = {
  */
 declare function resolveFieldPath(schema: Fields, text: string): FieldTarget | undefined;
 
+declare const RECORD_ID_KEY = "id";
+declare function isRecordId(value: unknown): value is string;
+/** A new record of a collection: its fields empty, its id the given one. */
+declare function newRecord<F extends RecordFields>(collection: CollectionField<F>, id: string): Content;
+/**
+ * The content with an id given to every record that has none, and a new one to a record whose id
+ * another record of its collection already has (a copy). Records with ids of their own keep them.
+ */
+declare function withRecordIds<F extends Fields>(schema: F, content: ContentOf<F>, newId: () => string): ContentOf<F>;
+interface CollectionRecords {
+    readonly collection: CollectionField;
+    readonly records: readonly Content[];
+}
+/**
+ * The collection a reference points at, `"teachers"` or `"studio.teachers"` through groups, with
+ * its records in the content; undefined when the schema has no collection there.
+ */
+declare function collectionAt(schema: Fields, content: Content, path: string): CollectionRecords | undefined;
+/** The record of the list with the id, if it is there. */
+declare function findRecord<R extends {
+    readonly id?: string;
+}>(records: readonly R[], id: string | null): R | undefined;
+
 /** On the element the site hides and shows itself: `<div data-cms-reveal hidden>`. */
 declare const REVEAL_ATTRIBUTE = "data-cms-reveal";
 /** Set by the bridge on a part it revealed; a site can show it with CSS alone. */
@@ -72,4 +96,4 @@ declare function linkTargetOf(href: string): LinkTarget | undefined;
  */
 declare function hrefOf(target: LinkTarget): string;
 
-export { CollectionField, type ContentPath, FIELD_PATH_ATTRIBUTE, Field, type FieldMarker, FieldPath, type FieldTarget, Fields, ImageValue, type LinkKind, type LinkTarget, LinkValue, REVEALED_ATTRIBUTE, REVEAL_ATTRIBUTE, REVEAL_EVENT, editable, hrefOf, linkTargetOf, resolveFieldPath };
+export { CollectionField, type CollectionRecords, Content, ContentOf, type ContentPath, FIELD_PATH_ATTRIBUTE, Field, type FieldMarker, FieldPath, type FieldTarget, Fields, ImageValue, type LinkKind, type LinkTarget, LinkValue, RECORD_ID_KEY, REVEALED_ATTRIBUTE, REVEAL_ATTRIBUTE, REVEAL_EVENT, RecordFields, collectionAt, editable, findRecord, hrefOf, isRecordId, linkTargetOf, newRecord, resolveFieldPath, withRecordIds };

package/dist/schema.js

@@ -1,56 +1,72 @@
 import {
   FIELD_PATH_ATTRIBUTE,
+  RECORD_ID_KEY,
   REVEALED_ATTRIBUTE,
   REVEAL_ATTRIBUTE,
   REVEAL_EVENT,
   choice,
   choices,
   collection,
+  collectionAt,
   countCharacters,
   date,
   defaultContent,
   defaultValue,
   defineSchema,
   editable,
+  findRecord,
   formatFieldPath,
   group,
   hrefOf,
   image,
+  isRecordId,
   link,
   linkTargetOf,
+  newRecord,
   number,
   parseContent,
+  reference,
+  references,
   resolveFieldPath,
   text,
   time,
   toggle,
-  url
-} from "./chunk-2MRY5Z6U.js";
+  url,
+  withRecordIds
+} from "./chunk-AFTVM755.js";
 export {
   FIELD_PATH_ATTRIBUTE,
+  RECORD_ID_KEY,
   REVEALED_ATTRIBUTE,
   REVEAL_ATTRIBUTE,
   REVEAL_EVENT,
   choice,
   choices,
   collection,
+  collectionAt,
   countCharacters,
   date,
   defaultContent,
   defaultValue,
   defineSchema,
   editable,
+  findRecord,
   formatFieldPath,
   group,
   hrefOf,
   image,
+  isRecordId,
   link,
   linkTargetOf,
+  newRecord,
   number,
   parseContent,
+  reference,
+  references,
   resolveFieldPath,
   text,
   time,
   toggle,
-  url
+  url,
+  withRecordIds
 };

package/dist/site.d.ts

@@ -1,5 +1,5 @@
 import { AstroComponentFactory } from 'astro/runtime/server/index.js';
-import { F as Fields, C as ContentOf } from './content-CD5TXi4R.js';
+import { F as Fields, C as ContentOf } from './content-GL5k9Mch.js';
 
 interface SeamletSiteDefinition<F extends Fields> {
     /** The site's address in the CMS: `/sites/<id>`. */

package/dist/site.js

@@ -1,6 +1,6 @@
 import {
   parseContent
-} from "./chunk-2MRY5Z6U.js";
+} from "./chunk-AFTVM755.js";
 
 // src/site.ts
 import { cmsOrigin } from "virtual:seamlet/config";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamlet/astro",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Connects an Astro site to the Seamlet CMS: the schema of its content, the preview the editor frames, and its published content.",
   "license": "MIT",
   "type": "module",