@jxsuite/studio 10.4.0 → 10.5.0

package/src/editor/repeater-scope.ts

@@ -1,6 +1,12 @@
 /**
- * Repeater scope resolution — enumerate the local `item` / `index` / field tokens available when
- * the author inline-edits text INSIDE a repeater (`$prototype: "Array"`) on the design canvas.
+ * Repeater scope resolution: what the item of a repeater (`$prototype: "Array"`) holds, deduced
+ * from the document and the project without running either.
+ *
+ * Two surfaces ask. Inline text edited INSIDE a repeater inserts a `${item.data.title}` token, and
+ * the `From data…` rung binds a `$map/item/data/title` pointer. They are the same field spelled for
+ * two grammars, so there is one walk and each field carries both spellings. A third surface asks
+ * for the one field that is neither text nor a value: `$children`, which an element draws by
+ * holding it as computed children (spec.md §8.4).
  *
  * There is no live `$map` in edit mode: `prepareForEditMode` renders a mapped array as a
  * `repeater-perimeter` wrapping one glyph-ified template instance, so `renderMappedArrayInto`
@@ -9,23 +15,30 @@
  * document path (which carries a real `"map"` segment — see canvas/path-mapping.ts
  * `classifyRenderNode`).
  *
- * Pure and DOM-free: deps limited to `@jxsuite/schema` guards/types + {@link getNodeAtPath}.
+ * Pure and DOM-free: deps limited to `@jxsuite/schema` guards/types, the runtime's pointer grammar
+ *
+ * - {@link getNodeAtPath}.
+ *
+ * @docs studio/design/repeaters
  */
 
+import { escapeToken, refSegments } from "@jxsuite/runtime/pointer";
 import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
 import {
   isJsonObject,
   isMappedArray,
-  isNonNullObject,
   isRef,
+  isSchemaOnlyDef,
   isString,
 } from "@jxsuite/schema/guards";
 
 import type { JxPath } from "../state";
 import type {
+  JsonObject,
+  JsonValue,
+  JxDocumentValue,
   JxMappedArray,
   JxMutableNode,
-  JxStateDefinition,
   ProjectConfig,
 } from "@jxsuite/schema/types";
 
@@ -58,93 +71,339 @@ export function findEnclosingRepeater(
   return isMappedArray(node) ? node : null;
 }
 
-/** Strip a `#/state/<name>` JSON-Pointer ref to its bare state name (null when it is not one). */
-function refToStateName(binding: JxMappedArray["items"]): string | null {
+/** One field of a repeater's item, in each grammar that can name it. */
+export interface RepeaterField {
+  /** The members walked from the item, unescaped. */
+  path: string[];
+  /** What a template reads and a person is shown: `item.data.title`. */
+  token: string;
+  /** What a `$ref` holds: `$map/item/data/title`, with each member escaped (RFC 6901 §3). */
+  pointer: string;
+  /** Whether the field holds a list, which is all a nested repeater's Items can read. */
+  isArray: boolean;
+  /** Whether the field holds child nodes, which only an element's computed children can draw. */
+  holdsNodes: boolean;
+}
+
+/** The one `$`-prefixed member an item offers: the Jx tree a parsed body came out as. */
+const NODES_MEMBER = "$children";
+
+/** The content format whose loader parses an entry's body into {@link NODES_MEMBER}. */
+const NODES_FORMAT = "Markdown";
+
+/** What every step of the walk reads from. */
+interface ItemSources {
+  doc: JxMutableNode;
+  config: ProjectConfig | null | undefined;
+}
+
+/** Marks a schema as an entry of this content type, so a relationship cycle can be stopped. */
+const ENTRY_TYPE = "$entryType";
+
+/** Marks an entry's `data` member, which is a level of the path rather than a field to offer. */
+const ENTRY_DATA = "$entryData";
+
+/** How many members a sample list contributes to the shape it implies. */
+const SAMPLE_CAP = 20;
+
+/** How many members deep a field path may run, so a walk of a deep schema stays a short list. */
+const DEPTH_CAP = 6;
+
+/** How many pointers a `$ref` chain may follow, so `a → b → a` ends. */
+const HOP_CAP = 8;
+
+/** The shape of what a content type's loader hands back (`ContentLoaderEntry`). */
+function entrySchema(contentType: string, ctx: ItemSources): JsonObject {
+  /* The `content` section is contributed by an extension and absorbed by the project config's index
+     signature, so each level is checked before it is read. */
+  const content: unknown = ctx.config?.content;
+  const type = isJsonObject(content) ? content[contentType] : undefined;
+  const data = isJsonObject(type) && isJsonObject(type.schema) ? type.schema : {};
+  // A CSV row has no body to parse. A type naming no format is not known to lack one.
+  const format = isJsonObject(type) ? type.format : undefined;
+  const hasNodes = !isString(format) || format === NODES_FORMAT;
+  // Built from entries because the order is what the picker lists: id and body, then the fields.
+  const members: [string, JsonValue][] = [
+    ["id", {}],
+    ["body", {}],
+    ...(hasNodes ? ([[NODES_MEMBER, {}]] satisfies [string, JsonValue][]) : []),
+    ["data", { ...data, [ENTRY_DATA]: true }],
+  ];
+  return { [ENTRY_TYPE]: contentType, properties: Object.fromEntries(members) };
+}
+
+/** Whether a schema's own keys say what is inside it, so a sample has nothing to add. */
+function describesFields(schema: JsonObject | null, ctx: ItemSources): boolean {
+  return (
+    isJsonObject(schema?.properties) || isJsonObject(followPointers(schema?.items, ctx)?.properties)
+  );
+}
+
+/**
+ * Follow a schema's pointers to the schema they name, or `null` for one this walk cannot read.
+ *
+ * Three spellings reach another schema: `{ "$ref": "#/content/authors" }` is a relationship, whose
+ * value the loader resolves to the full entry; `{ "$ref": "#/$defs/Member" }` is a shared type; and
+ * `{ "type": { "$ref": … } }` is a typed value naming one.
+ */
+function followPointers(
+  schema: JxDocumentValue | undefined,
+  ctx: ItemSources,
+  hops = 0,
+): JsonObject | null {
+  if (!isJsonObject(schema) || hops > HOP_CAP) {
+    return null;
+  }
+  const pointer = isRef(schema) ? schema.$ref : isRef(schema.type) ? schema.type.$ref : null;
+  if (pointer === null) {
+    return schema;
+  }
+  if (pointer.startsWith("#/content/")) {
+    return entrySchema(pointer.slice("#/content/".length), ctx);
+  }
+  if (pointer.startsWith("#/$defs/")) {
+    const [name, ...rest] = refSegments(pointer.slice("#/$defs/".length));
+    const projectDefs: unknown = ctx.config?.$defs;
+    const declared =
+      name === undefined
+        ? undefined
+        : (ctx.doc.$defs?.[name] ?? (isJsonObject(projectDefs) ? projectDefs[name] : undefined));
+    return walkSchema(followPointers(declared, ctx, hops + 1), rest, ctx);
+  }
+  return null;
+}
+
+/** The union of two implied shapes, so an optional field the first row lacks is still found. */
+function mergeSamples(a: JsonObject, b: JsonObject): JsonObject {
+  const merged: JsonObject = { ...a, ...b };
+  if (isJsonObject(a.items) && isJsonObject(b.items)) {
+    merged.items = mergeSamples(a.items, b.items);
+  }
+  if (isJsonObject(a.properties) && isJsonObject(b.properties)) {
+    const properties: JsonObject = { ...a.properties, ...b.properties };
+    for (const [key, left] of Object.entries(a.properties)) {
+      const right = b.properties[key];
+      if (isJsonObject(left) && isJsonObject(right)) {
+        properties[key] = mergeSamples(left, right);
+      }
+    }
+    merged.properties = properties;
+  }
+  return merged;
+}
+
+/** The shape a sample value implies. */
+function sampleSchema(value: JsonValue | undefined): JsonObject {
+  if (Array.isArray(value)) {
+    let items: JsonObject = {};
+    for (const member of value.slice(0, SAMPLE_CAP)) {
+      items = mergeSamples(items, sampleSchema(member));
+    }
+    return { items };
+  }
+  if (isJsonObject(value)) {
+    return {
+      properties: Object.fromEntries(
+        Object.entries(value).map(([key, member]) => [key, sampleSchema(member)]),
+      ),
+    };
+  }
+  return {};
+}
+
+/** The shape of a state entry's value, or `null` when only running it would say. */
+function stateSchema(def: JxDocumentValue | undefined, ctx: ItemSources): JsonObject | null {
+  if (Array.isArray(def)) {
+    // SAFETY: a naked array state entry is the JSON value it reads as (schema/types `JxStateDefinition`).
+    return sampleSchema(def as JsonValue[]);
+  }
+  if (!isJsonObject(def)) {
+    return null;
+  }
+  /* Detected on the `contentType` string, not the prototype's name, so an import-aliased
+     `$prototype` still matches. An `id` is what asks for one entry rather than the list. */
+  if (isString(def.contentType)) {
+    const entry = entrySchema(def.contentType, ctx);
+    return def.$prototype === "ContentEntry" || def.id !== undefined ? entry : { items: entry };
+  }
+  const declared = followPointers(def, ctx);
+  if (describesFields(declared, ctx)) {
+    return declared;
+  }
+  if ("default" in def) {
+    return sampleSchema(def.default);
+  }
+  const isNakedObject = !isSchemaOnlyDef(def) && !Object.keys(def).some((k) => k.startsWith("$"));
+  return isNakedObject ? sampleSchema(def) : declared;
+}
+
+/** Follow members down a schema, or `null` where the schema stops saying. */
+function walkSchema(
+  schema: JsonObject | null,
+  segments: readonly string[],
+  ctx: ItemSources,
+): JsonObject | null {
+  let current = followPointers(schema, ctx);
+  for (const segment of segments) {
+    const member = isJsonObject(current?.properties) ? current.properties[segment] : undefined;
+    current = followPointers(member ?? (/^\d+$/.test(segment) ? current?.items : undefined), ctx);
+  }
+  return current;
+}
+
+/** The shape of what a repeater's `items` binding reads, in the scope of the repeater itself. */
+function bindingSchema(
+  binding: JxMappedArray["items"],
+  repeaterPath: JxPath,
+  ctx: ItemSources,
+): JsonObject | null {
+  if (Array.isArray(binding)) {
+    // SAFETY: an inline `items` list is read straight out of the JSON document.
+    return sampleSchema(binding as JsonValue[]);
+  }
   if (!isRef(binding)) {
     return null;
   }
-  const { $ref: target } = binding;
-  return target.startsWith("#/state/") ? target.slice("#/state/".length) : null;
+  const ref = binding.$ref.replace(/^#\/\$map\//, "$map/");
+  if (ref.startsWith("#/state/")) {
+    const [name, ...rest] = refSegments(ref.slice("#/state/".length));
+    const def = name === undefined ? undefined : ctx.doc.state?.[name];
+    return walkSchema(stateSchema(def, ctx), rest, ctx);
+  }
+  // A nested repeater reads a member of the repeater around it, so the walk starts from that item.
+  if (ref === "$map/item" || ref.startsWith("$map/item/")) {
+    const rest = refSegments(ref.slice("$map/item/".length));
+    return walkSchema(itemSchemaAt(repeaterPath, ctx), rest, ctx);
+  }
+  return null;
+}
+
+/** The shape of the item in scope at `path`, or `null` outside a repeater or past what is known. */
+function itemSchemaAt(path: JxPath, ctx: ItemSources): JsonObject | null {
+  const repeater = findEnclosingRepeater(ctx.doc, path);
+  if (!repeater) {
+    return null;
+  }
+  const list = bindingSchema(repeater.items, path.slice(0, path.lastIndexOf("map")), ctx);
+  return followPointers(list?.items, ctx);
 }
 
-/** Cap + $-filter a field-name list to a stable, author-facing subset. */
-function safeFields(names: string[]): string[] {
-  return names.filter((k) => !k.startsWith("$")).slice(0, FIELD_CAP);
+/** A field name as a template reads it: a member access where a name allows one, else a bracket. */
+function fieldToken(path: readonly string[]): string {
+  let token = "item";
+  for (const member of path) {
+    token += /^[A-Za-z_$][\w$]*$/.test(member) ? `.${member}` : `[${JSON.stringify(member)}]`;
+  }
+  return token;
 }
 
 /**
- * Resolve the local scope tokens for text edited inside `arrayNode`. Always leads with `item` and
- * `index`; appends field tokens resolved from the repeater's binding:
+ * Every field the item in scope at `path` is known to hold, nearest the item first.
  *
- * - **Content collection** — `items` refs a `{ contentType }` state def. Item shape is `{ id, data: {
- *   …fields }, body }`, so fields come from `projectConfig.content[contentType].schema.properties`
- *   and emit as `item.data.<f>` (the `.data.` nesting is LOAD-BEARING — runtime templates use
- *   `${item.data.title}`), plus `item.id` / `item.body`.
- * - **State array** — `items` refs a state def that is an array of objects. Fields come from a
- *   declared `items.properties`, else are inferred from a sample `default[0]`. Emitted FLAT
- *   (`item.<f>`, no `.data.`).
- * - **Inline array** — `items` is a literal array; fields inferred from `items[0]` object keys.
- * - **Fallback** — anything unresolvable yields exactly `["item", "index"]`.
+ * Walked a level at a time so {@link FIELD_CAP} cuts the deepest fields and never a top-level one.
+ * An object is offered as well as its members, because a component can take the whole value. A list
+ * is offered and not entered: one of its members has no single value to bind. A relationship is
+ * entered unless the branch already passed through that content type, which ends a post → author →
+ * post cycle.
  *
- * @param arrayNode - The repeater node from {@link findEnclosingRepeater}.
- * @param state - The document's `state` definitions (`tab.doc.document.state`).
+ * `$children` is left out unless asked for: it is a tree of nodes, so a text position, an attribute
+ * or a formula operand that read it would draw `[object Object]`.
+ *
+ * @param doc - The tab's document root (`tab.doc.document`).
+ * @param path - The path of the node asking.
  * @param projectConfig - Parsed `project.json` (`projectState?.projectConfig`).
- * @returns Token strings, e.g. `["item", "index", "item.id", "item.body", "item.data.title"]`.
+ * @param options - `withNodes` also lists the fields that hold child nodes.
+ * @returns The fields, empty outside a repeater and wherever the item's shape cannot be deduced.
  */
-export function resolveRepeaterItemFields(
-  arrayNode: JxMappedArray,
-  state: Readonly<Record<string, JxStateDefinition>> | null | undefined,
+export function repeaterItemFields(
+  doc: JxMutableNode,
+  path: JxPath | null | undefined,
   projectConfig: ProjectConfig | null | undefined,
-): string[] {
-  const base = ["item", "index"];
-  const { items } = arrayNode;
-  const defs = state ?? {};
-
-  const stateName = refToStateName(items);
-  if (stateName) {
-    const def = defs[stateName];
-    if (isJsonObject(def)) {
-      // (a) Content collection — `{ contentType: "<name>" }`. Import-aliased `$prototype` still
-      // Matches because we detect on the `contentType` string, not the prototype name.
-      if (isString(def.contentType)) {
-        /* The `content` section is contributed by an extension and absorbed by the project
-           config's index signature, so each level is checked before it is read. */
-        const content = projectConfig?.content;
-        const ct = isJsonObject(content) ? content[def.contentType] : undefined;
-        const ctSchema = isJsonObject(ct) ? ct.schema : undefined;
-        const props = isJsonObject(ctSchema) ? ctSchema.properties : undefined;
-        const out = [...base, "item.id", "item.body"];
-        if (isNonNullObject(props)) {
-          for (const f of safeFields(Object.keys(props))) {
-            out.push(`item.data.${f}`);
-          }
-        }
-        return out;
+  { withNodes = false }: { withNodes?: boolean } = {},
+): RepeaterField[] {
+  if (!Array.isArray(path)) {
+    return [];
+  }
+  const ctx: ItemSources = { config: projectConfig, doc };
+  const fields: RepeaterField[] = [];
+  const pending: { at: string[]; schema: JsonObject | null; via: string[] }[] = [
+    { at: [], schema: itemSchemaAt(path, ctx), via: [] },
+  ];
+  for (const { at, schema, via } of pending) {
+    const entryType = isString(schema?.[ENTRY_TYPE]) ? schema[ENTRY_TYPE] : null;
+    const passed = entryType === null ? via : [...via, entryType];
+    const members = isJsonObject(schema?.properties) ? Object.entries(schema.properties) : [];
+    for (const [key, member] of members) {
+      const holdsNodes = key === NODES_MEMBER;
+      if ((key.startsWith("$") && !(holdsNodes && withNodes)) || fields.length >= FIELD_CAP) {
+        continue;
       }
-
-      // (b) State array — declared object item-schema, or inferred from a sample default[0].
-      const itemsSchema = def.items;
-      const declared = isJsonObject(itemsSchema) ? itemsSchema.properties : undefined;
-      if (isNonNullObject(declared)) {
-        return [...base, ...safeFields(Object.keys(declared)).map((f) => `item.${f}`)];
+      const memberPath = [...at, key];
+      const resolved = followPointers(member, ctx);
+      if (resolved?.[ENTRY_DATA] !== true) {
+        fields.push({
+          holdsNodes,
+          isArray: resolved?.type === "array" || isJsonObject(resolved?.items),
+          path: memberPath,
+          pointer: `$map/item/${memberPath.map((m) => escapeToken(m)).join("/")}`,
+          token: fieldToken(memberPath),
+        });
       }
-      const defaults = def.default;
-      const sample = Array.isArray(defaults) ? defaults[0] : undefined;
-      if (isJsonObject(sample)) {
-        return [...base, ...safeFields(Object.keys(sample)).map((f) => `item.${f}`)];
+      const type = isString(resolved?.[ENTRY_TYPE]) ? resolved[ENTRY_TYPE] : null;
+      if (memberPath.length < DEPTH_CAP && !(type !== null && passed.includes(type))) {
+        pending.push({ at: memberPath, schema: resolved, via: passed });
       }
     }
-    return base;
   }
+  return fields;
+}
 
-  // (c) Inline literal array — infer fields from the first object element.
-  if (Array.isArray(items)) {
-    const [first] = items;
-    if (isJsonObject(first)) {
-      return [...base, ...safeFields(Object.keys(first)).map((f) => `item.${f}`)];
-    }
-  }
+/**
+ * The local scope tokens for text edited inside a repeater: `item` and `index`, then the fields of
+ * the item in scope (see {@link repeaterItemFields}).
+ *
+ * @returns Token strings, e.g. `["item", "index", "item.id", "item.body", "item.data.title"]`.
+ */
+export function resolveRepeaterItemFields(
+  doc: JxMutableNode,
+  path: JxPath | null | undefined,
+  projectConfig: ProjectConfig | null | undefined,
+): string[] {
+  return ["item", "index", ...repeaterItemFields(doc, path, projectConfig).map((f) => f.token)];
+}
 
-  // (d) Fallback — unresolvable binding, primitive/empty items, or missing schema.
-  return base;
+/**
+ * The `children` template that draws a field's nodes. The fallback is part of it because the field
+ * is only known to be possible: an entry loaded without a body has no `$children` to read.
+ */
+export function childrenTemplate(field: RepeaterField): string {
+  return `\${${field.token} ?? []}`;
+}
+
+/**
+ * The field a `children` template reads, with or without the fallback {@link childrenTemplate}
+ * writes. Anything more than the bare field is the author's own expression and is left as theirs.
+ */
+export function fieldOfChildrenTemplate(
+  template: string,
+  fields: readonly RepeaterField[],
+): RepeaterField | undefined {
+  const token = /^\$\{\s*(.+?)\s*(?:\?\?\s*\[\s*\]\s*)?\}$/u.exec(template)?.[1];
+  return fields.find((field) => field.token === token);
+}
+
+/**
+ * A `$map/…` pointer in the words {@link repeaterItemFields} offers it under, or `null` for any
+ * other pointer. A bound chip says the same name the picker did: `item.data.title`.
+ */
+export function mapRefLabel(ref: string): string | null {
+  if (ref === "$map/index") {
+    return "index";
+  }
+  if (ref === "$map/item") {
+    return "item";
+  }
+  return ref.startsWith("$map/item/")
+    ? fieldToken(refSegments(ref.slice("$map/item/".length)))
+    : null;
 }

package/src/grid/sources/content-source.ts

@@ -12,22 +12,18 @@
  * Collections type their columns from the content-type schema (plus inferred extras found in the
  * data); the pages grid is fully inference-driven.
  *
- * **A collection listing obeys the draft perspective (site-architecture.md §7.6).**
- * `content/draft-state.ts` owns both the one flag and the one definition of what a draft is, and
- * this source calls it rather than testing `draft === true` itself — which is what makes "including
- * drafts" mean the same thing here as it does on the tab chip. It can, because that module imports
- * nothing but `reactivity`: the richer `content/entry-model.ts` asks THIS file where a collection's
- * entries live, so an edge back to it would be the cycle `import/no-cycle` rejects.
+ * **A collection listing obeys the hold perspective (site-architecture.md §7.6).**
+ * `content/hold-state.ts` owns both the one flag and the reading of a project's rules, and this
+ * source calls it rather than reading fields itself, which is what makes "including held entries"
+ * mean the same thing here as it does on the tab chip. It can, because that module does not import
+ * the richer `content/entry-model.ts`, which asks THIS file where a collection's entries live, so
+ * an edge back to it would be the cycle `import/no-cycle` rejects.
  */
 import { getPlatform } from "../../platform";
 import { projectState } from "../../store";
 import { workspace } from "../../workspace/workspace";
-import {
-  DRAFT_FIELD,
-  applyDraftFilter,
-  hasDraftAxis,
-  includingDrafts,
-} from "../../content/draft-state";
+import { applyHoldFilter, holdSwitch, includingHeld } from "../../content/hold-state";
+import type { HoldBearer } from "../../content/hold-state";
 import { getGridController } from "../grid-controller";
 import { isRecentLocal, markLocalMutation } from "../../files/fs-events";
 import {
@@ -275,39 +271,38 @@ interface EntryFileSourceOptions {
   /** Inferred columns to front-load, in order (e.g. title/description for pages). */
   priorityFields?: string[];
   /**
-   * Whether this listing is subject to the draft perspective (site-architecture.md §7.6) —
-   * collections are, the pages tree is not. A draft is a property of a content ENTRY: a page
-   * carrying `draft: true` would vanish from the only tree that lists it, with no collection schema
-   * to explain why.
+   * The collection's definition, when this listing is subject to the hold perspective
+   * (site-architecture.md §7.6). Collections are and the pages tree is not: `hold` rules are
+   * written on a content type, and a page belongs to none.
    */
-  drafts?: boolean;
+  holdDef?: () => HoldBearer | null | undefined;
 }
 
 /**
- * The live sources that obey the draft perspective.
+ * The live sources that obey the hold perspective.
  *
  * A `WeakSet` of the source objects rather than a list of tab-id prefixes: whether a listing is
- * draft filtered is decided by one `drafts: true` in this file, and re-deriving it from
- * `"grid://collection/"` in {@link reloadDraftAwareGrids} would be a second answer free to drift.
- * Membership is added by the engine off that same option, so the two cannot disagree. Weak, so a
- * closed tab's source is collectable.
+ * filtered is decided by one `holdDef` in this file, and re-deriving it from `"grid://collection/"`
+ * in {@link reloadHoldAwareGrids} would be a second answer free to drift. Membership is added by the
+ * engine off that same option, so the two cannot disagree. Weak, so a closed tab's source is
+ * collectable.
  */
-const draftAwareSources = new WeakSet<GridSource>();
+const holdAwareSources = new WeakSet<GridSource>();
 
 /**
- * Reload every open grid whose rows depend on the draft perspective.
+ * Reload every open grid whose rows depend on the hold perspective.
  *
  * The perspective is a flag, and a grid holds its rows in controller state that was loaded once —
- * so `content.setIncludeDrafts` changing the flag has to say so. `load()` (not `refresh()`) is the
+ * so `content.setIncludeHeld` changing the flag has to say so. `load()` (not `refresh()`) is the
  * right verb: it re-pulls columns and rows and leaves the edit buffer alone, whereas `refresh()`
  * would stop to ask an author with pending edits whether to discard them, which is not a question a
  * change of perspective should provoke.
  */
-export async function reloadDraftAwareGrids(): Promise<void> {
+export async function reloadHoldAwareGrids(): Promise<void> {
   const reloads: Promise<void>[] = [];
   for (const tab of workspace.tabs.values()) {
     const controller = getGridController(tab);
-    if (controller && draftAwareSources.has(controller.source)) {
+    if (controller && holdAwareSources.has(controller.source)) {
       reloads.push(controller.load());
     }
   }
@@ -317,8 +312,8 @@ export async function reloadDraftAwareGrids(): Promise<void> {
 /** Shared engine for frontmatter-file sources (collections, pages). */
 function createEntryFileSource(opts: EntryFileSourceOptions): GridSource {
   const source = buildEntryFileSource(opts);
-  if (opts.drafts) {
-    draftAwareSources.add(source);
+  if (opts.holdDef) {
+    holdAwareSources.add(source);
   }
   return source;
 }
@@ -420,43 +415,26 @@ function buildEntryFileSource(opts: EntryFileSourceOptions): GridSource {
       extraColumns.sort((a, b) => rank(a) - rank(b));
     }
 
-    columnsCache = withDraftColumn([pathColumn, ...schemaColumns, ...extraColumns]);
+    columnsCache = withHoldColumn([pathColumn, ...schemaColumns, ...extraColumns]);
     return columnsCache;
   };
 
-  /** Whether this listing has a draft axis at all — the schema declares one, or an entry claims one. */
-  const draftAxis = (): boolean => {
-    if (!opts.drafts) {
-      return false;
-    }
-    const schema = opts.schema();
-    return (
-      hasDraftAxis(schema) ||
-      [...entries.values()].some((entry) => hasDraftAxis(schema, entry.frontmatter))
-    );
-  };
-
   /**
-   * Put the Draft column immediately after Path, when this collection has a draft axis.
-   *
-   * A MOVE, and deliberately not a synthesis: wherever there is an axis there is already a column.
-   * A schema that declares `draft` gave `columnsFromSchema` one, and an entry that carries the
-   * field without the schema declaring it gave `inferColumnsFromRows` one — the two conditions of
-   * {@link hasDraftAxis} are exactly the two conditions that produce a column. Building a third here
-   * would be an unreachable branch pretending to be a safety net.
+   * Put the hold switch's column immediately after Path, when the collection's rules offer one.
    *
+   * A MOVE, and deliberately not a synthesis: a field the rules name but neither the schema nor any
+   * entry states has no column to move, and inventing one would show a state nobody wrote down.
    * What the move buys is that the one field deciding whether an entry appears in its own list is
    * not sitting out at column nine, where declaration order or first-sight order happened to put
-   * it. A collection whose entries only ever say `draft: false` has NO axis and is left alone: the
-   * column is ordinary data there, and promoting it would invent a workflow the project never
-   * declared.
+   * it.
    */
-  const withDraftColumn = (columns: GridColumn[]): GridColumn[] => {
-    const index = columns.findIndex((column) => column.field === DRAFT_FIELD);
-    if (index < 1 || !draftAxis()) {
+  const withHoldColumn = (columns: GridColumn[]): GridColumn[] => {
+    const field = holdSwitch(opts.holdDef?.())?.field;
+    const index = columns.findIndex((column) => column.field === field);
+    if (index < 1) {
       return columns;
     }
-    const rest = columns.filter((column) => column.field !== DRAFT_FIELD);
+    const rest = columns.filter((column) => column.field !== field);
     return [rest[0]!, columns[index]!, ...rest.slice(1)];
   };
 
@@ -661,15 +639,13 @@ function buildEntryFileSource(opts: EntryFileSourceOptions): GridSource {
     async rows(): Promise<GridRowsResult> {
       await load();
       // The perspective is applied to the LISTING, not the load: `entries` keeps every parsed file,
-      // So the Draft column still knows the collection has an axis while its drafts are hidden, and
-      // Turning the perspective back on is a re-list rather than a re-read of the directory.
-      const listed = opts.drafts
-        ? applyDraftFilter(
-            [...entries.entries()],
-            ([, entry]) => entry.frontmatter,
-            includingDrafts(),
-          )
-        : [...entries.entries()];
+      // So turning the perspective back on is a re-list rather than a re-read of the directory.
+      const listed = applyHoldFilter(
+        [...entries.entries()],
+        opts.holdDef?.(),
+        ([, entry]) => entry.frontmatter,
+        includingHeld(),
+      );
       const rows = listed.map(([path, entry]) => rowFor(path, entry));
       return { rows, total: rows.length };
     },
@@ -687,7 +663,7 @@ export function createCollectionSource(typeName: string): GridSource {
   };
 
   return createEntryFileSource({
-    drafts: true,
+    holdDef: () => collectionInfo(typeName)?.def,
     id: makeGridTabId({ kind: "collection", name: typeName }),
     insertFormatName: (path) => {
       const info = requireInfo();

package/src/panels/block-action-bar.ts

@@ -1193,11 +1193,10 @@ function openMergeTagMenu(anchor: HTMLElement): void {
   // No live `$map` in edit mode — the perimeter renders one glyph template — so fields resolve
   // Parent-side from schema, keyed off the selected element's doc path (which carries a `map` segment).
   const selPath = getEditSnapshot().snapshot?.path ?? primarySelection(tab?.session.selection);
-  const arrayNode = tab && selPath ? findEnclosingRepeater(tab.doc.document, selPath) : null;
-  if (arrayNode && tab) {
+  if (tab && selPath && findEnclosingRepeater(tab.doc.document, selPath)) {
     const tokens = resolveRepeaterItemFields(
-      arrayNode,
-      tab.doc.document.state,
+      tab.doc.document,
+      selPath,
       projectState?.projectConfig,
     );
     tags.push(...buildRepeaterTagsFromFields(tokens));