@eeacms/volto-cca-policy 0.3.126 → 0.3.127

package/CHANGELOG.md

@@ -4,19 +4,23 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-### [0.3.126](https://github.com/eea/volto-cca-policy/compare/1.0.0-alpha.3...0.3.126) - 26 May 2026
+### [0.3.127](https://github.com/eea/volto-cca-policy/compare/1.0.0-alpha.3...0.3.127) - 27 May 2026
 
 #### :bug: Bug Fixes
 
+- fix: resolve remaining lint warnings in WorkflowLinkIntegrityModal [Tiberiu Ichim - [`f1add88`](https://github.com/eea/volto-cca-policy/commit/f1add881c7240ba12dd223bfccb0c4ac86f83056)]
+- fix: resolve lint warnings and a11y errors in WorkflowLinkIntegrityModal [Tiberiu Ichim - [`bc60ca6`](https://github.com/eea/volto-cca-policy/commit/bc60ca604f30f62d6fb225bb319f76bab700ff04)]
 - fix: update warning message in link integrity workflow state change modal [Tiberiu Ichim - [`1244b2e`](https://github.com/eea/volto-cca-policy/commit/1244b2e826590050c6b10506651482cd615b8c92)]
 - fix: resolve workflow state transition failure when confirming via link integrity warning modal [Tiberiu Ichim - [`2fd0d89`](https://github.com/eea/volto-cca-policy/commit/2fd0d899fc421b4944de5488902f4bc35f5102d9)]
 
 #### :house: Internal changes
 
+- style: Automated code fix [eea-jenkins - [`8ca0234`](https://github.com/eea/volto-cca-policy/commit/8ca0234d1d429ed5964061989dad13cd6b44b027)]
 - style: Automated code fix [eea-jenkins - [`1e4caaf`](https://github.com/eea/volto-cca-policy/commit/1e4caafffd7b026c565887d6ace3c7ec87866bfe)]
 
 #### :house: Documentation changes
 
+- docs: update link-integrity artifact spec to reflect Portal-based modal [Tiberiu Ichim - [`f697e7e`](https://github.com/eea/volto-cca-policy/commit/f697e7e5b453a31032feeb862526d97a1c995483)]
 - docs: convert index.md absolute links to clean relative links [Tiberiu Ichim - [`bfb2d6a`](https://github.com/eea/volto-cca-policy/commit/bfb2d6a6c592991c4f65875c8db5f9b55205bf4d)]
 - docs: reorganize link integrity workflow artifacts, adding README specification and index overview [Tiberiu Ichim - [`1208c96`](https://github.com/eea/volto-cca-policy/commit/1208c9619ff4097a4d954e355895382978b326dc)]
 - docs: add specification for link integrity check during workflow transitions [Tiberiu Ichim - [`842da3d`](https://github.com/eea/volto-cca-policy/commit/842da3d371f0c5c38a538e3d519bc5eb79705e34)]
@@ -69,7 +73,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - Refs #296263 - styles and messages [iugin - [`359f2fc`](https://github.com/eea/volto-cca-policy/commit/359f2fcd207a6e58bc9e32d514ca23183ea6ca8e)]
 - Refs #296263 - jenkins update [iugin - [`b424df5`](https://github.com/eea/volto-cca-policy/commit/b424df51271e975a9721e4c0712c3009b68e53fa)]
 - Refs #296263 - init [iugin - [`01bff47`](https://github.com/eea/volto-cca-policy/commit/01bff4757de9d2b01b9476f19b61715a7983999b)]
-### [1.0.0-alpha.1](https://github.com/eea/volto-cca-policy/compare/0.3.125...1.0.0-alpha.1) - 20 May 2026
+### [1.0.0-alpha.1](https://github.com/eea/volto-cca-policy/compare/0.3.126...1.0.0-alpha.1) - 20 May 2026
 
 #### :rocket: New Features
 
@@ -116,6 +120,23 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - test: update snapshots [kreafox - [`420d51d`](https://github.com/eea/volto-cca-policy/commit/420d51d1e88323db7295752dc1a184888d3d504e)]
 - test: mock withScrollToTarget in Spotlight.test.jsx [kreafox - [`5fe54fb`](https://github.com/eea/volto-cca-policy/commit/5fe54fb44960bacc9ff0fe1d91bbbeec2bc58e83)]
 - update language import path [iugin - [`1217dcc`](https://github.com/eea/volto-cca-policy/commit/1217dcc9e6aa3971bf30c07bb93203cb73949c23)]
+### [0.3.126](https://github.com/eea/volto-cca-policy/compare/0.3.125...0.3.126) - 26 May 2026
+
+#### :bug: Bug Fixes
+
+- fix: update warning message in link integrity workflow state change modal [Tiberiu Ichim - [`1244b2e`](https://github.com/eea/volto-cca-policy/commit/1244b2e826590050c6b10506651482cd615b8c92)]
+- fix: resolve workflow state transition failure when confirming via link integrity warning modal [Tiberiu Ichim - [`2fd0d89`](https://github.com/eea/volto-cca-policy/commit/2fd0d899fc421b4944de5488902f4bc35f5102d9)]
+
+#### :house: Internal changes
+
+- style: Automated code fix [eea-jenkins - [`1e4caaf`](https://github.com/eea/volto-cca-policy/commit/1e4caafffd7b026c565887d6ace3c7ec87866bfe)]
+
+#### :house: Documentation changes
+
+- docs: convert index.md absolute links to clean relative links [Tiberiu Ichim - [`bfb2d6a`](https://github.com/eea/volto-cca-policy/commit/bfb2d6a6c592991c4f65875c8db5f9b55205bf4d)]
+- docs: reorganize link integrity workflow artifacts, adding README specification and index overview [Tiberiu Ichim - [`1208c96`](https://github.com/eea/volto-cca-policy/commit/1208c9619ff4097a4d954e355895382978b326dc)]
+- docs: add specification for link integrity check during workflow transitions [Tiberiu Ichim - [`842da3d`](https://github.com/eea/volto-cca-policy/commit/842da3d371f0c5c38a538e3d519bc5eb79705e34)]
+
 ### [0.3.125](https://github.com/eea/volto-cca-policy/compare/0.3.124...0.3.125) - 18 May 2026
 
 #### :rocket: New Features

package/artifacts/link-integrity-workflow/README.md

@@ -56,13 +56,20 @@ sequenceDiagram
 
 ### 2. Warning Modal Component
 *   **Path**: [WorkflowLinkIntegrityModal.jsx](file:///home/tibi/work/eea.docker.plone-climateadapt/cca/frontend/src/addons/volto-cca-policy/src/components/manage/Workflow/WorkflowLinkIntegrityModal.jsx)
-*   **Role**: A custom `semantic-ui-react` `Confirm` component wrapper. Utilizes a unified and stable component template to ensure reliable event loop listener binding.
+*   **Role**: A plain HTML overlay dialog rendered via `ReactDOM.createPortal` into a `<div>` appended to `document.body`. Zero `semantic-ui-react` dependencies — no `Confirm`, `Modal`, or `Portal`.
+*   **Why not `semantic-ui-react`?** The `Confirm` and `Modal` components use internal Portals, auto-controlled state, and shorthand factory systems that made click handlers unreliable in the toolbar dropdown context. The Toolbar's global `document mousedown` handler (`handleClickOutside`) would intercept clicks, close the menu, and unmount the modal before `onConfirm` could fire.
+*   **Key implementation details**:
+    *   **Portal rendering** — renders at `document.body` level with `z-index: 10000`, placing it outside the toolbar dropdown's DOM subtree and CSS stacking context so it appears as a proper full-page overlay.
+    *   **Capture-phase `mousedown` guard** — a `capture=true` listener on the portal root calls `e.stopPropagation()`, preventing the Toolbar's `handleClickOutside` from firing while the modal is open.
+    *   **Synchronous breach derivation** — `computeBreaches()` computes `brokenReferences` and `breaches` during render (no `useEffect` + `useState`), so the data is always in sync with `loading` in the same render cycle. This prevents a race condition where `loading` becomes `false` but `brokenReferences` is still `0`, causing premature modal closure.
+    *   **Inline styles** — all CSS is embedded via a `<style>` tag, no external stylesheet dependency.
 *   **Key UX Features**:
     *   Maintains button state `disabled: loading` during ongoing checks to prevent premature actions.
-    *   Renders an active `Loader` and `Dimmer` during loading.
+    *   Renders a CSS spinner and loading text during the check.
     *   Displays the exact list of referencing (source) items and target sub-items.
-    *   Displays the warning copy: 
+    *   Displays the warning copy:
         > *"By changing the state, we're not breaking references, but may break user experience for final Anonymous users. There are {brokenReferences} {variation} to this item:"*
+    *   Closes on backdrop click, button click, or `Escape` key.
 
 ### 3. Unit Verification Suite
 *   **Path**: [WorkflowLinkIntegrityModal.test.jsx](file:///home/tibi/work/eea.docker.plone-climateadapt/cca/frontend/src/addons/volto-cca-policy/src/components/manage/Workflow/WorkflowLinkIntegrityModal.test.jsx)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eeacms/volto-cca-policy",
-  "version": "0.3.126",
+  "version": "0.3.127",
   "description": "@eeacms/volto-cca-policy: Volto add-on",
   "main": "src/index.js",
   "author": "European Environment Agency: IDM2 A-Team",

package/src/components/manage/Workflow/WorkflowLinkIntegrityModal.jsx

@@ -1,10 +1,10 @@
-import React, { useState, useEffect } from 'react';
+import React, { useEffect, useCallback, useRef } from 'react';
+import { createPortal } from 'react-dom';
 import PropTypes from 'prop-types';
 import { useSelector } from 'react-redux';
 import { Link } from 'react-router-dom';
 import { defineMessages, useIntl, FormattedMessage } from 'react-intl';
 import { flattenToAppURL } from '@plone/volto/helpers';
-import { Confirm, Dimmer, Loader, Table } from 'semantic-ui-react';
 
 const messages = defineMessages({
   confirmHeader: {
@@ -29,80 +29,166 @@ const messages = defineMessages({
   },
 });
 
+/**
+ * Derive breach data synchronously from linkintegrityInfo.
+ * No useEffect + useState — computed during render so it is always
+ * in sync with the loading flag in the same render cycle.
+ */
+function computeBreaches(linkintegrityInfo) {
+  if (!linkintegrityInfo) {
+    return { brokenReferences: 0, breaches: [] };
+  }
+
+  const all = linkintegrityInfo.flatMap((result) =>
+    result.breaches.map((source) => ({ source, target: result })),
+  );
+
+  const sourceByUid = new Map();
+  const bySource = new Map();
+
+  for (const entry of all) {
+    sourceByUid.set(entry.source.uid, entry.source);
+    if (!bySource.has(entry.source.uid)) {
+      bySource.set(entry.source.uid, new Set());
+    }
+    bySource.get(entry.source.uid).add(entry.target);
+  }
+
+  return {
+    brokenReferences: bySource.size,
+    breaches: Array.from(bySource, ([uid, targets]) => ({
+      source: sourceByUid.get(uid),
+      targets: Array.from(targets),
+    })),
+  };
+}
+
+/**
+ * Plain HTML overlay dialog — no semantic-ui-react, no Portal,
+ * no Confirm, no Modal.  Just a fixed-position div with inline styles.
+ */
 const WorkflowLinkIntegrityModal = (props) => {
   const { open, onCancel, onOk } = props;
   const intl = useIntl();
   const linkintegrityInfo = useSelector((state) => state.linkIntegrity?.result);
   const loading = useSelector((state) => state.linkIntegrity?.loading);
 
-  const [brokenReferences, setBrokenReferences] = useState(0);
-  const [breaches, setBreaches] = useState([]);
+  const { brokenReferences, breaches } = computeBreaches(linkintegrityInfo);
+
+  // Keep visible while loading OR while breaches exist.
+  // Because brokenReferences is derived synchronously, it is always
+  // consistent with `loading` in the same render.
+  const show = open && (loading || brokenReferences > 0);
+
+  // Create a dedicated mount container attached to document.body so the
+  // modal renders outside the toolbar dropdown's stacking context.
+  // Initialized synchronously (not in useEffect) so it is available on
+  // the first render — important for tests and to avoid a flicker.
+  const containerRef = useRef(
+    (() => {
+      const el = document.createElement('div');
+      document.body.appendChild(el);
+      return el;
+    })(),
+  );
+
+  useEffect(() => {
+    const container = containerRef.current;
+    return () => {
+      if (container && container.parentNode) {
+        container.parentNode.removeChild(container);
+      }
+    };
+  }, []);
+
+  // Close on Escape key
+  const handleKeyDown = useCallback(
+    (e) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        e.stopPropagation();
+        onCancel();
+      }
+    },
+    [onCancel],
+  );
+
+  // Prevent the Toolbar's global `document mousedown` handler from closing
+  // the toolbar menu while our modal is open. The Toolbar listens on
+  // `document` for `mousedown` and calls `closeMenu()` if the click is
+  // outside the toolbar pusher. By adding a capture-phase listener on our
+  // portal root, we intercept the event before it bubbles to `document`.
+  const handleMousedown = useCallback((e) => {
+    e.stopPropagation();
+  }, []);
 
   useEffect(() => {
-    if (linkintegrityInfo) {
-      const breaches = linkintegrityInfo.flatMap((result) =>
-        result.breaches.map((source) => ({
-          source: source,
-          target: result,
-        })),
-      );
-      const source_by_uid = breaches.reduce(
-        (acc, value) => acc.set(value.source.uid, value.source),
-        new Map(),
-      );
-      const by_source = breaches.reduce((acc, value) => {
-        if (acc.get(value.source.uid) === undefined) {
-          acc.set(value.source.uid, new Set());
-        }
-        acc.get(value.source.uid).add(value.target);
-        return acc;
-      }, new Map());
-
-      setBrokenReferences(by_source.size);
-      setBreaches(
-        Array.from(by_source, (entry) => ({
-          source: source_by_uid.get(entry[0]),
-          targets: Array.from(entry[1]),
-        })),
-      );
-    } else {
-      setBrokenReferences(0);
-      setBreaches([]);
+    if (show) {
+      const container = containerRef.current;
+      document.addEventListener('keydown', handleKeyDown);
+      // capture=true: fires before any bubbling listeners on ancestors
+      container.addEventListener('mousedown', handleMousedown, true);
+      return () => {
+        document.removeEventListener('keydown', handleKeyDown);
+        container.removeEventListener('mousedown', handleMousedown, true);
+      };
     }
-  }, [linkintegrityInfo]);
+  }, [show, handleKeyDown, handleMousedown]);
 
-  const showModal = open && (loading || brokenReferences > 0);
+  if (!show) return null;
 
-  return (
-    showModal && (
-      <Confirm
-        open={showModal}
-        confirmButton={{
-          content: intl.formatMessage(messages.confirmAction),
-          disabled: loading,
+  return createPortal(
+    <>
+      <div
+        className="li-modal-backdrop"
+        role="presentation"
+        tabIndex={-1}
+        onClick={(e) => {
+          // Only cancel when clicking the backdrop itself, not children
+          if (e.target === e.currentTarget) {
+            onCancel();
+          }
+        }}
+        onKeyDown={(e) => {
+          if (e.key === 'Escape') {
+            e.preventDefault();
+            e.stopPropagation();
+            onCancel();
+          }
         }}
-        cancelButton={intl.formatMessage(messages.cancel)}
-        header={intl.formatMessage(messages.confirmHeader)}
-        content={
-          <div
-            className="content"
-            style={{ minHeight: loading ? '100px' : 'auto' }}
-          >
-            <Dimmer active={loading} inverted>
-              <Loader indeterminate size="massive">
-                {intl.formatMessage(messages.loading)}
-              </Loader>
-            </Dimmer>
+        data-testid="li-modal-backdrop"
+      >
+        <div
+          className="li-modal-dialog"
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby="li-modal-title"
+          data-testid="li-modal-dialog"
+        >
+          <div className="li-modal-header">
+            <span className="li-modal-title" id="li-modal-title">
+              {intl.formatMessage(messages.confirmHeader)}
+            </span>
+          </div>
+
+          <div className="li-modal-content">
+            {loading && (
+              <div className="li-modal-loading">
+                <div className="li-spinner" />
+                <span>{intl.formatMessage(messages.loading)}</span>
+              </div>
+            )}
+
             {!loading && brokenReferences > 0 && (
               <>
-                <FormattedMessage
-                  id="By changing the state, we're not breaking references, but may break user experience for final Anonymous users. There are {brokenReferences} {variation} to this item:"
-                  defaultMessage="By changing the state, we're not breaking references, but may break user experience for final Anonymous users. There are {brokenReferences} {variation} to this item:"
-                  values={{
-                    brokenReferences: <span>{brokenReferences}</span>,
-                    variation: (
-                      <span>
-                        {brokenReferences === 1 ? (
+                <p>
+                  <FormattedMessage
+                    id="By changing the state, we're not breaking references, but may break user experience for final Anonymous users. There are {brokenReferences} {variation} to this item:"
+                    defaultMessage="By changing the state, we're not breaking references, but may break user experience for final Anonymous users. There are {brokenReferences} {variation} to this item:"
+                    values={{
+                      brokenReferences: <strong>{brokenReferences}</strong>,
+                      variation:
+                        brokenReferences === 1 ? (
                           <FormattedMessage
                             id="reference"
                             defaultMessage="reference"
@@ -112,49 +198,68 @@ const WorkflowLinkIntegrityModal = (props) => {
                             id="references"
                             defaultMessage="references"
                           />
-                        )}
-                      </span>
-                    ),
-                  }}
-                />
+                        ),
+                    }}
+                  />
+                </p>
                 <BrokenLinksList intl={intl} breaches={breaches} />
               </>
             )}
           </div>
-        }
-        onCancel={onCancel}
-        onConfirm={onOk}
-        size="small"
-      />
-    )
+
+          <div className="li-modal-actions">
+            <button
+              className="li-btn li-btn-secondary"
+              onClick={onCancel}
+              disabled={loading}
+              data-testid="li-btn-cancel"
+            >
+              {intl.formatMessage(messages.cancel)}
+            </button>
+            <button
+              className="li-btn li-btn-primary"
+              onClick={onOk}
+              disabled={loading}
+              data-testid="li-btn-confirm"
+            >
+              {intl.formatMessage(messages.confirmAction)}
+            </button>
+          </div>
+        </div>
+      </div>
+      <style>{modalStyles}</style>
+    </>,
+    containerRef.current,
   );
 };
 
 const BrokenLinksList = ({ intl, breaches }) => {
   return (
-    <div className="broken-links-list" style={{ marginTop: '20px' }}>
-      <FormattedMessage
-        id="These items will have broken links"
-        defaultMessage="These items will have broken links"
-      />
-      :
-      <Table compact>
-        <Table.Body>
+    <div className="li-broken-links-list">
+      <p>
+        <FormattedMessage
+          id="These items will have broken links"
+          defaultMessage="These items will have broken links"
+        />
+        :
+      </p>
+      <table className="li-breach-table">
+        <tbody>
           {breaches.map((breach) => (
-            <Table.Row key={breach.source['@id']} verticalAlign="top">
-              <Table.Cell>
+            <tr key={breach.source['@id']}>
+              <td className="li-breach-source">
                 <Link
                   to={flattenToAppURL(breach.source['@id'])}
                   title={intl.formatMessage(messages.navigate_to_this_item)}
                 >
                   {breach.source.title}
                 </Link>
-              </Table.Cell>
-              <Table.Cell style={{ minWidth: '140px' }}>
+              </td>
+              <td className="li-breach-label">
                 <FormattedMessage id="refers to" defaultMessage="refers to" />:
-              </Table.Cell>
-              <Table.Cell>
-                <ul style={{ margin: 0 }}>
+              </td>
+              <td className="li-breach-targets">
+                <ul>
                   {breach.targets.map((target) => (
                     <li key={target['@id']}>
                       <Link
@@ -168,11 +273,11 @@ const BrokenLinksList = ({ intl, breaches }) => {
                     </li>
                   ))}
                 </ul>
-              </Table.Cell>
-            </Table.Row>
+              </td>
+            </tr>
           ))}
-        </Table.Body>
-      </Table>
+        </tbody>
+      </table>
     </div>
   );
 };
@@ -184,3 +289,155 @@ WorkflowLinkIntegrityModal.propTypes = {
 };
 
 export default WorkflowLinkIntegrityModal;
+
+/**
+ * Minimal inline styles — no external CSS dependency.
+ * Matches Volto's general look (white dialog, centred, dark backdrop).
+ */
+const modalStyles = `
+  .li-modal-backdrop {
+    position: fixed;
+    inset: 0;
+    z-index: 10000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: rgba(0, 0, 0, 0.6);
+  }
+
+  .li-modal-dialog {
+    background: #fff;
+    border-radius: 8px;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+    max-width: 600px;
+    width: 90%;
+    max-height: 80vh;
+    overflow-y: auto;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .li-modal-header {
+    padding: 16px 20px;
+    border-bottom: 1px solid #e0e0e0;
+  }
+
+  .li-modal-title {
+    font-size: 18px;
+    font-weight: 600;
+    color: #333;
+  }
+
+  .li-modal-content {
+    padding: 20px;
+    min-height: 80px;
+    color: #4a4a4a;
+    font-size: 14px;
+    line-height: 1.5;
+  }
+
+  .li-modal-loading {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    justify-content: center;
+    padding: 20px 0;
+  }
+
+  .li-spinner {
+    width: 24px;
+    height: 24px;
+    border: 3px solid #e0e0e0;
+    border-top-color: #007bc1;
+    border-radius: 50%;
+    animation: li-spin 0.7s linear infinite;
+  }
+
+  @keyframes li-spin {
+    to { transform: rotate(360deg); }
+  }
+
+  .li-modal-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 10px;
+    padding: 16px 20px;
+    border-top: 1px solid #e0e0e0;
+  }
+
+  .li-btn {
+    padding: 8px 18px;
+    border-radius: 4px;
+    font-size: 14px;
+    cursor: pointer;
+    border: 1px solid transparent;
+    transition: background 0.15s, border-color 0.15s;
+  }
+
+  .li-btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .li-btn-secondary {
+    background: #f5f5f5;
+    border-color: #d0d0d0;
+    color: #333;
+  }
+
+  .li-btn-secondary:hover:not(:disabled) {
+    background: #ebebeb;
+  }
+
+  .li-btn-primary {
+    background: #007bc1;
+    color: #fff;
+  }
+
+  .li-btn-primary:hover:not(:disabled) {
+    background: #005a89;
+  }
+
+  .li-broken-links-list {
+    margin-top: 16px;
+  }
+
+  .li-breach-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 13px;
+  }
+
+  .li-breach-table td {
+    padding: 6px 8px;
+    vertical-align: top;
+    border-bottom: 1px solid #eee;
+  }
+
+  .li-breach-label {
+    white-space: nowrap;
+    padding-left: 12px;
+    color: #888;
+    width: 1px;
+  }
+
+  .li-breach-targets ul {
+    margin: 0;
+    padding-left: 18px;
+  }
+
+  .li-breach-targets li {
+    margin-bottom: 2px;
+  }
+
+  .li-breach-source a,
+  .li-breach-targets a {
+    color: #007bc1;
+    text-decoration: none;
+  }
+
+  .li-breach-source a:hover,
+  .li-breach-targets a:hover {
+    text-decoration: underline;
+  }
+`;

package/src/components/manage/Workflow/WorkflowLinkIntegrityModal.test.jsx

@@ -55,7 +55,7 @@ describe('WorkflowLinkIntegrityModal', () => {
     expect(screen.getByText('Checking references...')).toBeInTheDocument();
   });
 
-  it('auto-proceeds when no breaches are found', () => {
+  it('renders nothing when no breaches are found (auto-proceed handled by parent)', () => {
     const store = makeStore({
       result: [{ breaches: [], '@id': 'http://localhost:8080/Plone/target' }],
       loaded: true,
@@ -68,11 +68,10 @@ describe('WorkflowLinkIntegrityModal', () => {
       />,
       store,
     );
-    // brokenReferences === 0 so the Confirm dialog is not rendered
     expect(container.innerHTML).toBe('');
   });
 
-  it('shows warning modal with breach list when breaches are found', () => {
+  it('shows warning dialog with breach list when breaches are found', () => {
     const store = makeStore({
       result: [
         {
@@ -141,7 +140,6 @@ describe('WorkflowLinkIntegrityModal', () => {
       />,
       store,
     );
-    // Both breaches come from the same source, so brokenReferences === 1
     expect(screen.getByText('Source Page')).toBeInTheDocument();
     expect(screen.getByText('Target 1')).toBeInTheDocument();
     expect(screen.getByText('Target 2')).toBeInTheDocument();

package/src/customizations/volto/components/manage/Workflow/README.md

@@ -12,11 +12,33 @@ By shadowing this component, we can intercept transitions that might hide conten
 
 1.  **Interception Logic**: The `transition` function was modified to check for "private-like" transitions (`private`, `reject`, `retract`).
 2.  **Link Integrity Check**: When a sensitive transition is selected, the `linkIntegrityCheck` action is dispatched to the backend.
-3.  **State Management**: Added local state (`showWarningModal`, `pendingOption`) to handle the asynchronous check and the confirmation flow.
+3.  **State Management**: Added local state (`showWarningModal`, `pendingOption`, `transitionTriggered`) to handle the asynchronous check and the confirmation flow.
 4.  **Confirmation Modal**: Integrated `WorkflowLinkIntegrityModal` which displays the list of pages that would have broken links.
-5.  **Auto-proceed**: Added an `useEffect` that automatically executes the transition if the link integrity check returns zero breaches.
+5.  **Auto-proceed**: Added an `useEffect` that automatically executes the transition if the link integrity check returns zero breaches. It is guarded by `transitionTriggered` to prevent double-execution if the user clicks "Change state anyway" at the same time.
 6.  **Activity Indicators**: Added `Dimmer` and `Loader` components from `semantic-ui-react` to provide visual feedback while the link integrity check is loading and during the workflow transition execution.
 
+## Design Decisions
+
+### Plain HTML dialog via React Portal — no semantic-ui-react
+
+The `WorkflowLinkIntegrityModal` renders via `ReactDOM.createPortal` into a `<div>` appended to `document.body`. This places it outside the toolbar dropdown's DOM subtree and CSS stacking context, so it appears as a proper full-page overlay at `z-index: 10000`.
+
+No `semantic-ui-react` `Confirm`, `Modal`, or `Portal` is used. Those components rely on Portals, auto-controlled state, and shorthand factory systems that make click handlers unreliable in our use case. The plain HTML approach gives us full, predictable control: `onClick` on a `<button>` always fires.
+
+### Toolbar `handleClickOutside` interference
+
+Volto's `Toolbar` component registers a global `document.addEventListener('mousedown', ...)` handler that closes the toolbar menu when clicking outside it. Since our modal renders on top of the toolbar menu, any `mousedown` would bubble up to `document` and trigger the menu close — which unmounts the `Workflow` component and our modal before the button `onClick` can fire.
+
+The fix: a **capture-phase** `mousedown` listener on the portal root calls `e.stopPropagation()`, preventing the event from ever reaching `document`. This keeps the toolbar menu open while our modal is visible, without interfering with normal `click` event handling on the buttons.
+
+### Synchronous breach derivation (no useEffect + local state)
+
+The breach data (`brokenReferences`, `breaches`) is computed synchronously inside a `computeBreaches()` helper function rather than via `useEffect` + `useState`. This is critical: the `linkIntegrity` reducer sets `loading: false` and `result: data` in the same action (`_SUCCESS`). If breach data were derived via `useEffect` + local state, there would be a render cycle where `loading` is already `false` but `brokenReferences` is still `0` (stale local state), causing the modal to close prematurely before the breach data is processed.
+
+### `transitionTriggered` guard
+
+A `transitionTriggered` state flag prevents the auto-proceed `useEffect` from firing after the user has already clicked "Change state anyway", avoiding duplicate workflow transition API calls.
+
 ## Reference
 
 See implementation details in:

package/src/customizations/volto/components/manage/Workflow/Workflow.jsx

@@ -220,6 +220,7 @@ const Workflow = (props) => {
 
   const [showWarningModal, setShowWarningModal] = useState(false);
   const [pendingOption, setPendingOption] = useState(null);
+  const [transitionTriggered, setTransitionTriggered] = useState(false);
 
   useEffect(() => {
     dispatch(getWorkflow(pathname));
@@ -229,6 +230,7 @@ const Workflow = (props) => {
   const executeTransition = useCallback(
     (selectedOption) => {
       if (selectedOption?.url) {
+        setTransitionTriggered(true);
         dispatch(transitionWorkflow(flattenToAppURL(selectedOption.url)));
         toast.success(
           <Toast
@@ -243,7 +245,7 @@ const Workflow = (props) => {
   );
 
   useEffect(() => {
-    if (showWarningModal) {
+    if (showWarningModal && !transitionTriggered) {
       if (linkintegrityError) {
         // If the check fails, we shouldn't block the user forever. Proceed with transition.
         executeTransition(pendingOption);
@@ -269,6 +271,7 @@ const Workflow = (props) => {
     linkintegrityError,
     showWarningModal,
     pendingOption,
+    transitionTriggered,
     content,
     executeTransition,
   ]);
@@ -281,6 +284,7 @@ const Workflow = (props) => {
 
     if (isPrivateTransition) {
       setPendingOption(selectedOption);
+      setTransitionTriggered(false);
       dispatch(linkIntegrityCheck([content.UID]));
       setShowWarningModal(true);
     } else {
@@ -341,6 +345,7 @@ const Workflow = (props) => {
         onCancel={() => {
           setShowWarningModal(false);
           setPendingOption(null);
+          setTransitionTriggered(false);
         }}
         onOk={() => {
           executeTransition(pendingOption);