@eeacms/volto-cca-policy 0.3.124 → 0.3.125

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.125](https://github.com/eea/volto-cca-policy/compare/0.3.124...0.3.125) - 18 May 2026
+
+#### :rocket: New Features
+
+- feat: add activity indicator during workflow transition [Tiberiu Ichim - [`869cf77`](https://github.com/eea/volto-cca-policy/commit/869cf7733968fc55739f0ad4e94b2d5ffb9a7bbc)]
+
+#### :bug: Bug Fixes
+
+- fix(eslint): silence no-console warning in ReadMoreView test [Tiberiu Ichim - [`751dfdb`](https://github.com/eea/volto-cca-policy/commit/751dfdb089bc3ebe8099c990147848338d2146e6)]
+- fix(tests): fix 3 failing test suites [Tiberiu Ichim - [`9956429`](https://github.com/eea/volto-cca-policy/commit/995642903bca5750bed270671881a9172476d242)]
+- fix: make workflow link integrity check robust to API errors and URL variations [Tiberiu Ichim - [`07260f2`](https://github.com/eea/volto-cca-policy/commit/07260f2ae89786ba49736d53b1650d4e6332eafb)]
+- fix: stale link integrity data and transition execution robustness [Tiberiu Ichim - [`704faf8`](https://github.com/eea/volto-cca-policy/commit/704faf8bf7aeb6ad4614715c3c95b5599ce13a57)]
+- fix: race condition in link integrity check during workflow transition [Tiberiu Ichim - [`a2f3deb`](https://github.com/eea/volto-cca-policy/commit/a2f3deb4e1b83c094138f46ec8da1573c7939694)]
+
+#### :house: Internal changes
+
+- style: Automated code fix [eea-jenkins - [`a7207bf`](https://github.com/eea/volto-cca-policy/commit/a7207bf7b41da19a845af247c5628aa00a870099)]
+- style: Automated code fix [eea-jenkins - [`eff3551`](https://github.com/eea/volto-cca-policy/commit/eff35514016705cc6103945beb298f9b0c0a4903)]
+
+#### :house: Documentation changes
+
+- docs: add test fixes specification for 4 failing test suites [Tiberiu Ichim - [`c00a536`](https://github.com/eea/volto-cca-policy/commit/c00a5368f06a5d28d8d455cf75b3b8cabb947155)]
+- docs: finalize detailed guide on block discovery and link extraction [Tiberiu Ichim - [`253d576`](https://github.com/eea/volto-cca-policy/commit/253d576176e6a76f860a8371a598d82a49323404)]
+- docs: finalize technical details on block nesting and link extraction [Tiberiu Ichim - [`78dcd18`](https://github.com/eea/volto-cca-policy/commit/78dcd18435eb192a0c380c11fe70d83d44b35545)]
+- docs: add technical documentation on how Volto discovers links in blocks [Tiberiu Ichim - [`89fff64`](https://github.com/eea/volto-cca-policy/commit/89fff648e9dda10a6b6145ac13fff7b14c2c330e)]
+- docs: document activity indicators and UX improvements [Tiberiu Ichim - [`e7bdb88`](https://github.com/eea/volto-cca-policy/commit/e7bdb888237eb8a3181b11520e1002c60a310aa5)]
+- docs: document race condition prevention logic [Tiberiu Ichim - [`5ce00b2`](https://github.com/eea/volto-cca-policy/commit/5ce00b255c6835132c50d74ce08af9a6ddb53262)]
+- docs: add user story for testing link integrity warning [Tiberiu Ichim - [`5026dcb`](https://github.com/eea/volto-cca-policy/commit/5026dcb039a5d2b603b51da33e999ba416e9e26e)]
+
+#### :hammer_and_wrench: Others
+
+- Add artifacts [Tiberiu Ichim - [`37cccf1`](https://github.com/eea/volto-cca-policy/commit/37cccf1d3f1d926c64c7d192b071c7cd0061cb0a)]
+- Add blocks overview [Tiberiu Ichim - [`1aa6e8b`](https://github.com/eea/volto-cca-policy/commit/1aa6e8b780f4f7a00641872ef7a99e2223cd1feb)]
+- test: add tests for WorkflowLinkIntegrityModal [Tiberiu Ichim - [`53e1dd1`](https://github.com/eea/volto-cca-policy/commit/53e1dd1ef924352f1b8328819cd727633b47658b)]
+- test: fix console warnings in test suite [Tiberiu Ichim - [`a3d49b4`](https://github.com/eea/volto-cca-policy/commit/a3d49b40d63a452546322b9f0e170a965f2dc3fc)]
+- Add spec [Tiberiu Ichim - [`2034b80`](https://github.com/eea/volto-cca-policy/commit/2034b80f470344a6c20524b04364f1ae9f770a6d)]
+- Add README for shadowed Workflow component [Tiberiu Ichim - [`5dac2e7`](https://github.com/eea/volto-cca-policy/commit/5dac2e7a7941c4e47afa229fb65c4b08db8606b8)]
+- Add implementation artifacts for link integrity warning [Tiberiu Ichim - [`84e2aa4`](https://github.com/eea/volto-cca-policy/commit/84e2aa4529dbd02a05bc148a9900f7cc4a25c54d)]
 ### [0.3.124](https://github.com/eea/volto-cca-policy/compare/0.3.123...0.3.124) - 12 May 2026
 
 #### :bug: Bug Fixes

package/artifacts/BLOCKS.md

@@ -0,0 +1,167 @@
+# Custom Blocks in `volto-cca-policy`
+
+This addon registers **20 custom blocks** and extends **2 existing blocks** (Listing, Tabs Block) with new variations.
+All blocks are installed via `src/components/manage/Blocks/index.js`.
+
+---
+
+## Custom Blocks
+
+### AST Navigation
+- **Block ID:** `astNavigation`
+- **Group:** `site`
+- **Restricted to:** Mission pages (via `blockAvailableInMission`)
+- **What it does:** Renders a visual navigation map (logo map) for the *Adaptation Support Tool (AST)*. Supports two image types (`ast` and `uast`). Editors configure 6 linked items that map to clickable regions on the logo image. Clicking a region navigates to the corresponding content page.
+
+### C3S Indicators Glossary
+- **Block ID:** `c3SIndicatorsGlossaryBlock`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** Displays a glossary table of C3S (Copernicus Climate Change Service) indicator terms. The content is provided by a server-side `@components` view (`c3s_indicators_glossary_table`) and rendered as raw HTML.
+
+### C3S Indicators Listing
+- **Block ID:** `c3SIndicatorListingBlock`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** Renders a description and a linked list of C3S indicators. Content (description text + item list with URLs) is provided by the server-side `@components` view `c3s_indicators_listing`.
+
+### C3S Indicators Overview
+- **Block ID:** `c3SIndicatorsOverviewBlock`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** Displays an HTML description/overview of C3S indicators, fetched from the server-side `@components` view `c3s_indicators_overview`.
+
+### Case Study Explorer
+- **Block ID:** `caseStudyExplorer`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** An interactive map-based explorer for climate adaptation case studies. Loads case study data from an ArcGIS JSON endpoint (`@@case-studies-map.arcgis.json`). Provides filter controls (sectors, impacts, etc.) and an interactive map with clickable features. Supports URL-based filter parameters.
+
+### Collection Statistics
+- **Block ID:** `collectionStats`
+- **Group:** `site`
+- **What it does:** Displays aggregated statistics for a content collection. Shows two groups of stats with icons and counts:
+  - **Health impacts:** Climate-sensitive diseases, Heat, Wildfires, Droughts and floods, Air pollution and aero-allergens
+  - **Content types:** Adaptation options, Case studies, Guidance, Indicators, Information portals, Organisations, Publications, Research projects, Tools, Videos
+- Stats are computed from query stats via `getQueryStats` and can link to filtered search results.
+
+### Content Links
+- **Block ID:** `contentLinks`
+- **Group:** `site`
+- **Variations:**
+  - `default` — Simple list of linked content items
+  - `navigationList` — Navigation-style list with active-state highlighting based on current URL
+  - `dropdown` — Dropdown selector for linking to content items (with configurable placeholder text)
+- **What it does:** Displays a set of manually selected content items as links. Useful for sidebars, navigation menus, or quick-access link groups.
+
+### Country Map Heat Index
+- **Block ID:** `countryMapHeatIndex`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** An interactive OpenLayers map of European countries colored by heat index data. Fetches metadata from `@@countries-heat-index-json`. Countries are highlighted with tooltips and are clickable, navigating to the respective country page. Includes a filter control and supports lazy loading via visibility sensor.
+
+### Country Map Observatory
+- **Block ID:** `countryMapObservatory`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** An interactive OpenLayers map for the Health Observatory section. Renders EU countries with metadata from `@@countries-metadata-extract-2025`. Supports thematic map modes (e.g., "National adaptation policy"), tooltips, and click-to-navigate interactions. Uses WMS tile sources and lazy loading.
+
+### Country Map Profile
+- **Block ID:** `countryMapProfile`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** An interactive OpenLayers map for country profiles. Renders EU countries with metadata from `@@countries-metadata-extract-2025` (including flag images). Supports thematic map modes, tooltips, click-to-navigate, and a filter control. Uses WMS tile sources and lazy loading.
+
+### Country Profile Detail
+- **Block ID:** `countryProfileDetail`
+- **Group:** `site`
+- **What it does:** Renders the detailed country profile content provided by a server-side `@components` view (`countryprofile.html`). Displays tabbed sections with accordions, including a language disclaimer for non-English content and optional top messages/accordions.
+
+### Data Connected Embed Block
+- **Block ID:** `data_connected_embed` (extends `@eeacms/volto-datablocks`)
+- **What it does:** Customizes the data-connected embed block from `volto-datablocks` to inject the current page language (`lang`) as an additional query parameter. This ensures embedded data visualizations respect the page's language context. Wraps the base `ViewEmbedBlock` with Redux connectivity and `injectIntl`.
+
+### ECDE Indicators
+- **Block ID:** `ecdeIndicators`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** Embeds European Climate Data Explorer (ECDE) indicator visualizations from the Copernicus Climate Data Store (CDS). Loads region data from an EEA ArcGIS service and renders interactive CDS toolbox apps (e.g., growing degree days, mean temperature) for selected European NUTS regions.
+
+### Filter AceContent
+- **Block ID:** `filterAceContent`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **Variations:**
+  - `simpleListing` — Listing view (default)
+  - `simpleCards` — Card grid view
+- **What it does:** Provides a faceted search/filter interface for ACE (Adaptation Content Exchange) content. Supports filtering by bio-regions, countries, climate impacts, sectors, element types, funding programmes, macro-regions, key types, and free-text search. Uses a custom select widget with styled dropdowns.
+
+### Flourish Visualization
+- **Block ID:** `FlourishEmbedBlock`
+- **Group:** `site`
+- **What it does:** Embeds interactive data visualizations from [Flourish.studio](https://flourish.studio). Editors paste a Flourish embed code, and the block extracts the visualization URL, wraps it in an iframe with privacy protection (lazy loading via consent gate), and displays it at a fixed height of 980px.
+
+### RAST (Related And Sub-Tree) Block
+- **Block ID:** `rastBlock`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** Renders a contextual navigation block showing related content and sub-items from a configurable root path. Supports skipping specific items and optionally showing subfolders. Uses `ContextNavigation` and `RASTAccordion` components to display a hierarchical accordion-style navigation tree.
+
+### Read More
+- **Block ID:** `readMoreBlock`
+- **Group:** `site`
+- **What it does:** Creates a collapsible "read more" section. Wraps all preceding sibling blocks in a height-constrained container with an expand/collapse button. Configurable properties include open/closed labels, button position, and initial height.
+
+### Redirection Block
+- **Block ID:** `redirectBlock`
+- **Group:** `site`
+- **What it does:** Automatically redirects anonymous users to a configured target URL. Logged-in users (editors) see a discreet notice showing the redirect target instead of being redirected, so they can still edit the page.
+
+### Relevant AceContent
+- **Block ID:** `relevantAceContent`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** Displays a list of relevant ACE (Adaptation Content Exchange) items. Supports two modes: manually selected items and dynamically searched results (by element type, sector, search type, special tags, or search text). Can combine both modes. Renders as a simple linked list.
+
+### Search AceContent
+- **Block ID:** `searchAceContent`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** Displays search results from the ACE content search API. Shows results as a linked list with translated labels and counts. Includes a "Share your information" button linking to the share page.
+
+### Tabs Block — Spotlight Variation
+- **Block ID:** `tabs_block` (extends `@eeacms/volto-tabs-block`)
+- **Variation added:** `spotlight`
+- **What it does:** Adds a "Spotlight" variation to the standard tabs block. Renders tab content with a spotlight-style layout featuring configurable icons or images (with position and size options), simple markdown support, and scroll-to-target behavior.
+
+### Trans Region Select
+- **Block ID:** `transRegionSelect`
+- **Group:** `site`
+- **Restricted to:** Mission pages
+- **What it does:** Renders a dropdown selector for transnational regions. Fetches region data from the content's `@components` view (`transnationalregion`) and provides a dropdown with links to each region's page, plus a default "Other regions" option.
+
+---
+
+## Extended Standard Blocks
+
+### Listing (standard Volto block — extended)
+The standard Volto `listing` block is extended with **6 new variations**:
+
+| Variation | Description |
+|-----------|-------------|
+| `dropdown` | Renders listed items as a dropdown selector with a configurable placeholder text |
+| `organisationCards` | Displays items as a 4-column card grid with logo/image and description (for organisations) |
+| `indicatorCards` | Displays C3S/Lancet Countdown indicators as styled cards with title and description |
+| `eventCards` | Displays events as cards with date info, contact details, event URL, and EEA branding |
+| `eventAccordion` | Displays events in an accordion layout with formatted date ranges and "read more" expand |
+| `simpleListing` | Plain text list of linked items (minimal styling) |
+| `simpleCards` | Generic 4-column card grid with image/logo and title |
+
+Additionally, the listing block's `noResultsComponent` is overridden to render nothing (instead of showing "No results" text).
+
+---
+
+## Shared Utilities
+
+- **`withResponsiveContainer.js`** — HOC that wraps map blocks in a responsive container (used by Country Map blocks)
+- **`withVisibilitySensor.jsx`** — HOC that defers map initialization until the block is visible in the viewport (lazy loading)

package/artifacts/link-integrity-block-fields-report.md

@@ -0,0 +1,132 @@
+# Link Integrity — Block Field Coverage Report
+
+**Date:** 2026-05-18
+**Scope:** All blocks registered by `volto-cca-policy`, analyzed against the link integrity retrievers available in `plone.restapi` and `eea.climateadapt`.
+
+---
+
+## Retrievers in Play
+
+Three retrievers scan block data when content is saved:
+
+| Retriever | Source | Order | Fields Scanned | Scope |
+|---|---|---|---|---|
+| `GenericBlockLinksRetriever` | `plone.restapi` | 1 | `url`, `href`, `preview_image` (top-level only) | All blocks (`block_type = None`) |
+| `TextBlockLinksRetriever` | `plone.restapi` | 100 | DraftJS `entityMap` LINK entities (`href`, `url`) | `block_type = "text"` |
+| `SlateBlockLinksRetriever` | `plone.restapi` | 100 | Slate nodes: `handle_a` → `data.link.internal.internal_link[0]["@id"]`, `handle_link` → `data.url` | `block_type = "slate"` |
+| `CCAObjectListLinksRetriever` | `eea.climateadapt` | 10 | `items[*].source`, `items[*].href`, `items[*].url`, top-level `linkTo`, top-level `image` | All blocks (`block_type = None`) |
+
+**Key constraint:** `GenericBlockLinksRetriever` only checks **top-level** fields named exactly `url`, `href`, or `preview_image`. It does NOT recurse into lists, dicts, or nested structures. Any link stored in a non-standard field name or nested inside a list requires the `CCAObjectListLinksRetriever` (or a new custom retriever).
+
+---
+
+## Block-by-Block Analysis
+
+### 1. Blocks WITH internal link fields — FULLY COVERED
+
+These blocks use standard top-level field names (`href`, `url`) that `GenericBlockLinksRetriever` catches, or their nested `items` are covered by `CCAObjectListLinksRetriever`.
+
+| Block | Field(s) | Widget | Covered By | Notes |
+|---|---|---|---|---|
+| **RedirectBlock** | `href` | `object_browser` | `GenericBlockLinksRetriever` | Standard `href` at top level |
+| **CountryMapObservatory** | `href` | `object_browser` | `GenericBlockLinksRetriever` | Standard `href` at top level |
+| **CollectionStatistics** | `href` | `object_browser` | `GenericBlockLinksRetriever` | Standard `href` at top level |
+| **ASTNavigation** | `href` (top-level) | `object_browser` | `GenericBlockLinksRetriever` | Main entry page link |
+| **ASTNavigation** | `items[*].href` | `object_browser` (in `object_list`) | `CCAObjectListLinksRetriever` | Nav items — `items` list with `href` field |
+| **ContentLinks** | `items[*].source` | `object_browser` (in `object_list`) | `CCAObjectListLinksRetriever` | `source` in items is explicitly handled |
+| **RelevantAceContent** | `items[*].source` | `object_browser` (in `object_list`) | `CCAObjectListLinksRetriever` | `source` in items is explicitly handled |
+
+### 2. Blocks WITH internal link fields — NOT COVERED (GAP)
+
+These blocks have fields that store internal links (via `object_browser`, path strings, or similar) but the field name or structure is **not** recognized by any existing retriever.
+
+| Block | Field(s) | Widget / Type | Why Not Covered | Risk |
+|---|---|---|---|---|
+| **Listing** (standard, extended) | `linkHref` | `object_browser` | Field name is `linkHref` — not in `GenericBlockLinksRetriever` (`url`, `href`, `preview_image`) and not in `CCAObjectListLinksRetriever` (`linkTo`, `image`). The CCA retriever checks `linkTo` but Volto core uses `linkHref`. | **Medium** — The "Link to..." / "More..." button link is silently missed. |
+| **RASTBlock** | `root_path` | plain `string` (path) | Stores a plain path string (e.g., `/en/knowledge-and-data/...`), NOT a `resolveuid/` URL. The retrievers only match strings containing `resolveuid`. | **Low** — Editors type paths manually; no object_browser. Moving the target folder breaks the link with no warning. |
+
+### 3. Blocks WITHOUT internal link fields — NO ACTION NEEDED
+
+These blocks either have no link-bearing fields, fetch content dynamically from the server, or use server-side `@components` views.
+
+| Block | Rationale |
+|---|---|
+| **C3SIndicatorsGlossaryBlock** | Empty schema. Content fetched from `@components` view `c3s_indicators_glossary_table`. |
+| **C3SIndicatorsListingBlock** | Empty schema. Content fetched from `@components` view `c3s_indicators_listing`. |
+| **C3SIndicatorsOverviewBlock** | Empty schema (category field commented out). Content fetched from `@components` view `c3s_indicators_overview`. |
+| **CaseStudyExplorer** | No schema file. Loads data from ArcGIS JSON endpoint (`@@case-studies-map.arcgis.json`). No content links stored in block data. |
+| **CountryMapHeatIndex** | No schema file. Renders country map from static GeoJSON + metadata endpoint. No content links in block data. |
+| **CountryMapProfile** | No schema file. Same pattern as CountryMapHeatIndex. No content links in block data. |
+| **CountryProfileDetail** | No schema file. Renders HTML from `@components` view `countryprofile`. |
+| **ECDEIndicators** | No schema file. Embeds CDS toolbox apps by region code. No content links in block data. |
+| **FilterAceContent** | Schema has only filter parameters (vocabularies, search text, sort). No `object_browser` or link fields. Results are fetched dynamically. |
+| **SearchAceContent** | Same as FilterAceContent — only filter/search parameters. No content links stored. |
+| **FlourishEmbedBlock** | `embed_code` is a `textarea` with raw HTML/JS. Not parsed by any retriever. Links (if any) are external Flourish URLs. |
+| **ReadMore** | Behavioral block only (labels, height, position). No links. |
+| **DataConnectedEmbedBlock** | Extends `@eeacms/volto-datablocks`. Only adds a `languageParam` string field. The base block's URL fields (if any) are handled by the base package's own mechanisms. |
+| **TransRegionSelect** | `region` is a vocabulary choice (not a link). Renders links dynamically from `@components` view. |
+| **TabsBlock (Spotlight)** | Container block. Links in child blocks are discovered recursively by `visit_blocks`. The spotlight variation's `image` field (in tab settings) is covered by `CCAObjectListLinksRetriever` (top-level `image`). |
+
+---
+
+## Summary of Gaps
+
+### Gap 1: Listing block — `linkHref` field
+
+**Problem:** The standard Volto listing block stores its "More..." link in a field named `linkHref`. The `GenericBlockLinksRetriever` only scans `url`, `href`, `preview_image`. The `CCAObjectListLinksRetriever` scans `linkTo` and `image` — neither matches `linkHref`.
+
+**Impact:** If an editor configures a listing block with a "Link to..." destination, and that destination is moved or made private, the link integrity system will NOT report this listing block as a breacher.
+
+**Remediation options:**
+1. **Extend `CCAObjectListLinksRetriever`** to also scan `linkHref` (add it to the top-level fields list alongside `linkTo` and `image`). This is the simplest fix — one line change.
+2. **Register a dedicated `ListingBlockLinksRetriever`** adapted to `block_type = "listing"`. More explicit but more code.
+
+**Recommendation:** Option 1 — add `linkHref` to the top-level fields in `CCAObjectListLinksRetriever`.
+
+### Gap 2: RASTBlock — `root_path` field
+
+**Problem:** `root_path` stores a plain content path (e.g., `/en/knowledge-and-data/rast`) as a string. It is NOT stored as `resolveuid/<UID>`, so even if the field name were recognized, `get_urls_from_value` would not match it (it checks for `resolveuid` in the string).
+
+**Impact:** If the root folder is moved, the RAST block silently points to a 404. No link integrity warning.
+
+**Remediation options:**
+1. **Change the widget** to `object_browser` and store as `resolveuid/` — then add `root_path` to a retriever. This is a schema change with migration implications.
+2. **Accept the risk** — the field is typed manually by editors and is inherently fragile regardless of link integrity.
+3. **Add a custom deserializer** that converts the path to `resolveuid/` on save, then add `root_path` to a retriever.
+
+**Recommendation:** Option 2 (accept risk) for now — the field is a single path string used by a small number of blocks, and converting it to `object_browser` would be a larger UX change. Document the limitation.
+
+---
+
+## Coverage Matrix
+
+| Block | Link Fields | Generic Retriever | CCA Retriever | Gap? |
+|---|---|---|---|---|
+| RedirectBlock | `href` | ✅ | — | No |
+| CountryMapObservatory | `href` | ✅ | — | No |
+| CollectionStatistics | `href` | ✅ | — | No |
+| ASTNavigation | `href` (top) | ✅ | — | No |
+| ASTNavigation | `items[*].href` | ❌ | ✅ | No |
+| ContentLinks | `items[*].source` | ❌ | ✅ | No |
+| RelevantAceContent | `items[*].source` | ❌ | ✅ | No |
+| **Listing** | `linkHref` | ❌ | ❌ | **Yes** |
+| RASTBlock | `root_path` | ❌ | ❌ | Yes (low risk) |
+| FlourishEmbedBlock | `embed_code` | ❌ | ❌ | N/A (external) |
+| All others | (none) | — | — | No |
+
+---
+
+## Notes on plone.restapi / plone.volto Checkouts
+
+- **plone.restapi** is checked out at `backend/sources/plone.restapi/`. It provides `GenericBlockLinksRetriever` (fields: `url`, `href`, `preview_image`), `TextBlockLinksRetriever` (DraftJS), and `SlateBlockLinksRetriever`.
+- **plone.volto** is NOT checked out in `backend/sources/`. It is installed as a packaged dependency in the backend venv. No custom link integrity retrievers were found in the EEA policy package (`eea.volto.policy`) — it only provides serialization/deserialization transformers, not link retrievers.
+- The `CCAObjectListLinksRetriever` in `eea.climateadapt` is the **only** custom link integrity retriever in the project. It runs at order 10 (before Generic at order 1, but both return independent lists that are unioned).
+
+---
+
+## Recommendations
+
+1. **Fix the Listing gap immediately** — add `linkHref` to `CCAObjectListLinksRetriever`'s top-level field scan (one-line change in `blocks_linkintegrity.py`).
+2. **Consider adding `image` to Generic coverage analysis** — `CCAObjectListLinksRetriever` already covers `image`, but if a future block uses `image` without items, it would only be caught by CCA's retriever.
+3. **Document the RASTBlock limitation** in the block's developer notes or BLOCKS.md.
+4. **Future blocks:** Always name link fields `href` or `url` at the top level, or `items[*].href` / `items[*].source` for nested lists, to benefit from existing retrievers.

package/artifacts/link-integrity-blocks-report.md

@@ -0,0 +1,52 @@
+# Volto Block Link Integrity Analysis Report - volto-cca-policy
+
+## Objective
+Identify blocks within the `volto-cca-policy` add-on that contain internal links in fields or structures not covered by the standard Plone/Volto link integrity discovery mechanisms.
+
+## Standard Coverage Recap
+
+The following mechanisms are provided by core packages:
+
+1.  **`plone.restapi` (Generic Retriever)**: Automatically extracts links from top-level fields: `url`, `href`, `preview_image`.
+2.  **`plone.restapi` (Visitors)**: Recursively visits sub-blocks stored in `blocks` or `data.blocks`.
+3.  **`plone.volto` (Visitors/Retrievers)**: Recursively visits sub-blocks stored in `columns`, `hrefList`, and `slides`.
+4.  **`eea.climateadapt` (Backend Custom Retriever)**: Specifically covers `items[*].source`, `items[*].href`, `items[*].url`, and top-level `linkTo` and `image`.
+
+## Analysis of volto-cca-policy Blocks
+
+| Block (@type) | Field Location | Covered? | Reason / Mechanism |
+| :--- | :--- | :--- | :--- |
+| `ContentLinks` | `items[*].source` | **Yes** | `CCAObjectListLinksRetriever` (Backend) |
+| `RelevantAceContent` | `items[*].source` | **Yes** | `CCAObjectListLinksRetriever` (Backend) |
+| `ASTNavigation` | `items[*].href` | **Yes** | `CCAObjectListLinksRetriever` (Backend) |
+| `Listing` (Shadowed) | `linkTo` | **Yes** | `CCAObjectListLinksRetriever` (Backend) |
+| `RedirectBlock` | `href` | **Yes** | `GenericBlockLinksRetriever` (Core) |
+| `CountryMapObservatory`| `href` | **Yes** | `GenericBlockLinksRetriever` (Core) |
+| `CollectionStatistics` | `href` | **Yes** | `GenericBlockLinksRetriever` (Core) |
+| `TabsBlock` (Spotlight)| `tabs[*].blocks` | **NO** | `tabs` key is not visited by core visitors. |
+| `TabsBlock` (Spotlight)| `tabs[*].image` | **NO** | `tabs` structure is not scanned for link fields. |
+| `FlourishEmbedBlock` | `embed_code` | **NO** | Raw HTML/JS (requires parsing). |
+| `CaseStudyExplorer` | `adaptation_options_links` | **NO** | Raw HTML (often dynamic source). |
+| `RASTBlock` | `root_path` | **NO** | Hardcoded string path (not a UID). |
+
+## Detailed Findings
+
+### 1. TabsBlock (Spotlight Variation)
+The `TabsBlock` in `volto-cca-policy` uses a custom `tabs` key to store a dictionary of tab data. Each tab can contain its own sub-blocks (`blocks` key) and a promotional `image`.
+*   **Sub-blocks Visibility**: Since neither `plone.restapi` nor `plone.volto` includes `tabs` in their `IBlockVisitor` implementations, the backend link integrity system is "blind" to any blocks placed inside a spotlight tab.
+*   **Image Visibility**: The `image` field within a tab is nested inside the `tabs` object list/map, which is not scanned by the generic or CCA-specific retrievers.
+
+### 2. FlourishEmbedBlock
+This block stores raw HTML or Javascript snippets for embedding Flourish charts. Internal links within these snippets are not tracked because they are not stored as structured data or `resolveuid/` patterns.
+
+### 3. RASTBlock
+Uses a `root_path` field which stores an absolute path as a string (e.g., `/en/knowledge-and-data/...`). Link integrity tracking depends on `resolveuid/` patterns and `zc.relation` objects. Paths are not automatically tracked or updated if the target moves.
+
+## Recommendations
+
+1.  **Expand Backend Retriever**: Update `CCAObjectListLinksRetriever` (or add a new one) to handle the `tabs` structure:
+    *   Visit each item in the `tabs` dictionary.
+    *   Extract links from the `image` field if present.
+    *   (Optional) If `tabs` items contain their own blocks, a custom `IBlockVisitor` should be registered to allow core recursion to reach them.
+2.  **Refactor RASTBlock**: If possible, change `root_path` to use a proper object browser widget and store a UID.
+3.  **Documentation**: Advise developers to stick to `blocks`, `columns`, or `slides` for sub-block storage, or `items` for list-based links to benefit from existing retrievers.

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

@@ -0,0 +1,143 @@
+# Understanding Link Integrity in Plone and Volto
+
+## Use Case
+A user is editing a content item and decides to change its workflow state to "Private". Before this action is finalized, the system should check if other content items on the website are linking to this item. If such links exist, the user should be informed that these links will effectively "break" for public users (leading to an unauthorized screen).
+
+## Goal
+Identify a programmatic way (ideally a REST API endpoint) to retrieve a list of content items that link to a specific object.
+
+## Research Findings
+
+### 1. `plone.app.linkintegrity`
+- **Mechanism**: Tracks internal links using the `zc.relation` catalog with the relationship name `isReferencing`.
+- **Logic**: Extracts links from Dexterity `RichText` fields and Volto blocks (via `plone.volto`).
+- **Querying**: Provides utility functions in `plone.app.linkintegrity.utils`, notably `getIncomingLinks(obj)`.
+
+### 2. `plone.restapi`
+- **Existing Endpoints**:
+    - **`/@linkintegrity?uids=<UID>`**: Returns "breaches" (items linking to the specified UIDs). This is the same logic used by Plone's delete confirmation screen.
+    - **`/@relations?target=<UID>&relation=isReferencing`**: A more generic endpoint to query the relation catalog. Omitting the `relation` parameter returns all types of incoming relations (including `relatedItems`).
+- **Recommendation**: For the "warn before private" use case, `/@linkintegrity` is highly suitable because it returns structured data specifically designed for notifying users about broken links. However, `/@relations` is better if a simple list of *any* linking item is needed.
+
+### 3. `plone.volto` / Volto Frontend
+- **Backend**: Ensures that internal links within Volto blocks (columns, teasers, etc.) are correctly indexed by `plone.app.linkintegrity`.
+- **Frontend Logic**: 
+    - Volto has a `linkIntegrityCheck` action in `@plone/volto/actions` that calls the `/@linkintegrity` endpoint.
+    - The results are stored in the `linkIntegrity` reducer.
+    - The `ContentsDeleteModal` component in Volto core is the canonical example of how to display these breaches.
+- **Workflow Integration**: The state transition dropdown is managed by the `Workflow` component (`@plone/volto/components/manage/Workflow/Workflow`).
+
+## Recommended Solution
+
+To implement the "warn before private" feature:
+
+1. **Backend Endpoint**: Use `GET /@linkintegrity?uids=<UID>`.
+2. **Frontend Integration (Shadowing)**: 
+    - Shadow the core `Workflow` component by copying it to `frontend/src/addons/volto-cca-policy/src/customizations/volto/components/manage/Workflow/Workflow.jsx`.
+    - Intercept the `onChange` handler in the shadowed component.
+    - If the target state is "Private" (or similar), trigger the `linkIntegrityCheck`.
+    - Show a confirmation modal (similar to `ContentsDeleteModal`) if breaches are found.
+
+## Volto Implementation Details
+
+### Shadowing Path
+```
+frontend/src/addons/volto-cca-policy/src/customizations/volto/components/manage/Workflow/Workflow.jsx
+```
+
+### Logic Hook
+In the shadowed `Workflow.jsx`, modify the `transition` function:
+
+```javascript
+const transition = (selectedOption) => {
+  const isPrivateTransition = ['private', 'reject', 'retract'].includes(selectedOption.value) || 
+                               selectedOption.url.endsWith('/reject') || 
+                               selectedOption.url.endsWith('/retract');
+
+  if (isPrivateTransition) {
+    setPendingOption(selectedOption);
+    dispatch(linkIntegrityCheck([content.UID]));
+    setShowWarningModal(true);
+  } else {
+    executeTransition(selectedOption);
+  }
+};
+```
+
+### Components to reuse
+- `Confirm` from `semantic-ui-react` for the modal wrapper.
+*   **Existing Actions**: `linkIntegrityCheck` from `@plone/volto/actions`.
+*   **Existing Reducers**: `state.linkIntegrity.result` to access the breaches.
+*   **UI Reference**: `ContentsDeleteModal.jsx` in Volto core for the table rendering logic of broken links.
+
+## Final Implementation
+
+The feature was implemented in the `volto-cca-policy` add-on on a dedicated branch.
+
+### Git Branch
+- **Branch Name**: `link-integrity-workflow`
+
+### Files Created/Modified
+1.  **Shadowed Component**: `src/customizations/volto/components/manage/Workflow/Workflow.jsx`
+    - Shadowed from `@plone/volto/components/manage/Workflow/Workflow.jsx`.
+    - Modified to intercept state changes to `private`, `reject`, and `retract`.
+    - Integrated with `linkIntegrityCheck` action and `WorkflowLinkIntegrityModal`.
+2.  **New Component**: `src/components/manage/Workflow/WorkflowLinkIntegrityModal.jsx`
+    - A custom confirmation modal that displays link integrity breaches.
+    - Uses `semantic-ui-react` for the UI (Confirm, Table, Loader).
+    - Accesses `state.linkIntegrity.result` to render the list of affected content.
+3.  **Components Index**: `src/components/index.js`
+    - Exported `WorkflowLinkIntegrityModal` for use in the shadowed `Workflow` component.
+
+### Logic Summary
+- **Trigger**: When the user selects a "Private" transition in the workflow dropdown.
+- **Verification**: The `linkIntegrityCheck` action is dispatched for the current object's UID.
+- **Race Condition Prevention**: The system explicitly waits for the `linkIntegrity.loaded` state to be true before deciding whether to auto-proceed or show the modal. This prevents transitions from executing prematurely due to stale or initial empty state.
+- **Activity Indicators (UX)**: 
+    - During the link integrity check, a `Dimmer` and `Loader` are shown within the `WorkflowLinkIntegrityModal` with the message "Checking references...".
+    - During the actual workflow transition execution, a `Dimmer` and `Loader` are shown over the state selection dropdown to indicate that the transition is in progress.
+- **Interaction**:
+    - If no incoming links exist (`breaches.length === 0`), the transition proceeds automatically once the check is loaded.
+    - If incoming links are found, the `WorkflowLinkIntegrityModal` displays the list of referencing pages.
+    - The user can either "Cancel" the transition or select "Change state anyway" to proceed.
+
+## User Story: Testing the Link Integrity Warning
+
+### Description
+As a Content Editor, I want to be warned when I am about to make a page private if other pages are linking to it, so that I can avoid creating broken links for visitors.
+
+### Acceptance Criteria
+1.  **Positive Case (Breaches Found)**: 
+    - Given a "Target Page" that is published.
+    - Given a "Source Page" that contains a link to "Target Page".
+    - When I go to "Target Page" and select "Make Private" (or "Reject" / "Retract") from the state dropdown.
+    - Then I should see a "Checking references..." loading indicator.
+    - Then I should see a warning modal titled "Warning: Potential broken links".
+    - Then the modal should list "Source Page" as an item that will have a broken link.
+    - When I click "Cancel", the modal should close and the page should remain "Published".
+    - When I click "Change state anyway", the modal should close and the page should transition to "Private".
+
+2.  **Negative Case (No Breaches)**:
+    - Given a "Target Page" that is published and has NO incoming links.
+    - When I select "Make Private" from the state dropdown.
+    - Then I should see a brief "Checking references..." indicator.
+    - Then the page should transition to "Private" immediately without showing a warning modal.
+
+### Test Procedure
+1.  **Setup Content**:
+    - Create a page named "Linked Page" and Publish it.
+    - Create another page named "Referencing Page". 
+    - In "Referencing Page", add a Text block and insert an internal link to "Linked Page". Publish "Referencing Page".
+2.  **Verify Warning**:
+    - Navigate to "Linked Page".
+    - Open the state dropdown in the toolbar.
+    - Select "Make Private".
+    - **Observe**: The "Checking references..." dimmer should appear briefly.
+    - **Verify**: The warning modal should appear listing "Referencing Page".
+3.  **Test Cancellation**:
+    - Click "Cancel" in the modal.
+    - **Verify**: The page is still in "Published" state.
+4.  **Test Confirmation**:
+    - Select "Make Private" again.
+    - Click "Change state anyway" in the modal.
+    - **Verify**: The page state changes to "Private" and a success toast appears.

package/artifacts/link-integrity-workflow/volto-block-link-analysis.md

@@ -0,0 +1,63 @@
+# Volto Block Link Discovery Analysis - volto-cca-policy
+
+This document analyzes the custom blocks defined in the `volto-cca-policy` add-on to identify which fields contain internal links and whether they are covered by the standard Plone/Volto link integrity discovery mechanism.
+
+## Standard Discovery Mechanism Recap
+
+As documented in `volto-block-link-discovery.md`, the `GenericBlockLinksRetriever` automatically extracts internal links from the following top-level fields:
+- `url`
+- `href`
+- `preview_image`
+
+Any field not named exactly like one of these, or any link nested within a list or dictionary (unless it's a `blocks` container), requires a specialized retriever on the backend.
+
+## Analysis of volto-cca-policy Blocks
+
+### 1. Blocks Covered by Generic Retriever
+The following blocks use standard field names at the top level and should be automatically tracked.
+
+| Block | Field | Description |
+|---|---|---|
+| `RedirectBlock` | `href` | The target object for the redirection. |
+| `CountryMapObservatory` | `href` | The parent location of all country profiles. |
+| `CollectionStatistics` | `href` | The destination listing page. |
+| `ASTNavigation` | `href` | The main entry page to AST/UAST (top-level). |
+
+### 2. Blocks NOT Covered (Custom Field Names)
+The following blocks use field names that are not recognized by the generic retriever.
+
+| Block | Field | Description |
+|---|---|---|
+| `Listing` (Shadowed) | `linkTo` | Standard Volto listing block uses `linkTo` for the "More..." link. |
+
+### 3. Blocks NOT Covered (Nested Links)
+The following blocks store links within an `object_list`. The generic retriever does not scan inside these lists.
+
+| Block | Field Path | Description |
+|---|---|---|
+| `ContentLinks` | `items[*].source` | A list of hand-picked content items. |
+| `RelevantAceContent` | `items[*].source` | A list of hand-picked content items (assigned items). |
+| `ASTNavigation` | `items[*].href` | Individual navigation steps in the AST map. |
+
+### 4. Special Cases
+
+#### `FlourishEmbedBlock`
+- **Field**: `embed_code` (Textarea)
+- **Status**: Not covered.
+- **Reason**: Contains raw HTML/JS snippets. Discovery would require parsing the HTML for URLs, which is not performed by the standard block retrievers.
+
+#### `TabsBlock` (Spotlight Variation)
+- **Status**: Covered (indirectly).
+- **Reason**: This is a container block. The `NestedBlocksVisitor` handles the recursion into its child blocks, so any links within those children will be discovered normally.
+
+#### `ReadMore`
+- **Status**: No Links.
+- **Reason**: This is a behavioral block that manipulates the DOM of its siblings on the frontend. It does not store links in its own block data.
+
+## Recommendations for Link Integrity
+
+To ensure full coverage for `volto-cca-policy` content, the following actions are recommended:
+
+1.  **Backend Adapters**: Register custom `IBlockFieldLinkIntegrityRetriever` adapters for `ContentLinks`, `RelevantAceContent`, and `ASTNavigation` to extract links from their `items` lists.
+2.  **Field Mapping**: If possible, refactor `ContentLinks` and `RelevantAceContent` to use `href` or `url` instead of `source` for individual items, although a custom retriever is still needed for the list structure.
+3.  **Core Coverage**: Verify if `plone.restapi` or `plone.volto` provides a specialized retriever for the `listing` block's `linkTo` field. If not, one should be added.