canopycms 0.11.1 → 0.12.1

package/dist/editor/hooks/useDraftManager.js

@@ -187,12 +187,19 @@ export function useDraftManager(options) {
     //
     // 3. The comparison is `fast-deep-equal`, so key insertion order of a
     //    rehydrated draft does not make it dirty.
-    const dirtyIds = useMemo(() => Object.keys(drafts).filter((id) => {
-        if (entriesKnown && !entryById.has(id))
-            return false;
-        const baseline = loadedValues[id] ?? verifiedBaselines[id];
-        return baseline === undefined || !equal(drafts[id], baseline);
-    }), [drafts, loadedValues, verifiedBaselines, entriesKnown, entryById]);
+    //
+    // 4. An entry with a conflict choice to send counts, draft or not (`pendingIds`).
+    const pendingIds = options.pendingIds;
+    const dirtyIds = useMemo(() => {
+        const dirty = Object.keys(drafts).filter((id) => {
+            if (entriesKnown && !entryById.has(id))
+                return false;
+            const baseline = loadedValues[id] ?? verifiedBaselines[id];
+            return baseline === undefined || !equal(drafts[id], baseline);
+        });
+        const pending = [...(pendingIds ?? [])].filter((id) => !dirty.includes(id) && (!entriesKnown || entryById.has(id)));
+        return pending.length > 0 ? [...dirty, ...pending] : dirty;
+    }, [drafts, loadedValues, verifiedBaselines, entriesKnown, entryById, pendingIds]);
     const modifiedCount = dirtyIds.length;
     const editedFiles = useMemo(() => dirtyIds
         .map((id) => {
@@ -963,7 +970,10 @@ export function useDraftManager(options) {
      */
     const saveOneOfAll = async (entry, branch) => {
         const id = entry.contentId;
-        const sent = latestRef.current.drafts[id];
+        const sent = latestRef.current.drafts[id] ??
+            (latestOptionsRef.current.pendingIds?.has(id)
+                ? latestRef.current.loadedValues[id]
+                : undefined);
         if (sent === undefined)
             return undefined;
         const onBranch = () => latestOptionsRef.current.branchName === branch;
@@ -1137,7 +1147,9 @@ export function useDraftManager(options) {
             // Discarded, refreshed or saved mid-run, so neither saved nor failed by this run.
             const { drafts: remaining } = latestRef.current;
             const settled = settledDuringRunRef.current;
-            result.failed = result.failed.filter((failure) => failure.contentId in remaining && !settled.has(failure.contentId));
+            const pendingNow = latestOptionsRef.current.pendingIds;
+            result.failed = result.failed.filter((failure) => (failure.contentId in remaining || !!pendingNow?.has(failure.contentId)) &&
+                !settled.has(failure.contentId));
             result.total = result.saved.length + result.failed.length;
             if (result.saved.length > 0)
                 latestOptionsRef.current.onSaved?.();
@@ -1351,6 +1363,8 @@ export function useDraftManager(options) {
         if (!entry)
             return false;
         const id = entry.contentId;
+        if (pendingIds?.has(id))
+            return true;
         if (!drafts[id])
             return false;
         const baseline = loadedValues[id] ?? verifiedBaselines[id];
@@ -1359,6 +1373,8 @@ export function useDraftManager(options) {
     const isSelectedDirty = () => {
         if (!currentId)
             return false;
+        if (pendingIds?.has(currentId))
+            return true;
         if (!drafts[currentId])
             return false;
         return !loadedValues[currentId] || !equal(drafts[currentId], loadedValues[currentId]);

package/dist/editor/hooks/useEntryManager.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedFieldConflict } from '../../merge-conflicts.js';
 import type { ApiErrorCode } from '../../api/types.js';
 import type { EditorEntry, EditorCollection } from '../Editor.js';
 import type { LogicalPath } from '../../paths/types.js';
@@ -62,6 +63,14 @@ export interface UseEntryManagerOptions {
      * refreshes the entries, so what reads the same branch state reloads here.
      */
     onContentRefresh?: (branch: string) => void;
+    /**
+     * The conflicts a save of an entry resolves (useConflictChoices.ts): `pending` names them as the
+     * save sends them, and `onSaved` hears which the save sent and which the server cleared.
+     */
+    conflictResolutions?: {
+        pending: (branch: string, contentId: string) => ResolvedFieldConflict[];
+        onSaved: (branch: string, contentId: string, sent: ResolvedFieldConflict[], cleared: ResolvedFieldConflict[]) => void;
+    };
 }
 export interface UseEntryManagerReturn {
     selectedPath: string;

package/dist/editor/hooks/useEntryManager.js

@@ -339,15 +339,20 @@ export function useEntryManager(options) {
         if (expectedVersion === undefined) {
             throw new SaveApiError(409, "This entry hasn't finished loading, so it can't be saved yet. Reload it and try again (your unsaved edits will be lost).");
         }
+        const resolving = options.conflictResolutions?.pending(requestBranch, entry.contentId) ?? [];
         const writeBody = {
             ...payload,
             expectedVersion,
+            ...(resolving.length > 0 && { resolvedConflicts: resolving }),
         };
         const result = await apiClient.content.write(writeParams, writeBody);
         if (isGatewayFailure(result))
             throw new UnansweredError();
         if (!result.ok)
             throw new SaveApiError(result.status, result.error, result.fieldErrors, result.code);
+        if (resolving.length > 0) {
+            options.conflictResolutions?.onSaved(requestBranch, entry.contentId, resolving, result.data?.resolvedConflicts ?? []);
+        }
         // Update stored version token from write response
         if (typeof result.data?.version === 'number') {
             entryVersionsRef.current.set(versionKey(requestBranch, entry.contentId), result.data.version);

package/dist/editor/release-hold.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An admin's release of a branch held as its record of conflicts was set aside
+ * (api/merge-conflicts.ts `releaseHold`). An unanswered request is settled by reading the record
+ * again, as the release may have landed.
+ */
+import type { ApiClient } from './context/index.js';
+import type { ReleaseOutcome } from './components/ReleaseHoldButton.js';
+/** A release's outcome, and on release whether it found the branch held, when that is known. */
+export type ReleaseResult = ReleaseOutcome & {
+    wasHeld?: boolean;
+};
+export declare function releaseConflictsHold(apiClient: Pick<ApiClient, 'conflicts'>, branch: string): Promise<ReleaseResult>;

package/dist/editor/release-hold.js

@@ -0,0 +1,39 @@
+/**
+ * An admin's release of a branch held as its record of conflicts was set aside
+ * (api/merge-conflicts.ts `releaseHold`). An unanswered request is settled by reading the record
+ * again, as the release may have landed.
+ */
+import { isGatewayFailure, isUnanswered } from './unanswered.js';
+import { getErrorMessage } from '../utils/error.js';
+const UNKNOWN = {
+    error: "The release may have gone through even though the server didn't answer. Reload the page to see whether the branch is still on hold.",
+    tone: 'warning',
+};
+const STILL_HELD = {
+    error: "The server didn't answer, and the branch is still on hold. Try again in a moment.",
+    tone: 'warning',
+};
+export async function releaseConflictsHold(apiClient, branch) {
+    const settle = async () => {
+        const now = await apiClient.conflicts.list({ branch }).catch(() => undefined);
+        if (!now?.ok || !now.data)
+            return UNKNOWN;
+        // Not held now, but this read can't say whose release that was.
+        return now.data.held ? STILL_HELD : { released: true };
+    };
+    let result;
+    try {
+        result = await apiClient.conflicts.releaseHold({ branch });
+    }
+    catch (err) {
+        return isUnanswered(err) ? settle() : { error: getErrorMessage(err), tone: 'error' };
+    }
+    if (result.ok)
+        return { released: true, wasHeld: result.data?.released !== false };
+    if (isGatewayFailure(result))
+        return settle();
+    return {
+        error: result.error ?? "Couldn't release the hold. Try again in a moment.",
+        tone: result.status === 409 ? 'warning' : 'error',
+    };
+}

package/dist/editor/server-clock.d.ts

@@ -0,0 +1,4 @@
+/** Record a time the server reported, as of when its answer arrived. */
+export declare function noteServerTime(serverTime: number, receivedAt?: number): void;
+/** Now, by the server's clock as last heard; the browser's until then. */
+export declare function serverNow(): number;

package/dist/editor/server-clock.js

@@ -0,0 +1,15 @@
+/**
+ * The server's clock as the editor last heard it, so a wait timed against a server timestamp
+ * (base-update-wait.ts) doesn't depend on the browser's clock being right. One offset per page:
+ * the editor talks to one server.
+ */
+let offsetMs = 0;
+/** Record a time the server reported, as of when its answer arrived. */
+export function noteServerTime(serverTime, receivedAt = Date.now()) {
+    if (Number.isFinite(serverTime))
+        offsetMs = serverTime - receivedAt;
+}
+/** Now, by the server's clock as last heard; the browser's until then. */
+export function serverNow() {
+    return Date.now() + offsetMs;
+}

package/dist/editor/undo-change.d.ts

@@ -0,0 +1,52 @@
+/**
+ * "Undo change" in the "Show changes" drawer: one saved change of an entry set back, in its form
+ * value, to how `source` has it: the base's version to undo it, the branch's saved one to redo it.
+ * Pure; the editor puts the result in the entry's draft, so an undo is an unsaved edit until saved.
+ * List and block items are found by item key, so an undo lands on the item the change named
+ * wherever it now sits, and an item put back keeps its key, which its comment threads are anchored
+ * by (`resolveThreadPath` in item-keys.ts).
+ */
+import type { EntryChangeSide } from '../api/branch-entry-changes.js';
+import type { CanopyPathSegment } from './canopy-path.js';
+import type { EntryChange } from './entry-diff.js';
+type FormValue = Record<string, unknown>;
+/** A side as the editor's form holds it: an md/mdx body under `body` (`normalizeContentPayload`). */
+export declare const formValueOfSide: (side: EntryChangeSide) => FormValue;
+/** A form value as a side shaped like `like`, for comparing it with the base. */
+export declare const sideOfFormValue: (value: FormValue, like: EntryChangeSide) => EntryChangeSide;
+/**
+ * `value` with `next` at a change's place, records on the way made as needed; undefined when the
+ * place is inside an item `value` no longer has.
+ */
+export declare const withValueAt: (value: FormValue, change: Pick<EntryChange, "dataPath">, next: unknown, bodyField?: string) => FormValue | undefined;
+/** What `value` holds at a change's place; undefined where it has nothing there. */
+export declare const valueAtChange: (value: FormValue, change: Pick<EntryChange, "dataPath">, bodyField?: string) => unknown;
+/**
+ * Whether `value` holds `change` as `side` has it, so setting the change to `side` would change
+ * nothing: a moved item placed as `side` places it, anything else the same value at the change's
+ * path, an added or removed item's whole content included.
+ */
+export declare function holdsAs(value: FormValue, side: FormValue, change: EntryChange, bodyField?: string): boolean;
+/** Whether a change has a place in the form value that an undo can set back. */
+export declare const canSetBack: (change: EntryChange) => boolean;
+/**
+ * `current` with `change` set to how `source` has it. A whole item added or removed is put in or
+ * taken out; a moved item goes back beside its neighbours in `source`; anything else takes
+ * `source`'s value at the change's path. Undefined when the change can't be placed in `current`,
+ * such as a field inside an item `current` no longer has. `bodyField` is the schema's body field
+ * on an md/mdx entry.
+ */
+export declare function setChangeBack(current: FormValue, source: FormValue, change: EntryChange, bodyField?: string): FormValue | undefined;
+/**
+ * The canopy path (`blocks[2].title`) of a change in `value`, which comment threads anchor to;
+ * undefined when an item on it isn't in `value`.
+ */
+export declare function canopyPathOf(value: FormValue, change: EntryChange, bodyField?: string): CanopyPathSegment[] | undefined;
+/**
+ * `current` with every one of `changes` set to how `source` has it, leaving anything else, such
+ * as an unsaved edit to an unchanged field, as it is. Items are placed in `source`'s order, so
+ * each lands beside a neighbour already back in place and the list ends in `source`'s order. A
+ * change that can't be placed is skipped.
+ */
+export declare function setAllBack(current: FormValue, source: FormValue, changes: readonly EntryChange[], bodyField?: string): FormValue;
+export {};

package/dist/editor/undo-change.js

@@ -0,0 +1,241 @@
+/**
+ * "Undo change" in the "Show changes" drawer: one saved change of an entry set back, in its form
+ * value, to how `source` has it: the base's version to undo it, the branch's saved one to redo it.
+ * Pure; the editor puts the result in the entry's draft, so an undo is an unsaved edit until saved.
+ * List and block items are found by item key, so an undo lands on the item the change named
+ * wherever it now sits, and an item put back keeps its key, which its comment threads are anchored
+ * by (`resolveThreadPath` in item-keys.ts).
+ */
+import equal from 'fast-deep-equal';
+import { ITEM_KEY } from '../item-keys.js';
+import { isPlainRecord } from '../validation/field-traversal.js';
+/** The form key of an md/mdx body, which the diff names by the schema's body field. */
+const FORM_BODY_KEY = 'body';
+/** A side as the editor's form holds it: an md/mdx body under `body` (`normalizeContentPayload`). */
+export const formValueOfSide = (side) => side.body === undefined ? { ...side.data } : { ...side.data, [FORM_BODY_KEY]: side.body };
+/** A form value as a side shaped like `like`, for comparing it with the base. */
+export const sideOfFormValue = (value, like) => {
+    if (like.body === undefined)
+        return { ...like, data: value };
+    const { [FORM_BODY_KEY]: body, ...data } = value;
+    return { ...like, data, body: typeof body === 'string' ? body : '' };
+};
+const indexOfKey = (list, key) => list.findIndex((item) => isPlainRecord(item) && item[ITEM_KEY] === key);
+/** A change's data path in form keys: the body field, when it heads the path, is `body`. */
+const formPath = (change, bodyField) => {
+    const path = change.dataPath ?? [];
+    const head = path[0];
+    return bodyField && head && 'field' in head && head.field === bodyField
+        ? [{ field: FORM_BODY_KEY }, ...path.slice(1)]
+        : path;
+};
+const step = (value, segment) => {
+    if ('field' in segment)
+        return isPlainRecord(value) ? value[segment.field] : undefined;
+    if ('item' in segment) {
+        if (!Array.isArray(value))
+            return undefined;
+        const index = indexOfKey(value, segment.item);
+        return index < 0 ? undefined : value[index];
+    }
+    return isPlainRecord(value) ? (isPlainRecord(value.value) ? value.value : value) : undefined;
+};
+const valueAt = (value, path) => path.reduce(step, value);
+/**
+ * `value` with `next` at a change's place, records on the way made as needed; undefined when the
+ * place is inside an item `value` no longer has.
+ */
+export const withValueAt = (value, change, next, bodyField) => {
+    const placed = updateAt(value, formPath(change, bodyField), () => next);
+    return placed && isPlainRecord(placed.value) ? placed.value : undefined;
+};
+/** What `value` holds at a change's place; undefined where it has nothing there. */
+export const valueAtChange = (value, change, bodyField) => valueAt(value, formPath(change, bodyField));
+/** What a `replace` returns when the change has nothing to act on, so it can't be placed. */
+const NOT_PLACED = Symbol('not-placed');
+/**
+ * `value` with what is at `path` replaced by `replace`'s result, copied on the way down; a
+ * record missing on the way is made, so a field comes back inside an object the branch cleared.
+ * Undefined when the path leads through an item or block the value no longer has. A record
+ * member replaced by undefined is dropped.
+ */
+const updateAt = (value, path, replace) => {
+    if (path.length === 0) {
+        const next = replace(value);
+        return next === NOT_PLACED ? undefined : { value: next };
+    }
+    const [segment, ...rest] = path;
+    if ('field' in segment) {
+        const record = isPlainRecord(value) ? value : value == null ? {} : undefined;
+        if (!record)
+            return undefined;
+        const next = updateAt(record[segment.field], rest, replace);
+        if (!next)
+            return undefined;
+        const out = { ...record };
+        if (next.value === undefined)
+            delete out[segment.field];
+        else
+            out[segment.field] = next.value;
+        return { value: out };
+    }
+    if ('item' in segment) {
+        if (!Array.isArray(value))
+            return undefined;
+        const index = indexOfKey(value, segment.item);
+        if (index < 0)
+            return undefined;
+        const next = updateAt(value[index], rest, replace);
+        if (!next)
+            return undefined;
+        const out = [...value];
+        out[index] = next.value;
+        return { value: out };
+    }
+    if (!isPlainRecord(value))
+        return undefined;
+    if (!isPlainRecord(value.value))
+        return updateAt(value, rest, replace);
+    const next = updateAt(value.value, rest, replace);
+    return next && { value: { ...value, value: next.value } };
+};
+/**
+ * `item` placed in `list` (which lacks it) where `order` has it: after the nearest item before it
+ * in `order` that `list` holds, else before the nearest one after it, else at its place in `order`.
+ */
+const placeLike = (list, item, key, order) => {
+    const at = indexOfKey(order, key);
+    const indexIn = (other) => isPlainRecord(other) ? indexOfKey(list, other[ITEM_KEY]) : -1;
+    for (let i = at - 1; i >= 0; i--) {
+        const index = indexIn(order[i]);
+        if (index >= 0)
+            return [...list.slice(0, index + 1), item, ...list.slice(index + 1)];
+    }
+    for (let i = at + 1; at > 0 && i < order.length; i++) {
+        const index = indexIn(order[i]);
+        if (index >= 0)
+            return [...list.slice(0, index), item, ...list.slice(index)];
+    }
+    return at > 0 ? [...list.slice(0, at), item, ...list.slice(at)] : [item, ...list];
+};
+const isNothing = (value) => value === undefined || isEmptyContainer(value);
+/**
+ * Whether `value` holds `change` as `side` has it, so setting the change to `side` would change
+ * nothing: a moved item placed as `side` places it, anything else the same value at the change's
+ * path, an added or removed item's whole content included.
+ */
+export function holdsAs(value, side, change, bodyField) {
+    if (change.item && change.kind === 'moved') {
+        const placed = setChangeBack(value, side, change, bodyField);
+        return !!placed && equal(placed, value);
+    }
+    const path = formPath(change, bodyField);
+    const [mine, theirs] = [valueAt(value, path), valueAt(side, path)];
+    return (isNothing(mine) && isNothing(theirs)) || equal(mine, theirs);
+}
+/** Whether a change has a place in the form value that an undo can set back. */
+export const canSetBack = (change) => change.dataPath !== undefined;
+/**
+ * `current` with `change` set to how `source` has it. A whole item added or removed is put in or
+ * taken out; a moved item goes back beside its neighbours in `source`; anything else takes
+ * `source`'s value at the change's path. Undefined when the change can't be placed in `current`,
+ * such as a field inside an item `current` no longer has. `bodyField` is the schema's body field
+ * on an md/mdx entry.
+ */
+export function setChangeBack(current, source, change, bodyField) {
+    if (!canSetBack(change))
+        return undefined;
+    const path = formPath(change, bodyField);
+    const last = path[path.length - 1];
+    let next;
+    if (change.item && last && 'item' in last) {
+        const listPath = path.slice(0, -1);
+        const order = valueAt(source, listPath);
+        const sourceList = Array.isArray(order) ? order : [];
+        const wanted = valueAt(source, path);
+        next = updateAt(current, listPath, (old) => {
+            const list = Array.isArray(old) ? old : [];
+            const index = indexOfKey(list, last.item);
+            if (wanted === undefined)
+                return index < 0 ? old : list.filter((_, i) => i !== index);
+            if (change.kind === 'moved') {
+                if (index < 0)
+                    return NOT_PLACED;
+                const without = list.filter((_, i) => i !== index);
+                return placeLike(without, list[index], last.item, sourceList);
+            }
+            return index >= 0 ? old : placeLike(list, structuredClone(wanted), last.item, sourceList);
+        });
+    }
+    else {
+        const wanted = valueAt(source, path);
+        next = updateAt(current, path, () => wanted === undefined ? undefined : structuredClone(wanted));
+    }
+    const placed = next && isPlainRecord(next.value) ? next.value : undefined;
+    return placed && withoutEmptyContainers(placed, source, path);
+}
+const isEmptyContainer = (value) => Array.isArray(value)
+    ? value.length === 0
+    : isPlainRecord(value) && Object.keys(value).length === 0;
+/**
+ * `value` without the records and lists on `path` that setting a change back left empty where
+ * `source` has none, so a value set back matches `source` rather than holding `seo: {}`.
+ */
+const withoutEmptyContainers = (value, source, path) => {
+    let out = value;
+    for (let end = path.length; end > 0; end--) {
+        const at = path.slice(0, end);
+        if (!('field' in at[at.length - 1]))
+            continue;
+        if (valueAt(source, at) !== undefined || !isEmptyContainer(valueAt(out, at)))
+            continue;
+        const next = updateAt(out, at, () => undefined);
+        if (next && isPlainRecord(next.value))
+            out = next.value;
+    }
+    return out;
+};
+/**
+ * The canopy path (`blocks[2].title`) of a change in `value`, which comment threads anchor to;
+ * undefined when an item on it isn't in `value`.
+ */
+export function canopyPathOf(value, change, bodyField) {
+    const out = [];
+    let at = value;
+    for (const segment of formPath(change, bodyField)) {
+        if ('item' in segment) {
+            const index = Array.isArray(at) ? indexOfKey(at, segment.item) : -1;
+            if (index < 0)
+                return undefined;
+            out.push(index);
+        }
+        else if ('field' in segment) {
+            out.push(segment.field);
+        }
+        at = step(at, segment);
+    }
+    return out;
+}
+/** An item change's place in `source`'s list: -1 for an item `source` lacks; undefined otherwise. */
+const sourcePosition = (source, change, bodyField) => {
+    if (!change.item)
+        return undefined;
+    const path = formPath(change, bodyField);
+    const last = path[path.length - 1];
+    if (!last || !('item' in last))
+        return undefined;
+    const list = valueAt(source, path.slice(0, -1));
+    return Array.isArray(list) ? indexOfKey(list, last.item) : -1;
+};
+/**
+ * `current` with every one of `changes` set to how `source` has it, leaving anything else, such
+ * as an unsaved edit to an unchanged field, as it is. Items are placed in `source`'s order, so
+ * each lands beside a neighbour already back in place and the list ends in `source`'s order. A
+ * change that can't be placed is skipped.
+ */
+export function setAllBack(current, source, changes, bodyField) {
+    const ordered = changes
+        .map((change) => ({ change, position: sourcePosition(source, change, bodyField) }))
+        .sort((a, b) => (a.position ?? -2) - (b.position ?? -2));
+    return ordered.reduce((value, { change }) => setChangeBack(value, source, change, bodyField) ?? value, current);
+}

package/dist/git-manager.d.ts

@@ -560,6 +560,11 @@ export declare class GitManager {
      * path. Any other failure, such as an unknown `rev`, throws.
      */
     showFile(rev: string, filePath: string): Promise<string | undefined>;
+    /**
+     * The text of the blob `sha`, `'too-large'` when it is over `maxBytes`, or `undefined` when this
+     * clone has no such blob. Any other failure throws.
+     */
+    readBlob(sha: string, maxBytes: number): Promise<string | 'too-large' | undefined>;
     ensureAuthor(author: {
         name: string;
         email: string;

package/dist/git-manager.js

@@ -1763,6 +1763,36 @@ export class GitManager {
             throw err;
         }
     }
+    /**
+     * The text of the blob `sha`, `'too-large'` when it is over `maxBytes`, or `undefined` when this
+     * clone has no such blob. Any other failure throws.
+     */
+    async readBlob(sha, maxBytes) {
+        if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha))
+            return undefined;
+        let sizeText;
+        try {
+            sizeText = (await this.git.raw(['cat-file', '-s', '--end-of-options', sha])).trim();
+        }
+        catch (err) {
+            // LC_ALL=C (gitChildEnv), so git's own wording is stable to match.
+            if (/could not get object info|Not a valid object name/.test(getErrorMessage(err))) {
+                return undefined;
+            }
+            throw err;
+        }
+        // simple-git resolves "" when git exits non-zero without writing to stderr, so anything but
+        // digits is a failed read rather than an empty blob.
+        if (!/^\d+$/.test(sizeText))
+            throw new Error(`git cat-file -s ${sha} printed no size`);
+        const size = Number(sizeText);
+        if (size > maxBytes)
+            return 'too-large';
+        const text = await this.git.raw(['cat-file', 'blob', '--end-of-options', sha]);
+        if (size > 0 && text === '')
+            throw new Error(`git cat-file blob ${sha} printed nothing`);
+        return text;
+    }
     async ensureAuthor(author) {
         const config = (await this.git.listConfig());
         // Verify this is a CanopyCMS-managed workspace before setting author

package/dist/item-keys.d.ts

@@ -12,6 +12,14 @@ export declare const ITEM_KEY = "_key";
 export declare const isItemKey: (value: unknown) => value is string;
 /** A new random item key: 12 Base58 characters. */
 export declare function mintItemKey(): string;
+/**
+ * True for a key with the shape {@link contentKey} gives, `h` and a 53-bit hash in at most 10
+ * Base58 digits (`-2` and on for a repeat): one a read wrote down. A key {@link mintItemKey}
+ * minted is 12 digits long, so it never has this shape.
+ */
+export declare const hasContentKeyShape: (key: string) => boolean;
+/** True for a key a read or {@link mintItemKey} wrote, never one a person typed, such as `faq`. */
+export declare const hasMachineKeyShape: (key: string) => boolean;
 /**
  * How `withItemKeys` keys an item that lacks a usable key, or repeats one an earlier item of its
  * list holds:
@@ -31,6 +39,11 @@ type ListField = ObjectFieldConfig | BlockFieldConfig;
 export declare function withItemKeys(fields: readonly FieldConfig[], data: Record<string, unknown>, fill: ItemKeyFill): Record<string, unknown>;
 /** `item`, a copy about to join `field`'s list, with fresh keys for it and every item inside it. */
 export declare function withFreshItemKeys<T>(field: ListField, item: T): T;
+/**
+ * The key a read gives each item of a list, as `withItemKeys` with `content` does: its own usable
+ * key, else a hash of its content. Undefined for an item that isn't a record.
+ */
+export declare const itemKeysAsRead: (items: readonly unknown[]) => Array<string | undefined>;
 /**
  * The keys of the list items on `canopyPath` in `value`, outermost first: what a new field thread
  * stores to name them. Undefined when an item on the path has no usable key or the path isn't

package/dist/item-keys.js

@@ -40,6 +40,14 @@ function contentKey(item) {
     } while (n > 0);
     return `h${out}`;
 }
+/**
+ * True for a key with the shape {@link contentKey} gives, `h` and a 53-bit hash in at most 10
+ * Base58 digits (`-2` and on for a repeat): one a read wrote down. A key {@link mintItemKey}
+ * minted is 12 digits long, so it never has this shape.
+ */
+export const hasContentKeyShape = (key) => /^h[1-9A-HJ-NP-Za-km-z]{1,10}(-\d+)?$/.test(key);
+/** True for a key a read or {@link mintItemKey} wrote, never one a person typed, such as `faq`. */
+export const hasMachineKeyShape = (key) => hasContentKeyShape(key) || /^[1-9A-HJ-NP-Za-km-z]{12}$/.test(key);
 const isListField = (field) => field.type === 'block' || (field.type === 'object' && !!field.list);
 /**
  * `data` with every object-list item and block keyed, each unique in its list, nested lists
@@ -72,6 +80,22 @@ export function withFreshItemKeys(field, item) {
     return keyList(field, [item], 'fresh')[0];
 }
 function keyList(field, items, fill) {
+    const keys = listKeys(items, fill);
+    let changed = false;
+    const out = items.map((item, i) => {
+        if (!isPlainRecord(item))
+            return item;
+        let next = keyInside(field, item, fill);
+        if (keys[i] !== item[ITEM_KEY])
+            next = { ...next, [ITEM_KEY]: keys[i] };
+        if (next !== item)
+            changed = true;
+        return next;
+    });
+    return changed ? out : items;
+}
+/** The key each record of `items` ends with under `fill`; undefined for an item that isn't one. */
+function listKeys(items, fill) {
     const held = new Set();
     if (fill !== 'fresh') {
         for (const item of items) {
@@ -80,27 +104,25 @@ function keyList(field, items, fill) {
         }
     }
     const kept = new Set();
-    let changed = false;
-    const out = items.map((item) => {
+    return items.map((item) => {
         if (!isPlainRecord(item))
-            return item;
-        let next = keyInside(field, item, fill);
+            return undefined;
         const own = item[ITEM_KEY];
         if (fill !== 'fresh' && isItemKey(own) && !kept.has(own)) {
             kept.add(own);
+            return own;
         }
-        else {
-            const key = fill === 'content' ? unheld(contentKey(item), held) : mintItemKey();
-            held.add(key);
-            kept.add(key);
-            next = { ...next, [ITEM_KEY]: key };
-        }
-        if (next !== item)
-            changed = true;
-        return next;
+        const key = fill === 'content' ? unheld(contentKey(item), held) : mintItemKey();
+        held.add(key);
+        kept.add(key);
+        return key;
     });
-    return changed ? out : items;
 }
+/**
+ * The key a read gives each item of a list, as `withItemKeys` with `content` does: its own usable
+ * key, else a hash of its content. Undefined for an item that isn't a record.
+ */
+export const itemKeysAsRead = (items) => listKeys(items, 'content');
 /** `key`, or with a suffix when another item of the list already holds it (identical items). */
 function unheld(key, held) {
     let out = key;