canopycms 0.0.67 → 0.0.68-int.100

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

@@ -1,4 +1,4 @@
-import type { CanopyConfig, FlatSchemaItem } from '../config/index.js';
+import type { FlatSchemaItem } from '../config/index.js';
 import type { EditorCollection } from './Editor.js';
 /**
  * Build hierarchical editor collections from the flattened schema.
@@ -10,4 +10,3 @@ import type { EditorCollection } from './Editor.js';
  * shown as separate nodes in the navigation tree.
  */
 export declare const buildEditorCollections: (flatSchema: FlatSchemaItem[]) => EditorCollection[];
-export declare const buildPreviewBaseByCollection: (config: Pick<CanopyConfig, "contentRoot">, flatSchema: FlatSchemaItem[]) => Record<string, string>;

package/dist/editor/editor-config.js

@@ -1,14 +1,3 @@
-import { trimSlashes } from '../paths/normalize.js';
-const normalizeContentRoot = (value) => {
-    return trimSlashes(value ?? 'content');
-};
-const stripContentRoot = (logicalPath, contentRoot) => {
-    const prefix = contentRoot ? `${contentRoot}/` : '';
-    if (prefix && logicalPath.startsWith(prefix)) {
-        return logicalPath.slice(prefix.length);
-    }
-    return logicalPath;
-};
 /**
  * Build hierarchical editor collections from the flattened schema.
  * Uses logicalPath as IDs to match API responses.
@@ -64,15 +53,3 @@ export const buildEditorCollections = (flatSchema) => {
     // This now includes the content root collection itself
     return buildTree(undefined);
 };
-export const buildPreviewBaseByCollection = (config, flatSchema) => {
-    const contentRoot = normalizeContentRoot(config.contentRoot);
-    const flat = flatSchema;
-    const map = {};
-    for (const item of flat) {
-        // Strip content root from all items and normalize to preview URL
-        const base = stripContentRoot(item.logicalPath, contentRoot);
-        const normalizedBase = base ? `/${base}` : '/';
-        map[item.logicalPath] = normalizedBase;
-    }
-    return map;
-};

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

@@ -3,36 +3,38 @@ import type { ContentFormat, FlatSchemaItem } from '../config/index.js';
 import type { FormValue } from './FormRenderer.js';
 import type { EditorEntry, EditorCollection } from './Editor.js';
 import type { TreeNodeData } from '@mantine/core';
-import { normalizeCollectionPath } from '../paths/normalize.js';
-/** @internal Exported for tests. */
-export { normalizeCollectionPath };
 export interface PreviewContext {
     branchName?: string;
-    previewBaseByCollection?: Record<string, string>;
+    /** `editor.previewBase`: routes by root entry path, collection path or name; `false` is no page. */
+    previewBaseByCollection?: Record<string, string | false>;
+    /** `editor.previewPrefix`: where the host mounts the pages the preview pane loads. */
+    previewPrefix?: string;
 }
-/**
- * Builds the preview iframe `src` for an entry, prefixed with the deployment `basePath`
- * (`CanopyClientConfig.basePath`, e.g. `/preview-123`) when configured.
- *
- * This matters twice: the raw `<iframe src>` (`PreviewFrame` in preview-bridge.tsx) 404s
- * without the prefix under a basePath, and `resolvePreviewPath` there compares the same
- * string against `window.location.pathname` -- which browsers report WITH the basePath --
- * so an unprefixed `previewSrc` also breaks draft sync / click-to-focus even when the
- * iframe itself resolves.
- *
- * Applied via `joinUrlPrefix`: a no-op when `basePath` is unset, and passes an
- * already-absolute `previewSrc` (a cross-origin override) through untouched.
- */
-export declare const buildPreviewSrc: (entry: {
+type PreviewEntry = {
     collectionPath?: string;
     collectionName?: string;
     slug?: string;
     itemType?: string;
     previewSrc?: string;
-}, context: PreviewContext & {
+};
+/**
+ * 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
+ * trailing-slash form, with `?branch=`. An absolute prefix skips the `basePath`. An absolute route
+ * (from `previewBaseByCollection`) skips all three and gets only `?branch=`. An entry's own
+ * `previewSrc` gets only the `basePath`.
+ *
+ * The result must equal the framed page's own URL: the `<iframe src>` (`PreviewFrame` in
+ * preview-bridge.tsx) 404s without the prefixes, and a URL the host redirects costs a round trip
+ * on every load. `trailingSlash` defaults to the value `withCanopy` inlines at build time.
+ *
+ * `undefined` means the entry has no page, so the editor frames nothing rather than another page.
+ */
+export declare const buildPreviewSrc: (entry: PreviewEntry, context: PreviewContext & {
     contentRoot?: string;
     basePath?: string;
-}) => string;
+    trailingSlash?: boolean;
+}) => string | undefined;
 export declare const normalizeContentPayload: (raw: unknown) => FormValue;
 export declare const buildWritePayload: (entry: {
     collectionPath?: string;
@@ -41,7 +43,7 @@ export declare const buildWritePayload: (entry: {
 }, value: FormValue) => FormValue;
 interface BuildEntriesFromListParams {
     response: ListEntriesResponse;
-    resolvePreviewSrc: (entry: Pick<CollectionItem, 'collectionPath' | 'collectionName' | 'slug' | 'entryType'>) => string;
+    resolvePreviewSrc: (entry: Pick<CollectionItem, 'collectionPath' | 'collectionName' | 'slug' | 'entryType'>) => string | undefined;
     flatSchema: FlatSchemaItem[];
 }
 export declare const buildEntriesFromListResponse: ({ response, resolvePreviewSrc, flatSchema, }: BuildEntriesFromListParams) => EditorEntry[];
@@ -63,3 +65,4 @@ export declare const buildBreadcrumbSegments: (currentEntry: EditorEntry | undef
  * @returns Record<string, boolean> - Expanded state object where keys are collection node values
  */
 export declare const calculatePathToEntry: (entryPath: string | undefined, treeData: TreeNodeData[]) => Record<string, boolean>;
+export {};

package/dist/editor/editor-utils.js

@@ -1,84 +1,97 @@
 // Import directly from normalize to avoid pulling in server-only branch.ts
-import { normalizeCollectionPath } from '../paths/normalize.js';
-import { isIndexSlug } from '../utils/entry-url.js';
+import { normalizeFilesystemPath } from '../paths/normalize.js';
+import { computeEntryUrl, isIndexSlug } from '../utils/entry-url.js';
 import { isDataOnlyFormat } from '../utils/format.js';
-import { joinUrlPrefix } from '../utils/url-prefix.js';
-/** @internal Exported for tests. */
-export { normalizeCollectionPath };
+import { isAbsoluteUrl, joinUrlPrefix, matchTrailingSlash, readTrailingSlashEnv, stripTrailingSlashes, } from '../utils/url-prefix.js';
 /**
- * The slug portion of a preview URL, or '' for an index entry -- `resolveUrlPathCandidates`
+ * The slug a `previewBase` route is extended by, or '' for an index entry: an index entry's URL
+ * is its collection's, the collapse `computeEntryUrl` applies, and `resolveUrlPathCandidates`
  * refuses `/x/index`, so a preview built that way 404s.
- *
- * An index entry's URL is its COLLECTION's path, the same collapse `computeEntryUrl`,
- * `listEntries`, and `defaultBuildPath` apply.
- *
- * Kept separate from `computeEntryUrl`, which shares only the index decision: this builder
- * must percent-encode each segment and must NOT lowercase, since a preview base is
- * adopter-supplied and case-sensitive.
  */
-const encodePreviewSlug = (slug) => (isIndexSlug(slug) ? '' : encodeSlug(slug));
-const encodeSlug = (value) => (value ?? '')
+const encodePreviewSlug = (slug) => (isIndexSlug(slug) ? '' : encodeSegments(slug));
+const encodeSegments = (value) => (value ?? '')
     .split('/')
     .filter(Boolean)
     .map((segment) => encodeURIComponent(segment))
     .join('/');
+/** Splits `url` before its query or fragment, so a path can be extended without entering either. */
+const splitPathSuffix = (url) => {
+    const index = url.search(/[?#]/);
+    return index === -1 ? [url, ''] : [url.slice(0, index), url.slice(index)];
+};
+/** Adds `?branch=` to the query, ahead of any fragment. */
+const appendBranch = (url, branchName) => {
+    if (!branchName)
+        return url;
+    const hashIndex = url.indexOf('#');
+    const beforeHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+    const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
+    const separator = beforeHash.includes('?') ? '&' : '?';
+    return `${beforeHash}${separator}branch=${encodeURIComponent(branchName)}${hash}`;
+};
 /**
- * Builds the (unprefixed) preview URL -- see `buildPreviewSrc` below, which wraps this with the
- * deployment `basePath`. Split out so that prefixing happens exactly once, at the end, uniformly
- * across every branch (including the `entry.previewSrc` escape hatch).
+ * The `previewBase` value under `key`, or `undefined` for none. An empty value counts as none, and
+ * so does anything `Object.prototype` supplies.
  */
-const buildRawPreviewSrc = (entry, { branchName, previewBaseByCollection, contentRoot }) => {
-    if (entry.previewSrc)
-        return entry.previewSrc;
-    const appendBranch = (url) => {
-        if (!branchName)
-            return url;
-        const separator = url.includes('?') ? '&' : '?';
-        return `${url}${separator}branch=${encodeURIComponent(branchName)}`;
-    };
-    // Root-level entries have collectionPath === contentRoot (e.g., 'content')
-    const isRootEntry = contentRoot && entry.collectionPath === contentRoot;
-    if (isRootEntry) {
-        const customPreview = previewBaseByCollection?.[`${contentRoot}/${entry.slug}`];
-        if (customPreview) {
-            return appendBranch(customPreview);
-        }
-        return appendBranch('/');
-    }
-    const base = (entry.collectionPath && previewBaseByCollection?.[entry.collectionPath]) ??
-        (entry.collectionName && previewBaseByCollection?.[entry.collectionName]);
-    if (!base) {
-        // Pass contentRoot through so a non-default (or multi-segment, e.g.
-        // "cms/content") configured root is stripped too; normalizeCollectionPath
-        // defaults to 'content' when contentRoot is undefined.
-        const collectionPath = entry.collectionPath
-            ? normalizeCollectionPath(entry.collectionPath, contentRoot)
-            : '';
-        const encoded = encodePreviewSlug(entry.slug);
-        const segments = [collectionPath, encoded].filter(Boolean);
-        const url = segments.length > 0 ? `/${segments.join('/')}` : '/';
-        return appendBranch(url);
+const previewBaseFor = (bases, key) => bases && key && Object.prototype.hasOwnProperty.call(bases, key) && bases[key] !== ''
+    ? bases[key]
+    : undefined;
+/**
+ * The entry's route on the host site, or `undefined` when it has no page. The first
+ * `previewBaseByCollection` key present decides: for a root entry its own path
+ * (`<contentRoot>/<slug>`, used as-is), then its collection path, then its collection name (both
+ * with the slug appended). The spelling `<parent>/<name>` names both an entry and a same-named
+ * sibling collection (a landing entry beside its folder), so below the root it is read only as a
+ * collection key, and at the root one key routes both.
+ * A `false` value means no page. With no key, the route is the entry's `urlPath`, by the rule
+ * `listEntries` publishes it, so a root entry previews at `/<slug>` and only a root index at `/`.
+ * Site-relative unless a matching value is absolute.
+ */
+const buildPreviewRoute = (entry, { previewBaseByCollection, contentRoot = 'content' }) => {
+    const collectionPath = normalizeFilesystemPath(entry.collectionPath ?? '');
+    const isRootEntry = collectionPath === normalizeFilesystemPath(contentRoot);
+    const entryRoute = previewBaseFor(previewBaseByCollection, isRootEntry && entry.slug ? `${collectionPath}/${entry.slug}` : undefined);
+    if (entryRoute !== undefined)
+        return entryRoute === false ? undefined : entryRoute;
+    const pathBase = previewBaseFor(previewBaseByCollection, collectionPath);
+    const base = pathBase ?? previewBaseFor(previewBaseByCollection, entry.collectionName);
+    if (base === false)
+        return undefined;
+    if (base === undefined) {
+        const urlPath = computeEntryUrl(collectionPath, entry.slug ?? '', contentRoot);
+        return `/${encodeSegments(urlPath)}`;
     }
-    const trimmed = base.endsWith('/') ? base.slice(0, -1) : base;
     const encoded = encodePreviewSlug(entry.slug);
-    const url = encoded ? `${trimmed}/${encoded}` : trimmed || '/';
-    return appendBranch(url);
+    const [basePathPart, suffix] = splitPathSuffix(base);
+    const trimmed = stripTrailingSlashes(basePathPart);
+    return `${encoded ? `${trimmed}/${encoded}` : basePathPart || '/'}${suffix}`;
 };
 /**
- * Builds the preview iframe `src` for an entry, prefixed with the deployment `basePath`
- * (`CanopyClientConfig.basePath`, e.g. `/preview-123`) when configured.
+ * 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
+ * trailing-slash form, with `?branch=`. An absolute prefix skips the `basePath`. An absolute route
+ * (from `previewBaseByCollection`) skips all three and gets only `?branch=`. An entry's own
+ * `previewSrc` gets only the `basePath`.
  *
- * This matters twice: the raw `<iframe src>` (`PreviewFrame` in preview-bridge.tsx) 404s
- * without the prefix under a basePath, and `resolvePreviewPath` there compares the same
- * string against `window.location.pathname` -- which browsers report WITH the basePath --
- * so an unprefixed `previewSrc` also breaks draft sync / click-to-focus even when the
- * iframe itself resolves.
+ * The result must equal the framed page's own URL: the `<iframe src>` (`PreviewFrame` in
+ * preview-bridge.tsx) 404s without the prefixes, and a URL the host redirects costs a round trip
+ * on every load. `trailingSlash` defaults to the value `withCanopy` inlines at build time.
  *
- * Applied via `joinUrlPrefix`: a no-op when `basePath` is unset, and passes an
- * already-absolute `previewSrc` (a cross-origin override) through untouched.
+ * `undefined` means the entry has no page, so the editor frames nothing rather than another page.
  */
 export const buildPreviewSrc = (entry, context) => {
-    return joinUrlPrefix(context.basePath, buildRawPreviewSrc(entry, context));
+    if (entry.previewSrc)
+        return joinUrlPrefix(context.basePath, entry.previewSrc);
+    const route = buildPreviewRoute(entry, context);
+    if (route === undefined)
+        return undefined;
+    // An absolute route is another site's URL, so the host's trailing-slash form says nothing
+    // about it.
+    if (isAbsoluteUrl(route))
+        return appendBranch(route, context.branchName);
+    const mounted = joinUrlPrefix(context.basePath, joinUrlPrefix(context.previewPrefix, route));
+    const shaped = matchTrailingSlash(mounted, context.trailingSlash ?? readTrailingSlashEnv());
+    return appendBranch(shaped, context.branchName);
 };
 export const normalizeContentPayload = (raw) => {
     const candidate = raw;

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

@@ -7,6 +7,7 @@ export interface BlockInstance {
 type RenderField = (field: FieldConfig, value: unknown, onChange: (v: unknown) => void, path: Array<string | number>) => React.ReactNode;
 export interface BlockFieldProps {
     label?: string;
+    description?: string;
     templates: BlockConfig[];
     value: BlockInstance[];
     onChange: (blocks: BlockInstance[]) => void;

package/dist/editor/fields/BlockField.js

@@ -1,12 +1,13 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { useMemo, useState } from 'react';
+import React, { useId, useMemo, useState } from 'react';
 let blockKeyCounter = 0;
 import { ActionIcon, Button, Group, Paper, Select, Stack, Text } from '@mantine/core';
 import { DndContext, KeyboardSensor, PointerSensor, useSensor, useSensors, } from '@dnd-kit/core';
 import { SortableContext, arrayMove, sortableKeyboardCoordinates, useSortable, verticalListSortingStrategy, } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import { formatCanopyPath } from '../canopy-path.js';
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 const findTemplate = (templates, name) => templates.find((t) => t.name === name);
 const SortableBlock = ({ id, children }) => {
     const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
@@ -19,7 +20,8 @@ const SortableBlock = ({ id, children }) => {
     };
     return (_jsx(Paper, { ref: setNodeRef, withBorder: true, radius: "md", p: "sm", shadow: "xs", style: style, children: _jsxs(Group, { align: "flex-start", gap: "sm", children: [_jsx(ActionIcon, { variant: "subtle", "aria-label": "Drag to reorder", ...attributes, ...listeners, style: { cursor: 'grab' }, children: "\u21C5" }, "drag-handle"), _jsx("div", { style: { flex: 1, minWidth: 0, width: '100%' }, children: children }, "content")] }) }));
 };
-export const BlockField = ({ label, templates, value, onChange, renderField, path, dataCanopyField, }) => {
+export const BlockField = ({ label, description, templates, value, onChange, renderField, path, dataCanopyField, }) => {
+    const descriptionBaseId = useId();
     const [itemKeys, setItemKeys] = useState(() => value.map(() => `block-${blockKeyCounter++}`));
     const [pendingTemplate, setPendingTemplate] = useState(null);
     // Keeps itemKeys in sync with value's length; setState runs directly in render, not an effect.
@@ -69,12 +71,12 @@ export const BlockField = ({ label, templates, value, onChange, renderField, pat
         moveBlock(oldIndex, newIndex);
     };
     const selectableTemplates = useMemo(() => templates.map((t) => ({ value: t.name, label: t.label ?? t.name })), [templates]);
-    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", "data-canopy-field": dataCanopyField ?? formatCanopyPath(path), shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Group, { justify: "space-between", children: [_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label ?? 'Blocks' }), _jsx(Select, { "aria-label": "Add block", placeholder: "Add block...", data: selectableTemplates, value: pendingTemplate, onChange: (next) => {
+    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", "data-canopy-field": dataCanopyField ?? formatCanopyPath(path), shadow: "xs", ...groupDescriptionProps(descriptionBaseId, description), children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Group, { justify: "space-between", children: [_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label ?? 'Blocks' }), _jsx(Select, { "aria-label": "Add block", placeholder: "Add block...", data: selectableTemplates, value: pendingTemplate, onChange: (next) => {
                                 if (next) {
                                     addBlock(next);
                                 }
                                 setPendingTemplate(null);
-                            }, allowDeselect: true, size: "xs", w: 180 })] }), _jsx(DndContext, { sensors: sensors, onDragEnd: handleDragEnd, children: _jsx(SortableContext, { items: itemKeys, strategy: verticalListSortingStrategy, children: _jsx(Stack, { gap: "sm", children: value.map((block, idx) => {
+                            }, allowDeselect: true, size: "xs", w: 180 })] }), _jsx(FieldDescription, { baseId: descriptionBaseId, description: description }), _jsx(DndContext, { sensors: sensors, onDragEnd: handleDragEnd, children: _jsx(SortableContext, { items: itemKeys, strategy: verticalListSortingStrategy, children: _jsx(Stack, { gap: "sm", children: value.map((block, idx) => {
                                 const template = findTemplate(templates, block.template);
                                 const currentPath = [...path, idx];
                                 return (_jsx(SortableBlock, { id: itemKeys[idx], children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Group, { justify: "space-between", align: "flex-start", children: [_jsx(Text, { size: "sm", fw: 600, children: template?.label ?? block.template ?? 'Unknown block' }), _jsxs(Group, { gap: 4, children: [_jsx(ActionIcon, { variant: "light", "aria-label": "Move block up", disabled: idx === 0, onClick: () => moveBlock(idx, idx - 1), children: "\u2191" }), _jsx(ActionIcon, { variant: "light", "aria-label": "Move block down", disabled: idx === value.length - 1, onClick: () => moveBlock(idx, idx + 1), children: "\u2193" }), _jsx(Button, { variant: "subtle", color: "red", size: "xs", onClick: () => removeBlock(idx), children: "Remove" })] })] }), template ? (_jsx(Stack, { gap: "sm", children: template.fields.map((f) => (_jsx(React.Fragment, { children: renderField(f, block.value?.[f.name], (next) => updateBlockValue(idx, {

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

@@ -2,6 +2,7 @@ import React from 'react';
 export interface CodeFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string;
     onChange: (value: string) => void;
     language?: string;

package/dist/editor/fields/CodeField.js

@@ -2,8 +2,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from 'react';
 import { Textarea } from '@mantine/core';
 // Placeholder for Monaco integration; host app can provide custom renderer for production.
-export const CodeField = ({ id, label, value, onChange, language, dataCanopyField, }) => {
+export const CodeField = ({ id, label, description, value, onChange, language, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(Textarea, { id: inputId, label: label, value: value, onChange: (e) => onChange(e.currentTarget.value), placeholder: language ? `Code (${language})` : 'Code', autosize: true, minRows: 6, size: "sm", "data-canopy-field": dataCanopyField, styles: { input: { fontFamily: 'Menlo, Consolas, monospace' } } }));
+    return (_jsx(Textarea, { id: inputId, label: label, description: description, value: value, onChange: (e) => onChange(e.currentTarget.value), placeholder: language ? `Code (${language})` : 'Code', autosize: true, minRows: 6, size: "sm", "data-canopy-field": dataCanopyField, styles: { input: { fontFamily: 'Menlo, Consolas, monospace' } } }));
 };

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

@@ -2,6 +2,7 @@ import React from 'react';
 export interface DateTimeFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string;
     onChange: (value: string) => void;
     dataCanopyField?: string;

package/dist/editor/fields/DateTimeField.js

@@ -49,8 +49,8 @@ export function datetimeLocalValueToIso(local) {
  * round-trip; sub-second precision is not preserved (no milliseconds field),
  * so a value with non-zero milliseconds is zeroed out once resaved.
  */
-export const DateTimeField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const DateTimeField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(Input.Wrapper, { id: inputId, label: label, size: "sm", children: _jsx(Input, { type: "datetime-local", step: 1, size: "sm", value: isoToDatetimeLocalValue(value), onChange: (e) => onChange(datetimeLocalValueToIso(e.currentTarget.value)), "data-canopy-field": dataCanopyField }) }));
+    return (_jsx(Input.Wrapper, { id: inputId, label: label, description: description, size: "sm", children: _jsx(Input, { type: "datetime-local", step: 1, size: "sm", value: isoToDatetimeLocalValue(value), onChange: (e) => onChange(datetimeLocalValueToIso(e.currentTarget.value)), "data-canopy-field": dataCanopyField }) }));
 };

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

@@ -0,0 +1,16 @@
+import React from 'react';
+/** The id Mantine gives a native input's description, so custom fields match it. */
+export declare const fieldDescriptionId: (baseId: string) => string;
+/**
+ * Guidance text for fields that don't use a Mantine input's native `description` prop.
+ * Renders nothing for an absent or empty description.
+ */
+export declare const FieldDescription: React.FC<{
+    baseId: string;
+    description?: string;
+}>;
+/** Props that tie a custom field's container to its `FieldDescription`; empty without one. */
+export declare const groupDescriptionProps: (baseId: string, description: string | undefined) => {
+    role?: "group";
+    "aria-describedby"?: string;
+};

package/dist/editor/fields/FieldDescription.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Input } from '@mantine/core';
+/** The id Mantine gives a native input's description, so custom fields match it. */
+export const fieldDescriptionId = (baseId) => `${baseId}-description`;
+/**
+ * Guidance text for fields that don't use a Mantine input's native `description` prop.
+ * Renders nothing for an absent or empty description.
+ */
+export const FieldDescription = ({ baseId, description, }) => description ? (_jsx(Input.Description, { id: fieldDescriptionId(baseId), children: description })) : null;
+/** Props that tie a custom field's container to its `FieldDescription`; empty without one. */
+export const groupDescriptionProps = (baseId, description) => description ? { role: 'group', 'aria-describedby': fieldDescriptionId(baseId) } : {};

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

@@ -8,6 +8,7 @@ interface ImageFieldErrors {
 export interface ImageFieldProps {
     id?: string;
     label?: string;
+    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. */

package/dist/editor/fields/ImageField.js

@@ -11,8 +11,9 @@ import { 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 { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 const PREVIEW_WIDTH = 320;
-export const ImageField = ({ id, label, value, onChange, aspect, altOptional, dataCanopyField, errors, }) => {
+export const ImageField = ({ id, label, description, value, onChange, aspect, altOptional, dataCanopyField, errors, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const { baseUrl } = useAssetContext();
@@ -101,7 +102,7 @@ export const ImageField = ({ id, label, value, onChange, aspect, altOptional, da
             ? assetUrl({ src: 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}`, children: [label && (_jsx(Text, { size: "sm", fw: 500, children: label })), !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", size: "xs", 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: "red", children: errors.src }))] })) : (_jsxs(Stack, { gap: "xs", children: [previewFailed ? (_jsxs("div", { "data-testid": `image-field-preview-fallback-${dataCanopyField}`, style: {
+    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `image-field-${dataCanopyField}`, ...groupDescriptionProps(inputId, description), children: [label && (_jsx(Text, { size: "sm", fw: 500, children: label })), _jsx(FieldDescription, { baseId: inputId, description: description }), !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", size: "xs", 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: "red", 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',

package/dist/editor/fields/InlineGroupField.js

@@ -1,8 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
 import { Paper, Stack, Text } from '@mantine/core';
 import { formatCanopyPath } from '../canopy-path.js';
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 export const InlineGroupField = ({ label, description, fields, value, onChange, renderField, path, }) => {
-    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [(label || description) && (_jsxs(Stack, { gap: 2, children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label })), description && (_jsx(Text, { size: "xs", c: "dimmed", children: description }))] })), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
+    const descriptionBaseId = useId();
+    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", shadow: "xs", ...groupDescriptionProps(descriptionBaseId, description), children: _jsxs(Stack, { gap: "sm", children: [(label || description) && (_jsxs(Stack, { gap: 2, children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label })), _jsx(FieldDescription, { baseId: descriptionBaseId, description: description })] })), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
                         // Nested inline groups are also transparent — pass the same parent value/onChange
                         if (field.type === 'group') {
                             const childGroup = field;

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

@@ -2,6 +2,7 @@ import React from 'react';
 export interface MarkdownFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string;
     onChange: (value: string) => void;
     dataCanopyField?: string;