canopycms 0.0.68-int.98 → 0.1.0

package/dist/editor/editor-config.js

@@ -1,3 +1,9 @@
+import { titleFieldPath } from '../utils/title-field.js';
+/** The `titleField` an entry type contributes: absent for an unavailable type, which has no schema. */
+const titleFieldFor = (schema) => {
+    const titleField = titleFieldPath(schema ?? []);
+    return titleField ? { titleField } : {};
+};
 /**
  * Build hierarchical editor collections from the flattened schema.
  * Uses logicalPath as IDs to match API responses.
@@ -18,6 +24,13 @@ export const buildEditorCollections = (flatSchema) => {
         }
         childrenByParent.get(key).push(item);
     }
+    // A collection's own `entries` carry no schema on the wire; the entry-type items hold the
+    // hydrated one.
+    const schemaByEntryType = new Map();
+    for (const item of flat) {
+        if (item.type === 'entry-type')
+            schemaByEntryType.set(`${item.parentPath}\0${item.name}`, item.schema);
+    }
     // Build tree recursively using the grouped map
     const buildTree = (parentPath) => {
         const children = childrenByParent.get(parentPath) || [];
@@ -32,6 +45,9 @@ export const buildEditorCollections = (flatSchema) => {
                     format: et.format,
                     default: et.default,
                     maxItems: et.maxItems,
+                    ...(et.unavailable
+                        ? { unavailable: et.unavailable }
+                        : titleFieldFor(schemaByEntryType.get(`${item.logicalPath}\0${et.name}`) ?? et.schema)),
                 }));
                 results.push({
                     path: item.logicalPath,

package/dist/editor/editor-utils.d.ts

@@ -17,6 +17,20 @@ type PreviewEntry = {
     itemType?: string;
     previewSrc?: string;
 };
+/**
+ * The entry's route on the host site, or `undefined` when it has no page. The first
+ * `previewBaseByCollection` key present decides: for a root entry its own path
+ * (`<contentRoot>/<slug>`, used as-is), then its collection path, then its collection name (both
+ * with the slug appended). The spelling `<parent>/<name>` names both an entry and a same-named
+ * sibling collection (a landing entry beside its folder), so below the root it is read only as a
+ * collection key, and at the root one key routes both.
+ * A `false` value means no page. With no key, the route is the entry's `urlPath`, by the rule
+ * `listEntries` publishes it, so a root entry previews at `/<slug>` and only a root index at `/`.
+ * Site-relative unless a matching value is absolute.
+ */
+export declare const buildPreviewRoute: (entry: PreviewEntry, { previewBaseByCollection, contentRoot }: PreviewContext & {
+    contentRoot?: string;
+}) => string | undefined;
 /**
  * Builds the preview iframe `src` for an entry: its route under `previewPrefix`, under the
  * deployment `basePath` (`CanopyClientConfig.basePath`, e.g. `/preview-123`), in the host's
@@ -24,8 +38,8 @@ type PreviewEntry = {
  * (from `previewBaseByCollection`) skips all three and gets only `?branch=`. An entry's own
  * `previewSrc` gets only the `basePath`.
  *
- * The result must equal the framed page's own URL: the `<iframe src>` (`PreviewFrame` in
- * preview-bridge.tsx) 404s without the prefixes, and a URL the host redirects costs a round trip
+ * The result must equal the framed page's own URL: the `<iframe src>` (`PreviewFrame.tsx`)
+ * 404s without the prefixes, and a URL the host redirects costs a round trip
  * on every load. `trailingSlash` defaults to the value `withCanopy` inlines at build time.
  *
  * `undefined` means the entry has no page, so the editor frames nothing rather than another page.
@@ -49,13 +63,25 @@ interface BuildEntriesFromListParams {
 export declare const buildEntriesFromListResponse: ({ response, resolvePreviewSrc, flatSchema, }: BuildEntriesFromListParams) => EditorEntry[];
 export declare const buildCollectionLabels: (collections?: EditorCollection[]) => Map<string, string>;
 /**
- * Builds breadcrumb segments for an entry based on its collection hierarchy.
- *
- * @param currentEntry - The entry to build breadcrumbs for (or undefined for root)
- * @param collectionLabels - Map of collection IDs to labels
- * @returns Array of breadcrumb segment strings, starting with 'All Files'
+ * An entry's type as its collection labels it, else its name read as words; undefined when
+ * untyped.
+ */
+export declare const entryTypeLabel: (collections: EditorCollection[] | undefined, entry: Pick<EditorEntry, "collectionPath" | "entryType">) => string | undefined;
+/** An entry's navigator badge: "Missing" when its file is gone, else its type's label or name. */
+export declare const entryStatusLabel: (collections: EditorCollection[] | undefined, entry: Pick<EditorEntry, "status" | "collectionPath" | "entryType">) => string | undefined;
+/** One crumb before the entry's own: "All content", a collection, or a folder of a nested slug. */
+export interface BreadcrumbSegment {
+    label: string;
+    /** The collection the crumb opens in the content panel; absent on "All content" and slug folders. */
+    collectionPath?: string;
+    /** A slug folder, which is not a node of the content tree, so it navigates nowhere. */
+    folder?: true;
+}
+/**
+ * Builds breadcrumb segments for an entry based on its collection hierarchy, starting with
+ * "All content". The first path part is skipped as the content root, which the tree does not show.
  */
-export declare const buildBreadcrumbSegments: (currentEntry: EditorEntry | undefined, collectionLabels: Map<string, string>) => string[];
+export declare const buildBreadcrumbSegments: (currentEntry: EditorEntry | undefined, collectionLabels: Map<string, string>) => BreadcrumbSegment[];
 /**
  * Calculates which collection nodes need to be expanded to show the path to a specific entry.
  * Recursively walks the tree to find the target entry and marks all ancestor collections as expanded.

package/dist/editor/editor-utils.js

@@ -1,5 +1,6 @@
 // Import directly from normalize to avoid pulling in server-only branch.ts
 import { normalizeFilesystemPath } from '../paths/normalize.js';
+import { humanizeName } from './schema-label.js';
 import { computeEntryUrl, isIndexSlug } from '../utils/entry-url.js';
 import { isDataOnlyFormat } from '../utils/format.js';
 import { isAbsoluteUrl, joinUrlPrefix, matchTrailingSlash, readTrailingSlashEnv, stripTrailingSlashes, } from '../utils/url-prefix.js';
@@ -47,7 +48,7 @@ const previewBaseFor = (bases, key) => bases && key && Object.prototype.hasOwnPr
  * `listEntries` publishes it, so a root entry previews at `/<slug>` and only a root index at `/`.
  * Site-relative unless a matching value is absolute.
  */
-const buildPreviewRoute = (entry, { previewBaseByCollection, contentRoot = 'content' }) => {
+export const buildPreviewRoute = (entry, { previewBaseByCollection, contentRoot = 'content' }) => {
     const collectionPath = normalizeFilesystemPath(entry.collectionPath ?? '');
     const isRootEntry = collectionPath === normalizeFilesystemPath(contentRoot);
     const entryRoute = previewBaseFor(previewBaseByCollection, isRootEntry && entry.slug ? `${collectionPath}/${entry.slug}` : undefined);
@@ -73,8 +74,8 @@ const buildPreviewRoute = (entry, { previewBaseByCollection, contentRoot = 'cont
  * (from `previewBaseByCollection`) skips all three and gets only `?branch=`. An entry's own
  * `previewSrc` gets only the `basePath`.
  *
- * The result must equal the framed page's own URL: the `<iframe src>` (`PreviewFrame` in
- * preview-bridge.tsx) 404s without the prefixes, and a URL the host redirects costs a round trip
+ * The result must equal the framed page's own URL: the `<iframe src>` (`PreviewFrame.tsx`)
+ * 404s without the prefixes, and a URL the host redirects costs a round trip
  * on every load. `trailingSlash` defaults to the value `withCanopy` inlines at build time.
  *
  * `undefined` means the entry has no page, so the editor frames nothing rather than another page.
@@ -132,12 +133,14 @@ export const buildEntriesFromListResponse = ({ response, resolvePreviewSrc, flat
     return response.entries.map((entry) => {
         // Resolve schema from flatSchema using parentPath + name
         let schema = [];
+        let unavailable;
         if (entry.collectionPath && entry.entryType) {
             const entryTypeItem = flatSchema.find((item) => item.type === 'entry-type' &&
                 item.parentPath === entry.collectionPath &&
                 item.name === entry.entryType);
             if (entryTypeItem && entryTypeItem.type === 'entry-type') {
                 schema = entryTypeItem.schema;
+                unavailable = entryTypeItem.unavailable;
             }
         }
         return {
@@ -154,6 +157,7 @@ export const buildEntriesFromListResponse = ({ response, resolvePreviewSrc, flat
             entryType: entry.entryType,
             type: 'entry',
             canEdit: entry.canEdit,
+            ...(unavailable && { unavailable }),
         };
     });
 };
@@ -173,34 +177,52 @@ export const buildCollectionLabels = (collections) => {
     return map;
 };
 /**
- * Builds breadcrumb segments for an entry based on its collection hierarchy.
- *
- * @param currentEntry - The entry to build breadcrumbs for (or undefined for root)
- * @param collectionLabels - Map of collection IDs to labels
- * @returns Array of breadcrumb segment strings, starting with 'All Files'
+ * An entry's type as its collection labels it, else its name read as words; undefined when
+ * untyped.
+ */
+export const entryTypeLabel = (collections, entry) => {
+    if (!entry.entryType)
+        return undefined;
+    const find = (nodes) => {
+        for (const c of nodes) {
+            if (c.path === entry.collectionPath)
+                return c;
+            const inner = c.children ? find(c.children) : undefined;
+            if (inner)
+                return inner;
+        }
+        return undefined;
+    };
+    const collection = collections ? find(collections) : undefined;
+    const type = collection?.entryTypes?.find((t) => t.name === entry.entryType);
+    return type?.label ?? humanizeName(entry.entryType);
+};
+/** An entry's navigator badge: "Missing" when its file is gone, else its type's label or name. */
+export const entryStatusLabel = (collections, entry) => {
+    if (entry.status === 'missing')
+        return 'Missing';
+    return entryTypeLabel(collections, entry) ?? (entry.status && humanizeName(entry.status));
+};
+/**
+ * Builds breadcrumb segments for an entry based on its collection hierarchy, starting with
+ * "All content". The first path part is skipped as the content root, which the tree does not show.
  */
 export const buildBreadcrumbSegments = (currentEntry, collectionLabels) => {
+    const segments = [{ label: 'All content' }];
     if (!currentEntry)
-        return ['All Files'];
-    const segments = ['All Files'];
-    // Show collection hierarchy for entries that belong to a collection
+        return segments;
     if (currentEntry.collectionPath) {
-        // Split the collectionPath into path parts and build cumulative paths
-        // e.g., "content/documentation/guides" -> ["content/documentation", "content/documentation/guides"]
         const parts = currentEntry.collectionPath.split('/').filter(Boolean);
         for (let i = 1; i < parts.length; i++) {
             const pathUpToHere = parts.slice(0, i + 1).join('/');
             const label = collectionLabels.get(pathUpToHere);
-            if (label) {
-                segments.push(label);
-            }
+            if (label)
+                segments.push({ label, collectionPath: pathUpToHere });
         }
     }
-    // Add slug path segments (for nested slugs like "folder/file")
     const slugSegments = (currentEntry.slug ?? '').split('/').filter(Boolean);
-    if (slugSegments.length > 1) {
-        segments.push(...slugSegments.slice(0, -1));
-    }
+    for (const folder of slugSegments.slice(0, -1))
+        segments.push({ label: folder, folder: true });
     return segments;
 };
 /**

package/dist/editor/entry-search.d.ts

@@ -0,0 +1,20 @@
+/** Entry search shared by the navigator filter and the quick-open palette. */
+export interface SearchableEntry {
+    label: string;
+    slug?: string;
+    collectionPath?: string;
+    collectionName?: string;
+}
+/** Case-insensitive substring match over label and slug; an empty query matches everything. */
+export declare function matchesEntryQuery(entry: Pick<SearchableEntry, 'label' | 'slug'>, query: string): boolean;
+export declare function filterEntries<T extends SearchableEntry>(entries: readonly T[], query: string): T[];
+export interface EntryGroup<T> {
+    heading: string;
+    entries: T[];
+}
+/**
+ * Groups entries by collection, in first-seen order, each under its display heading:
+ * `labelFor(collectionPath)`, else the collection name or path, else `Root`. Two collections
+ * that share a heading stay separate groups.
+ */
+export declare function groupEntriesByCollection<T extends SearchableEntry>(entries: readonly T[], labelFor?: (collectionPath: string) => string | undefined): EntryGroup<T>[];

package/dist/editor/entry-search.js

@@ -0,0 +1,34 @@
+/** Entry search shared by the navigator filter and the quick-open palette. */
+/** Case-insensitive substring match over label and slug; an empty query matches everything. */
+export function matchesEntryQuery(entry, query) {
+    const needle = query.trim().toLowerCase();
+    if (!needle)
+        return true;
+    return (entry.label.toLowerCase().includes(needle) ||
+        (entry.slug?.toLowerCase().includes(needle) ?? false));
+}
+export function filterEntries(entries, query) {
+    return entries.filter((entry) => matchesEntryQuery(entry, query));
+}
+/**
+ * Groups entries by collection, in first-seen order, each under its display heading:
+ * `labelFor(collectionPath)`, else the collection name or path, else `Root`. Two collections
+ * that share a heading stay separate groups.
+ */
+export function groupEntriesByCollection(entries, labelFor) {
+    const groups = new Map();
+    for (const entry of entries) {
+        const key = entry.collectionPath ?? entry.collectionName ?? '';
+        const group = groups.get(key);
+        if (group) {
+            group.entries.push(entry);
+            continue;
+        }
+        const heading = (entry.collectionPath ? labelFor?.(entry.collectionPath) : undefined) ??
+            entry.collectionName ??
+            entry.collectionPath ??
+            'Root';
+        groups.set(key, { heading, entries: [entry] });
+    }
+    return [...groups.values()];
+}

package/dist/editor/field-breadcrumb.d.ts

@@ -0,0 +1,12 @@
+import type { FieldConfig } from '../config/index.js';
+/**
+ * The human labels along a canopy path, for messages: `blocks[0].title` reads
+ * `['Page sections', 'Hero', 'Heading']`. A block is named by its template's label and an
+ * object-list item by its title (`listItemHeading`); a segment the schema doesn't know keeps its
+ * raw name, so a stale path still reads. A block whose template isn't known (no `value`, or an
+ * item that is gone) has its fields looked up in every template. `items: false` leaves the item
+ * crumbs out, for a path whose indexes no longer say which item it was.
+ */
+export declare const fieldBreadcrumb: (fields: readonly FieldConfig[], value: unknown, path: string, { items }?: {
+    items?: boolean;
+}) => string[];

package/dist/editor/field-breadcrumb.js

@@ -0,0 +1,85 @@
+import { isPlainRecord } from '../validation/field-traversal.js';
+import { parseCanopyPath } from './canopy-path.js';
+import { listItemHeading } from './fields/list-item-title.js';
+import { schemaLabel } from './schema-label.js';
+/** Labels for an image field's parts, which `ImageField` reports errors on. */
+const IMAGE_PART_LABELS = new Map([
+    ['src', 'File'],
+    ['alt', 'Alt text'],
+    ['crop', 'Crop'],
+    ['width', 'Width'],
+    ['height', 'Height'],
+]);
+/** The field named `name` in `fields`, looking inside inline groups, which add no path segment. */
+const findField = (fields, name) => {
+    for (const field of fields) {
+        if (field.type === 'group' && 'fields' in field) {
+            const inner = findField(field.fields, name);
+            if (inner)
+                return inner;
+        }
+        else if (field.name === name) {
+            return field;
+        }
+    }
+    return undefined;
+};
+/**
+ * The human labels along a canopy path, for messages: `blocks[0].title` reads
+ * `['Page sections', 'Hero', 'Heading']`. A block is named by its template's label and an
+ * object-list item by its title (`listItemHeading`); a segment the schema doesn't know keeps its
+ * raw name, so a stale path still reads. A block whose template isn't known (no `value`, or an
+ * item that is gone) has its fields looked up in every template. `items: false` leaves the item
+ * crumbs out, for a path whose indexes no longer say which item it was.
+ */
+export const fieldBreadcrumb = (fields, value, path, { items = true } = {}) => {
+    const crumbs = [];
+    let scope = fields;
+    let current = value;
+    let field;
+    for (const segment of parseCanopyPath(path)) {
+        if (typeof segment === 'number') {
+            const item = Array.isArray(current) ? current[segment] : undefined;
+            if (field?.type === 'block') {
+                const block = isPlainRecord(item) ? item : {};
+                const templateName = typeof block.template === 'string' ? block.template : undefined;
+                const templates = field.templates;
+                const template = templates.find((t) => t.name === templateName);
+                if (items)
+                    crumbs.push(template ? schemaLabel(template) : (templateName ?? `Item ${segment + 1}`));
+                scope = template ? template.fields : templates.flatMap((t) => t.fields);
+                current = block.value;
+            }
+            else if (field?.type === 'object') {
+                const objectField = field;
+                if (items)
+                    crumbs.push(listItemHeading(item, objectField, segment));
+                scope = objectField.fields;
+                current = item;
+            }
+            else {
+                if (items)
+                    crumbs.push(`Item ${segment + 1}`);
+                scope = undefined;
+                current = item;
+            }
+            field = undefined;
+            continue;
+        }
+        const imagePart = field?.type === 'image' ? IMAGE_PART_LABELS.get(segment) : undefined;
+        if (imagePart) {
+            crumbs.push(imagePart);
+            field = undefined;
+            scope = undefined;
+            current = undefined;
+            continue;
+        }
+        const found = scope ? findField(scope, segment) : undefined;
+        crumbs.push(found ? schemaLabel(found) : segment);
+        current = isPlainRecord(current) ? current[segment] : undefined;
+        field = found;
+        scope =
+            found?.type === 'object' && !found.list ? found.fields : undefined;
+    }
+    return crumbs;
+};

package/dist/editor/field-props.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Preview field marks, typed against the view's content. Exported from the root `canopycms`,
+ * not `canopycms/preview`: that module is `'use client'`, and a server component calling its
+ * functions gets a client reference that throws. A public page passes `fieldProps` as
+ * `undefined`, never a no-op function, which Next refuses to pass from server to client.
+ */
+import type { ResolvedReferenceMeta } from '../entry-schema.js';
+import { type CanopyPathSegment } from './canopy-path.js';
+export type FieldAttrs = {
+    'data-canopy-path'?: string;
+};
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type IsDigits<S extends string> = S extends `${Digit}${infer Rest}` ? Rest extends '' ? true : IsDigits<Rest> : false;
+/** A template literal's `${number}` hole: a computed path, so untyped. */
+type TemplateHole = {
+    readonly templateHole: true;
+};
+type ParseSegment<S extends string> = IsDigits<S> extends true ? number : `${number}` extends S ? TemplateHole : S;
+type ParseBrackets<S extends string> = S extends `${infer Key}[${infer Index}]${infer Rest}` ? [...(Key extends '' ? [] : [ParseSegment<Key>]), ParseSegment<Index>, ...ParseBrackets<Rest>] : S extends '' ? [] : [ParseSegment<S>];
+/** As `parseCanopyPath`: `'blocks.0.title'` → `['blocks', number, 'title']`. */
+type ParsePath<S extends string> = S extends `${infer Head}.${infer Rest}` ? [...ParseBrackets<Head>, ...ParsePath<Rest>] : ParseBrackets<S>;
+type ImageKeys = 'src' | 'alt' | 'width' | 'height' | 'crop';
+/** A value the form edits as one field: a scalar, a reference in any state, an image. */
+type IsLeaf<V> = V extends string | number | boolean | bigint | symbol ? true : V extends {
+    unavailable: true;
+} | ResolvedReferenceMeta ? true : V extends {
+    src: string;
+    alt: string;
+} ? [Exclude<keyof V, ImageKeys>] extends [never] ? true : false : false;
+/**
+ * A block item's fields are its template's, under `value`; the form's paths skip `value`. Its
+ * `_key` (`ITEM_KEY`, item-keys.ts) is structure, not a field.
+ */
+type ListItem<E> = E extends {
+    template: string;
+    value: infer W;
+} ? [Exclude<keyof E, 'template' | 'value' | '_key'>] extends [never] ? W : E : E;
+type NextSegment<V> = unknown extends V ? CanopyPathSegment : V extends unknown ? IsLeaf<V> extends true ? never : V extends readonly unknown[] ? number : V extends object ? Exclude<keyof V & string, '_key'> : never : never;
+type Child<V, S> = unknown extends V ? unknown : V extends unknown ? V extends readonly (infer E)[] ? S extends number ? Defined<ListItem<Defined<E>>> : never : IsLeaf<V> extends true ? never : S extends keyof V ? Defined<V[S]> : never : never;
+type ValueAt<V, P> = P extends readonly [infer Head, ...infer Rest] ? ValueAt<Child<V, Head>, Rest> : V;
+type IsFieldPath<V, P> = P extends readonly [infer Head, ...infer Rest] ? Head extends NextSegment<V> ? IsFieldPath<Child<V, Head>, Rest> : false : true;
+/** The path with the allowed segments at its first wrong one, for the compile error. */
+type ExpectedSegments<V, P> = P extends readonly [infer Head, ...infer Rest] ? Head extends NextSegment<V> ? readonly [Head, ...ExpectedSegments<Child<V, Head>, Rest>] : readonly [NextSegment<V>, ...CanopyPathSegment[]] : readonly [];
+type SegmentsArg<V, P extends readonly unknown[]> = unknown extends V ? P : number extends P['length'] ? ComputedPathError : IsFieldPath<V, P> extends true ? P : ExpectedSegments<V, P>;
+type Spell<P> = P extends readonly [infer Head, ...infer Rest] ? `${Head extends number ? `[${Head}]` : `.${Head & string}`}${Spell<Rest>}` : '';
+type TrimDot<S extends string> = S extends `.${infer Rest}` ? Rest : S;
+/** The paths one step past `P`'s last valid prefix, for the compile error. */
+type Completions<V, P, Done extends readonly CanopyPathSegment[] = []> = P extends readonly [
+    infer Head,
+    ...infer Rest
+] ? Head extends NextSegment<V> ? Completions<Child<V, Head>, Rest, [...Done, Head]> : [NextSegment<V>] extends [never] ? TrimDot<Spell<Done>> : TrimDot<Spell<[...Done, NextSegment<V>]>> : never;
+type ComputedPathError = 'a computed path is untyped: pass segments as a literal, e.g. ["list", i, "field"]';
+type StringArg<V, S extends string> = unknown extends V ? S : string extends S ? ComputedPathError : TemplateHole extends ParsePath<S>[number] ? ComputedPathError : IsFieldPath<V, ParsePath<S>> extends true ? S : Completions<V, ParsePath<S>>;
+/** `NonNullable<unknown>` is `{}`, which would make untyped content typed. */
+type Defined<T> = unknown extends T ? unknown : NonNullable<T>;
+declare const fieldPropsContent: unique symbol;
+/**
+ * Marks the element rendering a field: `<h1 {...fieldProps('title')}>`. A path is a string
+ * literal or literal segments (`['blocks', i, 'title']`, for anything computed), checked against `T`
+ * the way the form names fields: a block's fields follow its index (no `.value`), and nothing
+ * is below a reference or image. Any template's fields compile after a block's index; the
+ * editor warns about the rest. `FieldProps` alone (`T = unknown`) takes any path.
+ */
+export type FieldProps<T = unknown> = FieldPropsCall<Defined<T>> & {
+    /** Bivariant, so any typed `FieldProps` still assigns to plain `FieldProps`. */
+    readonly [fieldPropsContent]?: {
+        bivariant(content: T): void;
+    }['bivariant'];
+};
+interface FieldPropsCall<V> {
+    <const S extends string>(path: StringArg<V, S>): FieldAttrs;
+    <const P extends readonly CanopyPathSegment[]>(path: SegmentsArg<V, P>): FieldAttrs;
+}
+/** An empty path marks nothing. @internal `useCanopyPreview` is its only caller. */
+export declare const createFieldProps: <T>() => FieldProps<T>;
+/** `fieldProps(path)`, or nothing on a public page; `[]` marks the field a caller scoped to. */
+export declare function fieldAttrs<T, const S extends string>(fieldProps: FieldProps<T> | undefined, path: StringArg<Defined<T>, S>): FieldAttrs;
+export declare function fieldAttrs<T, const P extends readonly CanopyPathSegment[]>(fieldProps: FieldProps<T> | undefined, path: SegmentsArg<Defined<T>, P>): FieldAttrs;
+/**
+ * `fieldProps` for a component rendering part of the entry, which marks paths relative to it
+ * while its caller names the part: `scopeFieldProps(fieldProps, ['sections', i])`. `undefined`
+ * in, `undefined` out, so a public page never builds a function.
+ */
+export declare function scopeFieldProps<T, const S extends string>(fieldProps: FieldProps<T> | undefined, prefix: StringArg<Defined<T>, S>): FieldProps<ValueAt<Defined<T>, ParsePath<S>>> | undefined;
+export declare function scopeFieldProps<T, const P extends readonly CanopyPathSegment[]>(fieldProps: FieldProps<T> | undefined, prefix: SegmentsArg<Defined<T>, P>): FieldProps<ValueAt<Defined<T>, P>> | undefined;
+export {};

package/dist/editor/field-props.js

@@ -0,0 +1,27 @@
+/**
+ * Preview field marks, typed against the view's content. Exported from the root `canopycms`,
+ * not `canopycms/preview`: that module is `'use client'`, and a server component calling its
+ * functions gets a client reference that throws. A public page passes `fieldProps` as
+ * `undefined`, never a no-op function, which Next refuses to pass from server to client.
+ */
+import { normalizeCanopyPath } from './canopy-path.js';
+const markField = (path) => {
+    const normalized = normalizeCanopyPath(path);
+    return normalized ? { 'data-canopy-path': normalized } : {};
+};
+/** An empty path marks nothing. @internal `useCanopyPreview` is its only caller. */
+export const createFieldProps = () => markField;
+export function fieldAttrs(fieldProps, path) {
+    return fieldProps ? fieldProps(path) : {};
+}
+export function scopeFieldProps(fieldProps, prefix) {
+    if (!fieldProps)
+        return undefined;
+    const base = normalizeCanopyPath(prefix);
+    return (path) => {
+        const relative = normalizeCanopyPath(path);
+        if (!relative)
+            return fieldProps(base);
+        return fieldProps(relative.startsWith('[') ? `${base}${relative}` : `${base}.${relative}`);
+    };
+}

package/dist/editor/field-target.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The form element for a path, as given or as `canopy-path.ts` spells it (`blocks.2.title` is
+ * `blocks[2].title`), else for its nearest ancestor that has one: a list item (`tags[1]`) has no
+ * field of its own. Compares values, not a selector: the path is untrusted.
+ */
+export declare const findFieldTarget: (path: string, root?: ParentNode) => {
+    element: HTMLElement;
+    path: string;
+} | undefined;
+/** Dispatched from a form element to open every collapsed list row holding it (`ItemList`). */
+export declare const REVEAL_FIELD_EVENT = "canopy:reveal-field";
+/**
+ * Asks every collapsed row holding `element` to open. True when one was closed: its content shows
+ * once React re-renders, so act on the element through `whenRevealed`. @internal Exported for
+ * tests; callers use `whenRevealed`.
+ */
+export declare const revealField: (element: HTMLElement) => boolean;
+/**
+ * Runs `then` once `element` is shown: at once, or a few frames on when a row had to open. It asks
+ * again each frame, since a row mounted in the same commit as the element may not listen yet.
+ */
+export declare const whenRevealed: (element: HTMLElement, then: () => void) => void;
+/**
+ * Scrolls a field's element into view and focuses what a person would type into: the element
+ * itself when it is an input, else its first focusable input, else its first other focusable
+ * control that is not a comment control, else the element when it takes programmatic focus.
+ * An input out of the tab order or not rendered, such as a dropzone's file input, is never chosen.
+ * Collapsed list rows holding the element open first.
+ */
+export declare const focusFieldTarget: (element: HTMLElement) => void;

package/dist/editor/field-target.js

@@ -0,0 +1,77 @@
+import { formatCanopyPath, parseCanopyPath } from './canopy-path.js';
+/**
+ * The form element for a path, as given or as `canopy-path.ts` spells it (`blocks.2.title` is
+ * `blocks[2].title`), else for its nearest ancestor that has one: a list item (`tags[1]`) has no
+ * field of its own. Compares values, not a selector: the path is untrusted.
+ */
+export const findFieldTarget = (path, root = document) => {
+    const byField = new Map();
+    for (const element of root.querySelectorAll('[data-canopy-field]')) {
+        const field = element.getAttribute('data-canopy-field');
+        if (field && !byField.has(field))
+            byField.set(field, element);
+    }
+    const exact = byField.get(path);
+    if (exact)
+        return { element: exact, path };
+    const segments = parseCanopyPath(path);
+    for (let length = segments.length; length > 0; length--) {
+        const candidate = formatCanopyPath(segments.slice(0, length));
+        const element = byField.get(candidate);
+        if (element)
+            return { element, path: candidate };
+    }
+    return undefined;
+};
+/** Dispatched from a form element to open every collapsed list row holding it (`ItemList`). */
+export const REVEAL_FIELD_EVENT = 'canopy:reveal-field';
+/**
+ * Asks every collapsed row holding `element` to open. True when one was closed: its content shows
+ * once React re-renders, so act on the element through `whenRevealed`. @internal Exported for
+ * tests; callers use `whenRevealed`.
+ */
+export const revealField = (element) => !element.dispatchEvent(new CustomEvent(REVEAL_FIELD_EVENT, { bubbles: true, cancelable: true }));
+const MAX_REVEAL_FRAMES = 10;
+/**
+ * Runs `then` once `element` is shown: at once, or a few frames on when a row had to open. It asks
+ * again each frame, since a row mounted in the same commit as the element may not listen yet.
+ */
+export const whenRevealed = (element, then) => {
+    const shown = () => typeof element.checkVisibility !== 'function' || element.checkVisibility();
+    if (!revealField(element) && shown()) {
+        then();
+        return;
+    }
+    let frames = 0;
+    const check = () => {
+        frames += 1;
+        if (shown() || frames >= MAX_REVEAL_FRAMES) {
+            then();
+            return;
+        }
+        revealField(element);
+        requestAnimationFrame(check);
+    };
+    requestAnimationFrame(check);
+};
+const EDITABLE = 'input:not([type="hidden"]), textarea, select, [contenteditable="true"]';
+const FOCUSABLE = 'button, [href], [tabindex]';
+/** Takes keyboard focus as it stands: enabled, in the tab order, and rendered. */
+const canTakeFocus = (el) => !el.matches(':disabled, [tabindex="-1"]') &&
+    (typeof el.checkVisibility !== 'function' || el.checkVisibility({ visibilityProperty: true }));
+/**
+ * Scrolls a field's element into view and focuses what a person would type into: the element
+ * itself when it is an input, else its first focusable input, else its first other focusable
+ * control that is not a comment control, else the element when it takes programmatic focus.
+ * An input out of the tab order or not rendered, such as a dropzone's file input, is never chosen.
+ * Collapsed list rows holding the element open first.
+ */
+export const focusFieldTarget = (element) => whenRevealed(element, () => focusShownField(element));
+const focusShownField = (element) => {
+    element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    const inputs = [element, ...element.querySelectorAll(EDITABLE)].filter((el) => el.matches(EDITABLE) && canTakeFocus(el));
+    // The element itself counts: a date field's target is its picker's trigger button.
+    const controls = [element, ...element.querySelectorAll(FOCUSABLE)].filter((el) => el.matches(FOCUSABLE) && canTakeFocus(el) && !el.closest('[data-comment-control]'));
+    const focusable = inputs[0] ?? controls[0] ?? (element.hasAttribute('tabindex') ? element : undefined);
+    focusable?.focus({ preventScroll: true });
+};

package/dist/editor/fields/BlockField.d.ts

@@ -1,12 +1,16 @@
 import React from 'react';
 import type { BlockConfig, FieldConfig } from '../../config/index.js';
+import { ITEM_KEY } from '../../item-keys.js';
 export interface BlockInstance {
     template: string;
     value: Record<string, unknown>;
+    /** The block's key (`item-keys.ts`). */
+    [ITEM_KEY]?: string;
 }
 type RenderField = (field: FieldConfig, value: unknown, onChange: (v: unknown) => void, path: Array<string | number>) => React.ReactNode;
 export interface BlockFieldProps {
     label?: string;
+    required?: boolean;
     description?: string;
     templates: BlockConfig[];
     value: BlockInstance[];
@@ -14,6 +18,14 @@ export interface BlockFieldProps {
     renderField: RenderField;
     path: Array<string | number>;
     dataCanopyField?: string;
+    /** No add, remove, reorder or drag; rows still collapse. */
+    readOnly?: boolean;
+    /** Names the entry being edited; another entry starts with the default rows open. */
+    resetKey?: string;
+    /** True when a field inside block `index` has a validation error. */
+    hasErrors?: (index: number) => boolean;
+    /** Told of each block Remove takes out, so the caller can offer Undo. */
+    onRemoved?: (index: number, block: BlockInstance) => void;
 }
 export declare const BlockField: React.FC<BlockFieldProps>;
 export {};