@eeacms/volto-cca-policy 1.0.2 → 1.0.4

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

@@ -1,63 +0,0 @@
-# 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.

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

@@ -1,60 +0,0 @@
-# How Volto Discovers Links in Blocks for Link Integrity
-
-When a content item is saved in Plone, the system needs to know which other internal items it links to, so it can maintain the `zc.relation` catalog (specifically using the `isReferencing` relationship). 
-
-For traditional Plone, this meant parsing HTML in `RichText` fields. For Volto, the content is stored as JSON blocks, requiring a recursive discovery mechanism.
-
-## Sub-block Storage and Discovery
-
-Sub-blocks are stored in the JSON data of a parent block using one of two primary patterns. The Plone backend uses a recursive generator called `visit_blocks` (defined in `plone.restapi.blocks`) to walk this tree.
-
-### 1. Dictionary Mapping (Key-Value)
-This is the standard Volto pattern for container-like blocks.
-- **Storage Pattern**: A dictionary where keys are UUIDs and values are the sub-block data.
-- **Common Keys**: `blocks` or `data["blocks"]`.
-- **Discovery**: `plone.restapi.blocks.NestedBlocksVisitor` is registered for these keys. It yields each value in the dictionary.
-
-### 2. Sequential Lists
-This pattern is used by layout-oriented blocks where the order is strictly positional.
-- **Storage Pattern**: A simple list of block data objects.
-- **Core Volto Keys**: `columns`, `slides`, `hrefList`.
-- **Discovery**: `plone.volto.transforms.NestedBlocksVisitor` handles these keys. It iterates through the list and yields each block.
-
-### 3. Recursive Discovery Logic
-The `visit_blocks` function uses `IBlockVisitor` subscribers to find children. When a visitor yields a sub-block, `visit_blocks` immediately recurses into that sub-block. This ensures that a block tree of any depth (e.g., a Grid containing Columns containing Teasers) is fully flattened during the discovery phase.
-
-## Internal Link Extraction
-
-Once a block is discovered, the `BlocksRetriever` (in `plone.restapi.blocks_linkintegrity`) uses `IBlockFieldLinkIntegrityRetriever` subscribers to find internal links within that specific block's fields.
-
-### Automatic Link Detection (The Generic Retriever)
-The `GenericBlockLinksRetriever` provides a "zero-configuration" discovery for most custom blocks. It automatically scans the following fields if they contain the `resolveuid/` pattern:
-- `url`
-- `href`
-- `preview_image`
-
-**Note**: If a block uses custom field names for links (e.g., `source`, `target`, `link_to`), they will **NOT** be caught by the generic retriever unless they are specifically registered.
-
-### Complex Data Extraction
-Some blocks store links deep within complex JSON structures rather than simple top-level strings. These require specialized retrievers:
-
-1. **Slate Blocks (Rich Text)**:
-   - Uses `SlateBlockLinksRetriever`.
-   - Recursively walks the Slate node tree.
-   - Extracts UIDs from `data.link.internal.internal_link[0]["@id"]` and `data.url`.
-
-2. **DraftJS Blocks (Legacy Text)**:
-   - Uses `TextBlockLinksRetriever`.
-   - Parses the `entityMap` for `LINK` entities.
-   - Extracts data from `url` and `href` keys within the entity data.
-
-## Redundancy and Reliability
-To ensure maximum reliability, `plone.volto` includes a `NestedBlockLinkRetriever` (registered with `block_type = None`). This serves as a fail-safe that manually walks the `columns`, `hrefList`, and `slides` keys to trigger link extraction, providing a second layer of defense for nested layouts.
-
-## Summary for Developers
-To ensure a custom block is correctly tracked by the link integrity system:
-
-1.  **Field Naming**: Prefer naming your link fields `url` or `href` to benefit from the generic retriever.
-2.  **Nesting**: If your block contains sub-blocks, store them in a dictionary under the key `blocks`.
-3.  **Link Format**: Always store internal links using the `resolveuid/<UID>` format.
-4.  **Custom Retrievers**: If you must use unique field names or storage patterns, register a custom `IBlockFieldLinkIntegrityRetriever` adapter for your block's `@type` in the backend.

package/artifacts/test-fixes/test-fixes-specification.md

@@ -1,267 +0,0 @@
-# Test Fix Specification for volto-cca-policy
-
-> Generated: 2026-05-14
-> Branch: `link-integrity-workflow`
-> Machine timezone: EEST (UTC+3)
-
-## Current State
-
-```
-Test Suites: 4 failed, 57 passed, 61 total
-Tests:       7 failed, 115 passed, 122 total
-Snapshots:   6 failed, 12 passed, 18 total
-```
-
-Four test suites fail for three distinct root causes:
-
-| # | Test File | Failure Type | Root Cause |
-|---|-----------|-------------|------------|
-| 1 | `Spotlight.test.jsx` | Suite won't run | `node:crypto` module resolution (uuid@10 + Jest 26) |
-| 2 | `GeolocationWidget.test.jsx` | Assertion error | Mock path mismatch → real OpenLayers loads in Jest |
-| 3 | `EventView.test.jsx` | 3 snapshot mismatches | Timezone-dependent date formatting |
-| 4 | `CcaEventView.test.jsx` | 3 snapshot mismatches | Timezone-dependent date formatting |
-
----
-
-## Problem 1: `node:crypto` — Spotlight.test.jsx
-
-### Symptom
-
-```
-ENOENT: no such file or directory, open 'node:crypto'
-    at Runtime.readFile (node_modules/jest-runtime/build/index.js:1987:21)
-    at Object.<anonymous> (node_modules/uuid/dist/rng.js:7:42)
-```
-
-### Root Cause
-
-The `uuid` package (v10.0.0) uses `require('node:crypto')` — the Node.js built-in module protocol prefix (`node:`). Jest 26.6.3 does not understand this protocol and tries to resolve `node:crypto` as a filesystem path, which fails.
-
-`Spotlight.test.jsx` doesn't import `uuid` directly. It's a transitive dependency pulled in through Volto core or one of its addons when the Spotlight component tree is evaluated.
-
-### Proposed Fix
-
-Add a `moduleNameMapper` entry in `jest-addon.config.js` to redirect `node:crypto` to the real Node.js `crypto` module:
-
-**File: `jest-addon.config.js`**
-
-In the `moduleNameMapper` section, add:
-
-```js
-'^node:crypto$': 'crypto',
-```
-
-This tells Jest to resolve `node:crypto` to the standard `crypto` module, which Node.js provides natively and Jest can handle.
-
-**Why this approach:**
-- Minimal: one line in the config, no new files needed.
-- Follows the established pattern used across the addon ecosystem (moduleNameMapper entries in jest-addon.config.js).
-- Does NOT require creating a mock file (the AI agent's `crypto-mock.js` approach).
-- The real `crypto` module works fine in Jest's Node.js environment — it just needs the `node:` prefix stripped.
-
----
-
-## Problem 2: Mock path mismatch — GeolocationWidget.test.jsx
-
-### Symptom
-
-```
-Invalid lib or bundle name ol,olCondition,olControl,olCoordinate,olEvents,olExtent,olFormat,olGeom,olInteraction,olLayer,olLoadingstrategy,olOverlay,olProj,olRender,olSource,olStyle,olTilegrid
-    at flattenLazyBundle (Loadable/Loadable.js:30:11)
-```
-
-### Root Cause
-
-Two layers of the problem:
-
-**Layer 1 — Webpack vs Jest module resolution mismatch:**
-
-Volto's webpack config uses `RelativeResolverPlugin` (`webpack-plugins/webpack-relative-resolver.js`) which rewrites relative imports into absolute addon-scoped paths at build time. For example, in production:
-
-```
-import MapContainer from './GeolocationWidgetMapContainer'
-```
-
-gets resolved by webpack to:
-
-```
-@eeacms/volto-cca-policy/components/theme/Widgets/GeolocationWidgetMapContainer
-```
-
-Jest does **not** use webpack. It resolves `./GeolocationWidgetMapContainer` as a relative filesystem path. So the two environments resolve the same import line to **different module identifiers**.
-
-**Layer 2 — The test mocks the absolute path, but Jest loads the relative path:**
-
-```js
-// In the test — mocks the absolute (webpack-resolved) path:
-jest.mock(
-  '@eeacms/volto-cca-policy/components/theme/Widgets/GeolocationWidgetMapContainer',
-);
-
-// But GeolocationWidget.jsx imports it relatively:
-import MapContainer from './GeolocationWidgetMapContainer';
-```
-
-In Jest, these are two different modules. The mock never applies. The real `GeolocationWidgetMapContainer` loads, which uses the `withOpenLayers` HOC from `volto-openlayers-map`. That HOC calls `useLazyLibs()` to dynamically load OpenLayers bundles, which crashes in Jest's environment.
-
-### Proposed Fix
-
-Two options. **Option A is recommended** because it fixes the source code to match the project convention (the rest of the codebase uses `@eeacms/volto-cca-policy/...` absolute imports — the relative import in `GeolocationWidget.jsx` is the outlier).
-
----
-
-#### Option A: Change the source code to use the absolute import (recommended)
-
-**File: `src/components/theme/Widgets/GeolocationWidget.jsx`**
-
-Replace:
-
-```js
-import MapContainer from './GeolocationWidgetMapContainer';
-```
-
-With:
-
-```js
-import MapContainer from '@eeacms/volto-cca-policy/components/theme/Widgets/GeolocationWidgetMapContainer';
-```
-
-This makes the import consistent with the rest of the codebase (20+ files in this addon use `@eeacms/volto-cca-policy/...` imports). The existing test mock path (`@eeacms/volto-cca-policy/components/theme/Widgets/GeolocationWidgetMapContainer`) will now match in **both** webpack and Jest environments. No test file changes needed.
-
----
-
-#### Option B: Mock both paths in the test file
-
-If changing the source code is not desired, mock **both** the relative and absolute paths in the test:
-
-**File: `src/components/theme/Widgets/GeolocationWidget.test.jsx`**
-
-Replace:
-
-```js
-jest.mock(
-  '@eeacms/volto-cca-policy/components/theme/Widgets/GeolocationWidgetMapContainer',
-);
-```
-
-With:
-
-```js
-const MapContainerMock = () => <div id="map-container-mock" />;
-
-// Mock the relative path (what Jest resolves):
-jest.mock('./GeolocationWidgetMapContainer', () => MapContainerMock);
-
-// Mock the absolute path (what webpack resolves — belt and suspenders):
-jest.mock(
-  '@eeacms/volto-cca-policy/components/theme/Widgets/GeolocationWidgetMapContainer',
-  () => MapContainerMock,
-);
-```
-
-**Why Option A is preferred:**
-- One-line source code change, zero test changes.
-- The relative import `./GeolocationWidgetMapContainer` is the **only** relative import to a sibling file within this addon's component tree. Every other internal import in `volto-cca-policy` uses the `@eeacms/volto-cca-policy/...` convention.
-- Fixes the root cause (import inconsistency) rather than working around it in every test file.
-- The existing test mock already targets the correct absolute path — it just never matched because of the relative import in the source.
-
----
-
-## Problem 3 & 4: Timezone-dependent snapshots — EventView.test.jsx, CcaEventView.test.jsx
-
-### Symptom
-
-```
-- Snapshot  - 2
-+ Received  + 2
-
-      <span className="start-time">
--       3:20 PM
-+       6:20 PM
-      </span>
-```
-
-The snapshots expect `3:20 PM` but the test produces `6:20 PM` (a 3-hour offset = UTC vs EEST).
-
-### Root Cause
-
-The test data uses UTC timestamps (e.g., `'2019-06-23T15:20:00+00:00'`). The `EventDetails` component (from `@eeacms/volto-cca-policy/helpers`) formats these dates using JavaScript's built-in `Date` methods, which convert to the **local timezone**. The snapshots were recorded on a machine in UTC (or a timezone with offset 0), but the current test machine is in EEST (UTC+3).
-
-The snapshots contain:
-- `3:20 PM` for `15:20:00+00:00` — correct in UTC
-- `4:20 PM` for `16:20:00+00:00` — correct in UTC
-
-On EEST, these render as `6:20 PM` and `7:20 PM` respectively.
-
-### Proposed Fix
-
-Set `TZ=UTC` for the Jest process so date formatting is deterministic and matches the snapshots. This is done via the `TZ` environment variable, which is the standard, cross-platform way to control timezone in JavaScript tests.
-
-Two approaches (pick one):
-
-**Approach A — Makefile target (recommended):**
-
-Modify the `test` target in `frontend/Makefile` to set `TZ=UTC`:
-
-```makefile
-test: ## Run Jest tests for Volto add-on
-	TZ=UTC RAZZLE_JEST_CONFIG=$(filter-out $@,$(MAKECMDGOALS))/jest-addon.config.js yarn test $(filter-out $@,$(MAKECMDGOALS))
-```
-
-This is the cleanest approach because:
-- It applies to ALL addon tests consistently, preventing the same issue in other addons.
-- No changes needed in individual test files.
-- `TZ=UTC` is the standard approach for timezone-independent tests in CI environments.
-
-**Approach B — jest.setup.js (if Approach A is not preferred):**
-
-Add to `jest.setup.js` (at the top, before any imports that might use Date):
-
-```js
-// Ensure deterministic timezone for snapshot tests
-process.env.TZ = 'UTC';
-```
-
-**Why this approach:**
-- `TZ=UTC` is the established convention for deterministic date formatting in tests.
-- Does not modify the component code or test data.
-- Does not require updating snapshots — the tests will produce the same output as the recorded snapshots.
-- Solves the problem for any future tests that render dates.
-
----
-
-## Summary of Changes
-
-### Option A (recommended — fix source import)
-
-| File | Change | Lines |
-|------|--------|-------|
-| `jest-addon.config.js` | Add `'^node:crypto$': 'crypto'` to `moduleNameMapper` | +1 |
-| `src/components/theme/Widgets/GeolocationWidget.jsx` | Change `import ... from './GeolocationWidgetMapContainer'` → `import ... from '@eeacms/volto-cca-policy/components/theme/Widgets/GeolocationWidgetMapContainer'` | 1 line |
-| `frontend/Makefile` (root) | Add `TZ=UTC` to the `test` target | +1 |
-
-### Option B (mock both paths in test)
-
-| File | Change | Lines |
-|------|--------|-------|
-| `jest-addon.config.js` | Add `'^node:crypto$': 'crypto'` to `moduleNameMapper` | +1 |
-| `src/components/theme/Widgets/GeolocationWidget.test.jsx` | Mock both `./GeolocationWidgetMapContainer` and `@eeacms/.../GeolocationWidgetMapContainer` | ~6 lines |
-| `frontend/Makefile` (root) | Add `TZ=UTC` to the `test` target | +1 |
-
-**No changes needed to:**
-- `jest.setup.js` — the existing setup (with `thunk` middleware) is correct.
-- `EventView.test.jsx` or `CcaEventView.test.jsx` — the snapshots are correct (UTC), the timezone environment is the fix.
-- Any snapshot files — once `TZ=UTC` is set, they will match.
-- `GeolocationWidget.test.jsx` (Option A only) — the existing absolute-path mock already works once the source import is aligned.
-
-## What the Previous AI Agent Did Wrong
-
-The previous attempt made these changes (now stashed/discarded):
-
-1. **`jest.setup.js` — massive rewrite:** Mocked `uuid`, `redux-mock-store`, `useLazyLibs` globally; added `lazyBundles`/`loadables` config; switched to CommonJS `require()`. This was overly invasive — it changed the global test environment for ALL 61 test suites, introducing risk of masking real issues.
-
-2. **`EventView.test.jsx` and `CcaEventView.test.jsx`:** Removed the `jest.mock('Loadable')` + `beforeAll(__setLoadables())` pattern. This was counterproductive — the Loadable mock is the established pattern used by 19+ test files across the addons. Removing it doesn't fix the timezone issue at all.
-
-3. **`GeolocationWidget.test.jsx`:** Added `thunk` middleware to the local `configureStore()` call. Unnecessary — `jest.setup.js` already configures `configureStore([thunk])` globally. Also changed the mock path to `./GeolocationWidgetMapContainer` which fixes the Jest-side resolution but doesn't address the root cause: the source code uses a relative import where the rest of the codebase uses absolute `@eeacms/...` imports, creating a webpack/Jest resolution mismatch.
-
-4. **Created `src/crypto-mock.js`:** An unnecessary file when `moduleNameMapper: 'node:crypto' -> 'crypto'` solves it in one line.