canopycms 0.0.68-int.98 → 0.1.0

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

@@ -33,7 +33,7 @@ export interface ThreadCarouselProps {
     contextType: 'field' | 'entry' | 'branch';
     /** Current user ID */
     currentUserId: string;
-    /** Whether user can resolve threads */
+    /** Whether the user may resolve any thread; a thread's own author always may resolve it. */
     canResolve: boolean;
     /** Handler to add a new comment (creates new thread or adds to existing) */
     onAddComment: (text: string, threadId?: string) => Promise<void>;

package/dist/editor/comments/ThreadCarousel.js

@@ -1,9 +1,11 @@
 'use client';
 import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState, useMemo, useEffect, useRef } from 'react';
-import { ActionIcon, Alert, Button, Group, Paper, Stack, Text, Textarea } from '@mantine/core';
-import { IconChevronLeft, IconChevronRight, IconAlertCircle } from '@tabler/icons-react';
+import { ActionIcon, Button, Group, Paper, Stack, Text, Textarea, Tooltip } from '@mantine/core';
+import { IconChevronLeft, IconChevronRight } from '@tabler/icons-react';
 import { InlineCommentThread } from './InlineCommentThread.js';
+import { useTrackedWrites } from './use-tracked-writes.js';
+import { CommentWriteAlert, toCommentWriteFailure, } from './CommentWriteAlert.js';
 export const ThreadCarousel = ({ threads, label = 'Comments', contextType: _, currentUserId, canResolve, onAddComment, onResolveThread, autoFocus, autoOpenNewThread, highlightThreadId, onGetUserMetadata, onCancelNewThread, }) => {
     const [currentIndex, setCurrentIndex] = useState(0);
     const [showNewThreadBox, setShowNewThreadBox] = useState(false);
@@ -112,39 +114,34 @@ export const ThreadCarousel = ({ threads, label = 'Comments', contextType: _, cu
             scrollToIndex(newIndex);
         }
     };
-    const handleAddReply = async (threadId, text) => {
-        try {
-            setError(null);
-            await onAddComment(text, threadId);
-        }
-        catch (err) {
-            setError(err instanceof Error ? err.message : 'Failed to add reply');
-            throw err; // Re-throw so InlineCommentThread can handle it
-        }
-    };
+    const { track } = useTrackedWrites();
+    const addComment = track(onAddComment);
+    const resolveThread = track(onResolveThread);
+    // A resolved thread's controls unmount with the focused button, so focus lands here.
+    const labelRef = useRef(null);
     const handleCreateNewThread = async () => {
         if (!newThreadText.trim())
             return;
         setIsSubmitting(true);
         setError(null);
         try {
-            await onAddComment(newThreadText);
+            await addComment(newThreadText);
             setNewThreadText('');
             setShowNewThreadBox(false);
         }
         catch (err) {
-            setError(err instanceof Error ? err.message : 'Failed to create comment');
+            setError(toCommentWriteFailure(err));
         }
         finally {
             setIsSubmitting(false);
         }
     };
     const unresolvedCount = sortedThreads.filter((t) => !t.resolved).length;
-    return (_jsx(Paper, { p: "sm", bg: "gray.0", style: { marginTop: 8 }, children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Group, { justify: "space-between", align: "center", children: [_jsxs(Group, { gap: "xs", children: [_jsxs(Text, { size: "sm", fw: 600, children: [label, sortedThreads.length > 0 && ` (${sortedThreads.length})`] }), unresolvedCount > 0 && (_jsxs(Text, { size: "xs", c: "orange", fw: 600, children: [unresolvedCount, " unresolved"] }))] }), _jsxs(Group, { gap: "xs", children: [sortedThreads.length > 1 && (_jsxs(_Fragment, { children: [_jsx(ActionIcon, { size: "sm", variant: "subtle", onClick: handlePrevious, disabled: currentIndex === 0, children: _jsx(IconChevronLeft, { size: 16 }) }), _jsxs(Text, { size: "xs", fw: 500, children: [currentIndex + 1, "/", sortedThreads.length] }), _jsx(ActionIcon, { size: "sm", variant: "subtle", onClick: handleNext, disabled: currentIndex === sortedThreads.length - 1, children: _jsx(IconChevronRight, { size: 16 }) }), _jsx("div", { style: {
+    return (_jsx(Paper, { p: "sm", bg: "var(--mantine-color-default-hover)", style: { marginTop: 8 }, children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Group, { justify: "space-between", align: "center", children: [_jsxs(Group, { gap: "xs", children: [_jsxs(Text, { ref: labelRef, size: "sm", fw: 600, tabIndex: -1, children: [label, sortedThreads.length > 0 && ` (${sortedThreads.length})`] }), unresolvedCount > 0 && (_jsxs(Text, { size: "xs", c: "orange", fw: 600, children: [unresolvedCount, " unresolved"] }))] }), _jsxs(Group, { gap: "xs", children: [sortedThreads.length > 1 && (_jsxs(_Fragment, { children: [_jsx(Tooltip, { label: "Previous thread", children: _jsx(ActionIcon, { variant: "subtle", onClick: handlePrevious, disabled: currentIndex === 0, "aria-label": "Previous thread", children: _jsx(IconChevronLeft, { size: 16, "aria-hidden": true }) }) }), _jsxs(Text, { size: "xs", fw: 500, children: [currentIndex + 1, "/", sortedThreads.length] }), _jsx(Tooltip, { label: "Next thread", children: _jsx(ActionIcon, { variant: "subtle", onClick: handleNext, disabled: currentIndex === sortedThreads.length - 1, "aria-label": "Next thread", children: _jsx(IconChevronRight, { size: 16, "aria-hidden": true }) }) }), _jsx("div", { style: {
                                                 width: 1,
                                                 height: 16,
-                                                background: 'var(--mantine-color-gray-4)',
-                                            } })] })), _jsx(Button, { size: "xs", variant: "light", onClick: () => setShowNewThreadBox(!showNewThreadBox), children: "+ New" })] })] }), error && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", variant: "light", onClose: () => setError(null), withCloseButton: true, children: error })), showNewThreadBox && (_jsx(Paper, { withBorder: true, p: "sm", bg: "white", children: _jsxs(Stack, { gap: "xs", children: [_jsx(Textarea, { placeholder: "Start a new thread...", value: newThreadText, onChange: (e) => setNewThreadText(e.target.value), minRows: 2, disabled: isSubmitting, autoFocus: true, "data-testid": "new-thread-textarea" }), _jsxs(Group, { gap: "xs", children: [_jsx(Button, { size: "xs", onClick: handleCreateNewThread, loading: isSubmitting, disabled: !newThreadText.trim(), "data-testid": "create-thread-button", children: "Create Thread" }), _jsx(Button, { size: "xs", variant: "subtle", onClick: () => {
+                                                background: 'var(--mantine-color-default-border)',
+                                            } })] })), _jsx(Button, { variant: "light", onClick: () => setShowNewThreadBox(!showNewThreadBox), children: "+ New" })] })] }), error && _jsx(CommentWriteAlert, { failure: error, onClose: () => setError(null) }), showNewThreadBox && (_jsx(Paper, { withBorder: true, p: "sm", bg: "var(--mantine-color-body)", children: _jsxs(Stack, { gap: "xs", children: [_jsx(Textarea, { placeholder: "Start a new thread...", value: newThreadText, onChange: (e) => setNewThreadText(e.target.value), minRows: 2, disabled: isSubmitting, autoFocus: true, "data-testid": "new-thread-textarea" }), _jsxs(Group, { gap: "xs", children: [_jsx(Button, { onClick: handleCreateNewThread, loading: isSubmitting, disabled: !newThreadText.trim(), "data-testid": "create-thread-button", children: "Create Thread" }), _jsx(Button, { variant: "subtle", onClick: () => {
                                             setShowNewThreadBox(false);
                                             onCancelNewThread?.();
                                         }, children: "Cancel" })] })] }) })), sortedThreads.length > 0 && (_jsxs("div", { style: {
@@ -173,7 +170,7 @@ export const ThreadCarousel = ({ threads, label = 'Comments', contextType: _, cu
                                             outlineOffset: isHighlighted ? 2 : undefined,
                                             borderRadius: isHighlighted ? 8 : undefined,
                                             transition: 'outline 0.3s ease, outline-offset 0.3s ease',
-                                        }, children: _jsx(InlineCommentThread, { thread: thread, onAddReply: (text) => handleAddReply(thread.id, text), onResolve: () => onResolveThread(thread.id), currentUserId: currentUserId, canResolve: canResolve, onGetUserMetadata: onGetUserMetadata }) }, thread.id));
+                                        }, children: _jsx(InlineCommentThread, { thread: thread, onAddReply: (text) => addComment(text, thread.id), onResolve: () => resolveThread(thread.id), focusAfterResolve: () => labelRef.current, currentUserId: currentUserId, canResolve: canResolve, onGetUserMetadata: onGetUserMetadata }) }, thread.id));
                                 }), sortedThreads.length > 1 && (_jsx("div", { style: {
                                         flexShrink: 0,
                                         width: 60, // Match peekaboo size
@@ -184,7 +181,7 @@ export const ThreadCarousel = ({ threads, label = 'Comments', contextType: _, cu
                                 right: 0,
                                 width: 60,
                                 height: '100%',
-                                background: 'linear-gradient(to left, var(--mantine-color-gray-0) 0%, transparent 100%)',
+                                background: 'linear-gradient(to left, var(--mantine-color-default-hover) 0%, transparent 100%)',
                                 pointerEvents: 'none',
                             } })), _jsx("div", { onMouseDown: handleResizeStart, style: {
                                 position: 'absolute',
@@ -199,7 +196,7 @@ export const ThreadCarousel = ({ threads, label = 'Comments', contextType: _, cu
                                 alignItems: 'center',
                                 justifyContent: 'center',
                             }, onMouseEnter: (e) => {
-                                e.currentTarget.style.background = 'var(--mantine-color-gray-3)';
+                                e.currentTarget.style.background = 'var(--mantine-color-default-hover)';
                             }, onMouseLeave: (e) => {
                                 if (!isResizing) {
                                     e.currentTarget.style.background = 'transparent';
@@ -208,6 +205,6 @@ export const ThreadCarousel = ({ threads, label = 'Comments', contextType: _, cu
                                     width: 40,
                                     height: 3,
                                     borderRadius: 2,
-                                    background: 'var(--mantine-color-gray-5)',
+                                    background: 'var(--mantine-color-dimmed)',
                                 } }) })] })), sortedThreads.length === 0 && !showNewThreadBox && (_jsx(Text, { size: "xs", c: "dimmed", ta: "center", py: "xs", children: "No comments yet. Click \"+ New\" to start a thread." }))] }) }));
 };

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

@@ -0,0 +1,28 @@
+import React from 'react';
+import type { CommentThread } from '../../comment-store.js';
+export interface ThreadReplyControlsProps {
+    /** An unresolved thread; a resolved one has nothing to reply to. */
+    thread: CommentThread;
+    /** Adds a reply to this thread; rejecting keeps the box open with the text. */
+    onAddReply: (text: string) => Promise<void>;
+    onResolve: () => Promise<void>;
+    /**
+     * Where focus goes once the thread is resolved and these controls are gone, unless the user put
+     * it somewhere else after clicking Resolve.
+     */
+    focusAfterResolve?: () => HTMLElement | null | undefined;
+    currentUserId: string;
+    /** Whether the user may resolve any thread; a thread's own author always may resolve it. */
+    canResolve: boolean;
+    /** The reply draft, when the caller keeps it, so it outlives this component; with `onReplyTextChange`. */
+    replyText?: string;
+    onReplyTextChange?: (text: string) => void;
+}
+/** Refocuses `box` when a submit settles: the busy button disabled itself and dropped focus. */
+export declare const useRefocusAfterSubmit: (submitting: boolean, box: React.RefObject<HTMLTextAreaElement | null>) => void;
+/**
+ * A thread's Reply and Resolve controls. Reply opens the reply box in place, so a list of open
+ * threads shows buttons rather than one box each; Cancel closes it and keeps the draft. Reply and
+ * Resolve each show only their own progress, and the one error here belongs to this thread.
+ */
+export declare const ThreadReplyControls: React.FC<ThreadReplyControlsProps>;

package/dist/editor/comments/ThreadReplyControls.js

@@ -0,0 +1,92 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { Button, Group, Stack, Textarea } from '@mantine/core';
+import { moveFocusIfUnmoved } from './move-focus-if-unmoved.js';
+import { CommentWriteAlert, toCommentWriteFailure, } from './CommentWriteAlert.js';
+/** Refocuses `box` when a submit settles: the busy button disabled itself and dropped focus. */
+export const useRefocusAfterSubmit = (submitting, box) => {
+    const wasSubmitting = useRef(false);
+    useEffect(() => {
+        if (wasSubmitting.current && !submitting)
+            box.current?.focus();
+        wasSubmitting.current = submitting;
+    }, [submitting, box]);
+};
+/**
+ * A thread's Reply and Resolve controls. Reply opens the reply box in place, so a list of open
+ * threads shows buttons rather than one box each; Cancel closes it and keeps the draft. Reply and
+ * Resolve each show only their own progress, and the one error here belongs to this thread.
+ */
+export const ThreadReplyControls = ({ thread, onAddReply, onResolve, focusAfterResolve, currentUserId, canResolve, replyText: controlledReply, onReplyTextChange, }) => {
+    const [ownReply, setOwnReply] = useState('');
+    const replyText = controlledReply ?? ownReply;
+    const setReplyText = onReplyTextChange ?? setOwnReply;
+    const [expanded, setExpanded] = useState(replyText.length > 0);
+    const [replying, setReplying] = useState(false);
+    const [resolving, setResolving] = useState(false);
+    const [error, setError] = useState(null);
+    const boxRef = useRef(null);
+    const replyButtonRef = useRef(null);
+    // Where focus goes once the next expand or collapse has rendered.
+    const focusNext = useRef(null);
+    useRefocusAfterSubmit(replying, boxRef);
+    useEffect(() => {
+        if (focusNext.current === (expanded ? 'box' : 'button')) {
+            ;
+            (expanded ? boxRef : replyButtonRef).current?.focus();
+            focusNext.current = null;
+        }
+    }, [expanded]);
+    const expand = () => {
+        focusNext.current = 'box';
+        setExpanded(true);
+    };
+    const collapse = () => {
+        focusNext.current = 'button';
+        setExpanded(false);
+    };
+    const handleReply = async () => {
+        if (!replyText.trim())
+            return;
+        setReplying(true);
+        setError(null);
+        try {
+            await onAddReply(replyText);
+            setReplyText('');
+            collapse();
+        }
+        catch (err) {
+            setError(toCommentWriteFailure(err));
+        }
+        finally {
+            setReplying(false);
+        }
+    };
+    // Resolving closes the thread and unmounts this box, so a draft in it is posted first, never lost.
+    const hasDraft = replyText.trim().length > 0;
+    const handleResolve = async () => {
+        // Taken at the click: a draft posts first, and focus moved during that post is the user's.
+        const origin = document.activeElement;
+        setResolving(true);
+        setError(null);
+        try {
+            if (hasDraft) {
+                await onAddReply(replyText);
+                setReplyText('');
+            }
+            await onResolve();
+            if (focusAfterResolve)
+                moveFocusIfUnmoved(origin, focusAfterResolve());
+        }
+        catch (err) {
+            setError(toCommentWriteFailure(err));
+        }
+        finally {
+            setResolving(false);
+        }
+    };
+    const mayResolve = canResolve || thread.authorId === currentUserId;
+    const resolveButton = mayResolve && (_jsx(Button, { variant: "light", color: "green", onClick: handleResolve, loading: resolving, disabled: replying, "data-testid": "resolve-thread-button", children: hasDraft ? 'Reply and resolve' : 'Resolve' }));
+    return (_jsxs(Stack, { gap: "xs", children: [error && _jsx(CommentWriteAlert, { failure: error, onClose: () => setError(null) }), expanded ? (_jsxs(_Fragment, { children: [_jsx(Textarea, { ref: boxRef, placeholder: "Write a reply\u2026", "aria-label": "Reply to this thread", value: replyText, onChange: (e) => setReplyText(e.target.value), minRows: 2, disabled: replying || resolving }), _jsxs(Group, { gap: "xs", children: [_jsx(Button, { onClick: handleReply, loading: replying, disabled: !replyText.trim() || resolving, "data-testid": "submit-reply-button", children: "Reply" }), _jsx(Button, { variant: "subtle", color: "gray", onClick: collapse, disabled: replying, children: "Cancel" }), resolveButton] })] })) : (_jsxs(Group, { gap: "xs", children: [_jsx(Button, { ref: replyButtonRef, variant: "light", onClick: expand, disabled: resolving, "data-testid": "reply-thread-button", children: "Reply\u2026" }), resolveButton] }))] }));
+};

package/dist/editor/comments/field-comment-context.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+export interface FieldCommentContextValue {
+    /** The canonical canopy path of the field whose `FieldWrapper` provides this. */
+    canopyPath: string;
+    /** That field's comment control, for its label row. */
+    control: React.ReactNode;
+}
+export declare const FieldCommentContext: React.Context<FieldCommentContextValue | null>;
+/**
+ * The comment control for the field at `canopyPath`, for its `FieldLabel`'s `commentControl`
+ * slot; null outside a `FieldWrapper` for that same path. Matching the path keeps a parent's
+ * control out of a nested field's label, and out of list item titles, so each field shows one.
+ */
+export declare const useFieldCommentControl: (canopyPath: string | undefined) => React.ReactNode;

package/dist/editor/comments/field-comment-context.js

@@ -0,0 +1,14 @@
+'use client';
+import { createContext, useContext } from 'react';
+export const FieldCommentContext = createContext(null);
+/**
+ * The comment control for the field at `canopyPath`, for its `FieldLabel`'s `commentControl`
+ * slot; null outside a `FieldWrapper` for that same path. Matching the path keeps a parent's
+ * control out of a nested field's label, and out of list item titles, so each field shows one.
+ */
+export const useFieldCommentControl = (canopyPath) => {
+    const context = useContext(FieldCommentContext);
+    if (!context || canopyPath === undefined || context.canopyPath !== canopyPath)
+        return null;
+    return context.control;
+};

package/dist/editor/comments/form-comments.d.ts

@@ -0,0 +1,48 @@
+import React from 'react';
+import type { CommentThread } from '../../comment-store.js';
+/** A field's comment popover, as the form-level keyboard route reaches it. */
+interface FieldCommentOpener {
+    /** The field's breadcrumb, as its control names it. */
+    subject: string;
+    /** Why a new thread can't be posted on the field yet; the menu shows it beside the field. */
+    blockedReason?: string;
+    /** Opens the popover; `returnFocusTo` stands in for its opener unless a click closes it. */
+    open: (returnFocusTo?: () => HTMLElement | null) => void;
+    /** The field's wrapper, which orders the menu as the form reads. */
+    element: () => HTMLElement | null;
+}
+export interface FormComments {
+    /** Registers a field's popover under its canopy path; returns the unregister. */
+    register: (canopyPath: string, opener: FieldCommentOpener) => () => void;
+    get: (canopyPath: string) => FieldCommentOpener | undefined;
+    /** Every registered field, in the form's order. */
+    fields: () => Array<FieldCommentOpener & {
+        canopyPath: string;
+    }>;
+    /** Records the field that last took focus, which "Comment on …" names; `undefined` forgets it. */
+    noteFocus: (canopyPath: string | undefined) => void;
+    lastFocused: () => string | undefined;
+    /** Bumped whenever the fields or the field last focused change, for `useSyncExternalStore`. */
+    version: () => number;
+    subscribe: (listener: () => void) => () => void;
+}
+/** One form's field comment popovers, for its "Field comments" menu and shortcut. */
+export declare const createFormComments: () => FormComments;
+export declare const FormCommentsContext: React.Context<FormComments | null>;
+export declare const useFormComments: () => FormComments | null;
+/** The shortcut's label for tooltips, in the platform's modifier. */
+export declare const commentsShortcutLabel: () => string;
+/** The shortcut for `aria-keyshortcuts`. */
+export declare const commentsAriaKeyShortcuts: () => string;
+export interface FormCommentsMenuProps {
+    /** Every thread on the branch; the menu counts this entry's field threads. */
+    comments: CommentThread[];
+    entryPath: string;
+}
+/**
+ * The form's one keyboard route to field comments: a menu listing the fields with threads, the
+ * field last focused, and every field, each opening that field's popover. Mod+Alt+M opens
+ * the focused field's popover, or this menu when focus is elsewhere in the editor.
+ */
+export declare const FormCommentsMenu: React.FC<FormCommentsMenuProps>;
+export {};

package/dist/editor/comments/form-comments.js

@@ -0,0 +1,178 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
+import { Badge, Button, Menu, Text, Tooltip } from '@mantine/core';
+import { useHotkeys } from '@mantine/hooks';
+import { IconChevronDown, IconMessages } from '@tabler/icons-react';
+import { modKeyLabel } from '../platform.js';
+const byFormOrder = (a, b) => {
+    if (!a || !b || a === b)
+        return 0;
+    return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+};
+/** One form's field comment popovers, for its "Field comments" menu and shortcut. */
+export const createFormComments = () => {
+    const openers = new Map();
+    const listeners = new Set();
+    let lastFocused;
+    let version = 0;
+    const notify = () => {
+        version += 1;
+        listeners.forEach((listener) => listener());
+    };
+    return {
+        register: (canopyPath, opener) => {
+            openers.set(canopyPath, opener);
+            notify();
+            return () => {
+                if (openers.get(canopyPath) !== opener)
+                    return;
+                openers.delete(canopyPath);
+                notify();
+            };
+        },
+        get: (canopyPath) => openers.get(canopyPath),
+        fields: () => [...openers]
+            .map(([canopyPath, opener]) => ({ ...opener, canopyPath }))
+            .sort((a, b) => byFormOrder(a.element(), b.element())),
+        noteFocus: (canopyPath) => {
+            if (lastFocused === canopyPath)
+                return;
+            lastFocused = canopyPath;
+            notify();
+        },
+        lastFocused: () => lastFocused,
+        version: () => version,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+};
+export const FormCommentsContext = createContext(null);
+export const useFormComments = () => useContext(FormCommentsContext);
+/** The shortcut's label for tooltips, in the platform's modifier. */
+export const commentsShortcutLabel = () => (modKeyLabel() === '⌘' ? '⌘⌥M' : 'Ctrl+Alt+M');
+/** The shortcut for `aria-keyshortcuts`. */
+export const commentsAriaKeyShortcuts = () => modKeyLabel() === '⌘' ? 'Meta+Alt+M' : 'Control+Alt+M';
+const FIELD_SCOPE_SELECTOR = '[data-field-comments]';
+/** One letter of a script other than Latin; AltGr symbols such as "µ" are Common, not letters of one. */
+const NON_LATIN_LETTER = /^(?![\p{Script=Latin}\p{Script=Common}])\p{L}$/u;
+/** Focus is in another overlay, or a modal not holding this form is open, so the shortcut leaves it be. */
+const inOtherOverlay = (active, form) => {
+    const dialog = active?.closest('[role="dialog"]');
+    if (dialog && !dialog.contains(form))
+        return true;
+    return Array.from(document.querySelectorAll('[role="dialog"][aria-modal="true"]')).some((modal) => !modal.contains(form));
+};
+const openThreadsText = (count) => count === 1 ? '1 open thread' : `${count} open threads`;
+/**
+ * The form's one keyboard route to field comments: a menu listing the fields with threads, the
+ * field last focused, and every field, each opening that field's popover. Mod+Alt+M opens
+ * the focused field's popover, or this menu when focus is elsewhere in the editor.
+ */
+export const FormCommentsMenu = ({ comments, entryPath }) => {
+    const formComments = useFormComments();
+    const [opened, setOpened] = useState(false);
+    const triggerRef = useRef(null);
+    // Re-renders on every registration, so counts and lists follow the fields mounted now.
+    useSyncExternalStore(formComments?.subscribe ?? noopSubscribe, formComments?.version ?? noVersion, noVersion);
+    const onRemovedItems = useMemo(() => comments.filter((t) => t.type === 'field' && t.entryPath === entryPath && t.onRemovedItem && !t.resolved).length, [comments, entryPath]);
+    const counts = useMemo(() => {
+        const byPath = new Map();
+        for (const thread of comments) {
+            if (thread.type !== 'field' ||
+                thread.entryPath !== entryPath ||
+                !thread.canopyPath ||
+                thread.onRemovedItem) {
+                continue;
+            }
+            const count = byPath.get(thread.canopyPath) ?? { open: 0, total: 0 };
+            count.total += 1;
+            if (!thread.resolved)
+                count.open += 1;
+            byPath.set(thread.canopyPath, count);
+        }
+        return byPath;
+    }, [comments, entryPath]);
+    const onShortcut = (event) => {
+        const form = triggerRef.current?.closest('[data-form-renderer]');
+        if (!formComments || !form)
+            return;
+        const active = document.activeElement;
+        // An inert form is covered by the content panel's overlay.
+        if (inOtherOverlay(active, form) || form.closest('[inert]'))
+            return;
+        event.preventDefault();
+        const field = active && form.contains(active) ? active.closest(FIELD_SCOPE_SELECTOR) : null;
+        const path = field?.getAttribute('data-canopy-field');
+        const opener = path ? formComments.get(path) : undefined;
+        if (opener)
+            opener.open();
+        else {
+            triggerRef.current?.scrollIntoView?.({ block: 'nearest' });
+            setOpened(true);
+        }
+    };
+    useHotkeys([
+        [
+            'mod+alt+M',
+            (event) => {
+                // ⌥ turns M into another character on macOS, so there the key matches by position.
+                if (modKeyLabel() === '⌘' && event.metaKey)
+                    onShortcut(event);
+            },
+            { preventDefault: false, usePhysicalKeys: true },
+        ],
+        [
+            'mod+alt+M',
+            (event) => {
+                // Elsewhere by character: AltGr reads as Ctrl+Alt, and AltGr+M types a character
+                // on some layouts, which this leaves alone.
+                if (modKeyLabel() !== '⌘')
+                    onShortcut(event);
+            },
+            { preventDefault: false },
+        ],
+        [
+            'mod+alt+M',
+            (event) => {
+                // A layout whose letters aren't Latin, such as Cyrillic or Greek, matches by position.
+                if (modKeyLabel() !== '⌘' &&
+                    NON_LATIN_LETTER.test(event.key) &&
+                    !event.getModifierState?.('AltGraph'))
+                    onShortcut(event);
+            },
+            { preventDefault: false, usePhysicalKeys: true },
+        ],
+    ], 
+    // `[]` ignores no tags and `true` fires from contenteditable, so it works while typing.
+    [], true);
+    if (!formComments)
+        return null;
+    // Counts only fields mounted now, which the menu can open.
+    const openCount = [...counts].reduce((sum, [path, { open }]) => (formComments.get(path) ? sum + open : sum), 0);
+    // The menu item is gone once the popover opens, so its trigger stands in as the opener.
+    const openField = (opener) => opener.open(() => triggerRef.current);
+    return (_jsxs(Menu, { opened: opened, onChange: setOpened, position: "bottom-end", withinPortal: true, shadow: "sm", children: [_jsx(Tooltip, { label: `Field comments (${commentsShortcutLabel()})`, withinPortal: true, disabled: opened, children: _jsx(Menu.Target, { children: _jsx(Button, { ref: triggerRef, variant: "subtle", color: "gray", 
+                        // The theme's text colour, not a palette shade: a fixed shade is unreadable on one scheme.
+                        c: "var(--mantine-color-text)", size: "compact-sm", leftSection: _jsx(IconMessages, { size: 16, "aria-hidden": true }), rightSection: _jsxs(_Fragment, { children: [openCount > 0 && (_jsx(Badge, { size: "sm", variant: "light", color: "orange", c: "var(--mantine-color-text)", "aria-hidden": true, mr: 4, children: openCount })), _jsx(IconChevronDown, { size: 14, "aria-hidden": true })] }), "aria-label": openCount > 0 ? `Field comments (${openThreadsText(openCount)})` : 'Field comments', "aria-keyshortcuts": commentsAriaKeyShortcuts(), "data-testid": "form-comments-menu-button", children: "Field comments" }) }) }), _jsx(Menu.Dropdown, { "data-testid": "form-comments-menu", maw: 420, mah: "min(480px, 70vh)", style: { overflowY: 'auto' }, children: _jsx(MenuItems, { formComments: formComments, counts: counts, onRemovedItems: onRemovedItems, openField: openField }) })] }));
+};
+/** The menu's items, built only while its dropdown is mounted: every field, in form order. */
+const MenuItems = ({ formComments, counts, onRemovedItems, openField }) => {
+    const allFields = formComments.fields();
+    const withThreads = allFields.flatMap((field) => {
+        const count = counts.get(field.canopyPath);
+        return count ? [{ field, ...count }] : [];
+    });
+    const lastFocusedPath = formComments.lastFocused();
+    const lastFocused = lastFocusedPath ? formComments.get(lastFocusedPath) : undefined;
+    const otherFields = allFields.filter((field) => field.canopyPath !== lastFocusedPath);
+    return (_jsxs(_Fragment, { children: [_jsx(Menu.Label, { children: "Fields with comments" }), withThreads.length === 0 ? (_jsx(Text, { size: "xs", c: "dimmed", px: "sm", pb: "xs", children: onRemovedItems > 0
+                    ? `${onRemovedItems === 1 ? '1 comment thread is' : `${onRemovedItems} comment threads are`} on a removed item, under "Comment on this entry".`
+                    : 'No field has comments yet.' })) : (withThreads.map(({ field, open }) => (_jsxs(Menu.Item, { onClick: () => openField(field), "data-testid": `form-comments-field-${field.canopyPath}`, children: [_jsx(Text, { size: "sm", lineClamp: 2, children: field.subject }), _jsx(Text, { size: "xs", c: "dimmed", children: open > 0 ? openThreadsText(open) : 'Resolved' })] }, field.canopyPath)))), _jsx(Menu.Divider, {}), lastFocused && (_jsxs(Menu.Item, { onClick: () => openField(lastFocused), "data-testid": "form-comments-comment-on-focused", children: [_jsxs(Text, { size: "sm", lineClamp: 2, children: ["Comment on ", lastFocused.subject] }), _jsx(BlockedReason, { opener: lastFocused })] })), _jsx(Menu.Label, { children: lastFocused ? 'Comment on another field' : 'Comment on a field' }), otherFields.map((field) => (_jsxs(Menu.Item, { onClick: () => openField(field), "data-testid": `form-comments-any-field-${field.canopyPath}`, children: [_jsx(Text, { size: "sm", lineClamp: 2, children: field.subject }), _jsx(BlockedReason, { opener: field })] }, field.canopyPath)))] }));
+};
+/** A field's reason it can't take a new thread yet; its popover still opens, to draft one. */
+const BlockedReason = ({ opener }) => opener.blockedReason ? (_jsx(Text, { size: "xs", c: "dimmed", children: opener.blockedReason })) : null;
+const noopSubscribe = () => () => { };
+const noVersion = () => 0;

package/dist/editor/comments/item-anchor-copy.d.ts

@@ -0,0 +1,6 @@
+/** Refuses a new thread on a field inside an item the draft added, which has no saved place yet. */
+export declare const NEW_ITEM_COMMENT_MESSAGE = "Save the entry before commenting on this new item.";
+/** Refuses a new thread inside a list before the entry's saved value has loaded. */
+export declare const ENTRY_NOT_LOADED_COMMENT_MESSAGE = "This entry hasn't finished loading, so a comment here can't be placed yet. Reload it and try again.";
+/** Names a field thread whose list item or block was removed; the field's labels follow it. */
+export declare const ON_REMOVED_ITEM = "On a removed item";

package/dist/editor/comments/item-anchor-copy.js

@@ -0,0 +1,6 @@
+/** Refuses a new thread on a field inside an item the draft added, which has no saved place yet. */
+export const NEW_ITEM_COMMENT_MESSAGE = 'Save the entry before commenting on this new item.';
+/** Refuses a new thread inside a list before the entry's saved value has loaded. */
+export const ENTRY_NOT_LOADED_COMMENT_MESSAGE = "This entry hasn't finished loading, so a comment here can't be placed yet. Reload it and try again.";
+/** Names a field thread whose list item or block was removed; the field's labels follow it. */
+export const ON_REMOVED_ITEM = 'On a removed item';

package/dist/editor/comments/move-focus-if-unmoved.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Focuses `target` unless the user has moved focus since `origin` had it. Focus that stayed on
+ * `origin`, or fell to the body with an unmounted element, is the user's to get back; focus they
+ * put somewhere else while a write was in flight stays where they put it.
+ */
+export declare const moveFocusIfUnmoved: (origin: Element | null, target: HTMLElement | null | undefined) => void;

package/dist/editor/comments/move-focus-if-unmoved.js

@@ -0,0 +1,11 @@
+/**
+ * Focuses `target` unless the user has moved focus since `origin` had it. Focus that stayed on
+ * `origin`, or fell to the body with an unmounted element, is the user's to get back; focus they
+ * put somewhere else while a write was in flight stays where they put it.
+ */
+export const moveFocusIfUnmoved = (origin, target) => {
+    const active = document.activeElement;
+    if (!active || active === origin || active === document.body || !active.isConnected) {
+        target?.focus();
+    }
+};

package/dist/editor/comments/popover-placement.d.ts

@@ -0,0 +1,18 @@
+/** The two places a field's comment popover may open, neither over the field's input. */
+export interface FieldAnchors {
+    /** At the top of the field, above its label row. */
+    above: HTMLElement | null;
+    /** At the bottom of the field, below its input. */
+    below: HTMLElement | null;
+}
+export type PopoverSide = 'above' | 'below';
+/**
+ * Picks the side a field's popover opens on. A short field prefers below its input; a group or a
+ * field taller than 40% of its scroll area prefers above its label row, since below is far from
+ * the control. Either takes the other side when only that one has room. When neither does, or
+ * when `scroll` asks, the preferred side scrolls to the middle first. Room is measured in the
+ * field's scroll container.
+ */
+export declare const choosePopoverSide: ({ above, below }: FieldAnchors, { scroll }?: {
+    scroll?: boolean;
+}) => PopoverSide;

package/dist/editor/comments/popover-placement.js

@@ -0,0 +1,58 @@
+/** Room the popover needs on its side, for its heading and a composer. */
+const POPOVER_ROOM = 280;
+const scrollBounds = (el) => {
+    for (let p = el.parentElement; p; p = p.parentElement) {
+        const { overflowY } = getComputedStyle(p);
+        if ((overflowY === 'auto' || overflowY === 'scroll') && p.scrollHeight > p.clientHeight) {
+            const { top, bottom } = p.getBoundingClientRect();
+            return { top, bottom };
+        }
+    }
+    return { top: 0, bottom: window.innerHeight };
+};
+/**
+ * Picks the side a field's popover opens on. A short field prefers below its input; a group or a
+ * field taller than 40% of its scroll area prefers above its label row, since below is far from
+ * the control. Either takes the other side when only that one has room. When neither does, or
+ * when `scroll` asks, the preferred side scrolls to the middle first. Room is measured in the
+ * field's scroll container.
+ */
+export const choosePopoverSide = ({ above, below }, { scroll = false } = {}) => {
+    if (!above || !below)
+        return 'below';
+    const measure = () => {
+        const bounds = scrollBounds(above);
+        const top = above.getBoundingClientRect().top;
+        const bottom = below.getBoundingClientRect().bottom;
+        const topInView = top >= bounds.top && top < bounds.bottom;
+        return {
+            tall: bottom - top > (bounds.bottom - bounds.top) * 0.4,
+            above: topInView && top - bounds.top >= POPOVER_ROOM,
+            below: topInView && bottom <= bounds.bottom && bounds.bottom - bottom >= POPOVER_ROOM,
+            roomAbove: top - bounds.top,
+            roomBelow: bounds.bottom - bottom,
+        };
+    };
+    const group = below.parentElement?.querySelector('[data-field-comments]') != null;
+    let room = measure();
+    const preferred = group || room.tall ? 'above' : 'below';
+    const other = preferred === 'above' ? 'below' : 'above';
+    if (!scroll) {
+        if (room[preferred])
+            return preferred;
+        if (room[other])
+            return other;
+    }
+    // Instant, so the second measure reads the new geometry even under `scroll-behavior: smooth`.
+    ;
+    (preferred === 'above' ? above : below).scrollIntoView?.({
+        block: 'center',
+        behavior: 'instant',
+    });
+    room = measure();
+    if (room[preferred])
+        return preferred;
+    if (room[other])
+        return other;
+    return room.roomBelow >= room.roomAbove ? 'below' : 'above';
+};

package/dist/editor/comments/use-tracked-writes.d.ts

@@ -0,0 +1,16 @@
+/** Shown while a surface refuses to close because a comment write is still in flight. */
+export declare const CLOSE_WAITS_FOR_WRITE = "Still saving\u2026 You can close this once it finishes.";
+/**
+ * Wraps a surface's comment writes: `inFlight` counts the unsettled ones, and a write that fails
+ * after the surface unmounted (the Branches drawer closed under the branch discussion, another
+ * entry or branch opened) still reports, as a toast, since nothing is left on screen to show the
+ * error. A wrapped write still rejects for its caller. `holdOpen()` is true while a write is in
+ * flight, and then sets `closeRefused` until the writes settle, which the API client's request
+ * deadline bounds, so a surface that refuses to close can say why.
+ */
+export declare function useTrackedWrites(): {
+    inFlight: number;
+    track: <A extends unknown[]>(write: (...args: A) => Promise<void>) => (...args: A) => Promise<void>;
+    holdOpen: () => boolean;
+    closeRefused: boolean;
+};