canopycms 0.2.0-int.119 → 0.2.0

package/dist/editor/hooks/editor-history.js

@@ -0,0 +1,80 @@
+/** Session-history writes stamped with their position, so a refused Back can be undone. */
+const STAMP_KEY = 'canopyHistory';
+// Next.js's router keys: its patched history methods copy `__NA` and the tree back and record the
+// URL, but do neither for state already holding `__NA` or `_N` (app-router.js, next 15.5).
+const ROUTER_KEYS = ['__NA', '__PRIVATE_NEXTJS_INTERNALS_TREE', '_N'];
+// A run restarts wherever the position is lost, so positions from two runs are never compared.
+let run = '';
+let position;
+let undoTarget;
+const newRun = () => {
+    run = Math.random().toString(36).slice(2);
+    position = undefined;
+};
+const currentState = () => {
+    const state = window.history.state;
+    return state !== null && typeof state === 'object' ? { ...state } : {};
+};
+const stampIn = (state) => {
+    const value = state[STAMP_KEY];
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const [stampRun, at] = [Reflect.get(value, 'run'), Reflect.get(value, 'position')];
+    return typeof stampRun === 'string' && typeof at === 'number'
+        ? { run: stampRun, position: at }
+        : undefined;
+};
+const samePage = (a, b) => {
+    const [x, y] = [new URL(a, window.location.href), new URL(b, window.location.href)];
+    const query = (u) => new URLSearchParams(u.search).toString();
+    return (x.origin === y.origin && x.pathname === y.pathname && query(x) === query(y) && x.hash === y.hash);
+};
+/** Shows `url`, pushed, or replaced keeping the entry's other state; never rewrites the URL shown. */
+export function writeEditorUrl(url, push) {
+    if (samePage(url, window.location.href))
+        return;
+    if (!run)
+        newRun();
+    const at = (position ?? 0) + (push ? 1 : 0);
+    const kept = push ? {} : currentState();
+    for (const key of ROUTER_KEYS)
+        delete kept[key];
+    const method = push ? window.history.pushState : window.history.replaceState;
+    method.call(window.history, { ...kept, [STAMP_KEY]: { run, position: at } }, '', url);
+    position = at;
+}
+/** Stamps the history entry the editor opened on, keeping Next.js's keys: the URL is unchanged. */
+export function markEditorHistoryStart() {
+    const state = currentState();
+    const stamp = stampIn(state);
+    if (stamp) {
+        run = stamp.run;
+        position = stamp.position;
+        return;
+    }
+    newRun();
+    position = 0;
+    window.history.replaceState({ ...state, [STAMP_KEY]: { run, position } }, '', window.location.href);
+}
+/** On `popstate`: entries moved, undefined if an end is not this run's, null for an undo's. */
+export function recordHistoryMove() {
+    const arrived = stampIn(currentState());
+    const undone = undoTarget !== undefined &&
+        arrived?.run === undoTarget.run &&
+        arrived.position === undoTarget.position;
+    undoTarget = undefined;
+    const moved = arrived?.run === run && position !== undefined ? arrived.position - position : undefined;
+    if (arrived) {
+        run = arrived.run;
+        position = arrived.position;
+    }
+    else
+        newRun();
+    return undone ? null : moved;
+}
+export function undoHistoryMove(moved) {
+    if (position === undefined)
+        return;
+    undoTarget = { run, position: position - moved };
+    window.history.go(-moved);
+}

package/dist/editor/hooks/useBranchActions.js

@@ -5,6 +5,7 @@ import { notifications } from '@mantine/notifications';
 import { Text } from '@mantine/core';
 import { useApiClient } from '../context/index.js';
 import { requestBranchCreate } from './create-branch-request.js';
+import { writeEditorUrl } from './editor-history.js';
 const MAX_LISTED_LABELS = 5;
 /** 'Unsaved changes in: "A", "B".' */
 export const describeUnsaved = ({ labels }) => {
@@ -25,10 +26,11 @@ export function useBranchActions(options) {
     const [confirmOpen, setConfirmOpen] = useState(false);
     const performBranchSwitch = (next) => {
         options.setBranchName(next);
+        // Its own history entry; a Back onto another branch already shows this URL, so writes nothing.
         if (typeof window !== 'undefined') {
             const url = new URL(window.location.href);
             url.searchParams.set('branch', next);
-            window.history.replaceState({}, '', url.toString());
+            writeEditorUrl(url.toString(), true);
         }
         options.onBranchSwitch?.(next);
     };

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

@@ -88,6 +88,8 @@ export interface UseBranchManagerReturn {
     branches: BranchListItem[];
     branchSummaries: BranchSummary[];
     currentBranch: BranchListItem | undefined;
+    /** The listing failed and nothing earlier stands in for it. */
+    branchesLoadFailed: boolean;
     /** Shows a branch the server just created before any listing includes it. */
     addCreatedBranch: (branch: BranchListItem) => void;
     handleSubmit: (branchName: string) => Promise<void>;

package/dist/editor/hooks/useBranchManager.js

@@ -18,6 +18,7 @@ import { RetryToastMessage } from '../components/RetryToastMessage.js';
 import { isNonApiResponse } from '../../api/client.js';
 import { isGatewayFailure, isUnanswered, UnansweredError } from '../unanswered.js';
 import { describeUnsaved } from './useBranchActions.js';
+import { writeEditorUrl } from './editor-history.js';
 const BRANCHES_LOAD_FAILED_TOAST_ID = 'canopy-branches-load-failed';
 const BRANCH_OUTCOME_UNKNOWN_TOAST_ID = 'canopy-branch-outcome-unknown';
 /** The error a refused branch action throws; a gateway's 5xx says nothing of whether it ran. */
@@ -583,16 +584,18 @@ export function useBranchManager(options) {
     const handleReloadBranchData = async () => {
         await loadBranches();
     };
+    // The editor's own page; a Back off it to a page of the host leaves that page's URL alone.
+    const editorPathRef = useRef(typeof window === 'undefined' ? '' : window.location.pathname);
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
-        if (!branchName)
+        if (!branchName || window.location.pathname !== editorPathRef.current)
             return;
         const url = new URL(window.location.href);
         const current = url.searchParams.get('branch');
         if (current !== branchName) {
             url.searchParams.set('branch', branchName);
-            window.history.replaceState({}, '', url.toString());
+            writeEditorUrl(url.toString(), false);
         }
     }, [branchName]);
     return {
@@ -601,6 +604,7 @@ export function useBranchManager(options) {
         branches,
         branchSummaries,
         currentBranch,
+        branchesLoadFailed: !!branchesError && !branchesData,
         addCreatedBranch,
         handleSubmit,
         handleWithdraw,

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

@@ -4,6 +4,8 @@ import type { LogicalPath } from '../../paths/types.js';
 import type { FormValue } from '../FormRenderer.js';
 import type { EntryFieldError } from '../../validation/entry-validator.js';
 /** @internal Exported for tests. */
+export declare const RESTORED_ENTRY_GONE_MESSAGE = "The entry you returned to is no longer on this branch, so the home page opened.";
+/** @internal Exported for tests. */
 export { listAllEntries } from './useEntriesData.js';
 /**
  * Thrown by saveEntry when the API returns a non-200 response. Carries the
@@ -37,12 +39,17 @@ export interface UseEntryManagerOptions {
     /** An entry's route on the site (`buildPreviewRoute`), which picks the home page to open first. */
     resolvePreviewRoute?: (entry: EditorEntry) => string | undefined;
     setBusy: (busy: boolean) => void;
+    /** Switches to the branch a Back or Forward reached; rejects when the switch does not happen. */
+    switchBranch?: (branch: string) => Promise<void>;
+    /** Called when a Back or Forward has opened another entry. */
+    onHistoryRestore?: () => void;
 }
 export interface UseEntryManagerReturn {
     selectedPath: string;
+    /** Opens an entry the user chose, adding a history entry, so Back returns to the one before. */
     setSelectedPath: (path: string) => void;
-    /** Leaves no entry open, as after deleting the open one, instead of opening the first. */
-    closeEntry: () => void;
+    /** Leaves no entry open if `path` on `branch` is still open, as after deleting it. */
+    closeEntry: (path: string, branch: string) => void;
     entries: EditorEntry[];
     setEntries: (entries: EditorEntry[]) => void;
     collections: EditorCollection[];

package/dist/editor/hooks/useEntryManager.js

@@ -10,7 +10,11 @@ import { SCHEMA_UNAVAILABLE_CODE } from '../unavailable-entry-type.js';
 import { entriesKey, fetchEntriesAndSchema } from './useEntriesData.js';
 import { RetryToastMessage } from '../components/RetryToastMessage.js';
 import { isGatewayFailure, isUnanswered, MayHaveLandedError, UnansweredError } from '../unanswered.js';
+import { sanitizeBranchName } from '../../paths/branch-name.js';
+import { markEditorHistoryStart, recordHistoryMove, undoHistoryMove, writeEditorUrl, } from './editor-history.js';
 const ENTRIES_LOAD_FAILED_TOAST_ID = 'canopy-entries-load-failed';
+/** @internal Exported for tests. */
+export const RESTORED_ENTRY_GONE_MESSAGE = 'The entry you returned to is no longer on this branch, so the home page opened.';
 // Re-exported so existing imports of `listAllEntries` from this module keep
 // working -- the implementation lives in useEntriesData.ts alongside the
 // other fetch/key/type pieces useEntryManager shares with the SWR layer.
@@ -56,6 +60,23 @@ const EMPTY_SCHEMAS = [];
  * from an entry that crashes the editor); null opens the home page (`resolveHomeEntry`).
  */
 const readUrlEntry = () => typeof window === 'undefined' ? null : new URLSearchParams(window.location.search).get('entry');
+/** The current URL with `branch` and the `entry` that `selectedPath` shows, as `readUrlEntry` reads it. */
+const entryUrl = (selectedPath, noEntry, branch) => {
+    const url = new URL(window.location.href);
+    if (branch)
+        url.searchParams.set('branch', branch);
+    if (selectedPath) {
+        url.searchParams.set('entry', selectedPath);
+    }
+    else if (noEntry) {
+        // Kept, so a reload still opens no entry.
+        url.searchParams.set('entry', '');
+    }
+    else {
+        url.searchParams.delete('entry');
+    }
+    return url.toString();
+};
 /**
  * Custom hook for managing editor entries (CRUD operations).
  */
@@ -102,6 +123,18 @@ export function useEntryManager(options) {
     selectedPathRef.current = selectedPath;
     // Counts selections through the returned setter, not this hook's own fallbacks.
     const selectionsByCallerRef = useRef(0);
+    // The path the user chose, which the URL sync pushes; any other selection replaces the URL.
+    const pushTargetRef = useRef(null);
+    // The `entry` a Back onto another branch opens once that branch shows; a later move drops it.
+    const entryAfterBranchChangeRef = useRef(undefined);
+    // Counts Back and Forward moves, so a branch switch one asked for knows when another followed.
+    const historyMovesRef = useRef(0);
+    // The path a Back or Forward opened, until the entries show whether it is still there.
+    const restoredPathRef = useRef(null);
+    // The editor's own page: a Back off it to another page of the host is no move between entries.
+    const editorPathRef = useRef(typeof window === 'undefined' ? '' : window.location.pathname);
+    const onHistoryRestoreRef = useRef(options.onHistoryRestore);
+    onHistoryRestoreRef.current = options.onHistoryRestore;
     const [navigatorOpen, setNavigatorOpen] = useState(() => readUrlEntry() === '');
     const isInitialMount = useRef(true);
     const hasSyncedFromUrl = useRef(false);
@@ -188,13 +221,18 @@ export function useEntryManager(options) {
     const noEntryRequested = useRef(initialUrlEntry.current === '');
     const selectEntryPath = useCallback((path) => {
         selectionsByCallerRef.current += 1;
+        pushTargetRef.current = path;
         setSelectedPath(path);
     }, []);
     // No entry open, as the URL's empty `entry` asks, where a lost selection opens the home page.
-    const closeEntry = useCallback(() => {
+    // Replaces the history entry: it follows a delete, which Back could not undo.
+    const closeEntry = useCallback((path, branch) => {
+        if (selectedPathRef.current !== path || currentBranchRef.current !== branch)
+            return;
         noEntryRequested.current = true;
-        selectEntryPath('');
-    }, [selectEntryPath]);
+        selectionsByCallerRef.current += 1;
+        setSelectedPath('');
+    }, []);
     const collectionByPath = useMemo(() => {
         const map = new Map();
         const walk = (collections) => {
@@ -470,6 +508,7 @@ export function useEntryManager(options) {
             // still empty when this function runs (slow server / cold start).
             const createdEntry = refreshed.find((e) => e.collectionPath === createModalCollection.path && e.slug === slug);
             if (createdEntry) {
+                pushTargetRef.current = createdEntry.path;
                 setSelectedPath(createdEntry.path);
             }
             else {
@@ -566,8 +605,16 @@ export function useEntryManager(options) {
             isInitialMount.current = false;
         }
         else {
-            noEntryRequested.current = false;
-            setSelectedPath('');
+            const restored = entryAfterBranchChangeRef.current;
+            entryAfterBranchChangeRef.current = undefined;
+            const entry = restored?.branch === options.branchName ? restored.entry : undefined;
+            noEntryRequested.current = entry === '';
+            setSelectedPath(entry ?? '');
+            if (entry !== undefined) {
+                restoredPathRef.current = entry;
+                setNavigatorOpen(entry === '');
+                onHistoryRestoreRef.current?.();
+            }
             // Bound version-map growth across switches. Correctness no longer
             // depends on this clear: tokens are keyed by `${branch}:${contentId}`
             // (see entryVersionsRef), so a late response from the previous branch
@@ -703,33 +750,100 @@ export function useEntryManager(options) {
                 return;
             }
         }
+        const restored = restoredPathRef.current === selectedPath;
+        if (restored)
+            restoredPathRef.current = null;
         // If the selected entry exists, keep it
         if (entriesState.find((e) => e.path === selectedPath))
             return;
         if (selectedPath === '' && noEntryRequested.current)
             return;
+        if (restored && selectedPath) {
+            notifications.show({ message: RESTORED_ENTRY_GONE_MESSAGE, color: 'blue' });
+        }
         setSelectedPath(resolveHomeEntry(entriesState, resolvePreviewRouteRef.current)?.path ?? '');
     }, [entriesState, selectedPath]);
     // Update URL when selection changes (skip until URL sync has happened)
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
+        // Pushed only once listed: a path the check above replaces would leave a stale entry behind.
+        const push = pushTargetRef.current === selectedPath && entriesState.some((e) => e.path === selectedPath);
+        pushTargetRef.current = null;
         // Don't update URL until we've synced from it first
         if (!hasSyncedFromUrl.current)
             return;
-        const url = new URL(window.location.href);
-        if (selectedPath) {
-            url.searchParams.set('entry', selectedPath);
-        }
-        else if (noEntryRequested.current) {
-            // Kept, so a reload still opens no entry.
-            url.searchParams.set('entry', '');
-        }
-        else {
-            url.searchParams.delete('entry');
-        }
-        window.history.replaceState({}, '', url.toString());
+        if (window.location.pathname !== editorPathRef.current)
+            return;
+        writeEditorUrl(entryUrl(selectedPath, noEntryRequested.current, currentBranchRef.current), push);
     }, [selectedPath]);
+    const entriesRef = useRef(entriesState);
+    entriesRef.current = entriesState;
+    const switchBranchRef = useRef(options.switchBranch);
+    switchBranchRef.current = options.switchBranch;
+    // Back and Forward open the entry their URL names, without a reload.
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        markEditorHistoryStart();
+        const restore = () => {
+            const moved = recordHistoryMove();
+            if (moved === null || window.location.pathname !== editorPathRef.current)
+                return;
+            historyMovesRef.current += 1;
+            entryAfterBranchChangeRef.current = undefined;
+            const params = new URLSearchParams(window.location.search);
+            const entry = params.get('entry');
+            const branch = params.get('branch');
+            const current = currentBranchRef.current;
+            // A legacy name and its sanitized form are one branch; a switch would key drafts by the other.
+            if (branch && sanitizeBranchName(branch) !== sanitizeBranchName(current)) {
+                const move = historyMovesRef.current;
+                const stay = () => {
+                    if (move !== historyMovesRef.current)
+                        return;
+                    if (moved)
+                        undoHistoryMove(moved);
+                    else {
+                        const url = entryUrl(selectedPathRef.current, noEntryRequested.current, currentBranchRef.current);
+                        writeEditorUrl(url, false);
+                    }
+                };
+                const switchBranch = switchBranchRef.current;
+                if (!switchBranch) {
+                    stay();
+                    return;
+                }
+                entryAfterBranchChangeRef.current = { branch, entry };
+                if (!hasSyncedFromUrl.current)
+                    initialUrlEntry.current = entry;
+                switchBranch(branch).catch(() => {
+                    if (move === historyMovesRef.current)
+                        entryAfterBranchChangeRef.current = undefined;
+                    stay();
+                });
+                return;
+            }
+            // A Back is a selection, so a rename, move or re-create landing afterwards leaves it open.
+            selectionsByCallerRef.current += 1;
+            noEntryRequested.current = entry === '';
+            setNavigatorOpen(entry === '');
+            if (!hasSyncedFromUrl.current) {
+                initialUrlEntry.current = entry;
+                setSelectedPath(entry ?? '');
+                return;
+            }
+            const target = entry ?? resolveHomeEntry(entriesRef.current, resolvePreviewRouteRef.current)?.path ?? '';
+            if (target === selectedPathRef.current)
+                return;
+            restoredPathRef.current = target;
+            // A path no longer listed falls back to the home page, through the selection check above.
+            setSelectedPath(target);
+            onHistoryRestoreRef.current?.();
+        };
+        window.addEventListener('popstate', restore);
+        return () => window.removeEventListener('popstate', restore);
+    }, []);
     return {
         selectedPath,
         setSelectedPath: selectEntryPath,

package/dist/editor/media/AssetCard.js

@@ -2,12 +2,12 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { ActionIcon, Badge, Card, Text, Tooltip } from '@mantine/core';
 import { IconEyeOff, IconFileTypePdf, IconPhotoOff, IconRestore } from '@tabler/icons-react';
+import { EDITOR_THUMBNAIL_WIDTHS } from '../../assets/editor-thumbnail-widths.js';
 import { EDITOR_ACTIONS } from '../copy.js';
 import { formatRelativeTime } from '../relative-time.js';
 import { editorImageSrc } from './editor-image-src.js';
 import { CARD_THUMBNAIL_HEIGHT } from './media-library-view.js';
 import { useThumbnailFailure } from './useThumbnailFailure.js';
-const THUMBNAIL_WIDTH = 160;
 /** Over the thumbnail, so opaque: the default fill. */
 const overlayActionStyle = {
     position: 'absolute',
@@ -24,7 +24,9 @@ export const AssetCard = ({ asset, baseUrl, onSelect, onRemove, onRestore, densi
     const compact = density === 'compact';
     const removed = asset.hidden === true;
     const thumbnailHeight = CARD_THUMBNAIL_HEIGHT[density];
-    const thumbnailSrc = editorImageSrc(asset.src, baseUrl ?? '', { width: THUMBNAIL_WIDTH });
+    const thumbnailSrc = editorImageSrc(asset.src, baseUrl ?? '', {
+        width: EDITOR_THUMBNAIL_WIDTHS.card,
+    });
     const [thumbnailFailed, markThumbnailFailed] = useThumbnailFailure(thumbnailSrc);
     const handleKeyDown = (event) => {
         if (!onSelect)

package/dist/editor/media/AssetListRow.js

@@ -2,13 +2,13 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { ActionIcon, Badge, Group, Text, Tooltip, UnstyledButton } from '@mantine/core';
 import { IconEyeOff, IconFileTypePdf, IconPhotoOff, IconRestore } from '@tabler/icons-react';
+import { EDITOR_THUMBNAIL_WIDTHS } from '../../assets/editor-thumbnail-widths.js';
 import { EDITOR_ACTIONS } from '../copy.js';
 import { formatRelativeTime } from '../relative-time.js';
 import { editorImageSrc } from './editor-image-src.js';
 import { formatBytes } from './format-bytes.js';
 import { useThumbnailFailure } from './useThumbnailFailure.js';
 const THUMBNAIL_SIZE = 40;
-const THUMBNAIL_WIDTH = 80;
 const rowStyle = {
     width: '100%',
     padding: 6,
@@ -32,7 +32,9 @@ const thumbnailBoxStyle = {
  */
 export const AssetListRow = ({ asset, baseUrl, onSelect, onRemove, onRestore, }) => {
     const removed = asset.hidden === true;
-    const thumbnailSrc = editorImageSrc(asset.src, baseUrl ?? '', { width: THUMBNAIL_WIDTH });
+    const thumbnailSrc = editorImageSrc(asset.src, baseUrl ?? '', {
+        width: EDITOR_THUMBNAIL_WIDTHS.listRow,
+    });
     const [thumbnailFailed, markThumbnailFailed] = useThumbnailFailure(thumbnailSrc);
     const hasDimensions = asset.width !== undefined && asset.height !== undefined;
     const content = (_jsxs(Group, { gap: "sm", wrap: "nowrap", style: { flex: 1, minWidth: 0 }, children: [_jsx("div", { style: thumbnailBoxStyle, children: asset.kind === 'pdf' ? (_jsx(IconFileTypePdf, { size: 24, stroke: 1.5, "aria-hidden": true })) : thumbnailFailed ? (_jsx(IconPhotoOff, { size: 20, stroke: 1.5, color: "var(--mantine-color-dimmed)", "data-testid": `asset-row-thumbnail-fallback-${asset.hash32}`, "aria-label": "Preview unavailable" })) : (

package/dist/editor/media/CropStep.d.ts

@@ -5,20 +5,18 @@ export interface CropStepProps {
     onClose: () => void;
     /** Full-frame image src to crop - `assetUrl()` with no crop directive, so the user always crops the original frame. */
     imageSrc: string;
-    /** Numeric aspect ratio (width/height) parsed from the field config's "W:H" string. */
-    aspect: number;
-    /** Existing crop rect, if re-cropping - seeds react-easy-crop's initial selection (best effort). */
+    /** Numeric aspect ratio (width/height) parsed from the field config's "W:H" string. Absent: the crop box is free-form. */
+    aspect?: number;
+    /** Existing crop rect, if re-cropping - the box it opens with. */
     initialCrop?: CropRect;
     onConfirm: (rect: CropRect) => void;
 }
 /**
- * react-easy-crop wrapped in a Modal for the ImageField crop step. Percentage
- * -> normalized-rect conversion is delegated to crop-math.ts's pure,
- * independently-unit-tested `cropAreaPercentToRect`.
+ * react-image-crop in a Modal for the ImageField crop step. Box -> normalized-rect
+ * conversion is delegated to crop-math.ts's pure, independently-unit-tested
+ * `cropAreaPercentToRect`.
  *
- * The pan/zoom/pending-selection state lives in `CropStepBody`, mounted only
- * while `opened` and keyed on `imageSrc` - so a fresh crop session always
- * starts from fresh state (React remounts on key change) without an effect
- * that would otherwise need to call `setState` synchronously to reset it.
+ * The box state lives in `CropStepBody`, mounted only while `opened` and keyed on `imageSrc`,
+ * so a fresh crop session always starts from a fresh box (React remounts on key change).
  */
 export declare const CropStep: React.FC<CropStepProps>;

package/dist/editor/media/CropStep.js

@@ -1,41 +1,53 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
-import { Button, Group, Modal, Slider, Stack, Text } from '@mantine/core';
-import Cropper from 'react-easy-crop';
-import { cropAreaPercentToRect, cropRectToAreaPercent } from './crop-math.js';
-const MIN_ZOOM = 1;
-const MAX_ZOOM = 3;
-const ZOOM_STEP = 0.05;
+import { Button, Group, Modal, Stack, Text } from '@mantine/core';
+import ReactCrop from 'react-image-crop';
+import { cropAreaPercentToRect, initialCropBox } from './crop-math.js';
+const MIN_BOX_PX = 16;
+const CORNER_LABEL = (corner) => `${corner} corner. Arrow keys resize the box.`;
+const ARIA_LABELS = {
+    cropArea: 'Crop box. Arrow keys move it; hold Shift for larger steps.',
+    nwDragHandle: CORNER_LABEL('Top-left'),
+    neDragHandle: CORNER_LABEL('Top-right'),
+    seDragHandle: CORNER_LABEL('Bottom-right'),
+    swDragHandle: CORNER_LABEL('Bottom-left'),
+    nDragHandle: 'Top edge. Up and down arrow keys resize the box.',
+    sDragHandle: 'Bottom edge. Up and down arrow keys resize the box.',
+    eDragHandle: 'Right edge. Left and right arrow keys resize the box.',
+    wDragHandle: 'Left edge. Left and right arrow keys resize the box.',
+};
+const PREVIEW_MAX_HEIGHT = 360;
+const toPercentCrop = (box) => ({
+    unit: '%',
+    ...box,
+});
 /**
- * react-easy-crop wrapped in a Modal for the ImageField crop step. Percentage
- * -> normalized-rect conversion is delegated to crop-math.ts's pure,
- * independently-unit-tested `cropAreaPercentToRect`.
+ * react-image-crop in a Modal for the ImageField crop step. Box -> normalized-rect
+ * conversion is delegated to crop-math.ts's pure, independently-unit-tested
+ * `cropAreaPercentToRect`.
  *
- * The pan/zoom/pending-selection state lives in `CropStepBody`, mounted only
- * while `opened` and keyed on `imageSrc` - so a fresh crop session always
- * starts from fresh state (React remounts on key change) without an effect
- * that would otherwise need to call `setState` synchronously to reset it.
+ * The box state lives in `CropStepBody`, mounted only while `opened` and keyed on `imageSrc`,
+ * so a fresh crop session always starts from a fresh box (React remounts on key change).
  */
 export const CropStep = ({ opened, onClose, imageSrc, aspect, initialCrop, onConfirm, }) => {
     return (_jsx(Modal, { opened: opened, onClose: onClose, title: "Crop image", size: "lg", overlayProps: { blur: 2 }, "data-testid": "crop-step-modal", children: opened && (_jsx(CropStepBody, { imageSrc: imageSrc, aspect: aspect, initialCrop: initialCrop, onConfirm: onConfirm, onClose: onClose }, imageSrc)) }));
 };
 const CropStepBody = ({ imageSrc, aspect, initialCrop, onConfirm, onClose, }) => {
-    const [crop, setCrop] = useState({ x: 0, y: 0 });
-    const [zoom, setZoom] = useState(1);
-    const [pendingArea, setPendingArea] = useState(null);
-    const handleConfirm = () => {
-        if (!pendingArea)
-            return;
-        const rect = cropAreaPercentToRect(pendingArea);
-        if (rect)
-            onConfirm(rect);
+    const [box, setBox] = useState(undefined);
+    const [loadFailed, setLoadFailed] = useState(false);
+    // The box can't be seeded until the image's displayed size is known, so Apply stays off until then.
+    const rect = box ? cropAreaPercentToRect(box) : null;
+    const handleImageLoad = (event) => {
+        const { width, height } = event.currentTarget;
+        setBox(toPercentCrop(initialCropBox({ imageWidth: width, imageHeight: height, aspect, existing: initialCrop })));
     };
-    const initialCroppedAreaPercentages = initialCrop ? cropRectToAreaPercent(initialCrop) : undefined;
     return (_jsxs(Stack, { gap: "md", children: [_jsx("div", { style: {
-                    position: 'relative',
-                    width: '100%',
-                    height: 360,
+                    display: 'flex',
+                    justifyContent: 'center',
                     background: 'var(--mantine-color-black)',
-                }, children: _jsx(Cropper, { image: imageSrc, crop: crop, zoom: zoom, aspect: aspect, initialCroppedAreaPercentages: initialCroppedAreaPercentages, onCropChange: setCrop, onZoomChange: setZoom, onCropComplete: (croppedArea) => setPendingArea(croppedArea) }) }), _jsxs(Group, { gap: "sm", align: "center", children: [_jsx(Text, { size: "sm", w: 50, children: "Zoom" }), _jsx(Slider, { style: { flex: 1 }, min: MIN_ZOOM, max: MAX_ZOOM, step: ZOOM_STEP, value: zoom, onChange: setZoom, label: (value) => `${value.toFixed(2)}x` })] }), _jsxs(Group, { justify: "flex-end", children: [_jsx(Button, { size: "sm", variant: "default", onClick: onClose, children: "Cancel" }), _jsx(Button, { size: "sm", onClick: handleConfirm, disabled: !pendingArea, "data-testid": "crop-step-apply", children: "Apply crop" })] })] }));
+                    '--rc-focus-color': 'var(--canopy-focus-ring)',
+                }, children: _jsx(ReactCrop, { crop: box, aspect: aspect, minWidth: MIN_BOX_PX, minHeight: MIN_BOX_PX, keepSelection: true, ariaLabels: ARIA_LABELS, onChange: (_pixels, percent) => setBox(percent), children: _jsx("img", { src: imageSrc, alt: "", style: { maxHeight: PREVIEW_MAX_HEIGHT, maxWidth: '100%', display: 'block' }, onLoad: handleImageLoad, onError: () => setLoadFailed(true) }) }) }), loadFailed && (_jsx(Text, { size: "sm", c: "var(--canopy-danger-text)", role: "alert", children: "This image couldn't be loaded, so it can't be cropped." })), _jsx(Text, { size: "sm", c: "dimmed", children: aspect === undefined
+                    ? 'Drag the box to move it, or its edges and corners to resize it. With a keyboard, arrow keys move it; Shift takes larger steps.'
+                    : 'Drag the box to move it, or a corner to resize it. Its shape is fixed. With a keyboard, arrow keys move it; Shift takes larger steps.' }), _jsxs(Group, { justify: "flex-end", children: [_jsx(Button, { size: "sm", variant: "default", onClick: onClose, children: "Cancel" }), _jsx(Button, { size: "sm", onClick: () => rect && onConfirm(rect), disabled: !rect, "data-testid": "crop-step-apply", children: "Apply crop" })] })] }));
 };

package/dist/editor/media/crop-availability.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Why `src` can't be cropped, as the full sentence its disabled Crop button shows; `undefined`
+ * when it can. A crop is a directive on a transform URL, which `assetUrl` writes only for a raster
+ * in the asset store, so a vector file or a file outside the store never renders one.
+ */
+export declare function cropBlockedReason(src: string): string | undefined;

package/dist/editor/media/crop-availability.js

@@ -0,0 +1,19 @@
+import { ASSET_PREFIXES } from '../../assets/asset-prefixes.js';
+import { isAssetStoreSrc } from '../../assets/asset-url.js';
+const TRANSFORM_SPACE_PREFIX = `/${ASSET_PREFIXES.transform}/`;
+/**
+ * Why `src` can't be cropped, as the full sentence its disabled Crop button shows; `undefined`
+ * when it can. A crop is a directive on a transform URL, which `assetUrl` writes only for a raster
+ * in the asset store, so a vector file or a file outside the store never renders one.
+ */
+export function cropBlockedReason(src) {
+    const path = src.split(/[?#]/)[0] ?? src;
+    if (/\.svg$/i.test(path))
+        return "SVG images can't be cropped. Replace it with a PNG or JPEG to crop it.";
+    if (!isAssetStoreSrc(src)) {
+        return 'Crop works on media-library images. Replace this file with a library copy to crop it.';
+    }
+    if (!src.startsWith(TRANSFORM_SPACE_PREFIX))
+        return "This file type can't be cropped. Replace it with a PNG or JPEG to crop it.";
+    return undefined;
+}