canopycms 0.0.68-int.98 → 0.1.0

package/dist/editor/comments/CommentThreadsPopover.js

@@ -0,0 +1,274 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { Badge, Button, Group, Popover, ScrollArea, Stack, Text, Textarea, Tooltip, } from '@mantine/core';
+import { useClickOutside, useDidUpdate, useId, useIsomorphicEffect, useMediaQuery, useWindowEvent, } from '@mantine/hooks';
+import { IconMessage, IconMessagePlus, IconPlus } from '@tabler/icons-react';
+import { InlineCommentThread } from './InlineCommentThread.js';
+import { useTrackedWrites } from './use-tracked-writes.js';
+import { CloseRefusedNotice } from './CloseRefusedNotice.js';
+import { useRefocusAfterSubmit } from './ThreadReplyControls.js';
+import { commentsAriaKeyShortcuts, commentsShortcutLabel } from './form-comments.js';
+import { choosePopoverSide } from './popover-placement.js';
+import { CommentWriteAlert, toCommentWriteFailure, } from './CommentWriteAlert.js';
+const HIGHLIGHT_MS = 2000;
+const sortThreads = (threads) => [...threads].sort((a, b) => {
+    if (a.resolved !== b.resolved)
+        return a.resolved ? 1 : -1;
+    return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+});
+const openThreadsLabel = (count) => count === 1 ? '1 open thread' : `${count} open threads`;
+/**
+ * A field's or entry's comment control and the popover it opens: the threads (open first), each
+ * with reply and Resolve, and a box for a new thread. Comments stay open on a read-only form,
+ * since reviewers comment on submitted branches.
+ */
+export const CommentThreadsPopover = ({ threads, subject, variant, revealed = false, anchors, openRequest, currentUserId, canResolve, onAddComment, onResolveThread, onGetUserMetadata, highlightThreadId, threadFieldLabel, composeBlockedReason, testId, }) => {
+    const [opened, setOpened] = useState(false);
+    const [composing, setComposing] = useState(false);
+    // Drafts live here, not in the dropdown, which unmounts whenever the popover closes.
+    const [newThreadDraft, setNewThreadDraft] = useState('');
+    const [replyDrafts, setReplyDrafts] = useState({});
+    const headingRef = useRef(null);
+    const [flashThreadId, setFlashThreadId] = useState(undefined);
+    const threadRefs = useRef(new Map());
+    // Set by a post; the "New thread" button takes focus when it next mounts, as the composer goes.
+    const focusNewThreadRef = useRef(false);
+    // Touch screens have no hover, so the field icon stays visible there.
+    const noHover = useMediaQuery('(hover: none)');
+    const popoverId = useId();
+    const [controlNode, setControlNode] = useState(null);
+    // Read when focus returns: a popover that mounts open has no `controlNode` state as it opens.
+    const controlRef = useRef(null);
+    const setControl = useCallback((el) => {
+        controlRef.current = el;
+        setControlNode(el);
+    }, []);
+    const [dropdownNode, setDropdownNode] = useState(null);
+    // Set by a menu item's open, whose item is gone by close: its menu's trigger stands in.
+    const [returnFocusTo, setReturnFocusTo] = useState(undefined);
+    // Where focus returns on close, recorded as the popover opens, before its focus trap runs.
+    const openerRef = useRef(null);
+    const [side, setSide] = useState('below');
+    // A highlight's open always scrolls its field into place, even when it fits, and so overrides
+    // the smooth scroll `handleJumpToField` (`hooks/useCommentSystem.ts`) starts.
+    const [scrollOnOpen, setScrollOnOpen] = useState(false);
+    const placedRef = useRef(false);
+    // A click chose where focus goes, so a stand-in never takes it.
+    const pointerClosedRef = useRef(false);
+    const open = ({ scroll = false } = {}) => {
+        setReturnFocusTo(undefined);
+        setScrollOnOpen(scroll);
+        setOpened(true);
+    };
+    const sortedThreads = useMemo(() => sortThreads(threads), [threads]);
+    const openCount = useMemo(() => threads.filter((t) => !t.resolved).length, [threads]);
+    // A newly highlighted thread here opens the popover on it; adjusted during render, not in an
+    // effect, so the popover opens in the same commit.
+    const [seenHighlight, setSeenHighlight] = useState(undefined);
+    // It stays unseen until its thread arrives, so a thread list that catches up still opens it.
+    const highlightHere = !!highlightThreadId && threads.some((t) => t.id === highlightThreadId);
+    if (highlightThreadId !== seenHighlight && (!highlightThreadId || highlightHere)) {
+        setSeenHighlight(highlightThreadId);
+        if (highlightHere) {
+            open({ scroll: true });
+            setFlashThreadId(highlightThreadId);
+        }
+    }
+    const [seenOpenRequest, setSeenOpenRequest] = useState(openRequest);
+    if (openRequest !== seenOpenRequest) {
+        setSeenOpenRequest(openRequest);
+        if (openRequest) {
+            setOpened(true);
+            setScrollOnOpen(false);
+            setReturnFocusTo(() => openRequest.returnFocusTo);
+        }
+    }
+    // Once per open, before paint, as soon as both anchors exist: a field that mounts already
+    // highlighted gets them a commit after the popover opens.
+    useIsomorphicEffect(() => {
+        if (!opened) {
+            placedRef.current = false;
+            return;
+        }
+        if (placedRef.current || !anchors?.above || !anchors.below)
+            return;
+        placedRef.current = true;
+        setSide(choosePopoverSide(anchors, { scroll: scrollOnOpen }));
+    }, [opened, anchors]);
+    useIsomorphicEffect(() => {
+        if (!opened)
+            return;
+        pointerClosedRef.current = false;
+        const active = document.activeElement;
+        openerRef.current = returnFocusTo
+            ? { target: returnFocusTo, standIn: true }
+            : {
+                // A popover that opened with nothing focused, as on a highlight, returns to its control.
+                target: () => active instanceof HTMLElement && active !== document.body && active.isConnected
+                    ? active
+                    : controlRef.current,
+                standIn: false,
+            };
+    }, [opened]);
+    // Focus returns here rather than through Mantine, which refocuses the opener even after a click
+    // has put focus on another control.
+    useDidUpdate(() => {
+        const opener = openerRef.current;
+        if (opened || !opener)
+            return;
+        if (pointerClosedRef.current && opener.standIn)
+            return;
+        const closing = dropdownNode;
+        const timer = window.setTimeout(() => {
+            const active = document.activeElement;
+            // Focus left in the fading dropdown, on a detached or closing menu item, or nowhere, hasn't
+            // been moved on by the user.
+            const unmoved = !active ||
+                active === document.body ||
+                !active.isConnected ||
+                closing?.contains(active) ||
+                active.closest('[data-menu-dropdown]');
+            if (!unmoved)
+                return;
+            const target = opener.target();
+            target?.focus({ preventScroll: true });
+            if (opener.standIn)
+                target?.scrollIntoView?.({ block: 'nearest' });
+        }, 20);
+        return () => window.clearTimeout(timer);
+    }, [opened]);
+    useEffect(() => {
+        if (!flashThreadId)
+            return;
+        const frame = window.requestAnimationFrame(() => {
+            threadRefs.current.get(flashThreadId)?.scrollIntoView({ block: 'nearest' });
+        });
+        const timer = window.setTimeout(() => setFlashThreadId(undefined), HIGHLIGHT_MS);
+        return () => {
+            window.cancelAnimationFrame(frame);
+            window.clearTimeout(timer);
+        };
+    }, [flashThreadId]);
+    // While a post or Resolve is in flight the popover stays open, so its busy state and any error
+    // stay in view and a reopened composer can't send the same text twice.
+    const { inFlight, track, holdOpen, closeRefused } = useTrackedWrites();
+    const addComment = track(onAddComment);
+    const resolveThread = track(onResolveThread);
+    const close = () => {
+        if (holdOpen())
+            return;
+        setOpened(false);
+        setComposing(false);
+        focusNewThreadRef.current = false;
+    };
+    const controlLabel = openCount > 0
+        ? `Comment on ${subject} (${openThreadsLabel(openCount)})`
+        : `Comment on ${subject}`;
+    // Open threads keep the control in view as a count; resolved ones are listed by the form's
+    // "Field comments" menu.
+    const shown = revealed || opened || noHover || openCount > 0;
+    // Idle, the control leaves the tab order: the form's menu and shortcut reach comments instead.
+    const idle = !opened && openCount === 0;
+    const anchored = variant === 'field' && anchors !== undefined;
+    const controlTooltip = openCount > 0
+        ? `Comment on ${subject} (${openThreadsLabel(openCount)}, ${commentsShortcutLabel()})`
+        : `Comment on ${subject} (${commentsShortcutLabel()})`;
+    // Mantine's Escape is off in flight; on the window, as a disabled composer drops focus.
+    useWindowEvent('keydown', (event) => {
+        if (event.key === 'Escape' && opened)
+            holdOpen();
+    });
+    const closeByPointer = () => {
+        if (holdOpen())
+            return;
+        pointerClosedRef.current = true;
+        close();
+    };
+    // Anchored, the control is outside the popover's target, so clicks on it count as inside here.
+    useClickOutside(() => anchored && opened && closeByPointer(), null, [controlNode, dropdownNode]);
+    const target = variant === 'entry' ? (_jsx(Button, { variant: "subtle", color: "gray", c: "var(--mantine-color-text)", size: "compact-sm", leftSection: _jsx(IconMessage, { size: 16, "aria-hidden": true }), rightSection: openCount > 0 ? (_jsx(Badge, { size: "sm", variant: "light", color: "orange", c: "var(--mantine-color-text)", "aria-hidden": true, children: openCount })) : undefined, ref: setControl, "aria-label": controlLabel, "aria-expanded": opened, "aria-haspopup": "dialog", onClick: (event) => (!opened ? open() : event.detail > 0 ? closeByPointer() : close()), "data-testid": testId, children: "Comment on this entry" })) : (
+    // One element for every state, so a count change never remounts the control focus returns to.
+    _jsx(Button, { variant: openCount > 0 ? 'light' : 'subtle', color: openCount > 0 ? 'orange' : 'gray', c: openCount > 0 ? 'var(--mantine-color-text)' : undefined, size: "compact-xs", px: 4, ref: setControl, tabIndex: idle ? -1 : undefined, "aria-label": controlLabel, "aria-expanded": opened, "aria-haspopup": "dialog", "aria-controls": anchored && opened ? `${popoverId}-dropdown` : undefined, "aria-keyshortcuts": commentsAriaKeyShortcuts(), onClick: (event) => (!opened ? open() : event.detail > 0 ? closeByPointer() : close()), "data-testid": testId, "data-comment-control": true, "data-revealed": shown ? '' : undefined, style: {
+            // Hidden by opacity, not display, so a pointer or focus on the field shows it in place.
+            opacity: shown ? 1 : 0,
+            transition: 'opacity 120ms ease',
+        }, children: _jsxs(Group, { gap: 4, wrap: "nowrap", children: [threads.length === 0 ? (_jsx(IconMessagePlus, { size: 16, "aria-hidden": true })) : (_jsx(IconMessage, { size: 14, color: openCount > 0 ? 'var(--mantine-color-orange-text)' : undefined, "aria-hidden": true })), openCount > 0 && _jsx("span", { children: openCount })] }) }));
+    const tooltipTarget = variant === 'entry' ? (target) : (_jsx(Tooltip, { label: controlTooltip, withinPortal: true, disabled: opened, children: target }));
+    const popover = (_jsxs(Popover, { id: popoverId, opened: opened, onChange: (next) => (next ? open() : close()), onClose: close, 
+        // Never over the field's input; the entry's button sits above the form.
+        position: anchored && side === 'below' ? 'bottom-start' : 'top-start', 
+        // Clamped to the room on its side, scrolling inside, since it never flips over the input.
+        middlewares: anchored ? { flip: false, shift: true, size: { padding: 8 } } : undefined, width: 380, shadow: "md", withArrow: !anchored, trapFocus: true, returnFocus: false, 
+        // Off while a write is in flight, when `close` refuses anyway, so Mantine's Escape handler
+        // doesn't run its focus return on a popover that stays open.
+        closeOnEscape: inFlight === 0, closeOnClickOutside: !anchored, 
+        // Anchored, the target is an empty element, so the control and dropdown carry the roles.
+        withRoles: !anchored, children: [_jsx(Popover.Target, { children: anchored ? _jsx(AnchorTarget, { node: anchors?.[side] }) : tooltipTarget }), _jsx(Popover.Dropdown, { ref: setDropdownNode, "aria-label": `Comments on ${subject}`, ...(anchored ? { role: 'dialog', id: `${popoverId}-dropdown`, tabIndex: -1 } : {}), style: anchored ? { overflowY: 'auto' } : undefined, "data-testid": `${testId}-popover`, p: "sm", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Text, { ref: headingRef, size: "sm", fw: 600, tabIndex: -1, "data-autofocus": sortedThreads.length > 0 || undefined, children: ["Comments on ", subject] }), sortedThreads.length > 0 && (_jsx(ScrollArea.Autosize, { mah: 360, offsetScrollbars: true, type: "auto", children: _jsx(Stack, { gap: "sm", children: sortedThreads.map((thread) => (_jsx("div", { ref: (el) => {
+                                        if (el)
+                                            threadRefs.current.set(thread.id, el);
+                                        else
+                                            threadRefs.current.delete(thread.id);
+                                    }, "data-highlighted": flashThreadId === thread.id ? '' : undefined, style: {
+                                        borderRadius: 4,
+                                        outline: flashThreadId === thread.id
+                                            ? '2px solid var(--mantine-color-blue-5)'
+                                            : undefined,
+                                        outlineOffset: -2,
+                                    }, children: _jsx(InlineCommentThread, { thread: thread, onAddReply: (text) => addComment(text, thread.id), onResolve: () => resolveThread(thread.id), 
+                                        // Resolve and the reply box go with the open state, so focus stays inside.
+                                        focusAfterResolve: () => headingRef.current, replyText: replyDrafts[thread.id] ?? '', onReplyTextChange: (text) => setReplyDrafts((prev) => ({ ...prev, [thread.id]: text })), currentUserId: currentUserId, canResolve: canResolve, onGetUserMetadata: onGetUserMetadata, fieldLabel: threadFieldLabel?.(thread) }) }, thread.id))) }) })), sortedThreads.length === 0 || composing ? (_jsx(NewThreadComposer, { blockedReason: composeBlockedReason, text: newThreadDraft, onTextChange: setNewThreadDraft, onSubmit: async (text) => {
+                                // Set first: the first thread's arrival mounts the button before this resolves.
+                                focusNewThreadRef.current = true;
+                                try {
+                                    await addComment(text);
+                                }
+                                catch (err) {
+                                    focusNewThreadRef.current = false;
+                                    throw err;
+                                }
+                                setComposing(false);
+                            }, onCancel: sortedThreads.length > 0 ? () => setComposing(false) : close })) : (_jsx(Group, { children: _jsx(Button, { ref: (el) => {
+                                    if (el && focusNewThreadRef.current) {
+                                        focusNewThreadRef.current = false;
+                                        el.focus();
+                                    }
+                                }, variant: "subtle", size: "compact-sm", leftSection: _jsx(IconPlus, { size: 14, "aria-hidden": true }), onClick: () => setComposing(true), "data-testid": "new-thread-button", children: "New thread" }) })), _jsx(CloseRefusedNotice, { refused: closeRefused })] }) })] }));
+    return anchored ? (_jsxs(_Fragment, { children: [tooltipTarget, popover] })) : (popover);
+};
+/** An empty element placed in `node`, as the popover's position reference. */
+const AnchorTarget = React.forwardRef(function AnchorTarget({ node }, ref) {
+    return node ? createPortal(_jsx("div", { ref: ref, "aria-hidden": true }), node) : null;
+});
+const NewThreadComposer = ({ text, onTextChange: setText, onSubmit, onCancel, blockedReason }) => {
+    const [submitting, setSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const boxRef = useRef(null);
+    // Shown on request ("New thread"), so it takes focus.
+    useEffect(() => {
+        boxRef.current?.focus();
+    }, []);
+    useRefocusAfterSubmit(submitting, boxRef);
+    const submit = async () => {
+        if (!text.trim() || blockedReason)
+            return;
+        setSubmitting(true);
+        setError(null);
+        try {
+            await onSubmit(text);
+            setText('');
+        }
+        catch (err) {
+            setError(toCommentWriteFailure(err));
+        }
+        finally {
+            setSubmitting(false);
+        }
+    };
+    const button = (_jsx(Button, { size: "compact-sm", onClick: () => void submit(), loading: submitting, disabled: !text.trim(), "data-disabled": blockedReason ? true : undefined, "aria-disabled": blockedReason ? true : undefined, "data-testid": "create-thread-button", children: "Comment" }));
+    // `aria-disabled` keeps it focusable for its reason. Unblocked it isn't wrapped: around a focused
+    // button the Tooltip keeps Escape from the listener that refuses a close mid-post.
+    const commentButton = blockedReason ? (_jsx(Tooltip, { label: blockedReason, multiline: true, maw: 280, children: button })) : (button);
+    return (_jsxs(Stack, { gap: "xs", children: [_jsx(Textarea, { ref: boxRef, "aria-label": "New comment", placeholder: "Add a comment\u2026", value: text, onChange: (e) => setText(e.currentTarget.value), minRows: 2, autosize: true, disabled: submitting, description: blockedReason, error: error && !error.mayHaveLanded ? error.message : undefined, "data-autofocus": true, "data-testid": "new-thread-textarea" }), error?.mayHaveLanded && _jsx(CommentWriteAlert, { failure: error, onClose: () => setError(null) }), _jsxs(Group, { gap: "xs", children: [commentButton, _jsx(Button, { size: "compact-sm", variant: "subtle", color: "gray", onClick: onCancel, disabled: submitting, children: "Cancel" })] })] }));
+};

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

@@ -0,0 +1,11 @@
+/** A comment write's failure, and whether the write may have landed anyway. */
+export interface CommentWriteFailure {
+    message: string;
+    mayHaveLanded: boolean;
+}
+export declare const toCommentWriteFailure: (err: unknown) => CommentWriteFailure;
+/** A failed comment write: red, or yellow when it may have been posted. */
+export declare function CommentWriteAlert({ failure, onClose, }: {
+    failure: CommentWriteFailure;
+    onClose: () => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/editor/comments/CommentWriteAlert.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Alert } from '@mantine/core';
+import { IconAlertCircle, IconAlertTriangle } from '@tabler/icons-react';
+import { getErrorMessage } from '../../utils/error.js';
+import { MayHaveLandedError } from '../unanswered.js';
+export const toCommentWriteFailure = (err) => ({
+    message: getErrorMessage(err),
+    mayHaveLanded: err instanceof MayHaveLandedError,
+});
+/** A failed comment write: red, or yellow when it may have been posted. */
+export function CommentWriteAlert({ failure, onClose, }) {
+    return (_jsx(Alert, { icon: failure.mayHaveLanded ? _jsx(IconAlertTriangle, { size: 16 }) : _jsx(IconAlertCircle, { size: 16 }), color: failure.mayHaveLanded ? 'yellow' : 'red', variant: "light", onClose: onClose, withCloseButton: true, children: failure.message }));
+}

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

@@ -1,5 +1,6 @@
 import React from 'react';
 import type { CommentThread } from '../../comment-store.js';
+import type { UserSearchResult } from '../../auth/types.js';
 export interface EntryCommentsProps {
     /** All comments (will be filtered for entry-level) */
     comments: CommentThread[];
@@ -13,13 +14,18 @@ export interface EntryCommentsProps {
     onAddComment: (text: string, type: 'field' | 'entry' | 'branch', entryPath?: string, canopyPath?: string, threadId?: string) => Promise<void>;
     /** Handler to resolve a thread */
     onResolveThread: (threadId: string) => Promise<void>;
-    /** Auto-focus and expand */
-    autoFocus?: boolean;
     /** Thread ID to highlight and scroll to */
     highlightThreadId?: string;
+    /** Resolves author ids to names; without it authors show as ids. */
+    onGetUserMetadata?: (userId: string) => Promise<UserSearchResult | null>;
+    /** Changes with the entry or branch, which resets the popover, so a draft never posts elsewhere. */
+    resetKey: string;
+    /** Names the field of a thread on a removed item. */
+    removedItemFieldLabel?: (thread: CommentThread) => string;
 }
 /**
- * Entry-level comments section displayed at the top of the form.
- * Uses ThreadCarousel for navigation.
+ * The top of the form's comment actions: the "Field comments" menu, the keyboard route to
+ * field comments, and "Comment on this entry" with the entry's threads. Those include the field
+ * threads whose list item or block was removed, which stay on the entry, marked.
  */
 export declare const EntryComments: React.FC<EntryCommentsProps>;

package/dist/editor/comments/EntryComments.js

@@ -1,21 +1,18 @@
 'use client';
-import { jsx as _jsx } from "react/jsx-runtime";
-import { useMemo, useState } from 'react';
-import { Box, Button } from '@mantine/core';
-import { ThreadCarousel } from './ThreadCarousel.js';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { Group } from '@mantine/core';
+import { CommentThreadsPopover } from './CommentThreadsPopover.js';
+import { FormCommentsMenu } from './form-comments.js';
 /**
- * Entry-level comments section displayed at the top of the form.
- * Uses ThreadCarousel for navigation.
+ * The top of the form's comment actions: the "Field comments" menu, the keyboard route to
+ * field comments, and "Comment on this entry" with the entry's threads. Those include the field
+ * threads whose list item or block was removed, which stay on the entry, marked.
  */
-export const EntryComments = ({ comments, entryPath, currentUserId, canResolve, onAddComment, onResolveThread, autoFocus, highlightThreadId, }) => {
-    const [showCarousel, setShowCarousel] = useState(false);
-    const entryThreads = useMemo(() => comments.filter((t) => t.type === 'entry' && t.entryPath === entryPath), [comments, entryPath]);
-    const shouldShowCarousel = entryThreads.length > 0 || showCarousel || autoFocus;
-    const handleAddComment = async (text, threadId) => {
-        await onAddComment(text, 'entry', entryPath, undefined, threadId);
-    };
-    if (!shouldShowCarousel) {
-        return (_jsx(Box, { children: _jsx(Button, { size: "xs", variant: "subtle", color: "gray", onClick: () => setShowCarousel(true), style: { fontSize: '0.75rem', height: '1.5rem' }, children: "New file comment" }) }));
-    }
-    return (_jsx(ThreadCarousel, { threads: entryThreads, label: "Entry Comments", contextType: "entry", currentUserId: currentUserId, canResolve: canResolve, onAddComment: handleAddComment, onResolveThread: onResolveThread, autoFocus: autoFocus, autoOpenNewThread: showCarousel && entryThreads.length === 0, highlightThreadId: highlightThreadId }));
+export const EntryComments = ({ comments, entryPath, currentUserId, canResolve, onAddComment, onResolveThread, highlightThreadId, onGetUserMetadata, resetKey, removedItemFieldLabel, }) => {
+    const entryThreads = useMemo(() => comments.filter((t) => t.entryPath === entryPath &&
+        (t.type === 'entry' || (t.type === 'field' && t.onRemovedItem))), [comments, entryPath]);
+    return (_jsxs(Group, { justify: "flex-end", gap: "xs", children: [_jsx(FormCommentsMenu, { comments: comments, entryPath: entryPath }), _jsx(CommentThreadsPopover, { threads: entryThreads, subject: "this entry", variant: "entry", currentUserId: currentUserId, canResolve: canResolve, onAddComment: (text, threadId) => onAddComment(text, 'entry', entryPath, undefined, threadId), onResolveThread: onResolveThread, onGetUserMetadata: onGetUserMetadata, highlightThreadId: highlightThreadId, threadFieldLabel: (thread) => thread.onRemovedItem && thread.canopyPath
+                    ? (removedItemFieldLabel?.(thread) ?? thread.canopyPath)
+                    : undefined, testId: "entry-comment-button" }, resetKey)] }));
 };

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

@@ -1,5 +1,6 @@
 import React from 'react';
 import type { CommentThread } from '../../comment-store.js';
+import type { UserSearchResult } from '../../auth/types.js';
 export interface FieldWrapperProps {
     /** Child form field element */
     children: React.ReactNode;
@@ -19,13 +20,26 @@ export interface FieldWrapperProps {
     onAddComment: (text: string, type: 'field' | 'entry' | 'branch', entryPath?: string, canopyPath?: string, threadId?: string) => Promise<void>;
     /** Handler to resolve a thread */
     onResolveThread: (threadId: string) => Promise<void>;
-    /** Field label for positioning the new comment button */
-    fieldLabel?: string;
+    /** The field's breadcrumb ("Links › /a › Href"), which names the control: "Comment on <breadcrumb>". */
+    fieldLabel: string;
     /** Thread ID to highlight and scroll to */
     highlightThreadId?: string;
+    /** Resolves author ids to names; without it authors show as ids. */
+    onGetUserMetadata?: (userId: string) => Promise<UserSearchResult | null>;
+    /**
+     * `label`: the field puts the control in its `FieldLabel` via `useFieldCommentControl`.
+     * `corner`: the wrapper places it at the top right, for custom renderers, whose labels are
+     * their own.
+     */
+    controlPlacement?: 'label' | 'corner';
+    /** Changes with the entry or branch, which resets the popover, so a draft never posts elsewhere. */
+    resetKey: string;
+    /** Why a new thread can't be posted on this field yet (`CommentThreadsPopover`). */
+    commentBlockedReason?: string;
 }
 /**
- * Wraps a form field with inline comment functionality.
- * Shows ThreadCarousel when comments exist or when user clicks "New comment".
+ * Gives a form field its comment control. The control shows while the pointer or focus is on
+ * this field and not on a field nested inside it, so a group never shows a second icon for its
+ * children; a field with open threads always shows it.
  */
 export declare const FieldWrapper: React.FC<FieldWrapperProps>;

package/dist/editor/comments/FieldWrapper.js

@@ -1,36 +1,70 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
-import { Box, Button } from '@mantine/core';
-import { ThreadCarousel } from './ThreadCarousel.js';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Box } from '@mantine/core';
+import { CommentThreadsPopover } from './CommentThreadsPopover.js';
+import { FieldCommentContext } from './field-comment-context.js';
+import { useFormComments } from './form-comments.js';
+import { whenRevealed } from '../field-target.js';
+const FIELD_SCOPE_ATTR = 'data-field-comments';
 /**
- * Wraps a form field with inline comment functionality.
- * Shows ThreadCarousel when comments exist or when user clicks "New comment".
+ * Gives a form field its comment control. The control shows while the pointer or focus is on
+ * this field and not on a field nested inside it, so a group never shows a second icon for its
+ * children; a field with open threads always shows it.
  */
-export const FieldWrapper = ({ children, canopyPath, entryPath, threads, autoFocus, currentUserId, canResolve, onAddComment, onResolveThread, highlightThreadId, }) => {
+export const FieldWrapper = ({ children, canopyPath, entryPath, threads, autoFocus, currentUserId, canResolve, onAddComment, onResolveThread, fieldLabel, highlightThreadId, onGetUserMetadata, controlPlacement = 'label', resetKey, commentBlockedReason, }) => {
     const wrapperRef = useRef(null);
-    const [showCarousel, setShowCarousel] = useState(false);
-    const shouldShowCarousel = threads.length > 0 || showCarousel;
+    const [pointerOn, setPointerOn] = useState(false);
+    const [focusOn, setFocusOn] = useState(false);
+    const [above, setAbove] = useState(null);
+    const [below, setBelow] = useState(null);
+    const anchors = useMemo(() => ({ above, below }), [above, below]);
+    // A highlighted thread here opens the popover, which scrolls the field itself.
+    const highlightHere = !!highlightThreadId && threads.some((t) => t.id === highlightThreadId);
+    const [openRequest, setOpenRequest] = useState(undefined);
+    const formComments = useFormComments();
+    useEffect(() => formComments?.register(canopyPath, {
+        subject: fieldLabel,
+        blockedReason: commentBlockedReason,
+        // A new object per request, so asking again while it is open still counts.
+        open: (returnFocusTo) => {
+            const field = wrapperRef.current;
+            if (field)
+                whenRevealed(field, () => setOpenRequest({ returnFocusTo }));
+            else
+                setOpenRequest({ returnFocusTo });
+        },
+        element: () => wrapperRef.current,
+    }), [formComments, canopyPath, fieldLabel, commentBlockedReason]);
     useEffect(() => {
-        if (autoFocus) {
-            wrapperRef.current?.scrollIntoView({
-                behavior: 'smooth',
-                block: 'center',
-            });
+        const field = wrapperRef.current;
+        if (!field)
+            return;
+        if (highlightHere)
+            whenRevealed(field, () => { });
+        else if (autoFocus) {
+            whenRevealed(field, () => field.scrollIntoView({ behavior: 'smooth', block: 'center' }));
         }
-    }, [autoFocus]);
-    const handleAddComment = async (text, threadId) => {
-        await onAddComment(text, 'field', entryPath, canopyPath, threadId);
-    };
-    return (_jsxs(Box, { ref: wrapperRef, "data-canopy-field": canopyPath, pos: "relative", style: { width: '100%' }, children: [_jsx(Box, { style: {
-                    outline: autoFocus ? '2px solid var(--mantine-color-blue-5)' : undefined,
-                    outlineOffset: autoFocus ? 2 : undefined,
-                    borderRadius: 4,
-                    transition: 'outline 0.2s ease',
-                }, children: children }), !shouldShowCarousel && (_jsx(Box, { style: {
-                    position: 'absolute',
-                    top: 4,
-                    right: 8,
-                    zIndex: 1,
-                }, children: _jsx(Button, { size: "xs", variant: "subtle", color: "gray", onClick: () => setShowCarousel(true), style: { fontSize: '0.75rem', height: '1.5rem' }, "data-testid": `field-new-comment-${canopyPath}`, children: "New comment" }) })), shouldShowCarousel && (_jsx(ThreadCarousel, { threads: threads, contextType: "field", currentUserId: currentUserId, canResolve: canResolve, onAddComment: handleAddComment, onResolveThread: onResolveThread, autoFocus: autoFocus, autoOpenNewThread: showCarousel && threads.length === 0, highlightThreadId: highlightThreadId, onCancelNewThread: () => setShowCarousel(false) }))] }));
+    }, [autoFocus, highlightHere]);
+    // Events from a nested field, or from a popover portalled out of the DOM, have another
+    // closest scope (or none), so they leave this field's icon hidden.
+    const ownsTarget = (target) => target instanceof Element &&
+        wrapperRef.current !== null &&
+        target.closest(`[${FIELD_SCOPE_ATTR}]`) === wrapperRef.current;
+    const control = (_jsx(CommentThreadsPopover, { threads: threads, subject: fieldLabel, variant: "field", revealed: pointerOn || focusOn, anchors: anchors, openRequest: openRequest, currentUserId: currentUserId, canResolve: canResolve, onAddComment: (text, threadId) => onAddComment(text, 'field', entryPath, canopyPath, threadId), onResolveThread: onResolveThread, onGetUserMetadata: onGetUserMetadata, highlightThreadId: highlightThreadId, composeBlockedReason: commentBlockedReason, testId: `field-comment-${canopyPath}` }, resetKey));
+    return (_jsxs(Box, { ref: wrapperRef, "data-canopy-field": canopyPath, [FIELD_SCOPE_ATTR]: '', pos: "relative", style: { width: '100%' }, onMouseOver: (event) => setPointerOn(ownsTarget(event.target)), onMouseLeave: () => setPointerOn(false), onFocus: (event) => {
+            const owned = ownsTarget(event.target);
+            setFocusOn(owned);
+            if (owned)
+                formComments?.noteFocus(canopyPath);
+        }, onBlur: (event) => {
+            const next = event.relatedTarget;
+            if (!(next instanceof Node && event.currentTarget.contains(next)))
+                setFocusOn(false);
+        }, children: [_jsx("div", { ref: setAbove, "data-comment-anchor": "above" }), _jsx(FieldCommentContext.Provider, { value: { canopyPath, control }, children: _jsx(Box, { style: {
+                        outline: autoFocus ? '2px solid var(--mantine-color-blue-5)' : undefined,
+                        outlineOffset: autoFocus ? 2 : undefined,
+                        borderRadius: 4,
+                        transition: 'outline 0.2s ease',
+                    }, children: children }) }), _jsx("div", { ref: setBelow, "data-comment-anchor": "below" }), controlPlacement === 'corner' && (_jsx(Box, { pos: "absolute", top: 4, right: 4, style: { zIndex: 1 }, children: control }))] }));
 };

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

@@ -8,15 +8,22 @@ export interface InlineCommentThreadProps {
     onAddReply: (text: string) => Promise<void>;
     /** Handler to resolve this thread */
     onResolve: () => Promise<void>;
+    /** Where focus goes after a resolve; see `ThreadReplyControls`. */
+    focusAfterResolve?: () => HTMLElement | null | undefined;
     /** Current user ID for permission checking */
     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;
     /** Optional function to fetch user metadata for displaying user badges */
     onGetUserMetadata?: (userId: string) => Promise<UserSearchResult | null>;
+    /** The reply draft, when the caller keeps it, so it outlives this component; with `onReplyTextChange`. */
+    replyText?: string;
+    onReplyTextChange?: (text: string) => void;
+    /** The field a thread shown away from it is on, such as one on a removed item. */
+    fieldLabel?: string;
 }
 /**
- * Individual comment thread display within the carousel.
+ * One comment thread, as the comment popover and ThreadCarousel list them.
  * Always shows full thread view with per-thread scrolling.
  */
 export declare const InlineCommentThread: React.FC<InlineCommentThreadProps>;

package/dist/editor/comments/InlineCommentThread.js

@@ -1,60 +1,24 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
-import { Alert, Badge, Button, Group, Paper, Stack, Text, Textarea } from '@mantine/core';
-import { IconAlertCircle } from '@tabler/icons-react';
+import { Badge, Group, Paper, Stack, Text } from '@mantine/core';
 import { UserBadge } from '../components/UserBadge.js';
-import { formatRelativeTime } from '../relative-time.js';
+import { userIdLabel } from '../user-display.js';
+import { RelativeTime } from '../components/RelativeTime.js';
+import { ThreadReplyControls } from './ThreadReplyControls.js';
+import { ON_REMOVED_ITEM } from './item-anchor-copy.js';
 /**
- * Individual comment thread display within the carousel.
+ * One comment thread, as the comment popover and ThreadCarousel list them.
  * Always shows full thread view with per-thread scrolling.
  */
-export const InlineCommentThread = ({ thread, onAddReply, onResolve, currentUserId, canResolve, onGetUserMetadata, }) => {
-    const [replyText, setReplyText] = useState('');
-    const [isSubmitting, setIsSubmitting] = useState(false);
-    const [error, setError] = useState(null);
-    const handleReply = async () => {
-        if (!replyText.trim())
-            return;
-        setIsSubmitting(true);
-        setError(null);
-        try {
-            await onAddReply(replyText);
-            setReplyText('');
-        }
-        catch (err) {
-            setError(err instanceof Error ? err.message : 'Failed to add reply');
-        }
-        finally {
-            setIsSubmitting(false);
-        }
-    };
-    const handleResolve = async () => {
-        setIsSubmitting(true);
-        setError(null);
-        try {
-            await onResolve();
-        }
-        catch (err) {
-            setError(err instanceof Error ? err.message : 'Failed to resolve thread');
-        }
-        finally {
-            setIsSubmitting(false);
-        }
-    };
-    const canUserResolve = () => {
-        if (!canResolve)
-            return false;
-        return thread.authorId === currentUserId || canResolve;
-    };
-    return (_jsx(Paper, { withBorder: true, p: "md", bg: "white", "data-testid": "inline-comment-thread", style: {
+export const InlineCommentThread = ({ thread, onAddReply, onResolve, focusAfterResolve, currentUserId, canResolve, onGetUserMetadata, replyText, onReplyTextChange, fieldLabel, }) => {
+    return (_jsx(Paper, { withBorder: true, p: "md", bg: "var(--mantine-color-body)", "data-testid": "inline-comment-thread", style: {
             width: '100%',
             overflowY: 'auto',
             display: 'flex',
             flexDirection: 'column',
-        }, children: _jsxs(Stack, { gap: "md", children: [_jsxs(Group, { gap: "xs", children: [!thread.resolved && (_jsx(Badge, { size: "xs", color: "orange", variant: "light", children: "Unresolved" })), thread.resolved && (_jsx(Badge, { size: "xs", color: "green", variant: "light", children: "Resolved" }))] }), _jsx(Stack, { gap: "md", children: thread.comments.map((comment, idx) => (_jsxs("div", { children: [idx > 0 && (_jsx("div", { style: {
-                                    borderTop: '1px solid var(--mantine-color-gray-3)',
+        }, children: _jsxs(Stack, { gap: "md", children: [_jsxs(Group, { gap: "xs", children: [!thread.resolved && (_jsx(Badge, { size: "xs", color: "orange", variant: "light", children: "Unresolved" })), thread.resolved && (_jsx(Badge, { size: "xs", color: "green", variant: "light", children: "Resolved" })), thread.onRemovedItem && (_jsx(Badge, { size: "xs", color: "gray", variant: "light", c: "var(--mantine-color-text)", children: ON_REMOVED_ITEM }))] }), fieldLabel && (_jsx(Text, { size: "xs", c: "dimmed", "data-testid": "inline-comment-thread-field", children: fieldLabel })), _jsx(Stack, { gap: "md", children: thread.comments.map((comment, idx) => (_jsxs("div", { children: [idx > 0 && (_jsx("div", { style: {
+                                    borderTop: '1px solid var(--mantine-color-default-border)',
                                     marginTop: 8,
                                     marginBottom: 8,
-                                } })), _jsxs(Stack, { gap: 4, children: [_jsxs(Group, { gap: "xs", justify: "space-between", children: [onGetUserMetadata ? (_jsx(UserBadge, { userId: comment.userId, getUserMetadata: onGetUserMetadata, variant: "avatar-name", size: "xs", showEmailTooltip: true, showBadge: true, badgeVariant: "light", color: "gray" })) : (_jsx(Text, { size: "xs", fw: 600, children: comment.userId })), _jsx(Text, { size: "xs", c: "dimmed", children: formatRelativeTime(comment.timestamp) })] }), _jsx(Text, { size: "sm", style: { whiteSpace: 'pre-wrap' }, children: comment.text })] })] }, comment.id))) }), error && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", variant: "light", onClose: () => setError(null), withCloseButton: true, children: error })), !thread.resolved && (_jsxs(Stack, { gap: "xs", children: [_jsx(Textarea, { placeholder: "Write a reply...", value: replyText, onChange: (e) => setReplyText(e.target.value), minRows: 2, disabled: isSubmitting }), _jsxs(Group, { gap: "xs", children: [_jsx(Button, { size: "xs", onClick: handleReply, loading: isSubmitting, disabled: !replyText.trim(), children: "Reply" }), canUserResolve() && (_jsx(Button, { size: "xs", variant: "light", color: "green", onClick: handleResolve, loading: isSubmitting, "data-testid": "resolve-thread-button", children: "Resolve" }))] })] })), thread.resolved && thread.resolvedBy && (_jsxs(Group, { gap: 4, children: [_jsx(Text, { size: "xs", c: "dimmed", fs: "italic", children: "Resolved by" }), onGetUserMetadata ? (_jsx(UserBadge, { userId: thread.resolvedBy, getUserMetadata: onGetUserMetadata, variant: "avatar-name", size: "xs", showEmailTooltip: true, showBadge: true, badgeVariant: "light", color: "gray" })) : (_jsx(Text, { size: "xs", c: "dimmed", fs: "italic", children: thread.resolvedBy })), thread.resolvedAt && (_jsx(Text, { size: "xs", c: "dimmed", fs: "italic", children: formatRelativeTime(thread.resolvedAt) }))] }))] }) }));
+                                } })), _jsxs(Stack, { gap: 4, children: [_jsxs(Group, { gap: "xs", justify: "space-between", children: [onGetUserMetadata ? (_jsx(UserBadge, { userId: comment.userId, getUserMetadata: onGetUserMetadata, variant: "avatar-name", size: "xs", showEmailTooltip: true, showBadge: true, badgeVariant: "light", color: "gray" })) : (_jsx(Text, { size: "xs", fw: 600, children: userIdLabel(comment.userId) })), _jsx(RelativeTime, { iso: comment.timestamp, size: "xs", c: "dimmed" })] }), _jsx(Text, { size: "sm", style: { whiteSpace: 'pre-wrap' }, children: comment.text })] })] }, comment.id))) }), !thread.resolved && (_jsx(ThreadReplyControls, { thread: thread, onAddReply: onAddReply, onResolve: onResolve, focusAfterResolve: focusAfterResolve, currentUserId: currentUserId, canResolve: canResolve, replyText: replyText, onReplyTextChange: onReplyTextChange })), thread.resolved && thread.resolvedBy && (_jsxs(Group, { gap: 4, children: [_jsx(Text, { size: "xs", c: "dimmed", fs: "italic", children: "Resolved by" }), onGetUserMetadata ? (_jsx(UserBadge, { userId: thread.resolvedBy, getUserMetadata: onGetUserMetadata, variant: "avatar-name", size: "xs", showEmailTooltip: true, showBadge: true, badgeVariant: "light", color: "gray" })) : (_jsx(Text, { size: "xs", c: "dimmed", fs: "italic", children: userIdLabel(thread.resolvedBy) })), thread.resolvedAt && (_jsx(RelativeTime, { iso: thread.resolvedAt, size: "xs", c: "dimmed", fs: "italic" }))] }))] }) }));
 };