canopycms 0.0.68-int.98 → 0.1.0

package/dist/editor/canopy-path.js

@@ -1,3 +1,9 @@
+/**
+ * The one spelling of a field path, `blocks[0].title`, for the form's fields, the preview's
+ * marks and comment threads. A digits-only segment is always a list index (`[0]` or `.0`):
+ * schemas refuse field names `isPathFieldName` rejects, since no path could spell them.
+ */
+export const isPathFieldName = (name) => name.length > 0 && !/^\d+$/.test(name) && !/[.[\]]/.test(name);
 /**
  * Convert a list of path segments into the canonical CanopyCMS path string.
  * Arrays are rendered with bracket notation (e.g., blocks[0].title).
@@ -22,7 +28,6 @@ export const parseCanopyPath = (path) => {
     while ((match = matcher.exec(path)) !== null) {
         if (match[1]) {
             const raw = match[1];
-            // Allow dotted numeric segments (e.g., blocks.0.title)
             if (/^\d+$/.test(raw)) {
                 segments.push(Number(raw));
             }
@@ -36,13 +41,5 @@ export const parseCanopyPath = (path) => {
     }
     return segments;
 };
-/**
- * Normalize any supported path input (string or segments) into the
- * canonical bracketed representation.
- */
-export const normalizeCanopyPath = (input) => {
-    if (Array.isArray(input)) {
-        return formatCanopyPath(input);
-    }
-    return formatCanopyPath(parseCanopyPath(input));
-};
+/** The canonical string for a path; segments are re-parsed, so `['a', '0']` is `a[0]`. */
+export const normalizeCanopyPath = (input) => formatCanopyPath(parseCanopyPath(typeof input === 'string' ? input : formatCanopyPath(input)));

package/dist/editor/client-reference-resolver.d.ts

@@ -1,24 +1,51 @@
-import type { EntrySchema, FieldConfig } from '../config/index.js';
-import type { FormValue } from './FormRenderer.js';
+import type { EntrySchema } from '../config/index.js';
 import type { ApiClient } from './context/index.js';
 /**
- * Client-side utility for incrementally resolving reference fields in form data.
- * Used by FormRenderer to transform draft data before sending to preview.
- *
- * This module is a plain function file, not a hook/component -- it's invoked from inside a
- * `setTimeout` callback in `useReferenceResolution`'s effect, well after that render has
- * finished, where calling a React hook would violate the rules of hooks. So the API client
- * can't be sourced here via `useApiClient()`/`useOptionalApiClient()` directly; instead every
- * entry point takes an optional `apiClient`, which the caller (a hook, which CAN call
- * `useOptionalApiClient()` during render) resolves and passes down. Falls back to a
- * default-configured `createApiClient()` when no client is supplied.
+ * Resolves the reference fields of a draft for live preview, at every position the server's
+ * `ContentStore.resolveReferencesInData` resolves them: top level, inline groups, objects,
+ * object lists and blocks, nested to any depth. `useReferenceResolution` drives it.
  */
+type FormValue = Record<string, unknown>;
 /**
- * Only returns top-level field configs for fields that changed.
+ * How long a `MissingReference`, or an id the endpoint omitted (its lookup threw), stays cached.
+ * The target can appear or the lookup succeed later, so the first edit after this asks again.
  * @internal Exported for tests.
  */
-export declare function findChangedFields(prevValue: FormValue, currentValue: FormValue, schema: EntrySchema): FieldConfig[];
+export declare const MISSING_REFERENCE_TTL_MS = 10000;
+interface ReferenceCacheEntry {
+    /** What the endpoint returned for the id, or `null` when it omitted the id. */
+    value: unknown;
+    /** From then on the id is fetched again; set on storing `null`, and by `expireReferences`. */
+    expiresAt?: number;
+}
+/** Resolved targets keyed by `${branch}:${id}`. */
+export type ReferenceCache = Map<string, ReferenceCacheEntry>;
+/** The ids in the draft with no fresh cache entry: never fetched, or expired. */
+export declare function idsToFetch(fields: EntrySchema, value: FormValue, branch: string, cache: ReferenceCache, now: number): string[];
+/**
+ * Resolve `ids` in batches of the endpoint's cap. Every requested id is in the result: the
+ * endpoint's value, or `null` for an id it omitted. Throws when any batch fails, so a transient
+ * error caches nothing and the ids stay pending.
+ */
+export declare function fetchReferences(ids: readonly string[], branch: string, apiClient?: ApiClient): Promise<Map<string, unknown>>;
+/** Cache what {@link fetchReferences} returned; a missing or omitted id expires after the TTL. */
+export declare function storeReferences(cache: ReferenceCache, branch: string, found: Map<string, unknown>, now: number): void;
 /**
- * Uses cache to avoid duplicate API calls.
+ * Mark every entry expired, so each id is fetched again while its cached value keeps showing.
+ * Used when the open entry changes, since a target may have been edited in the meantime.
+ */
+export declare function expireReferences(cache: ReferenceCache): void;
+/**
+ * The draft as the preview sees it, computed synchronously from the cache.
+ *
+ * Each reference becomes its cached value (the target, or an `unavailable` reference), or `null`
+ * while it has none (still resolving, a failed lookup, or a malformed id). A list field's array maps element by element, a
+ * non-string element to `null`; anything else is left as the form holds it, as on the server.
+ * `loadingState` holds a boolean only at reference positions, `true` while resolving, at the
+ * reference's own path (`boolean[]` for a list).
  */
-export declare function resolveChangedReferences(prevValue: FormValue, currentValue: FormValue, schema: EntrySchema, branch: string, cache: Map<string, unknown>, apiClient?: ApiClient): Promise<Partial<FormValue>>;
+export declare function applyReferenceCache(fields: EntrySchema, value: FormValue, branch: string, cache: ReferenceCache): {
+    resolvedValue: FormValue;
+    loadingState: FormValue;
+};
+export {};

package/dist/editor/client-reference-resolver.js

@@ -1,81 +1,172 @@
 import { createApiClient } from '../api/client.js';
 import { flattenGroupFields } from '../utils/flatten-group-fields.js';
+import { isValidContentId } from '../paths/validation.js';
+import { traverseFields } from '../validation/field-traversal.js';
+/** The resolve-references endpoint's per-request id cap (`MAX_RESOLVE_REFERENCE_IDS`). */
+const MAX_IDS_PER_REQUEST = 100;
 /**
- * Client-side utility for incrementally resolving reference fields in form data.
- * Used by FormRenderer to transform draft data before sending to preview.
- *
- * This module is a plain function file, not a hook/component -- it's invoked from inside a
- * `setTimeout` callback in `useReferenceResolution`'s effect, well after that render has
- * finished, where calling a React hook would violate the rules of hooks. So the API client
- * can't be sourced here via `useApiClient()`/`useOptionalApiClient()` directly; instead every
- * entry point takes an optional `apiClient`, which the caller (a hook, which CAN call
- * `useOptionalApiClient()` during render) resolves and passes down. Falls back to a
- * default-configured `createApiClient()` when no client is supplied.
- */
-/**
- * Only returns top-level field configs for fields that changed.
+ * How long a `MissingReference`, or an id the endpoint omitted (its lookup threw), stays cached.
+ * The target can appear or the lookup succeed later, so the first edit after this asks again.
  * @internal Exported for tests.
  */
-export function findChangedFields(prevValue, currentValue, schema) {
-    const changed = [];
-    for (const field of flattenGroupFields(schema)) {
-        const prevFieldValue = prevValue[field.name];
-        const currentFieldValue = currentValue[field.name];
-        if (JSON.stringify(prevFieldValue) !== JSON.stringify(currentFieldValue)) {
-            changed.push(field);
+export const MISSING_REFERENCE_TTL_MS = 10_000;
+function isMissingReference(value) {
+    return isContainer(value) && value.unavailable === true && value.reason === 'missing';
+}
+function cacheKey(branch, id) {
+    return `${branch}:${id}`;
+}
+function isContainer(value) {
+    return typeof value === 'object' && value !== null;
+}
+function referenceSlots(fields, value) {
+    return traverseFields(fields, value, () => [], '', ({ fields: containerFields, data, dataPath }) => flattenGroupFields(containerFields)
+        .filter((field) => field.type === 'reference')
+        .map((field) => ({
+        path: [...dataPath, field.name],
+        value: data[field.name],
+        list: field.list === true,
+    })));
+}
+/** A slot's ids, by the server's rule; never a malformed one, which fails the whole request. */
+function slotIds(slot) {
+    const ids = typeof slot.value === 'string'
+        ? [slot.value]
+        : slot.list && Array.isArray(slot.value)
+            ? slot.value.filter((id) => typeof id === 'string')
+            : [];
+    return ids.filter(isValidContentId);
+}
+/** The ids in the draft with no fresh cache entry: never fetched, or expired. */
+export function idsToFetch(fields, value, branch, cache, now) {
+    const ids = new Set();
+    for (const slot of referenceSlots(fields, value)) {
+        for (const id of slotIds(slot)) {
+            const entry = cache.get(cacheKey(branch, id));
+            if (!entry || (entry.expiresAt !== undefined && entry.expiresAt <= now))
+                ids.add(id);
         }
     }
-    return changed;
+    return [...ids];
 }
 /**
- * Uses cache to avoid duplicate API calls.
+ * Resolve `ids` in batches of the endpoint's cap. Every requested id is in the result: the
+ * endpoint's value, or `null` for an id it omitted. Throws when any batch fails, so a transient
+ * error caches nothing and the ids stay pending.
  */
-export async function resolveChangedReferences(prevValue, currentValue, schema, branch, cache, apiClient) {
-    const changedFields = findChangedFields(prevValue, currentValue, schema);
-    const updates = {};
-    for (const field of changedFields) {
-        if (field.type === 'reference') {
-            const refField = field;
-            const fieldValue = currentValue[field.name];
-            if (refField.list && Array.isArray(fieldValue)) {
-                const resolved = await Promise.all(fieldValue.map((id) => resolveReferenceId(id, branch, cache, apiClient)));
-                updates[field.name] = resolved;
-            }
-            else if (fieldValue) {
-                const resolved = await resolveReferenceId(fieldValue, branch, cache, apiClient);
-                updates[field.name] = resolved;
-            }
-        }
+export async function fetchReferences(ids, branch, apiClient) {
+    const client = apiClient ?? createApiClient();
+    const batches = [];
+    for (let i = 0; i < ids.length; i += MAX_IDS_PER_REQUEST) {
+        batches.push(ids.slice(i, i + MAX_IDS_PER_REQUEST));
     }
-    return updates;
+    const responses = await Promise.all(batches.map((batch) => client.content.resolveReferences({ branch }, { ids: batch })));
+    const found = new Map();
+    responses.forEach((response, index) => {
+        if (!response.ok || !response.data) {
+            throw new Error(`Resolving references failed with status ${response.status}`);
+        }
+        const { resolved } = response.data;
+        for (const id of batches[index]) {
+            found.set(id, Object.prototype.hasOwnProperty.call(resolved, id) ? resolved[id] : null);
+        }
+    });
+    return found;
 }
-async function resolveReferenceId(id, branch, cache, apiClient) {
-    if (typeof id !== 'string') {
-        return id;
-    }
-    // Check if already resolved (has __typename or other object properties)
-    if (typeof id === 'object' && id !== null) {
-        return id;
+/** Cache what {@link fetchReferences} returned; a missing or omitted id expires after the TTL. */
+export function storeReferences(cache, branch, found, now) {
+    for (const [id, value] of found) {
+        cache.set(cacheKey(branch, id), value === null || isMissingReference(value)
+            ? { value, expiresAt: now + MISSING_REFERENCE_TTL_MS }
+            : { value });
     }
-    const cacheKey = `${branch}:${id}`;
-    if (cache.has(cacheKey)) {
-        return cache.get(cacheKey);
+}
+/**
+ * Mark every entry expired, so each id is fetched again while its cached value keeps showing.
+ * Used when the open entry changes, since a target may have been edited in the meantime.
+ */
+export function expireReferences(cache) {
+    for (const entry of cache.values())
+        entry.expiresAt = 0;
+}
+/**
+ * Write `leaf` at `path`, copying each container on the way the first time it is touched, so
+ * the input is never mutated and untouched subtrees keep their identity.
+ */
+function setCopied(root, path, leaf, copies) {
+    const copy = (node) => {
+        if (copies.has(node))
+            return node;
+        const next = (Array.isArray(node) ? [...node] : { ...node });
+        copies.add(next);
+        return next;
+    };
+    const nextRoot = copy(root);
+    let node = nextRoot;
+    for (const key of path.slice(0, -1)) {
+        const child = node[key];
+        if (!isContainer(child))
+            return nextRoot;
+        const next = copy(child);
+        node[key] = next;
+        node = next;
     }
-    try {
-        // Fetch from API (single ID) -- use the caller-supplied (context-sourced) client when
-        // available, so requests carry the deployment's configured basePath; fall back to a
-        // default-configured client for direct callers that don't have one to hand.
-        const client = apiClient ?? createApiClient();
-        const result = await client.content.resolveReferences({ branch }, { ids: [id] });
-        if (result.ok && result.data && result.data.resolved[id]) {
-            const resolved = result.data.resolved[id];
-            cache.set(cacheKey, resolved);
-            return resolved;
+    node[path[path.length - 1]] = leaf;
+    return nextRoot;
+}
+/**
+ * Write `leaf` at `path` in a fresh tree, creating each missing level. An array is created as
+ * long as `source`'s array at that path, with an empty object per item, so it has no holes.
+ */
+function setCreating(root, path, leaf, source) {
+    let node = root;
+    let from = source;
+    path.slice(0, -1).forEach((key) => {
+        from = isContainer(from) ? from[key] : undefined;
+        let child = node[key];
+        if (!isContainer(child)) {
+            child = Array.isArray(from) ? Array.from(from, () => ({})) : {};
+            node[key] = child;
+        }
+        node = child;
+    });
+    node[path[path.length - 1]] = leaf;
+}
+/**
+ * The draft as the preview sees it, computed synchronously from the cache.
+ *
+ * Each reference becomes its cached value (the target, or an `unavailable` reference), or `null`
+ * while it has none (still resolving, a failed lookup, or a malformed id). A list field's array maps element by element, a
+ * non-string element to `null`; anything else is left as the form holds it, as on the server.
+ * `loadingState` holds a boolean only at reference positions, `true` while resolving, at the
+ * reference's own path (`boolean[]` for a list).
+ */
+export function applyReferenceCache(fields, value, branch, cache) {
+    let resolvedValue = value;
+    const loadingState = {};
+    const copies = new WeakSet();
+    const lookup = (id) => {
+        if (typeof id !== 'string' || !isValidContentId(id))
+            return { value: null, loading: false };
+        const entry = cache.get(cacheKey(branch, id));
+        return entry ? { value: entry.value, loading: false } : { value: null, loading: true };
+    };
+    for (const slot of referenceSlots(fields, value)) {
+        if (typeof slot.value === 'string' && slot.value) {
+            const { value: target, loading } = lookup(slot.value);
+            resolvedValue = setCopied(resolvedValue, slot.path, target, copies);
+            setCreating(loadingState, slot.path, loading, value);
+        }
+        else if (slot.list && Array.isArray(slot.value)) {
+            const items = slot.value.map(lookup);
+            if (slot.value.length > 0) {
+                resolvedValue = setCopied(resolvedValue, slot.path, items.map((item) => item.value), copies);
+            }
+            setCreating(loadingState, slot.path, items.map((item) => item.loading), value);
+        }
+        else {
+            setCreating(loadingState, slot.path, false, value);
         }
-        return id;
-    }
-    catch (error) {
-        console.error(`Failed to resolve reference ID ${id}:`, error);
-        return id;
     }
+    return { resolvedValue, loadingState };
 }

package/dist/editor/comments/BranchComments.d.ts

@@ -6,7 +6,7 @@ export interface BranchCommentsProps {
     comments: CommentThread[];
     /** Current user ID */
     currentUserId: string;
-    /** Whether user can resolve threads */
+    /** Whether the user may resolve any thread; a thread's own author always may resolve it. */
     canResolve: boolean;
     /** Handler to add a comment */
     onAddComment: (text: string, type: 'field' | 'entry' | 'branch', entryPath?: string, canopyPath?: string, threadId?: string) => Promise<void>;

package/dist/editor/comments/BranchComments.js

@@ -15,7 +15,7 @@ export const BranchComments = ({ comments, currentUserId, canResolve, onAddComme
         await onAddComment(text, 'branch', undefined, undefined, threadId);
     };
     if (!shouldShowCarousel) {
-        return (_jsx(Box, { children: _jsx(Button, { size: "xs", variant: "subtle", color: "gray", onClick: () => setShowCarousel(true), style: { fontSize: '0.75rem', height: '1.5rem' }, children: "New branch comment" }) }));
+        return (_jsx(Box, { children: _jsx(Button, { variant: "subtle", color: "gray", onClick: () => setShowCarousel(true), style: { fontSize: '0.75rem', height: '1.5rem' }, children: "New branch comment" }) }));
     }
-    return (_jsx(ThreadCarousel, { threads: branchThreads, label: "Branch Discussion", contextType: "branch", currentUserId: currentUserId, canResolve: canResolve, onAddComment: handleAddComment, onResolveThread: onResolveThread, autoFocus: autoFocus, autoOpenNewThread: showCarousel && branchThreads.length === 0, highlightThreadId: highlightThreadId, onGetUserMetadata: onGetUserMetadata }));
+    return (_jsx(ThreadCarousel, { threads: branchThreads, label: "Branch discussion", contextType: "branch", currentUserId: currentUserId, canResolve: canResolve, onAddComment: handleAddComment, onResolveThread: onResolveThread, autoFocus: autoFocus, autoOpenNewThread: showCarousel && branchThreads.length === 0, highlightThreadId: highlightThreadId, onGetUserMetadata: onGetUserMetadata }));
 };

package/dist/editor/comments/CloseRefusedNotice.d.ts

@@ -0,0 +1,4 @@
+/** Why a comments surface stayed open: an always-mounted live region, so it is announced. */
+export declare function CloseRefusedNotice({ refused }: {
+    refused: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/editor/comments/CloseRefusedNotice.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text, VisuallyHidden } from '@mantine/core';
+import { CLOSE_WAITS_FOR_WRITE } from './use-tracked-writes.js';
+/** Why a comments surface stayed open: an always-mounted live region, so it is announced. */
+export function CloseRefusedNotice({ refused }) {
+    return (_jsxs(_Fragment, { children: [_jsx(VisuallyHidden, { role: "status", children: refused ? CLOSE_WAITS_FOR_WRITE : '' }), refused && (_jsx(Text, { size: "xs", c: "dimmed", "aria-hidden": true, children: CLOSE_WAITS_FOR_WRITE }))] }));
+}

package/dist/editor/comments/CommentThreadsPopover.d.ts

@@ -0,0 +1,47 @@
+import React from 'react';
+import type { CommentThread } from '../../comment-store.js';
+import type { UserSearchResult } from '../../auth/types.js';
+import { type FieldAnchors } from './popover-placement.js';
+export interface CommentThreadsPopoverProps {
+    /** The threads on this field or entry. */
+    threads: CommentThread[];
+    /** What the comments are about, as a reader names it: a field's breadcrumb, or "this entry". */
+    subject: string;
+    /**
+     * `field`: an icon that shows while `revealed`, and as a count while a thread is open.
+     * `entry`: a labelled "Comment on this entry" button that is always shown.
+     */
+    variant: 'field' | 'entry';
+    /** For `field`: the pointer or focus is on the field, so the idle icon shows. */
+    revealed?: boolean;
+    /** For `field`: where the popover may open, above the label row or below the input. */
+    anchors?: FieldAnchors;
+    /** For `field`: each new request opens the popover, as the form's keyboard route asks. */
+    openRequest?: OpenRequest;
+    currentUserId: string;
+    canResolve: boolean;
+    /** Starts a thread, or replies to `threadId`. */
+    onAddComment: (text: string, threadId?: string) => Promise<void>;
+    onResolveThread: (threadId: string) => Promise<void>;
+    onGetUserMetadata?: (userId: string) => Promise<UserSearchResult | null>;
+    /** A thread here with this id opens the popover and is highlighted in it. */
+    highlightThreadId?: string;
+    /** Names the field of a thread shown away from it, such as one on a removed item. */
+    threadFieldLabel?: (thread: CommentThread) => string | undefined;
+    /**
+     * Why a new thread can't be posted here yet, such as a field of an item only the draft has.
+     * Shown before anyone types; the box stays usable, so a draft survives until it can be posted.
+     */
+    composeBlockedReason?: string;
+    testId: string;
+}
+export interface OpenRequest {
+    /** Takes focus in place of the opener, such as a menu item gone by close, unless a click closes the popover. */
+    returnFocusTo?: () => HTMLElement | null;
+}
+/**
+ * A field's or entry's comment control and the popover it opens: the threads (open first), each
+ * with reply and Resolve, and a box for a new thread. Comments stay open on a read-only form,
+ * since reviewers comment on submitted branches.
+ */
+export declare const CommentThreadsPopover: React.FC<CommentThreadsPopoverProps>;