canopycms 0.8.1 → 0.8.2

package/dist/editor/branch-status.js

@@ -1,3 +1,4 @@
+import { escapeForLog } from '../utils/escape-text.js';
 /** @internal Exported for tests. */
 export const PROTECTED_BRANCH_PRESENTATION = {
     label: 'Protected',
@@ -27,3 +28,77 @@ export function branchStatusPresentation(status, isProtected = false) {
         return BRANCH_STATUS_PRESENTATION[status];
     return { label: status, color: 'gray', variant: 'light' };
 }
+/** The badge for a branch something holds, in the bar, on the card and in System health. */
+export const HOLD_BADGE = { label: 'Needs action', color: 'yellow' };
+/**
+ * What's stuck and what this viewer can do about it. A retargeted base comes from GitHub and is
+ * attacker-chosen, so it's shown escaped.
+ */
+export function branchHoldMessage(hold, viewer) {
+    switch (hold.kind) {
+        case 'conflicts': {
+            const stuck = "This branch conflicts with its base branch, so its pull request can't be updated.";
+            if (viewer.role === 'review')
+                return `${stuck} Use "Request changes" to send it back to its editor.`;
+            if (viewer.role === 'none')
+                return `${stuck} Its editor needs to withdraw it from review.`;
+            return `${stuck} Use "Withdraw from review", check any flagged entries, then submit it again.`;
+        }
+        case 'retargeted':
+            return `This pull request now merges into ${escapeForLog(hold.base)} on GitHub, so CanopyCMS isn't updating it. Update it on the pull request${viewer.isAdmin ? '' : ', or ask an admin'}.`;
+        case 'rewritten': {
+            const stuck = "This branch was changed on GitHub in a way CanopyCMS can't combine with the work here, so changes here can't reach GitHub. Nothing is lost.";
+            if (viewer.inSystemHealth)
+                return `${stuck} A developer needs to merge the missing commit back into the branch on GitHub. The "Rebase failing" warning icon in this row names it.`;
+            return viewer.isAdmin
+                ? `${stuck} See the "Branches" tab in "System health".`
+                : `${stuck} Ask an admin for help.`;
+        }
+        case 'submit-unfinished': {
+            const stuck = hold.opened
+                ? "The last submit of this branch didn't finish, so its pull request may not have its latest changes."
+                : "The last submit of this branch didn't finish, so its pull request wasn't opened.";
+            if (hold.notQueued) {
+                if (viewer.role === 'review')
+                    return `${stuck} Use "Request changes" to send it back to its editor.`;
+                return viewer.role === 'withdraw'
+                    ? `${stuck} Use "Withdraw from review", then submit the branch again.`
+                    : `${stuck} Its editor needs to withdraw it from review and submit it again.`;
+            }
+            const retry = viewer.inSystemHealth
+                ? 'Retry the submit from the "Tasks" tab'
+                : viewer.isAdmin
+                    ? 'Retry the submit from the "Tasks" tab in "System health"'
+                    : 'Ask an admin to retry the submit';
+            const instead = viewer.role === 'withdraw'
+                ? ', or use "Withdraw from review", then submit the branch again'
+                : viewer.role === 'review'
+                    ? ', or use "Request changes" to send it back to its editor'
+                    : '';
+            return `${stuck} ${retry}${instead}.`;
+        }
+        case 'unpublished-at-merge': {
+            const stuck = 'This pull request merged before the last submit finished, so some changes may not be in the merge.';
+            if (viewer.inSystemHealth)
+                return `${stuck} The "Overview" tab says what to do.`;
+            return viewer.isAdmin
+                ? `${stuck} See the "Overview" tab in "System health".`
+                : `${stuck} Ask an admin to check it.`;
+        }
+    }
+}
+/** Ends `text` as a sentence, for a recorded reason that another sentence follows. */
+export function endSentence(text) {
+    const trimmed = text.trimEnd();
+    return /[.!?:][)"']*$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+/** Why a branch in review with a failed sync stays behind its base, after the failure itself. */
+export const SYNC_FAILED_IN_REVIEW_NOTE = "Until it syncs, CanopyCMS won't update this pull request from its base.";
+/** The failed-sync line when the worker recorded no reason. An archived branch has nothing to retry. */
+export const syncFailedFallback = (isAdmin, status) => {
+    if (status === 'archived')
+        return 'GitHub sync failed.';
+    return isAdmin
+        ? 'GitHub sync failed. Retry it from the "Tasks" tab in "System health".'
+        : 'GitHub sync failed. Ask an admin to retry it.';
+};

package/dist/editor/components/EditorHeader.d.ts

@@ -1,5 +1,5 @@
 import { type Ref } from 'react';
-import type { BranchStatus, PullRequestState } from '../../types.js';
+import type { BranchHold, BranchStatus, PullRequestState } from '../../types.js';
 import type { SaveAllProgress } from '../hooks/save-all.js';
 export interface EditorHeaderProps {
     branchName: string;
@@ -60,6 +60,10 @@ export interface EditorHeaderProps {
     branchServerProtected?: boolean;
     /** Whether the current branch is read-only (protected base branch in prod); disables Save all. */
     branchReadOnly?: boolean;
+    /** What holds the branch (api/branch.ts). */
+    branchHold?: BranchHold;
+    /** The server refuses Approve on this branch. */
+    branchApproveBlocked?: boolean;
     /** Server-computed: content writes are rejected on this branch; see `branchLockState`. */
     branchWriteBlocked?: boolean;
     /** No branch details yet: the fail-closed lock defaults are guesses the status doesn't name. */
@@ -74,4 +78,4 @@ export interface EditorHeaderProps {
  * warning, Save all, the way forward and Submit or Withdraw, or to a reviewer of someone else's
  * submission Approve and Request changes. The open entry's own controls are in `EntryHeader`.
  */
-export declare function EditorHeader({ branchName, branchLabel, busy, modifiedCount, onShowUnsaved, branchToggleRef, onBranchReloadData, onBranchDiscardDrafts, onBranchManagerOpen, onNewBranch, onSaveAll, saveAllProgress, singleSaving, entryListFailed, onSubmit, onWithdraw, onApprove, onRequestChanges, draftStorageFailed, branchStatus, userContext, branchCreatedBy, branchPullRequestState, branchAccess, branchIsProtected, branchServerProtected, branchReadOnly, branchWriteBlocked, branchLoading, branchPending, branchMissing, }: EditorHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function EditorHeader({ branchName, branchLabel, busy, modifiedCount, onShowUnsaved, branchToggleRef, onBranchReloadData, onBranchDiscardDrafts, onBranchManagerOpen, onNewBranch, onSaveAll, saveAllProgress, singleSaving, entryListFailed, onSubmit, onWithdraw, onApprove, onRequestChanges, draftStorageFailed, branchStatus, userContext, branchCreatedBy, branchPullRequestState, branchAccess, branchIsProtected, branchServerProtected, branchReadOnly, branchHold, branchApproveBlocked, branchWriteBlocked, branchLoading, branchPending, branchMissing, }: EditorHeaderProps): import("react/jsx-runtime").JSX.Element;

package/dist/editor/components/EditorHeader.js

@@ -1,15 +1,17 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useRef } from 'react';
-import { Box, Button, Group, Menu, Text, Tooltip, VisuallyHidden, em, getBreakpointValue, useMantineTheme, } from '@mantine/core';
+import { Badge, Box, Button, Group, Menu, Text, Tooltip, VisuallyHidden, em, getBreakpointValue, useMantineTheme, } from '@mantine/core';
 import { useMediaQuery, useMergedRef } from '@mantine/hooks';
 import { IconChevronDown, IconLock } from '@tabler/icons-react';
 import { isAdmin, isLockedOutOfBranch, isReviewer } from '../../authorization/helpers.js';
 import { branchBarStatus, describeBranchLock } from '../branch-lock.js';
-import { EDITOR_ACTIONS } from '../copy.js';
+import { HOLD_BADGE, branchHoldMessage } from '../branch-status.js';
+import { EDITOR_ACTIONS, UNFINISHED_SUBMIT_APPROVE_REASON, rewrittenSubmitReason } from '../copy.js';
 import { reviewRoleOf } from '../../authorization/review-role.js';
 import { SYSTEM_USER_ID } from '../../system-users.js';
 import { TopBar } from '../shell/TopBar.js';
 import { BranchPill } from './BranchPill.js';
+import { TooltipDetail } from './TooltipDetail.js';
 import { ReasonedMenuItem } from './ReasonedMenuItem.js';
 import { UnsavedMark } from './UnsavedMark.js';
 import { DraftStorageWarning, HIDDEN_STYLE, SaveAllButton } from './SaveAllButton.js';
@@ -19,7 +21,7 @@ import { useFocusHandOff, useMenuItemFocusReturn } from '../utils/focus-return.j
  * warning, Save all, the way forward and Submit or Withdraw, or to a reviewer of someone else's
  * submission Approve and Request changes. The open entry's own controls are in `EntryHeader`.
  */
-export function EditorHeader({ branchName, branchLabel, busy, modifiedCount, onShowUnsaved, branchToggleRef, onBranchReloadData, onBranchDiscardDrafts, onBranchManagerOpen, onNewBranch = onBranchManagerOpen, onSaveAll, saveAllProgress, singleSaving = false, entryListFailed = false, onSubmit, onWithdraw, onApprove = noopAction, onRequestChanges = noopAction, draftStorageFailed = false, branchStatus, userContext, branchCreatedBy, branchPullRequestState, branchAccess, branchIsProtected = false, branchServerProtected, branchReadOnly = false, branchWriteBlocked = false, branchLoading = false, branchPending = false, branchMissing = false, }) {
+export function EditorHeader({ branchName, branchLabel, busy, modifiedCount, onShowUnsaved, branchToggleRef, onBranchReloadData, onBranchDiscardDrafts, onBranchManagerOpen, onNewBranch = onBranchManagerOpen, onSaveAll, saveAllProgress, singleSaving = false, entryListFailed = false, onSubmit, onWithdraw, onApprove = noopAction, onRequestChanges = noopAction, draftStorageFailed = false, branchStatus, userContext, branchCreatedBy, branchPullRequestState, branchAccess, branchIsProtected = false, branchServerProtected, branchReadOnly = false, branchHold, branchApproveBlocked = false, branchWriteBlocked = false, branchLoading = false, branchPending = false, branchMissing = false, }) {
     const reviewRole = reviewRoleOf({
         status: branchStatus,
         createdBy: branchCreatedBy,
@@ -38,6 +40,8 @@ export function EditorHeader({ branchName, branchLabel, busy, modifiedCount, onS
         branchIsProtected,
         reviewRole,
         savingAll: !!saveAllProgress,
+        rewritten: branchHold?.kind === 'rewritten',
+        approveBlocked: branchApproveBlocked,
     });
     const lock = {
         branchStatus,
@@ -47,9 +51,16 @@ export function EditorHeader({ branchName, branchLabel, busy, modifiedCount, onS
         branchMissing,
         reviewing: workflow?.kind === 'review',
         pullRequestClosed: reviewRole === 'reviewing-closed',
+        approveBlocked: branchApproveBlocked,
     };
     const branchLockReason = describeBranchLock(lock);
     const status = branchBarStatus({ ...lock, isProtected: branchServerProtected });
+    const holdMessage = branchName && branchHold && status.value !== 'loading'
+        ? branchHoldMessage(branchHold, {
+            role: workflow?.kind === 'review' ? 'review' : workflow?.permitted ? 'withdraw' : 'none',
+            isAdmin: isAdmin(userContext?.groups ?? []),
+        })
+        : undefined;
     const theme = useMantineTheme();
     // Mantine's own below-`md` query, the one `visibleFrom="md"` hides under.
     const belowMd = `(max-width: ${em(getBreakpointValue('md', theme.breakpoints) - 0.1)})`;
@@ -81,7 +92,7 @@ export function EditorHeader({ branchName, branchLabel, busy, modifiedCount, onS
         returnFocusTo: () => focusTarget(2),
     };
     const caretOnWay = narrow && !!barAction && !!workflow;
-    return (_jsx(TopBar, { leading: _jsxs(Group, { gap: "xs", wrap: "wrap", align: "center", style: { rowGap: 4 }, children: [_jsx(BranchPill, { branchName: branchLabel ?? branchName, loading: busy, unsavedCount: modifiedCount, onSwitchBranch: onBranchManagerOpen, onRefreshBranch: onBranchReloadData, onDiscardAll: onBranchDiscardDrafts, pillRef: branchToggleRef }), _jsx(BranchStatusLabel, { status: branchName ? status : { value: 'none', readOnly: false }, reason: branchLockReason }), modifiedCount > 0 && (_jsx(Tooltip, { label: unsavedTooltip(branchName ? status : undefined, modifiedCount, workflow?.kind === 'withdraw' && workflow.permitted), events: TOOLTIP_EVENTS, multiline: true, maw: 320, children: _jsx(Button, { variant: "subtle", color: "gray", size: "compact-sm", style: { flexShrink: 0 }, leftSection: _jsx(UnsavedMark, { "aria-hidden": "true" }), onClick: onShowUnsaved, "data-testid": "branch-unsaved-count", children: `${modifiedCount} unsaved` }) }))] }), trailing: _jsxs(_Fragment, { children: [_jsx(DraftStorageWarning, { shown: draftStorageFailed && modifiedCount > 0 }), (!narrow || editable) && (_jsx(SaveAllButton
+    return (_jsx(TopBar, { leading: _jsxs(Group, { gap: "xs", wrap: "wrap", align: "center", style: { rowGap: 4 }, children: [_jsx(BranchPill, { branchName: branchLabel ?? branchName, loading: busy, unsavedCount: modifiedCount, onSwitchBranch: onBranchManagerOpen, onRefreshBranch: onBranchReloadData, onDiscardAll: onBranchDiscardDrafts, pillRef: branchToggleRef }), _jsx(BranchStatusLabel, { status: branchName ? status : { value: 'none', readOnly: false }, reason: branchLockReason, holdMessage: holdMessage }), modifiedCount > 0 && (_jsx(Tooltip, { label: unsavedTooltip(branchName ? status : undefined, modifiedCount, workflow?.kind === 'withdraw' && workflow.permitted), events: TOOLTIP_EVENTS, multiline: true, maw: 320, children: _jsx(Button, { variant: "subtle", color: "gray", size: "compact-sm", style: { flexShrink: 0 }, leftSection: _jsx(UnsavedMark, { "aria-hidden": "true" }), onClick: onShowUnsaved, "data-testid": "branch-unsaved-count", children: `${modifiedCount} unsaved` }) }))] }), trailing: _jsxs(_Fragment, { children: [_jsx(DraftStorageWarning, { shown: draftStorageFailed && modifiedCount > 0 }), (!narrow || editable) && (_jsx(SaveAllButton
                 // Its reserved width follows this branch's counts, not the session's largest.
                 , { onSaveAll: onSaveAll, unsavedCount: modifiedCount, blockedReason: branchLockReason ??
                         (!branchName
@@ -116,14 +127,17 @@ function unsavedTooltip(status, count, mayWithdraw) {
         return `${edits} This branch won't become editable, so they can only be discarded.`;
     return `${edits} They can be saved once the branch is editable again.`;
 }
-/** The branch's state beside the pill, heard in words with its reason, but not while it loads. */
-function BranchStatusLabel({ status, reason }) {
+/**
+ * The branch's state beside the pill, heard in words with its reason, but not while it loads. A
+ * hold follows it whatever the lock, since a lock doesn't say that the branch is stuck.
+ */
+function BranchStatusLabel({ status, reason, holdMessage, }) {
     const spoken = status.label && status.value !== 'loading'
         ? [status.label.replace(' · ', ', '), reason].filter(Boolean).join('. ')
         : '';
     return (
     // Always mounted, so a lock that arrives is announced.
-    _jsxs(Box, { role: "status", style: status.label ? { flexShrink: 0 } : HIDDEN_STYLE, children: [status.label && (_jsxs(Group, { gap: 4, wrap: "nowrap", "aria-hidden": "true", "data-testid": "branch-status", "data-status": status.value, children: [status.readOnly && _jsx(IconLock, { size: 14 }), _jsx(Text, { span: true, size: "sm", children: status.label })] })), _jsx(VisuallyHidden, { children: spoken })] }));
+    _jsxs(Box, { role: "status", style: status.label || holdMessage ? { flexShrink: 0 } : HIDDEN_STYLE, children: [_jsxs(Group, { gap: "xs", wrap: "nowrap", children: [status.label && (_jsxs(Group, { gap: 4, wrap: "nowrap", "aria-hidden": "true", "data-testid": "branch-status", "data-status": status.value, children: [status.readOnly && _jsx(IconLock, { size: 14 }), _jsx(Text, { span: true, size: "sm", children: status.label })] })), holdMessage && (_jsx(TooltipDetail, { detail: holdMessage, children: _jsx(Badge, { color: HOLD_BADGE.color, variant: "light", "data-testid": "branch-hold-status", children: HOLD_BADGE.label }) }))] }), _jsx(VisuallyHidden, { children: spoken })] }));
 }
 const WAY_LABEL = {
     newBranch: `${EDITOR_ACTIONS.newBranch}…`,
@@ -140,7 +154,7 @@ function BranchWayButton({ action, onClick, caret, buttonRef, }) {
  * Submit for review, or Withdraw from review once submitted or approved, or Approve and Request
  * changes to a reviewer of someone else's submission; null when none shows.
  */
-function workflowAction({ branchName, busy, branchStatus, userContext, branchCreatedBy, branchAccess, branchIsProtected, reviewRole, savingAll, }) {
+function workflowAction({ branchName, busy, branchStatus, userContext, branchCreatedBy, branchAccess, branchIsProtected, reviewRole, savingAll, rewritten, approveBlocked, }) {
     const isSubmitted = branchStatus === 'submitted';
     const isEditing = branchStatus === 'editing';
     // 'approved' withdraws too -- it is the author's way back from
@@ -162,6 +176,7 @@ function workflowAction({ branchName, busy, branchStatus, userContext, branchCre
             blocked: !branchName || busy || savingAll,
             permitted: true,
             reason: savingAll ? 'Wait for Save all to finish.' : busy ? BUSY_REASON : '',
+            approveReason: approveBlocked ? UNFINISHED_SUBMIT_APPROVE_REASON : undefined,
         };
     }
     // Who may submit/withdraw: creator, ACL access, the system branch, or an
@@ -186,22 +201,24 @@ function workflowAction({ branchName, busy, branchStatus, userContext, branchCre
     return {
         kind: isWithdrawable ? 'withdraw' : 'submit',
         // `busy` alone can't hold it: an entry load clears that shared flag mid-run.
-        blocked: !branchName || busy || savingAll || !canPerformAction,
+        blocked: !branchName || busy || savingAll || !canPerformAction || (rewritten && isEditing),
         permitted: canPerformAction,
         reason: savingAll
             ? 'Wait for Save all to finish.'
-            : // No branch data (`branchStatus === undefined`) must not be
-                // interpolated raw into this label. Guarded explicitly here rather
-                // than left to the early return above, which hides the action
-                // today only as a side effect of `branchIsProtected`'s `?? true`
-                // default -- not a guarantee this arm stays unreachable.
-                branchStatus === undefined
-                    ? 'Branch details could not be loaded. Use "Refresh branch" to try again.'
-                    : !statusHasAction
-                        ? `This branch is ${branchStatus}, so it can't be submitted for review or withdrawn from review.`
-                        : !userHasPermission
-                            ? 'You do not have permission to submit this branch for review or withdraw it from review. Ask an admin for access.'
-                            : '',
+            : rewritten && isEditing
+                ? rewrittenSubmitReason(isAdmin(userContext?.groups ?? []))
+                : // No branch data (`branchStatus === undefined`) must not be
+                    // interpolated raw into this label. Guarded explicitly here rather
+                    // than left to the early return above, which hides the action
+                    // today only as a side effect of `branchIsProtected`'s `?? true`
+                    // default -- not a guarantee this arm stays unreachable.
+                    branchStatus === undefined
+                        ? 'Branch details could not be loaded. Use "Refresh branch" to try again.'
+                        : !statusHasAction
+                            ? `This branch is ${branchStatus}, so it can't be submitted for review or withdrawn from review.`
+                            : !userHasPermission
+                                ? 'You do not have permission to submit this branch for review or withdraw it from review. Ask an admin for access.'
+                                : '',
     };
 }
 function WorkflowButton({ narrow, ...props }) {
@@ -209,7 +226,8 @@ function WorkflowButton({ narrow, ...props }) {
 }
 /**
  * Approve (leading) and Request changes. Below `md`, Approve is a split button whose caret holds
- * Request changes; with nothing to approve, Request changes stands alone.
+ * Request changes, the other way round while Approve is blocked, so the lead is what can act; with
+ * nothing to approve, Request changes stands alone.
  */
 function ReviewButtons({ action, onApprove, onRequestChanges, controlRef, secondaryRef, returnFocusTo, narrow, ...rest }) {
     // The bar's hand-off slot goes to Approve while there is one, in either layout, so focus on it
@@ -219,19 +237,22 @@ function ReviewButtons({ action, onApprove, onRequestChanges, controlRef, second
     const approveEl = useRef(null);
     const requestChangesEl = useRef(null);
     const approveRef = useMergedRef(approveEl, action.offersApprove ? controlRef : undefined);
-    const requestChangesRef = useMergedRef(requestChangesEl, action.offersApprove ? (narrow ? undefined : secondaryRef) : controlRef);
+    const requestChangesLeads = !action.offersApprove || (narrow && !!action.approveReason);
+    const requestChangesRef = useMergedRef(requestChangesEl, requestChangesLeads ? controlRef : narrow ? undefined : secondaryRef);
     // Each returns focus to its own button while that is mounted, else to the control left.
     const approveReturn = () => (approveEl.current?.isConnected ? approveEl.current : returnFocusTo());
     const requestChangesReturn = () => requestChangesEl.current?.isConnected ? requestChangesEl.current : returnFocusTo();
-    const approve = (_jsx(ReviewButton, { buttonRef: approveRef, action: action, color: "brand", testId: "approve-button", label: EDITOR_ACTIONS.approve, onClick: () => onApprove(approveReturn) }));
+    const approve = (_jsx(ReviewButton, { buttonRef: approveRef, action: approveAction(action), color: "brand", testId: "approve-button", label: EDITOR_ACTIONS.approve, onClick: () => onApprove(approveReturn) }));
     const requestChanges = (_jsx(ReviewButton, { buttonRef: requestChangesRef, action: action, color: "orange", testId: "request-changes-button", label: EDITOR_ACTIONS.requestChanges, onClick: () => onRequestChanges(requestChangesReturn) }));
     if (!action.offersApprove)
         return requestChanges;
     if (!narrow) {
         return (_jsxs(Group, { gap: 8, wrap: "nowrap", style: { flexShrink: 0 }, children: [requestChanges, approve] }));
     }
-    return (_jsxs(Button.Group, { style: { flexShrink: 0 }, renderRoot: (props) => _jsx("div", { ...props, role: "group", "aria-label": "Review controls" }), children: [approve, _jsx(WorkflowCaret, { ...rest, action: action, onApprove: onApprove, onRequestChanges: onRequestChanges, returnFocusTo: returnFocusTo, includeApprove: false, color: "brand", controlRef: secondaryRef })] }));
+    return (_jsxs(Button.Group, { style: { flexShrink: 0 }, renderRoot: (props) => _jsx("div", { ...props, role: "group", "aria-label": "Review controls" }), children: [requestChangesLeads ? requestChanges : approve, _jsx(WorkflowCaret, { ...rest, action: action, onApprove: onApprove, onRequestChanges: onRequestChanges, returnFocusTo: returnFocusTo, includeApprove: requestChangesLeads, includeRequestChanges: !requestChangesLeads, color: requestChangesLeads ? 'orange' : 'brand', controlRef: secondaryRef })] }));
 }
+/** The review action as Approve reads it, which has a block of its own. */
+const approveAction = (action) => action.approveReason ? { ...action, blocked: true, reason: action.approveReason } : action;
 /** One review button, blocked as a whole with the action's reason. */
 function ReviewButton({ action, buttonRef, color, testId, label, onClick, }) {
     return (_jsx(Tooltip, { label: action.reason, disabled: !action.reason, multiline: true, maw: 320, children: _jsx(Button, { ref: buttonRef, size: "sm", variant: "light", color: color, style: { flexShrink: 0 }, onClick: () => {
@@ -254,15 +275,15 @@ function SubmitOrWithdrawButton({ action, onSubmit, onWithdraw, controlRef, retu
 }
 /**
  * The workflow action's caret below `md`, on Save all or the way forward or, for a review, beside
- * Approve. `includeApprove` is false there, where Approve is already a button.
+ * the action that leads, which `includeApprove` or `includeRequestChanges` leaves out.
  */
-function WorkflowCaret({ action, onSubmit, onWithdraw, onApprove, onRequestChanges, controlRef, returnFocusTo, includeApprove = true, color, }) {
+function WorkflowCaret({ action, onSubmit, onWithdraw, onApprove, onRequestChanges, controlRef, returnFocusTo, includeApprove = true, includeRequestChanges = true, color, }) {
     const caret = useRef(null);
     const caretRef = useMergedRef(caret, controlRef);
     const menuFocus = useMenuItemFocusReturn(caret);
     const withdraw = action.kind === 'withdraw';
-    // Beside Approve it holds only Request changes, and a dialog it opens returns to the caret.
-    const reviewCaret = action.kind === 'review' && !includeApprove;
+    // Beside the lead it holds one action, and a dialog it opens returns to the caret.
+    const reviewCaret = action.kind === 'review' && !(includeApprove && includeRequestChanges);
     const caretLabel = reviewCaret ? 'More review actions' : 'Branch actions';
     const returnToCaret = reviewCaret
         ? () => (caret.current?.isConnected ? caret.current : returnFocusTo())
@@ -270,7 +291,7 @@ function WorkflowCaret({ action, onSubmit, onWithdraw, onApprove, onRequestChang
     const blockedReason = action.blocked ? action.reason || BUSY_REASON : undefined;
     return (
     // Bounded, so a blocked item's reason wraps on a phone rather than run off the screen.
-    _jsxs(Menu, { withinPortal: true, shadow: "sm", position: "bottom-end", width: 280, ...menuFocus.menu, children: [_jsx(Tooltip, { label: caretLabel, events: { hover: true, focus: true, touch: false }, children: _jsx(Menu.Target, { children: _jsx(Button, { ref: caretRef, variant: "light", color: color, size: "sm", px: 8, "aria-label": caretLabel, "data-testid": "branch-actions-button", style: { borderInlineStart: '1px solid var(--canopy-input-border)' }, children: _jsx(IconChevronDown, { size: 14, "aria-hidden": "true" }) }) }) }), _jsx(Menu.Dropdown, { ...menuFocus.dropdown, children: action.kind === 'review' ? (_jsxs(_Fragment, { children: [action.offersApprove && includeApprove && (_jsx(ReasonedMenuItem, { "data-testid": "approve-menu-item", blockedReason: blockedReason, onClick: () => onApprove(returnToCaret), children: EDITOR_ACTIONS.approve })), _jsx(ReasonedMenuItem, { "data-testid": "request-changes-menu-item", blockedReason: blockedReason, onClick: () => onRequestChanges(returnToCaret), children: EDITOR_ACTIONS.requestChanges })] })) : (_jsx(ReasonedMenuItem, { "data-testid": withdraw ? 'withdraw-menu-item' : 'submit-menu-item', blockedReason: blockedReason, onClick: () => {
+    _jsxs(Menu, { withinPortal: true, shadow: "sm", position: "bottom-end", width: 280, ...menuFocus.menu, children: [_jsx(Tooltip, { label: caretLabel, events: { hover: true, focus: true, touch: false }, children: _jsx(Menu.Target, { children: _jsx(Button, { ref: caretRef, variant: "light", color: color, size: "sm", px: 8, "aria-label": caretLabel, "data-testid": "branch-actions-button", style: { borderInlineStart: '1px solid var(--canopy-input-border)' }, children: _jsx(IconChevronDown, { size: 14, "aria-hidden": "true" }) }) }) }), _jsx(Menu.Dropdown, { ...menuFocus.dropdown, children: action.kind === 'review' ? (_jsxs(_Fragment, { children: [action.offersApprove && includeApprove && (_jsx(ReasonedMenuItem, { "data-testid": "approve-menu-item", blockedReason: action.approveReason ?? blockedReason, onClick: () => onApprove(returnToCaret), children: EDITOR_ACTIONS.approve })), includeRequestChanges && (_jsx(ReasonedMenuItem, { "data-testid": "request-changes-menu-item", blockedReason: blockedReason, onClick: () => onRequestChanges(returnToCaret), children: EDITOR_ACTIONS.requestChanges }))] })) : (_jsx(ReasonedMenuItem, { "data-testid": withdraw ? 'withdraw-menu-item' : 'submit-menu-item', blockedReason: blockedReason, onClick: () => {
                         if (withdraw)
                             onWithdraw(returnFocusTo);
                         else

package/dist/editor/components/EntryHeader.d.ts

@@ -67,6 +67,8 @@ export interface EntryHeaderProps {
     branchReviewing?: boolean;
     /** The user would review this branch but its pull request was closed; the lock reason says so. */
     branchPullRequestClosed?: boolean;
+    /** The server refuses Approve on this branch (`describeBranchLock`). */
+    branchApproveBlocked?: boolean;
 }
 /** The open entry's breadcrumb, menu, unsaved dot and "Read-only" chip, then Save, over the panes. */
-export declare function EntryHeader({ currentEntry, entryLoading, branchName, busy, breadcrumbSegments, onCollectionOpen, onEntryReveal, navigatorToggleRef, onShowChanges, showChangesPending, showChangesRef, onFileReload, onFileDiscardDraft, onEntryRename, onEntryDelete, onSave, saveAllRunning, saving, savedSignal, savedHere, hasUnsavedChanges, entryHasDraft, draftStorageFailed, entryReadOnly, entryUnavailable, branchStatus, branchReadOnly, branchWriteBlocked, branchLoading, branchPending, branchMissing, branchReviewing, branchPullRequestClosed, }: EntryHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function EntryHeader({ currentEntry, entryLoading, branchName, busy, breadcrumbSegments, onCollectionOpen, onEntryReveal, navigatorToggleRef, onShowChanges, showChangesPending, showChangesRef, onFileReload, onFileDiscardDraft, onEntryRename, onEntryDelete, onSave, saveAllRunning, saving, savedSignal, savedHere, hasUnsavedChanges, entryHasDraft, draftStorageFailed, entryReadOnly, entryUnavailable, branchStatus, branchReadOnly, branchWriteBlocked, branchLoading, branchPending, branchMissing, branchReviewing, branchPullRequestClosed, branchApproveBlocked, }: EntryHeaderProps): import("react/jsx-runtime").JSX.Element;

package/dist/editor/components/EntryHeader.js

@@ -28,7 +28,7 @@ const ShowChangesButton = ({ onClick, buttonRef, }) => {
     return (_jsx(Button, { ref: placeholder ? undefined : buttonRef, size: "compact-sm", variant: "subtle", leftSection: icon, onClick: onClick, "data-testid": placeholder ? 'entry-show-changes-pending' : 'entry-show-changes', ...hold, children: EDITOR_ACTIONS.showChanges }));
 };
 /** The open entry's breadcrumb, menu, unsaved dot and "Read-only" chip, then Save, over the panes. */
-export function EntryHeader({ currentEntry, entryLoading = false, branchName, busy, breadcrumbSegments, onCollectionOpen, onEntryReveal, navigatorToggleRef, onShowChanges, showChangesPending = false, showChangesRef, onFileReload, onFileDiscardDraft, onEntryRename, onEntryDelete, onSave, saveAllRunning, saving = false, savedSignal, savedHere = false, hasUnsavedChanges, entryHasDraft = hasUnsavedChanges, draftStorageFailed = false, entryReadOnly = false, entryUnavailable = false, branchStatus, branchReadOnly = false, branchWriteBlocked = false, branchLoading = false, branchPending = false, branchMissing = false, branchReviewing = false, branchPullRequestClosed = false, }) {
+export function EntryHeader({ currentEntry, entryLoading = false, branchName, busy, breadcrumbSegments, onCollectionOpen, onEntryReveal, navigatorToggleRef, onShowChanges, showChangesPending = false, showChangesRef, onFileReload, onFileDiscardDraft, onEntryRename, onEntryDelete, onSave, saveAllRunning, saving = false, savedSignal, savedHere = false, hasUnsavedChanges, entryHasDraft = hasUnsavedChanges, draftStorageFailed = false, entryReadOnly = false, entryUnavailable = false, branchStatus, branchReadOnly = false, branchWriteBlocked = false, branchLoading = false, branchPending = false, branchMissing = false, branchReviewing = false, branchPullRequestClosed = false, branchApproveBlocked = false, }) {
     const branchLockReason = describeBranchLock({
         branchStatus,
         branchReadOnly,
@@ -37,6 +37,7 @@ export function EntryHeader({ currentEntry, entryLoading = false, branchName, bu
         branchMissing,
         reviewing: branchReviewing,
         pullRequestClosed: branchPullRequestClosed,
+        approveBlocked: branchApproveBlocked,
     });
     const entryLockReason = entryReadOnly
         ? "You don't have edit access to this entry. Ask a CanopyCMS admin to grant it."

package/dist/editor/components/TooltipDetail.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+/**
+ * A detail that only a Tooltip would show: hidden text for assistive tech, plus a Tooltip that
+ * opens on hover, focus and touch. The trigger is a focusable span, not a button: it does nothing
+ * when pressed, so it must not be announced as one. A trigger with no text of its own, such as an
+ * icon, takes its name from `name`.
+ */
+export declare function TooltipDetail({ detail, name, maw, preLine, children, }: {
+    detail: string;
+    name?: string;
+    maw?: number;
+    preLine?: boolean;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/editor/components/TooltipDetail.js

@@ -0,0 +1,18 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { Box, Tooltip, VisuallyHidden } from '@mantine/core';
+/**
+ * A detail that only a Tooltip would show: hidden text for assistive tech, plus a Tooltip that
+ * opens on hover, focus and touch. The trigger is a focusable span, not a button: it does nothing
+ * when pressed, so it must not be announced as one. A trigger with no text of its own, such as an
+ * icon, takes its name from `name`.
+ */
+export function TooltipDetail({ detail, name, maw = 320, preLine = false, children, }) {
+    const detailId = useId();
+    return (_jsxs(_Fragment, { children: [_jsx(Tooltip
+            // A sighted user sees only the icon, so the tooltip names it too.
+            , { 
+                // A sighted user sees only the icon, so the tooltip names it too.
+                label: name ? `${name}: ${detail}` : detail, multiline: true, maw: maw, style: preLine ? { whiteSpace: 'pre-line' } : undefined, events: { hover: true, focus: true, touch: true }, children: _jsx(Box, { component: "span", tabIndex: 0, role: name ? 'img' : undefined, "aria-label": name, "aria-describedby": detailId, className: "mantine-focus-auto", display: "inline-flex", style: { borderRadius: 'var(--mantine-radius-xl)' }, children: children }) }), _jsx(VisuallyHidden, { id: detailId, children: detail })] }));
+}

package/dist/editor/copy.d.ts

@@ -27,5 +27,12 @@ export declare const EDITOR_ACTIONS: {
  * `one` and `many` name what the list holds.
  */
 export declare const listFullReason: (maxItems: number, one?: string, many?: string) => string;
+/** Why Submit for review can't act: the worker pushes nothing for a branch rewritten on GitHub. */
+export declare const rewrittenSubmitReason: (isAdmin: boolean) => string;
+/**
+ * Why Approve can't act: what's approved may not be what the pull request holds. The branch's hold
+ * says how to finish the submit, where it can be retried at all.
+ */
+export declare const UNFINISHED_SUBMIT_APPROVE_REASON = "The last submit didn't finish, so this branch can't be approved yet. Use \"Request changes\" to send it back to its editor.";
 /** Why Approve and Request changes can't act: the pull request they act on is gone. */
 export declare const CLOSED_PULL_REQUEST_REASON = "The pull request was closed on GitHub. Use \"Withdraw from review\", then submit it again to open a new one.";

package/dist/editor/copy.js

@@ -27,5 +27,14 @@ export const EDITOR_ACTIONS = {
  * `one` and `many` name what the list holds.
  */
 export const listFullReason = (maxItems, one = 'item', many = 'items') => `This list holds at most ${maxItems} ${maxItems === 1 ? one : many}. Remove one to add another.`;
+/** Why Submit for review can't act: the worker pushes nothing for a branch rewritten on GitHub. */
+export const rewrittenSubmitReason = (isAdmin) => isAdmin
+    ? 'This branch can\'t be submitted until the changes made to it on GitHub are sorted out. See the "Branches" tab in "System health".'
+    : "This branch can't be submitted until an admin sorts out the changes made to it on GitHub.";
+/**
+ * Why Approve can't act: what's approved may not be what the pull request holds. The branch's hold
+ * says how to finish the submit, where it can be retried at all.
+ */
+export const UNFINISHED_SUBMIT_APPROVE_REASON = 'The last submit didn\'t finish, so this branch can\'t be approved yet. Use "Request changes" to send it back to its editor.';
 /** Why Approve and Request changes can't act: the pull request they act on is gone. */
 export const CLOSED_PULL_REQUEST_REASON = 'The pull request was closed on GitHub. Use "Withdraw from review", then submit it again to open a new one.';

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

@@ -1,4 +1,4 @@
-import type { ConflictStatus, PullRequestState, SyncStatus } from '../../types.js';
+import type { BranchHold, ConflictStatus, PullRequestState, SyncStatus } from '../../types.js';
 import type { OperatingMode } from '../../operating-mode/index.js';
 import type { CommentThread } from '../../comment-store.js';
 import type { BranchListItem } from '../../api/branch.js';
@@ -50,6 +50,8 @@ interface BranchSummary {
     conflictStatus?: ConflictStatus;
     /** ContentIds of entries where --theirs was applied during rebase; cleared on clean rebase */
     conflictFiles?: string[];
+    /** What is stuck and needs a person (api/branch.ts). */
+    hold?: BranchHold;
     commentCount: number;
     isProtected: boolean;
     readOnly: boolean;
@@ -61,8 +63,9 @@ interface BranchSummary {
     writeBlocked: boolean;
     /**
      * Server-computed compound submit rule: true when the branch can never be
-     * submitted for review, for EITHER reason -- it is the protected base
-     * branch, or its workflow status has moved past 'editing'. Mirrors
+     * submitted for review, for ANY reason -- it is the protected base
+     * branch, its workflow status has moved past 'editing', or it was rewritten
+     * on GitHub (`toBranchListItem`). Mirrors
      * `writeBlocked`'s shape (a base-branch half + a status half, combined),
      * except this one is built from `isProtected`/`submitBlocked` (both modes)
      * rather than `readOnly` (prod-only) -- see
@@ -72,6 +75,8 @@ interface BranchSummary {
      * re-derive the status/protection halves client-side.
      */
     submitBlocked: boolean;
+    /** Server-computed: the API refuses Approve, as the last submit didn't finish. */
+    approveBlocked?: boolean;
 }
 export interface UseBranchManagerOptions {
     initialBranch: string;

package/dist/editor/hooks/useBranchManager.js

@@ -25,7 +25,7 @@ import { writeEditorUrl } from './editor-history.js';
 import { approveMessage, NoteNotSavedMessage, RequestChangesForm, } from '../components/ReviewDialogs.js';
 const BRANCHES_LOAD_FAILED_TOAST_ID = 'canopy-branches-load-failed';
 const BRANCH_OUTCOME_UNKNOWN_TOAST_ID = 'canopy-branch-outcome-unknown';
-/** The API's 409: the branch is no longer in the state the action needs, so a retry cannot pass. */
+/** The API's 409: the branch isn't in the state the action needs, so a retry cannot pass. */
 class StaleStatusError extends Error {
     constructor() {
         super(...arguments);
@@ -191,7 +191,7 @@ const showRequestChangesConfirmation = (branchName, pr, initialNote, onNoteChang
  * delete menu item calls `onDelete` directly, so this dialog is the only confirmation; `color:
  * 'red'` matches that item.
  */
-const showDeleteConfirmation = (branchName, pr, onConfirm, onDismiss) => {
+const showDeleteConfirmation = (branchName, pr, mayHoldUnpublished, onConfirm, onDismiss) => {
     // The server deletes the GitHub branch only for a branch with a PR (api/github-sync.ts's
     // syncDeleteRemoteBranch); GitHub closes a PR whose branch is deleted.
     const bullets = [
@@ -200,6 +200,9 @@ const showDeleteConfirmation = (branchName, pr, onConfirm, onDismiss) => {
             ? `Delete its branch on GitHub too, which closes pull request #${pr.pullRequestNumber} if it is still open`
             : undefined,
         'Discard any unsaved or unmerged changes',
+        mayHoldUnpublished
+            ? 'Remove the only copy of any changes that never reached GitHub, and the warning about them'
+            : undefined,
     ].filter((b) => b !== undefined);
     openConfirm({
         title: 'Delete branch',
@@ -396,6 +399,8 @@ export function useBranchManager(options) {
                 syncFailureReason: b.syncFailureReason,
                 conflictStatus: b.conflictStatus,
                 conflictFiles: b.conflictFiles,
+                hold: b.hold,
+                approveBlocked: b.approveBlocked,
                 commentCount: unresolvedCount,
                 // Fail CLOSED (`?? true`): these flags are optional on the wire (see
                 // BranchListItem's doc comment in api/branch.ts) so a version-skewed
@@ -560,10 +565,13 @@ export function useBranchManager(options) {
         }
     };
     const reviewFailureId = (kind, branch) => `canopy-${kind}-failed-${branch}`;
+    const submitRefusedId = (branch) => `canopy-submit-refused-${branch}`;
+    const deleteRefusedId = (branch) => `canopy-delete-refused-${branch}`;
     /**
      * Why an Approve or Request changes failed. Retry only on an API 5xx, 408, 429 or unsent request;
      * a timeout or gateway 5xx may have landed, so it reloads and says what to check. Other 4xx: a
-     * plain message and a reload. A 409 means the branch left review (see `showLeftReview`).
+     * plain message and a reload. A 409 means the branch left review, or for Approve that its last
+     * submit didn't finish (see `showLeftReview`, which shows the server's reason either way).
      */
     const reportReviewFailure = async (err, kind, branch, details) => {
         if (err instanceof StaleStatusError) {
@@ -657,6 +665,7 @@ export function useBranchManager(options) {
                         if (stamped && branchNameToSubmit === openListedName()) {
                             options.onStamped?.(stamped);
                         }
+                        notifications.hide(submitRefusedId(branchNameToSubmit));
                         notifications.show({
                             message: submittedMessage(stamped?.length ?? 0),
                             color: 'green',
@@ -666,7 +675,23 @@ export function useBranchManager(options) {
                         resolve();
                     }
                     catch (err) {
-                        await reportActionFailure(err, 'Failed to submit branch', EDITOR_ACTIONS.submitForReview);
+                        if (err instanceof RefusedError && err.status === 409) {
+                            // Nothing is lost, and it says what to do, so it stays until read. The reload shows
+                            // whatever the page hadn't heard yet, such as what's holding the branch.
+                            const id = submitRefusedId(branchNameToSubmit);
+                            notifications.hide(id);
+                            notifications.show({
+                                id,
+                                message: err.message,
+                                color: 'yellow',
+                                autoClose: false,
+                                withCloseButton: true,
+                            });
+                            await loadBranches();
+                        }
+                        else {
+                            await reportActionFailure(err, 'Failed to submit branch', EDITOR_ACTIONS.submitForReview);
+                        }
                         reject(err);
                     }
                     finally {
@@ -813,7 +838,8 @@ export function useBranchManager(options) {
         const branchNameToDelete = listedName(requested);
         const listedBefore = latest.current.branches;
         return singleFlight('delete', branchNameToDelete, () => new Promise((resolve) => {
-            showDeleteConfirmation(shownName(branchNameToDelete), pullRequestOf(branchNameToDelete), async () => {
+            showDeleteConfirmation(shownName(branchNameToDelete), pullRequestOf(branchNameToDelete), listedBefore.find((b) => b.name === branchNameToDelete)?.hold?.kind ===
+                'unpublished-at-merge', async () => {
                 options.setBusy(true);
                 try {
                     const result = await apiClient.branches.delete({
@@ -822,6 +848,7 @@ export function useBranchManager(options) {
                     // The API's own 404: the branch is already gone, by an earlier unanswered delete or
                     // another user's.
                     if (!result.ok && result.status === 404 && !isNonApiResponse(result)) {
+                        notifications.hide(deleteRefusedId(branchNameToDelete));
                         notifications.show({ message: 'Branch deleted', color: 'green' });
                         leaveDeletedBranch(branchNameToDelete, listedBefore, await reloadBranches());
                         return;
@@ -829,6 +856,7 @@ export function useBranchManager(options) {
                     if (!result.ok)
                         throw actionError(result, 'Failed to delete branch');
                     const cleanupWarning = result.data?.cleanupWarning;
+                    notifications.hide(deleteRefusedId(branchNameToDelete));
                     notifications.show(cleanupWarning
                         ? {
                             message: `Branch deleted, with a warning: ${cleanupWarning}`,
@@ -839,6 +867,20 @@ export function useBranchManager(options) {
                     leaveDeletedBranch(branchNameToDelete, listedBefore, await reloadBranches());
                 }
                 catch (err) {
+                    if (err instanceof RefusedError && err.status === 409) {
+                        // Nothing is lost, and the list says what changed.
+                        const id = deleteRefusedId(branchNameToDelete);
+                        notifications.hide(id);
+                        notifications.show({
+                            id,
+                            message: err.message,
+                            color: 'yellow',
+                            autoClose: false,
+                            withCloseButton: true,
+                        });
+                        await reloadBranches();
+                        return;
+                    }
                     if (!isUnanswered(err)) {
                         await reportActionFailure(err, 'Failed to delete branch', 'Delete branch');
                         return;
@@ -848,6 +890,7 @@ export function useBranchManager(options) {
                     const recent = pendingBranches.filter((p) => Date.now() - p.addedAt <= CREATED_BRANCH_GRACE_MS);
                     const listed = mergePendingBranches(fresh?.branches ?? [], recent).some((b) => sanitizeBranchName(b.name) === sanitizeBranchName(branchNameToDelete));
                     if (fresh && !listed) {
+                        notifications.hide(deleteRefusedId(branchNameToDelete));
                         notifications.show({ message: 'Branch deleted', color: 'green' });
                         leaveDeletedBranch(branchNameToDelete, listedBefore, fresh);
                     }

package/dist/pr-comments.d.ts

@@ -17,6 +17,8 @@ export declare function renderPrCommentsBody(options: {
     branch: string;
     editorUrl?: string;
     body: string;
+    /** Leaves the comment summary as it is, for a caller without the editor URL its links need. */
+    reviewBlockOnly?: boolean;
     warn: (message: string) => void;
 }): Promise<string | undefined>;
 /**