Add comment mode for content elements

Let reviewers enter a mode where content elements become
selectable for commenting. Selecting an element exits the mode,
highlights the element with an accent border, opens the comment
popover, and hides other badges to reduce clutter. Clicking
outside or toggling the toolbar button dismisses the mode.

REDMINE-21261

Author: tf

entry_types/scrolled/bin/rspec-with-retry-on-timeout

@@ -1,12 +1,12 @@
 #!/bin/bash
 
 # See REDMINE-17430
-# Running only the js specs should not take more than 20 seconds.
+# Running only the js specs should not take more than 30 seconds.
 # If Chrome Driver hangs, the timeout command will exit with 137.
 # Retry or else exit with original exit status of rspec command.
 
 for i in {1..10}; do
-  timeout --signal=KILL 30 bin/rspec $@
+  timeout --signal=KILL 45 bin/rspec $@
   e=$?
   [[ $e -gt 100 ]] && echo Timeout || exit $e;
 done;

entry_types/scrolled/config/locales/de.yml

@@ -1912,7 +1912,9 @@ de:
       content_element_margin_bottom: Unterer Außenabstand
       expose_motif_area: Motiv freilegen
     review:
-      toolbar_label: Kommentare
+      add_comment: Kommentar hinzufügen
+      cancel_add_comment: Abbrechen
+      select_content_element: Zum Kommentieren auswählen
       new_topic: Neues Thema
       add_comment_placeholder: Kommentar hinzufügen...
       reply_placeholder: Antworten...

entry_types/scrolled/config/locales/en.yml

@@ -1741,7 +1741,9 @@ en:
       content_element_margin_bottom: Bottom margin
       expose_motif_area: Expose motif
     review:
-      toolbar_label: Comments
+      add_comment: Add comment
+      cancel_add_comment: Cancel
+      select_content_element: Select to comment
       new_topic: New topic
       add_comment_placeholder: Add a comment...
       reply_placeholder: Reply...

entry_types/scrolled/package/spec/frontend/features/addCommentMode-spec.js

@@ -0,0 +1,191 @@
+import React from 'react';
+import '@testing-library/jest-dom/extend-expect';
+import {act} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {useFakeTranslations} from 'pageflow/testHelpers';
+
+import {Entry} from 'frontend/Entry';
+import {usePageObjects} from 'support/pageObjects';
+import {renderInEntry} from 'support';
+import {clearExtensions} from 'frontend/extensions';
+import {loadCommentingComponents} from 'frontend/commenting';
+
+describe('add comment mode', () => {
+  usePageObjects();
+
+  useFakeTranslations({
+    'pageflow_scrolled.review.add_comment': 'Add comment',
+    'pageflow_scrolled.review.select_content_element': 'Select to comment',
+    'pageflow_scrolled.review.add_comment_placeholder': 'Add a comment...',
+    'pageflow_scrolled.review.new_topic': 'New topic',
+    'pageflow_scrolled.review.send': 'Send',
+    'pageflow_scrolled.review.cancel': 'Cancel',
+    'pageflow_scrolled.review.cancel_add_comment': 'Cancel add comment'
+  });
+
+  beforeEach(() => {
+    jest.spyOn(window, 'fetch').mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({currentUser: null, commentThreads: []})
+    });
+
+    loadCommentingComponents();
+  });
+
+  afterEach(() => {
+    act(() => clearExtensions());
+    window.fetch.mockRestore();
+  });
+
+  it('renders add comment button', () => {
+    const {getByRole} = renderInEntry(<Entry />, {
+      seed: {
+        contentElements: [{
+          typeName: 'withTestId',
+          configuration: {testId: 5}
+        }]
+      }
+    });
+
+    expect(getByRole('button', {name: 'Add comment'})).toBeInTheDocument();
+  });
+
+  it('shows highlight overlays on content elements when activated', async () => {
+    const user = userEvent.setup();
+    const {getByRole} = renderInEntry(<Entry />, {
+      seed: {
+        contentElements: [{
+          typeName: 'withTestId',
+          configuration: {testId: 5}
+        }]
+      }
+    });
+
+    await user.click(getByRole('button', {name: 'Add comment'}));
+
+    expect(getByRole('button', {name: 'Select to comment'})).toBeInTheDocument();
+  });
+
+  it('opens new thread form when selecting element', async () => {
+    const user = userEvent.setup();
+    const {getByRole, getByPlaceholderText} = renderInEntry(<Entry />, {
+      seed: {
+        contentElements: [{
+          typeName: 'withTestId',
+          configuration: {testId: 5}
+        }]
+      }
+    });
+
+    await user.click(getByRole('button', {name: 'Add comment'}));
+    await user.click(getByRole('button', {name: 'Select to comment'}));
+
+    expect(getByPlaceholderText('Add a comment...')).toBeInTheDocument();
+  });
+
+  it('auto expands new thread form when selecting element with existing threads', async () => {
+    window.fetch.mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        currentUser: null,
+        commentThreads: [{
+          id: 1,
+          subjectType: 'ContentElement',
+          subjectId: 10,
+          comments: [{id: 1, body: 'Existing comment', createdAt: '2026-01-01T00:00:00Z'}]
+        }]
+      })
+    });
+
+    const user = userEvent.setup();
+    const {getByRole, getByPlaceholderText} = renderInEntry(<Entry />, {
+      seed: {
+        contentElements: [{
+          typeName: 'withTestId',
+          permaId: 10,
+          configuration: {testId: 5}
+        }]
+      }
+    });
+
+    await user.click(getByRole('button', {name: 'Add comment'}));
+    await user.click(getByRole('button', {name: 'Select to comment'}));
+
+    expect(getByPlaceholderText('Add a comment...')).toBeInTheDocument();
+  });
+
+  it('closes popover when cancelling new thread form on element without threads', async () => {
+    const user = userEvent.setup();
+    const {getByRole, queryByRole} = renderInEntry(<Entry />, {
+      seed: {
+        contentElements: [{
+          typeName: 'withTestId',
+          configuration: {testId: 5}
+        }]
+      }
+    });
+
+    await user.click(getByRole('button', {name: 'Add comment'}));
+    await user.click(getByRole('button', {name: 'Select to comment'}));
+    await user.click(getByRole('button', {name: 'Cancel'}));
+
+    expect(queryByRole('status')).not.toBeInTheDocument();
+  });
+
+  it('exits add comment mode when overlay is clicked', async () => {
+    const user = userEvent.setup();
+    const {getByRole, queryByRole} = renderInEntry(<Entry />, {
+      seed: {
+        contentElements: [{
+          typeName: 'withTestId',
+          configuration: {testId: 5}
+        }]
+      }
+    });
+
+    await user.click(getByRole('button', {name: 'Add comment'}));
+    expect(getByRole('button', {name: 'Select to comment'})).toBeInTheDocument();
+
+    await user.click(getByRole('button', {name: 'Select to comment'}));
+
+    expect(queryByRole('button', {name: 'Select to comment'})).not.toBeInTheDocument();
+  });
+
+  it('deactivates when clicking toggle button again', async () => {
+    const user = userEvent.setup();
+    const {getByRole, queryByRole} = renderInEntry(<Entry />, {
+      seed: {
+        contentElements: [{
+          typeName: 'withTestId',
+          configuration: {testId: 5}
+        }]
+      }
+    });
+
+    await user.click(getByRole('button', {name: 'Add comment'}));
+    expect(getByRole('button', {name: 'Select to comment'})).toBeInTheDocument();
+
+    await user.click(getByRole('button', {name: 'Cancel add comment'}));
+
+    expect(queryByRole('button', {name: 'Select to comment'})).not.toBeInTheDocument();
+  });
+
+  it('exits add comment mode when clicking outside', async () => {
+    const user = userEvent.setup();
+    const {getByRole, queryByRole} = renderInEntry(<Entry />, {
+      seed: {
+        contentElements: [{
+          typeName: 'withTestId',
+          configuration: {testId: 5}
+        }]
+      }
+    });
+
+    await user.click(getByRole('button', {name: 'Add comment'}));
+    expect(getByRole('button', {name: 'Select to comment'})).toBeInTheDocument();
+
+    await user.click(document.body);
+
+    expect(queryByRole('button', {name: 'Select to comment'})).not.toBeInTheDocument();
+  });
+});

entry_types/scrolled/package/src/frontend/commenting/AddCommentModeProvider.js

@@ -0,0 +1,52 @@
+import React, {createContext, useCallback, useContext, useEffect, useMemo, useState} from 'react';
+
+const AddCommentModeContext = createContext({
+  active: false,
+  toggle: () => {},
+  deactivate: () => {}
+});
+
+export function AddCommentModeProvider({children}) {
+  const [active, setActive] = useState(false);
+
+  const toggle = useCallback(() => {
+    setActive(prev => !prev);
+  }, []);
+
+  const deactivate = useCallback(() => {
+    setActive(false);
+  }, []);
+
+  useEffect(() => {
+    if (!active) return;
+
+    function handlePointerDown(event) {
+      if (!event.target.closest('[data-add-comment-overlay]') &&
+          !event.target.closest('[data-add-comment-toggle]')) {
+        setActive(false);
+      }
+    }
+
+    document.addEventListener('pointerdown', handlePointerDown);
+
+    return () => {
+      document.removeEventListener('pointerdown', handlePointerDown);
+    };
+  }, [active]);
+
+  const value = useMemo(() => ({
+    active,
+    toggle,
+    deactivate
+  }), [active, toggle, deactivate]);
+
+  return (
+    <AddCommentModeContext.Provider value={value}>
+      {children}
+    </AddCommentModeContext.Provider>
+  );
+}
+
+export function useAddCommentMode() {
+  return useContext(AddCommentModeContext);
+}

entry_types/scrolled/package/src/frontend/commenting/AddCommentOverlay.js

@@ -0,0 +1,33 @@
+import React from 'react';
+
+import {useI18n} from '../i18n';
+import {useAddCommentMode} from './AddCommentModeProvider';
+import {useSelectedSubject} from './SelectedSubjectProvider';
+
+import AddCommentIcon from './images/addComment.svg';
+import styles from './AddCommentOverlay.module.css';
+
+export function AddCommentOverlay({permaId}) {
+  const {t} = useI18n({locale: 'ui'});
+  const {active, deactivate} = useAddCommentMode();
+  const {select} = useSelectedSubject('ContentElement', permaId);
+
+  if (!active) return null;
+
+  function handleClick() {
+    select({showNewForm: true});
+    deactivate();
+  }
+
+  return (
+    <button onClick={handleClick}
+            data-add-comment-overlay
+            className={styles.highlight}
+            aria-label={t('pageflow_scrolled.review.select_content_element')}
+            title={t('pageflow_scrolled.review.select_content_element')}>
+      <span className={styles.pill}>
+        <AddCommentIcon />
+      </span>
+    </button>
+  );
+}

entry_types/scrolled/package/src/frontend/commenting/AddCommentOverlay.module.css

@@ -0,0 +1,35 @@
+.highlight {
+  position: absolute;
+  inset: 0;
+  cursor: pointer;
+  background-color: var(--ui-selection-color-lightest);
+  border: none;
+  outline: none;
+  box-shadow: 0 0 0 2px var(--ui-selection-color),
+              0 0 0 calc(2px + space(1)) var(--ui-selection-color-light);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.pill {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: space(1);
+  width: space(9);
+  border-radius: rounded(full);
+  background: var(--ui-accent-color);
+  color: var(--ui-on-accent-color);
+  font-family: var(--ui-font-family);
+  font-size: space(3.5);
+  font-weight: 600;
+  padding: space(1.5) space(3);
+  box-shadow: 0 0 0 space(1) var(--ui-accent-color-glow);
+  opacity: 0.9;
+}
+
+.highlight:hover .pill,
+.highlight:focus .pill {
+  opacity: 1;
+}

entry_types/scrolled/package/src/frontend/commenting/ContentElementDecorator.js

@@ -1,14 +1,22 @@
 import React from 'react';
+import classNames from 'classnames';
 
+import {useAddCommentMode} from './AddCommentModeProvider';
+import {AddCommentOverlay} from './AddCommentOverlay';
 import {FloatingAnchor} from './FloatingAnchor';
 import {Popover} from './Popover';
+import {useSelectedSubject} from './SelectedSubjectProvider';
 
 import styles from './ContentElementDecorator.module.css';
 
 export function ContentElementDecorator({permaId, children}) {
+  const {active} = useAddCommentMode();
+  const {isSelected} = useSelectedSubject('ContentElement', permaId);
+
   return (
-    <div className={styles.wrapper}>
-      {children}
+    <div className={classNames(styles.wrapper, {[styles.selected]: isSelected})}>
+      <div inert={active ? '' : undefined}>{children}</div>
+      <AddCommentOverlay permaId={permaId} />
       <FloatingAnchor>
         {({placement}) => (
           <Popover subjectType="ContentElement"

entry_types/scrolled/package/src/frontend/commenting/ContentElementDecorator.module.css

@@ -1,3 +1,8 @@
 .wrapper {
   position: relative;
 }
+
+.selected {
+  box-shadow: 0 0 0 2px var(--ui-accent-color),
+              0 0 0 calc(2px + space(1)) var(--ui-accent-color-glow);
+}