canopycms 0.1.0 → 0.2.0-int.121

package/dist/editor/components/UnsavedMark.js

@@ -0,0 +1,20 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { Box } from '@mantine/core';
+/**
+ * The editor's one "unsaved" mark, a dot, in the breadcrumb, the branch pill and the content tree.
+ * `--canopy-unsaved-mark` is the brand colour at 3:1 on the shell's surfaces in either scheme.
+ * The caller says whether it is named (`role="img"` and a label) or decoration (`aria-hidden`).
+ * It forwards its ref, so a Tooltip can wrap it.
+ */
+export const UnsavedMark = forwardRef(function UnsavedMark(props, ref) {
+    return (_jsx(Box, { ref: ref, component: "span", ...props, style: {
+            display: 'inline-block',
+            flexShrink: 0,
+            width: 8,
+            height: 8,
+            borderRadius: '50%',
+            backgroundColor: 'var(--canopy-unsaved-mark, var(--mantine-color-brand-6))',
+        } }));
+});

package/dist/editor/components/UserBadge.js

@@ -29,11 +29,14 @@ export const UserBadge = ({ userId, getUserMetadata, variant = 'avatar-name', sh
     // A light or outline badge tints its label with the badge colour, too faint for a name.
     const nameColor = inBadge && badgeVariant !== 'filled' ? 'var(--mantine-color-text)' : undefined;
     const wrap = (content, tooltip, personLabel) => {
-        const wrapped = inBadge ? (_jsx(Badge, { variant: badgeVariant, color: color, pr: onRemove ? 3 : 8, pl: 4, rightSection: onRemove ? (_jsx(Tooltip, { label: `Remove ${personLabel}`, position: "bottom", children: _jsx(ActionIcon, { size: "xs", radius: "xl", variant: "transparent", onClick: () => onRemove(userId), onMouseEnter: () => setOnRemoveButton(true), onMouseLeave: () => setOnRemoveButton(false), onFocus: () => setOnRemoveButton(true), onBlur: () => setOnRemoveButton(false), "aria-label": `Remove ${personLabel}`, style: { color: nameColor ?? 'var(--mantine-color-white)' }, children: _jsx(IconX, { size: 12, stroke: 2.5 }) }) })) : undefined, styles: {
+        const wrapped = inBadge ? (_jsx(Badge, { variant: badgeVariant, color: color, pr: onRemove ? 3 : 8, pl: 4, 
+            // A long name shrinks the badge to its container instead of wrapping inside its fixed height.
+            maw: "100%", rightSection: onRemove ? (_jsx(Tooltip, { label: `Remove ${personLabel}`, position: "bottom", children: _jsx(ActionIcon, { size: "xs", radius: "xl", variant: "transparent", onClick: () => onRemove(userId), onMouseEnter: () => setOnRemoveButton(true), onMouseLeave: () => setOnRemoveButton(false), onFocus: () => setOnRemoveButton(true), onBlur: () => setOnRemoveButton(false), "aria-label": `Remove ${personLabel}`, style: { color: nameColor ?? 'var(--mantine-color-white)' }, children: _jsx(IconX, { size: 12, stroke: 2.5 }) }) })) : undefined, styles: {
                 label: {
                     display: 'flex',
                     alignItems: 'center',
                     gap: '4px',
+                    minWidth: 0,
                 },
             }, children: content })) : (content);
         return showEmailTooltip ? (_jsx(Tooltip, { label: tooltip, disabled: !tooltip || onRemoveButton, children: wrapped })) : (wrapped);
@@ -49,9 +52,9 @@ export const UserBadge = ({ userId, getUserMetadata, variant = 'avatar-name', sh
         const describedWithEmail = emailDetail ? `${described}, ${emailDetail}` : described;
         // A filled badge keeps its white text; dimmed would not contrast with its fill.
         const fallbackColor = inBadge && badgeVariant === 'filled' ? undefined : 'dimmed';
-        const unavailableText = (_jsx(Text, { size: textSize, c: fallbackColor, fs: "italic", children: unavailable }));
+        const unavailableText = (_jsx(Text, { size: textSize, c: fallbackColor, fs: "italic", truncate: true, children: unavailable }));
         const hiddenDetail = `${revealIdOnFallback ? ` · ${userId}` : ''}${emailDetail ? `, ${emailDetail}` : ''}`;
-        return wrap(_jsxs(Group, { gap: 4, children: [_jsx(Avatar, { src: record?.avatarUrl, alt: "", size: avatarSize, color: "gray", "aria-hidden": true }), variant === 'avatar-only' ? (_jsx(VisuallyHidden, { component: "span", children: describedWithEmail })) : (_jsxs(_Fragment, { children: [variant === 'full' && record?.email ? (_jsxs("div", { children: [unavailableText, _jsx(Text, { size: "xs", c: "dimmed", children: record.email })] })) : (unavailableText), hiddenDetail && _jsx(VisuallyHidden, { component: "span", children: hiddenDetail })] }))] }), variant === 'avatar-only'
+        return wrap(_jsxs(Group, { gap: 4, wrap: "nowrap", miw: 0, children: [_jsx(Avatar, { src: record?.avatarUrl, alt: "", size: avatarSize, color: "gray", "aria-hidden": true }), variant === 'avatar-only' ? (_jsx(VisuallyHidden, { component: "span", children: describedWithEmail })) : (_jsxs(_Fragment, { children: [variant === 'full' && record?.email ? (_jsxs("div", { children: [unavailableText, _jsx(Text, { size: "xs", c: "dimmed", children: record.email })] })) : (unavailableText), hiddenDetail && _jsx(VisuallyHidden, { component: "span", children: hiddenDetail })] }))] }), variant === 'avatar-only'
             ? describedWithEmail
             : [revealIdOnFallback ? described : '', emailDetail].filter(Boolean).join(', '), described);
     }
@@ -89,23 +92,22 @@ export const UserBadge = ({ userId, getUserMetadata, variant = 'avatar-name', sh
     const detail = showEmailTooltip && variant !== 'full' && userId !== 'anonymous' ? record.email : '';
     const detailText = detail ? (_jsx(VisuallyHidden, { component: "span", children: `, ${detail}` })) : null;
     const personLabel = userId === 'anonymous' ? 'Anonymous (Public)' : displayName;
+    // Alone, the avatar shows no name, so its tooltip gives it before the email. A name beside the
+    // avatar is cut with an ellipsis when long, so its tooltip gives the full name too; with no
+    // tooltip, the name carries it as a title.
+    const tooltip = variant === 'full' ? '' : [personLabel, detail].filter(Boolean).join(', ');
+    const nameTitle = showEmailTooltip && tooltip ? undefined : personLabel;
     const renderContent = () => {
         const avatar = renderAvatar();
         switch (variant) {
             case 'avatar-only':
                 return (_jsxs(Group, { gap: 0, children: [avatar, _jsx(VisuallyHidden, { component: "span", children: personLabel }), detailText] }));
             case 'full':
-                return (_jsxs(Group, { gap: 4, children: [avatar, _jsxs("div", { children: [_jsx(Text, { size: textSize, fw: 500, children: displayName }), _jsx(Text, { size: "xs", c: "dimmed", children: record.email })] })] }));
+                return (_jsxs(Group, { gap: 4, wrap: "nowrap", miw: 0, children: [avatar, _jsxs("div", { style: { minWidth: 0 }, children: [_jsx(Text, { size: textSize, fw: 500, truncate: true, title: displayName, children: displayName }), _jsx(Text, { size: "xs", c: "dimmed", truncate: true, title: record.email, children: record.email })] })] }));
             case 'avatar-name':
             default:
-                return (_jsxs(Group, { gap: 4, children: [avatar, _jsx(Text, { size: textSize, fw: 500, c: nameColor, children: personLabel }), detailText] }));
+                return (_jsxs(Group, { gap: 4, wrap: "nowrap", miw: 0, children: [avatar, _jsx(Text, { size: textSize, fw: 500, c: nameColor, truncate: true, title: nameTitle, children: personLabel }), detailText] }));
         }
     };
-    // Alone, the avatar shows no name, so its tooltip gives it before the email.
-    const tooltip = variant === 'full'
-        ? ''
-        : variant === 'avatar-only'
-            ? [personLabel, detail].filter(Boolean).join(', ')
-            : record.email;
     return wrap(renderContent(), tooltip, personLabel);
 };

package/dist/editor/copy.d.ts

@@ -13,6 +13,10 @@ export declare const EDITOR_ACTIONS: {
     readonly switchBranch: "Switch branch";
     readonly newBranch: "New branch";
     readonly remove: "Remove";
+    readonly restore: "Restore";
     readonly clear: "Clear";
+    readonly undoClear: "Undo clear";
     readonly openEntry: "Open entry";
+    readonly changeUrl: "Change URL";
+    readonly changeSlug: "Change slug";
 };

package/dist/editor/copy.js

@@ -13,6 +13,10 @@ export const EDITOR_ACTIONS = {
     switchBranch: 'Switch branch',
     newBranch: 'New branch',
     remove: 'Remove',
+    restore: 'Restore',
     clear: 'Clear',
+    undoClear: 'Undo clear',
     openEntry: 'Open entry',
+    changeUrl: 'Change URL',
+    changeSlug: 'Change slug',
 };

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

@@ -31,6 +31,14 @@ type PreviewEntry = {
 export declare const buildPreviewRoute: (entry: PreviewEntry, { previewBaseByCollection, contentRoot }: PreviewContext & {
     contentRoot?: string;
 }) => string | undefined;
+/**
+ * The entry the editor opens when none is asked for: the one whose route is `/`, else the first
+ * with a preview, else the first. `routeFor` gives the route before any prefix or base path
+ * (`buildPreviewRoute`), so `previewPrefix` and `basePath` never hide the root page.
+ */
+export declare const resolveHomeEntry: <T extends {
+    previewSrc?: string;
+}>(entries: readonly T[], routeFor?: (entry: T) => string | undefined) => T | 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
@@ -67,19 +75,51 @@ export declare const buildCollectionLabels: (collections?: EditorCollection[]) =
  * 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. */
+/**
+ * The type shown under an entry's label, in the content tree and quick open: `entryTypeLabel`,
+ * except for a singleton, whose label already is its type's (`singletonLabel`).
+ */
+export declare const entryTypeLine: (collections: EditorCollection[] | undefined, entry: Pick<EditorEntry, "collectionPath" | "entryType">) => string | undefined;
+/**
+ * An entry's second line in the content tree: "Missing" when its file is gone, else its
+ * `entryTypeLine`, else its status read as words.
+ */
 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 {
+/**
+ * Where an entry's name comes from, which "Change URL" explains. The title chain is the server's
+ * (`resolveEntryTitle`): a non-empty title-field value, else a non-empty string `title` or `name`
+ * value whatever its field's type, else the type's label, else the slug. A labelled singleton is
+ * named by its type whatever its title. `fieldLabel` is absent when no field of that name is in the
+ * schema.
+ */
+export type EntryNameSource = {
+    from: 'type';
+} | {
+    from: 'title';
+    fieldLabel?: string;
+} | {
+    from: 'slug';
+};
+/**
+ * `data` is the entry's value where it is at hand; without it, a schema with a title field, or a
+ * `title` or `name` field, is taken to name the entry from it.
+ */
+export declare const entryNameSource: (collections: EditorCollection[] | undefined, entry: Pick<EditorEntry, "collectionPath" | "entryType" | "schema">, data?: Record<string, unknown>) => EntryNameSource;
+/** One crumb before the entry's own: a collection, or a folder of a nested slug. */
+export type BreadcrumbSegment = {
+    label: string;
+    /** The collection the crumb reveals in the content panel. */
+    collectionPath: string;
+    folder?: undefined;
+} | {
     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;
-}
+    folder: true;
+    collectionPath?: undefined;
+};
 /**
- * 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.
+ * Builds breadcrumb segments for an entry based on its collection hierarchy. The first path part
+ * is skipped as the content root, which the tree does not show, so a root entry has none.
  */
 export declare const buildBreadcrumbSegments: (currentEntry: EditorEntry | undefined, collectionLabels: Map<string, string>) => BreadcrumbSegment[];
 /**

package/dist/editor/editor-utils.js

@@ -1,7 +1,8 @@
 // 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 { humanizeName, schemaLabel } from './schema-label.js';
 import { computeEntryUrl, isIndexSlug } from '../utils/entry-url.js';
+import { titleFieldPath } from '../utils/title-field.js';
 import { isDataOnlyFormat } from '../utils/format.js';
 import { isAbsoluteUrl, joinUrlPrefix, matchTrailingSlash, readTrailingSlashEnv, stripTrailingSlashes, } from '../utils/url-prefix.js';
 /**
@@ -67,6 +68,18 @@ export const buildPreviewRoute = (entry, { previewBaseByCollection, contentRoot
     const trimmed = stripTrailingSlashes(basePathPart);
     return `${encoded ? `${trimmed}/${encoded}` : basePathPart || '/'}${suffix}`;
 };
+/** Whether a `buildPreviewRoute` route is the site's root page: `/`, with any query or fragment. */
+const isHomeRoute = (route) => route !== undefined &&
+    !isAbsoluteUrl(route) &&
+    stripTrailingSlashes(splitPathSuffix(route)[0]) === '';
+/**
+ * The entry the editor opens when none is asked for: the one whose route is `/`, else the first
+ * with a preview, else the first. `routeFor` gives the route before any prefix or base path
+ * (`buildPreviewRoute`), so `previewPrefix` and `basePath` never hide the root page.
+ */
+export const resolveHomeEntry = (entries, routeFor) => (routeFor && entries.find((entry) => isHomeRoute(routeFor(entry)))) ||
+    entries.find((entry) => entry.previewSrc) ||
+    entries[0];
 /**
  * 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
@@ -129,11 +142,18 @@ export const buildWritePayload = (entry, value) => {
         body: typeof body === 'string' ? body : '',
     };
 };
+/**
+ * The label an entry of this type goes by when the type allows only one entry (`maxItems: 1`):
+ * the type's own, as "Site settings" names the site's one settings entry. Undefined for any other
+ * type, and for an unlabelled one, whose entry keeps its title.
+ */
+const singletonLabel = (type) => type.maxItems === 1 && type.label ? type.label : undefined;
 export const buildEntriesFromListResponse = ({ response, resolvePreviewSrc, flatSchema, }) => {
     return response.entries.map((entry) => {
         // Resolve schema from flatSchema using parentPath + name
         let schema = [];
         let unavailable;
+        let typeName;
         if (entry.collectionPath && entry.entryType) {
             const entryTypeItem = flatSchema.find((item) => item.type === 'entry-type' &&
                 item.parentPath === entry.collectionPath &&
@@ -141,12 +161,14 @@ export const buildEntriesFromListResponse = ({ response, resolvePreviewSrc, flat
             if (entryTypeItem && entryTypeItem.type === 'entry-type') {
                 schema = entryTypeItem.schema;
                 unavailable = entryTypeItem.unavailable;
+                typeName = singletonLabel(entryTypeItem);
             }
         }
         return {
             path: entry.logicalPath,
             contentId: entry.contentId,
-            label: entry.title || entry.slug || entry.collectionName || entry.collectionPath,
+            label: typeName || entry.title || entry.slug || entry.collectionName || entry.collectionPath,
+            ...(entry.title && { title: entry.title }),
             status: entry.exists === false ? 'missing' : (entry.entryType ?? 'entry'),
             schema: schema,
             previewSrc: resolvePreviewSrc(entry),
@@ -176,13 +198,7 @@ export const buildCollectionLabels = (collections) => {
     walk(collections);
     return map;
 };
-/**
- * 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 findEntryType = (collections, entry) => {
     const find = (nodes) => {
         for (const c of nodes) {
             if (c.path === entry.collectionPath)
@@ -194,21 +210,106 @@ export const entryTypeLabel = (collections, entry) => {
         return undefined;
     };
     const collection = collections ? find(collections) : undefined;
-    const type = collection?.entryTypes?.find((t) => t.name === entry.entryType);
-    return type?.label ?? humanizeName(entry.entryType);
+    return collection?.entryTypes?.find((t) => t.name === entry.entryType);
+};
+/**
+ * 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;
+    return findEntryType(collections, entry)?.label ?? humanizeName(entry.entryType);
 };
-/** An entry's navigator badge: "Missing" when its file is gone, else its type's label or name. */
+/**
+ * The type shown under an entry's label, in the content tree and quick open: `entryTypeLabel`,
+ * except for a singleton, whose label already is its type's (`singletonLabel`).
+ */
+export const entryTypeLine = (collections, entry) => {
+    const type = findEntryType(collections, entry);
+    return type && singletonLabel(type) ? undefined : entryTypeLabel(collections, entry);
+};
+/**
+ * An entry's second line in the content tree: "Missing" when its file is gone, else its
+ * `entryTypeLine`, else its status read as words.
+ */
 export const entryStatusLabel = (collections, entry) => {
     if (entry.status === 'missing')
         return 'Missing';
-    return entryTypeLabel(collections, entry) ?? (entry.status && humanizeName(entry.status));
+    if (entry.entryType)
+        return entryTypeLine(collections, entry);
+    return entry.status && humanizeName(entry.status);
+};
+/**
+ * `data` is the entry's value where it is at hand; without it, a schema with a title field, or a
+ * `title` or `name` field, is taken to name the entry from it.
+ */
+export const entryNameSource = (collections, entry, data) => {
+    const type = findEntryType(collections, entry);
+    if (type && singletonLabel(type))
+        return { from: 'type' };
+    const titlePath = titleFieldPath(entry.schema);
+    if (data) {
+        const plain = data.title ?? data.name;
+        const plainName = isNonEmptyString(plain) ? (data.title != null ? 'title' : 'name') : undefined;
+        if (titlePath && isNonEmptyString(valueAt(data, titlePath))) {
+            return { from: 'title', fieldLabel: pathLabel(entry.schema, titlePath) };
+        }
+        if (plainName)
+            return { from: 'title', fieldLabel: pathLabel(entry.schema, [plainName]) };
+    }
+    else {
+        if (titlePath)
+            return { from: 'title', fieldLabel: pathLabel(entry.schema, titlePath) };
+        const named = ['title', 'name'].find((name) => findField(entry.schema, name));
+        if (named)
+            return { from: 'title', fieldLabel: pathLabel(entry.schema, [named]) };
+    }
+    if (type?.label)
+        return { from: 'type' };
+    return { from: 'slug' };
+};
+const isNonEmptyString = (value) => typeof value === 'string' && value !== '';
+/** The value at a data `path`, through nested objects. */
+const valueAt = (data, path) => path.reduce((value, key) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value[key]
+    : undefined, data);
+/**
+ * The label of the field at a data `path`, with its enclosing objects' labels before it
+ * ("Hero › Heading"); undefined when the schema has no such field.
+ */
+const pathLabel = (schema, path) => {
+    const labels = [];
+    let fields = schema;
+    for (const name of path) {
+        const field = fields && findField(fields, name);
+        if (!field)
+            return undefined;
+        labels.push(schemaLabel(field));
+        fields = field.type === 'object' && 'fields' in field && !field.list ? field.fields : undefined;
+    }
+    return labels.join(' › ');
+};
+const isInlineGroup = (field) => field.type === 'group';
+/** The field named `name` among `fields`, looking through inline groups, which hold no data. */
+const findField = (fields, name) => {
+    for (const field of fields) {
+        if (isInlineGroup(field)) {
+            const inner = findField(field.fields, name);
+            if (inner)
+                return inner;
+        }
+        else if (field.name === name)
+            return field;
+    }
+    return undefined;
 };
 /**
- * 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.
+ * Builds breadcrumb segments for an entry based on its collection hierarchy. The first path part
+ * is skipped as the content root, which the tree does not show, so a root entry has none.
  */
 export const buildBreadcrumbSegments = (currentEntry, collectionLabels) => {
-    const segments = [{ label: 'All content' }];
+    const segments = [];
     if (!currentEntry)
         return segments;
     if (currentEntry.collectionPath) {

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

@@ -1,12 +1,14 @@
 /** Entry search shared by the navigator filter and the quick-open palette. */
 export interface SearchableEntry {
     label: string;
+    /** The entry's title, when its label is something else (a singleton's type label). */
+    title?: 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;
+/** Case-insensitive substring match over label, title and slug; an empty query matches everything. */
+export declare function matchesEntryQuery(entry: Pick<SearchableEntry, 'label' | 'title' | 'slug'>, query: string): boolean;
 export declare function filterEntries<T extends SearchableEntry>(entries: readonly T[], query: string): T[];
 export interface EntryGroup<T> {
     heading: string;

package/dist/editor/entry-search.js

@@ -1,11 +1,10 @@
 /** 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. */
+/** Case-insensitive substring match over label, title 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));
+    return [entry.label, entry.title, entry.slug].some((text) => text?.toLowerCase().includes(needle));
 }
 export function filterEntries(entries, query) {
     return entries.filter((entry) => matchesEntryQuery(entry, query));

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

@@ -18,7 +18,7 @@ export interface FieldLabelProps {
     labelId?: string;
     /** Slot right after the label text, for the field's comment control. */
     commentControl?: React.ReactNode;
-    /** Right-aligned slot for field actions (Expand all, Clear). */
+    /** Right-aligned slot for field actions (Expand all, an object's "…" menu); it wraps under the label when the row is too narrow for both. */
     actions?: React.ReactNode;
 }
 export declare const FieldLabel: React.FC<FieldLabelProps>;

package/dist/editor/fields/FieldLabel.js

@@ -6,7 +6,7 @@ export const FieldLabel = ({ label, required, description, descriptionBaseId, ht
     const hasRow = Boolean(label) || Boolean(commentControl) || Boolean(actions);
     if (!hasRow && !description)
         return null;
-    return (_jsxs(Stack, { gap: 2, children: [hasRow && (_jsxs(Group, { justify: "space-between", wrap: "nowrap", gap: "xs", align: "center", children: [_jsxs(Group, { gap: 4, wrap: "nowrap", style: { minWidth: 0 }, children: [label && (_jsx(Input.Label, { required: required, htmlFor: htmlFor, id: labelId, labelElement: htmlFor ? 'label' : 'div', children: label })), commentControl] }), actions && (_jsx(Group, { gap: "xs", wrap: "nowrap", style: { flexShrink: 0 }, children: actions }))] })), descriptionBaseId && (_jsx(FieldDescription, { baseId: descriptionBaseId, description: description }))] }));
+    return (_jsxs(Stack, { gap: 2, children: [hasRow && (_jsxs(Group, { justify: "space-between", wrap: "wrap", gap: "xs", align: "center", children: [_jsxs(Group, { gap: 4, wrap: "nowrap", style: { minWidth: 0, flex: '1 1 8rem' }, children: [label && (_jsx(Input.Label, { required: required, htmlFor: htmlFor, id: labelId, labelElement: htmlFor ? 'label' : 'div', children: label })), commentControl] }), actions && (_jsx(Group, { gap: "xs", wrap: "nowrap", style: { flexShrink: 0, marginLeft: 'auto' }, children: actions }))] })), descriptionBaseId && (_jsx(FieldDescription, { baseId: descriptionBaseId, description: description }))] }));
 };
 /**
  * A Mantine input under a `FieldLabel` row, in place of the input's own `label` prop, so the

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

@@ -11,7 +11,7 @@ export interface ImageFieldProps {
     description?: string;
     value: ImageFieldValue | undefined;
     onChange: (value: ImageFieldValue | undefined) => void;
-    /** "W:H" aspect ratio - when set, picking/uploading a new image opens the crop step before the value commits, and a "Crop" button appears on the filled state. */
+    /** "W:H" aspect ratio - when set, picking or uploading a new raster opens the crop step before the value commits, and Crop keeps that shape. Without it, a pick commits as is and Crop is free-form. */
     aspect?: string;
     /** Allow empty alt text. Default: required (accessibility). */
     altOptional?: boolean;

package/dist/editor/fields/ImageField.js

@@ -1,21 +1,22 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useId, useRef, useState } from 'react';
-import { Alert, Button, Group, Stack, Text, TextInput } from '@mantine/core';
+import { Alert, Button, Group, Paper, Stack, Text, TextInput, Tooltip, VisuallyHidden, } from '@mantine/core';
 import { Dropzone } from '@mantine/dropzone';
 import { IconAlertCircle, IconPhoto, IconPhotoOff, IconUpload } from '@tabler/icons-react';
-import { isAssetStoreSrc } from '../../assets/asset-url.js';
+import { EDITOR_THUMBNAIL_WIDTHS } from '../../assets/editor-thumbnail-widths.js';
 import { useAssetContext } from '../context/index.js';
 import { CropStep } from '../media/CropStep.js';
+import { cropBlockedReason } from '../media/crop-availability.js';
 import { editorImageSrc } from '../media/editor-image-src.js';
-import { parseAspectRatio } from '../media/crop-math.js';
+import { isFullFrameCrop, parseAspectRatio } from '../media/crop-math.js';
 import { MediaLibrary } from '../media/MediaLibrary.js';
 import { useAssetUpload } from '../media/useAssetUpload.js';
 import { ACCEPTED_IMAGE_MIME_TYPES, MAX_UPLOAD_BYTES } from '../media/upload-constants.js';
 import { useFieldCommentControl } from '../comments/field-comment-context.js';
-import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
+import { groupDescriptionProps } from './FieldDescription.js';
 import { FieldLabel } from './FieldLabel.js';
-const PREVIEW_WIDTH = 320;
+const PREVIEW_WIDTH = EDITOR_THUMBNAIL_WIDTHS.imageField;
 export const ImageField = ({ id, label, description, value, onChange, aspect, altOptional, dataCanopyField, errors, readOnly = false, onRemoved, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
@@ -34,8 +35,8 @@ export const ImageField = ({ id, label, description, value, onChange, aspect, al
     const previewSrc = value
         ? editorImageSrc(value.src, baseUrl, { width: PREVIEW_WIDTH, crop: value.crop })
         : undefined;
-    // `assetUrl` never applies a crop to a src outside the asset store, so one stored there never renders.
-    const canCrop = aspectRatio !== undefined && !!value && isAssetStoreSrc(value.src);
+    const cropBlocked = value ? cropBlockedReason(value.src) : undefined;
+    const cropReasonId = `${inputId}-crop-reason`;
     // Broken-preview fallback, mirroring AssetCard.tsx's thumbnail fallback (same
     // icon/copy, same reset-during-render pattern). Covers both an asset broken
     // at upload time and a transform failing at render time.
@@ -71,7 +72,7 @@ export const ImageField = ({ id, label, description, value, onChange, aspect, al
     };
     const handleAssetReady = (asset) => {
         setPickerOpen(false);
-        if (aspectRatio !== undefined) {
+        if (aspectRatio !== undefined && !cropBlockedReason(asset.src)) {
             setCropRequest({ kind: 'new', asset });
         }
         else {
@@ -102,12 +103,16 @@ export const ImageField = ({ id, label, description, value, onChange, aspect, al
         onRemoved?.(value);
         field?.focus();
     };
+    // A whole-frame rectangle stores no crop: it would only turn the image's URL into a derivative
+    // that looks the same, and it is how an editor takes a crop back off.
     const handleCropConfirm = (rect) => {
+        const crop = isFullFrameCrop(rect) ? undefined : rect;
         if (cropRequest?.kind === 'new') {
-            commitAsset(cropRequest.asset, rect);
+            commitAsset(cropRequest.asset, crop);
         }
         else if (cropRequest?.kind === 'existing' && value) {
-            edit({ ...value, crop: rect });
+            const { crop: _previous, ...rest } = value;
+            edit(crop ? { ...rest, crop } : rest);
         }
         setCropRequest(null);
     };
@@ -117,20 +122,24 @@ export const ImageField = ({ id, label, description, value, onChange, aspect, al
             ? editorImageSrc(value.src, baseUrl)
             : '';
     const cropInitial = cropRequest?.kind === 'existing' ? value?.crop : undefined;
-    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `image-field-${dataCanopyField}`, ...groupDescriptionProps(inputId, description), role: "group", "aria-label": label, "data-removal-focus": true, tabIndex: -1, children: [_jsx(FieldLabel, { label: label, commentControl: commentControl }), _jsx(FieldDescription, { baseId: inputId, description: description }), !hasValue && readOnly ? (_jsx(Text, { size: "sm", c: "dimmed", "data-testid": `image-field-empty-${dataCanopyField}`, children: "No image" })) : !hasValue ? (_jsxs(Stack, { gap: "xs", children: [_jsx(Dropzone, { onDrop: (files) => void handleDrop(files), onReject: handleReject, maxSize: MAX_UPLOAD_BYTES, accept: ACCEPTED_IMAGE_MIME_TYPES, loading: upload.uploading, multiple: false, "data-testid": `image-field-dropzone-${dataCanopyField}`, children: _jsxs(Group, { justify: "center", gap: "xs", py: "xs", style: { pointerEvents: 'none' }, children: [_jsx(IconUpload, { size: 18 }), _jsx(Text, { size: "xs", children: "Drop an image here, or click to browse" })] }) }), _jsx(Group, { justify: "center", children: _jsx(Button, { variant: "light", leftSection: _jsx(IconPhoto, { size: 14 }), onClick: () => setPickerOpen(true), "data-testid": `image-field-browse-library-${dataCanopyField}`, children: "Browse library" }) }), (upload.error || dropError) && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", children: upload.error || dropError })), errors?.src && (_jsx(Text, { size: "xs", c: "var(--canopy-danger-text)", children: errors.src }))] })) : (_jsxs(Stack, { gap: "xs", children: [previewFailed ? (_jsxs("div", { "data-testid": `image-field-preview-fallback-${dataCanopyField}`, style: {
-                            width: PREVIEW_WIDTH,
-                            height: 160,
-                            display: 'flex',
-                            flexDirection: 'column',
-                            alignItems: 'center',
-                            justifyContent: 'center',
-                            gap: 4,
-                            borderRadius: 'var(--mantine-radius-sm)',
-                            background: 'var(--canopy-surface-muted)',
-                        }, children: [_jsx(IconPhotoOff, { size: 28, stroke: 1.5, color: "var(--mantine-color-dimmed)" }), _jsx(Text, { size: "xs", c: "dimmed", children: "Preview unavailable" })] })) : (_jsx("img", { src: previewSrc, alt: value.alt, style: {
-                            maxWidth: PREVIEW_WIDTH,
-                            maxHeight: PREVIEW_WIDTH,
-                            borderRadius: 'var(--mantine-radius-sm)',
-                            display: 'block',
-                        }, onError: () => setPreviewFailed(true) })), errors?.src && (_jsx(Text, { size: "xs", c: "var(--canopy-danger-text)", children: errors.src })), _jsx(TextInput, { id: inputId, ref: altInputRef, label: "Alt text", required: !altOptional, readOnly: readOnly, value: value.alt, onChange: (event) => handleAltChange(event.currentTarget.value), error: errors?.alt, size: "sm", "data-testid": `image-field-alt-${dataCanopyField}` }), !readOnly && (_jsxs(Group, { gap: "xs", children: [_jsx(Button, { variant: "light", onClick: () => setPickerOpen(true), "data-testid": `image-field-replace-${dataCanopyField}`, children: "Replace" }), canCrop && (_jsx(Button, { variant: "light", onClick: () => setCropRequest({ kind: 'existing' }), "data-testid": `image-field-crop-${dataCanopyField}`, children: "Crop" })), _jsx(Button, { variant: "subtle", color: "red", onClick: handleRemove, "data-testid": `image-field-remove-${dataCanopyField}`, children: "Remove" })] })), errors?.crop && (_jsx(Text, { size: "xs", c: "var(--canopy-danger-text)", children: errors.crop }))] })), !readOnly && (_jsx(MediaLibrary, { opened: pickerOpen, onClose: () => setPickerOpen(false), mode: "picker", onSelect: handleAssetReady })), aspectRatio !== undefined && !readOnly && (_jsx(CropStep, { opened: cropRequest !== null, onClose: () => setCropRequest(null), imageSrc: cropImageSrc, aspect: aspectRatio, initialCrop: cropInitial, onConfirm: handleCropConfirm }))] }));
+    const actions = hasValue && !readOnly ? (_jsxs(_Fragment, { children: [_jsx(Button, { size: "compact-sm", variant: "light", onClick: () => setPickerOpen(true), "data-testid": `image-field-replace-${dataCanopyField}`, children: "Replace" }), _jsx(Tooltip, { label: cropBlocked, disabled: !cropBlocked, position: "bottom-end", multiline: true, maw: 280, children: _jsx(Button, { size: "compact-sm", variant: "light", onClick: () => {
+                        if (!cropBlocked)
+                            setCropRequest({ kind: 'existing' });
+                    }, "data-disabled": cropBlocked ? true : undefined, "aria-disabled": cropBlocked ? true : undefined, "aria-describedby": cropBlocked ? cropReasonId : undefined, "data-testid": `image-field-crop-${dataCanopyField}`, children: "Crop" }) }), cropBlocked && _jsx(VisuallyHidden, { id: cropReasonId, children: cropBlocked }), _jsx(Button, { size: "compact-sm", variant: "subtle", color: "red", onClick: handleRemove, "data-testid": `image-field-remove-${dataCanopyField}`, children: "Remove" })] })) : undefined;
+    return (_jsx(Paper, { withBorder: true, p: "md", bg: "var(--canopy-surface-subtle)", shadow: "xs", "data-canopy-field": dataCanopyField, "data-testid": `image-field-${dataCanopyField}`, ...groupDescriptionProps(inputId, description), role: "group", "aria-label": label, "data-removal-focus": true, tabIndex: -1, children: _jsxs(Stack, { gap: "sm", children: [_jsx(FieldLabel, { label: label, description: description, descriptionBaseId: inputId, commentControl: commentControl, actions: actions }), !hasValue && readOnly ? (_jsx(Text, { size: "sm", c: "dimmed", "data-testid": `image-field-empty-${dataCanopyField}`, children: "No image" })) : !hasValue ? (_jsxs(Stack, { gap: "xs", children: [_jsx(Dropzone, { onDrop: (files) => void handleDrop(files), onReject: handleReject, maxSize: MAX_UPLOAD_BYTES, accept: ACCEPTED_IMAGE_MIME_TYPES, loading: upload.uploading, multiple: false, "data-testid": `image-field-dropzone-${dataCanopyField}`, children: _jsxs(Group, { justify: "center", gap: "xs", py: "xs", style: { pointerEvents: 'none' }, children: [_jsx(IconUpload, { size: 18 }), _jsx(Text, { size: "xs", children: "Drop an image here, or click to browse" })] }) }), _jsx(Group, { justify: "center", children: _jsx(Button, { variant: "light", leftSection: _jsx(IconPhoto, { size: 14 }), onClick: () => setPickerOpen(true), "data-testid": `image-field-browse-library-${dataCanopyField}`, children: "Browse library" }) }), (upload.error || dropError) && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", children: upload.error || dropError })), errors?.src && (_jsx(Text, { size: "xs", c: "var(--canopy-danger-text)", children: errors.src }))] })) : (_jsxs(Stack, { gap: "xs", children: [previewFailed ? (_jsxs("div", { "data-testid": `image-field-preview-fallback-${dataCanopyField}`, style: {
+                                width: PREVIEW_WIDTH,
+                                height: 160,
+                                display: 'flex',
+                                flexDirection: 'column',
+                                alignItems: 'center',
+                                justifyContent: 'center',
+                                gap: 4,
+                                borderRadius: 'var(--mantine-radius-sm)',
+                                background: 'var(--canopy-surface-muted)',
+                            }, children: [_jsx(IconPhotoOff, { size: 28, stroke: 1.5, color: "var(--mantine-color-dimmed)" }), _jsx(Text, { size: "xs", c: "dimmed", children: "Preview unavailable" })] })) : (_jsx("img", { src: previewSrc, alt: value.alt, style: {
+                                maxWidth: PREVIEW_WIDTH,
+                                maxHeight: PREVIEW_WIDTH,
+                                borderRadius: 'var(--mantine-radius-sm)',
+                                display: 'block',
+                            }, onError: () => setPreviewFailed(true) })), errors?.src && (_jsx(Text, { size: "xs", c: "var(--canopy-danger-text)", children: errors.src })), _jsx(TextInput, { id: inputId, ref: altInputRef, label: "Alt text", required: !altOptional, readOnly: readOnly, value: value.alt, onChange: (event) => handleAltChange(event.currentTarget.value), error: errors?.alt, size: "sm", "data-testid": `image-field-alt-${dataCanopyField}` }), errors?.crop && (_jsx(Text, { size: "xs", c: "var(--canopy-danger-text)", children: errors.crop }))] })), !readOnly && (_jsx(MediaLibrary, { opened: pickerOpen, onClose: () => setPickerOpen(false), mode: "picker", onSelect: handleAssetReady })), !readOnly && (_jsx(CropStep, { opened: cropRequest !== null, onClose: () => setCropRequest(null), imageSrc: cropImageSrc, aspect: aspectRatio, initialCrop: cropInitial, onConfirm: handleCropConfirm }))] }) }));
 };

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

@@ -11,7 +11,18 @@ export interface ObjectFieldProps {
     renderField: RenderField;
     path: Array<string | number>;
     dataCanopyField?: string;
-    /** Set, shows a gray "Clear" resetting the field to `undefined`; omitted for list items. */
-    onRemove?: () => void;
+    /** Set, a "…" menu offers Clear, resetting the field to `undefined`; omitted for list items. */
+    onClear?: () => void;
+    /** Set, an "Undo clear" button stands in the label row in place of the "…" menu. */
+    onUndoClear?: () => void;
+    /** Said with the Undo, such as where the object's comment threads went. */
+    clearNote?: string;
 }
+/**
+ * An object field's group of fields. Its Clear is an Undo-instead-of-confirm removal
+ * (docs/ux-guidelines.md, Destructive actions) whose Undo stays in the label row, where the clear
+ * happened, with no timer, until the caller drops `onUndoClear`. FormRenderer drops it once it
+ * can no longer put the object back where it was, another entry or branch opens, or the entry is
+ * saved or its draft discarded.
+ */
 export declare const ObjectField: React.FC<ObjectFieldProps>;