[anth-volk]

Fixes #1446
Fixes #1432

This PR combines #1433 (including the fix for Pavel's review, which places a map's areas from the layout all or none) and #1447, and supersedes both. Their commits are cherry-picked onto main with -x, in order, so each commit names the one it came from. #1447 was written on top of #1436, which removes the app's handling of the results' x and y. #1436 isn't included, so #1447's commits are adapted to main as listed below. #1436 will be rebuilt on top of this PR.

The original work in both PRs was done red-green: each commit's tests were written first and seen failing before the code.

What changes

v2's hex maps placed from the layout files (#1433)

v2's constituency and local-authority hex maps place each area from the app's layout files, through placeOnUKHexLayout, as v3's do, on the tiled grid. Placement is all or none. If the layout has no position for even one of a result's areas (an area with no code, or a pre-2023 local-authority code), every area keeps its result's x and y, on the untiled grid. This fixes v2's half-hex row offsets for constituencies, and the five local authorities the Public API stacks at (0, 0). A tiled map now also keeps its top and bottom hexagons inside its frame. #1433's description has the details.

UK areas withheld by disclosure control shown as not reported (#1447)

For a level from a local-area breakdown, which is disclosure-controlled, the v3 hex map and the four v2 hex charts now draw every area of the report's region:

• all 650 constituencies and 361 local authorities for a UK-wide report;
• the nation's areas for a nation's report.

An area that the result leaves out:

• is drawn in its place with grey stripes on the map's background and a grey edge, where a valued hexagon's edge is the background colour, so no colour on the scale resembles it;
• reads "name: Not reported" in its tooltip;
• has no value, so it isn't in the colour range or in v3's rankings and area finder, and can't be selected.

Withheld areas are drawn only on the tiled grid. A result that keeps its own positions (any area uncoded or missing from the layout) draws only its own areas, as does a saved level.

The note under the maps now reads "N of M constituencies are not reported" (or local authorities), so the map, its tooltips and the note use the same term.

The geographic map

UKAreaChoroplethMap already drew every boundary. A withheld boundary keeps its solid gray[300] fill; its tooltip now reads "Not reported" instead of "Not published". In v3 that text appears only on the level the breakdown supplied, and a saved level's boundary without a result reads "No data". gray[300] sits between two stops on the scale's grey side, so hatching the geographic map too would be a small follow-up.

How

• HexagonalMap takes missingAreas (areas it places without a value) and missingAreaText. It draws them on the same grid as the valued areas, hatched with an SVG pattern whose stripes are never closer than 4 SVG units, and fits its frame to them as well.
• withheldUKHexAreas(level, points, region) in ukHexLayout.ts lists the region's layout codes that the result lacks, each at its layout position. It lists none when any area has no code or a code outside the region's layout, or when the region is neither the UK nor a nation.
• Withheld areas are named from two new files beside the layouts, constituency_names_2024.json and local_authority_names_2023.json, built from the boundary files' PCON24NM and LAD23NM and checked against them by ukBoundaryFiles.test.ts. They add about 34 KB, before compression.

Adapted for main

On main, areas still carry x and y, HexagonalMap still has its untiled grid and tiled option, and #1436's note on areas the layout can't place never existed. Each adapted commit's message says what changed:

1. Say "not reported"…: the conflicts were test imports of Remove the app's handling of x and y on UK area results #1436's layout-note fixture, and a v3 section test, which keeps main's hexagon check with the new wording.
2. Draw areas without a value…: missing areas take the same grid as the valued areas, through a positionOnGrid helper shared by both. They are pointy-topped when tiled and fitted with the tiled reach. The tests draw them on the tiled grid, as the UK maps do.
3. List the areas of a report's region…: withheldUKHexAreas reads only each point's code, since main's points carry x and y. Its documentation says it lists none whenever placeOnUKHexLayout falls back to the result's positions.
4. Draw UK areas disclosure control withheld…: v3 and the four v2 charts pass hexMap.points as before, and compute withheld areas only when hexMap.tiled is true. v3's test of a breakdown area without a code checks that the map stays untiled with no withheld areas, instead of checking Remove the app's handling of x and y on UK area results #1436's note. Its fixture is added here.
5. Read "Not reported" only on a breakdown level's v3 geographic map: applied unchanged.
6. Keep a withheld hexagon's hatching distinct…: its two tests draw on the tiled grid.
7. Say in the hex map's docs…: the README keeps the sentence that withheld areas are drawn only on the tiled grid.

None of the adaptations needed behaviour beyond the original commits, so there are no new red-green commits.

Commits

From #1433: d2e72f8d (from 49adbc21), d130de1b (8263784e), 3a48e68e (94f42033), c6f816ff (54a674ee), 71dc49ef (d2af1321) and 07d096ca (f4e720cc).

From #1447: 41cbbeb3 (from 67c46a99), b1c66a38 (211701e9), 4dd70841 (bc4dade1), b3f8cd4b (e3ecff7a), f8a4d1f8 (78b1e8ed), 7a10d52d (184178f5) and 9ec3bf81 (dac1a6d9).

Then 08f9cb07 rewraps the documentation on HexagonalMap's missingAreas prop.

Review

A first review-code round on this PR found no bugs. It noted the overlong documentation row fixed in 08f9cb07, and that the tiled-only rule is checked both in withheldUKHexAreas and in the callers, deliberately. #1433 and #1447 were each reviewed before.

Three more review-code rounds then ran on the whole PR at 08f9cb07. None found a bug, so there are no fix commits.

• Round 1 read the placement, the withheld-area rule and its v2 and v3 callers, nation and UK-wide regions, saved and uncoded results, tooltips, selection, the area finder, the colour range, downloads and performance. Code-quality notes:

  • the four v2 charts repeat the same placement and withheld-area block, which a shared hook could hold;
  • HexMapMissingArea documents its x and y as 0-based, though layout positions are negative;
  • the nation tests use only Wales.

• Round 2 checked:

  • the hex map's geometry with missing areas: one grid for both sets, the frame fitted to both, no two hexagons in one place, all clear of the colour bar;
  • the export path: html-to-image copies the hatching pattern with the map;
  • zoom, the v2 Migration page's wiring, and every fixture's codes, names and positions against the data files.

  Code-quality notes:

  • ukNationFromRegion accepts only country/* regions, not the older forms that normalizeRegionCode maps (england, uk-wales). A report on such a region gets no hatching and the uncounted note, just as its geographic map already gets no nation focus.
  • A withheld hexagon's edge is gray[400], one of the scale's stops. How it reads on a narrow screen needs a look in a browser.

• Round 3 rendered realistic breakdowns in a scratch test, not committed:

  • England: 543 constituencies;
  • Scotland: 32 local authorities;
  • Northern Ireland: 18 constituencies and 11 local authorities, under both country/ni and country/northern_ireland;
  • UK-wide: 600 of 650 constituencies, and 361 local authorities.

  Each map drew every area of its region, with as many hatched hexagons as the note counts, no NaN coordinates, and every hexagon inside the frame. A level whose withheld count is unknown still draws its withheld areas, beside the uncounted note. A git range-diff against Show UK areas withheld by disclosure control on the hex maps as not reported #1447's commits shows only the adaptations listed above, and all 60 of Show UK areas withheld by disclosure control on the hex maps as not reported #1447's tests are here. Code-quality note: the UK-wide note counts against the region list by name, and the hex map against the layout by code. They agree now that the Public API lists 361 local authorities, but nothing checks that they stay in step.

Two review points fixed

Two code-quality points from the review rounds are fixed, each red-green: the tests were written first and seen failing, then the code, committed together.

1. One function places each hex map and its withheld areas (f7575a8d). The four v2 charts and v3's UKLocalAreaMaps each placed their areas from the layout and then worked out the withheld ones in a second step. placeUKHexMap(level, points, { disclosureControlled, region }) in ukHexLayout.ts does both: placeOnUKHexLayout's all-or-none placement and, for a disclosure-controlled level on the tiled grid, the withheld areas. All five maps call it. Its unit tests failed first because it didn't exist. The chart and v3 tests pass unchanged.
2. The note counts withheld areas the way the map draws them (e83c161e).
   • Before: for a UK-wide report, the note under the maps counted withheld areas by name against the Public API's region list. For a nation's report it counted by code against fixed per-nation totals. The hex map hatched the region's layout codes that the result lacks, so the two could disagree. With Ards and North Down published, the note read "1 of 3 local authorities is not reported" against the tests' trimmed region list while the map hatched 359. A region list from before Request UK local-area breakdowns, fix the Northern Ireland region name, and update .py to 6.10.0 policyengine-api#4024 gave no count at all.
   • Now: withheldUKAreaCodes holds one rule, each published area's ONS code against the layout's areas of the report's region, and both withheldUKHexAreas and countWithheldUKAreas follow it. A result that can't be matched by code (an area without a code, or one outside the region's layout) gives no count, as a nation's report did before.
   • Region list removed: the count no longer reads the region list. useUKLocalAreaOutput no longer calls useRegions. withheldUKAreasOf and countWithheldUKAreas lose their region-list and name arguments, and the tests no longer mock the region list. UK_AREA_COUNTS_BY_NATION had no other use, so it moves into the test fixture that checks the layout's per-nation counts.
   • Tests: new v3 and v2 tests check that, for a UK-wide breakdown that publishes Ards and North Down, the note's count equals the number of hatched local authorities (359). A unit test checks that the count equals withheldUKHexAreas' length. The existing note tests now expect counts against the layout, for example "649 of 650 constituencies" and "360 of 361 local authorities". A local authority published under a name the region list doesn't use is now counted.

One review-code round on these two commits found no bugs, so there was no second round. Its code-quality notes: the layouts README doesn't yet say that the note counts by the map's rule, and withheldUKHexAreas still guards a position lookup that can't be null.

Pavel's review

Pavel reviewed the PR at e83c161e. Five of his points are fixed. The first three are red-green: the test was written first and seen failing for the expected reason, then the code, committed together.

1. Hatching blends into flat grey on a phone (e4e754d9). The 4-unit minimum gave 4 pixels only on a map drawn at one pixel per SVG unit. v2's charts draw a fixed 600-unit viewBox, so at 375 pixels wide the UK-wide constituency map's stripes sat 2.5 pixels apart. HexagonalMap now measures its rendered width whenever it has missing areas, and sets the minimum at 4 screen pixels. The screen scale is the rendered width over the viewBox width, never more than one, since the SVG is as tall as its viewBox. A v2 chart test and a HexagonalMap test, each at 375 pixels, failed at 2.5 pixels and now pass.
2. Stripes widen with zoom on v3 (3fbc1ec9). The pattern sits inside the zoomed layer, so its stripes scaled with the zoom: at zoom 20 they sat 80 pixels apart where they sat 4 at zoom 1. The pattern's size is now divided by the zoom factor, so the stripes keep their spacing on screen. A test zooms from 1 to 20 and compares the spacing; it failed at 80 against 4.
3. Names of withheld hexagons come from the boundary files (4a674688). A test now checks that both name files equal the app's copies of .py 6.10.0's area lists (constituencies_2024.csv, local_authorities_2023.csv), code by code. The names match, so it passes. Run once against copies with one name changed in each file (not committed), it failed and named both differences.
4. The position ? … : [] guard can't fail (4203dfd7). It is removed: withheldUKHexAreas reads each withheld code's position from the layout directly, through a gridPosition helper that ukHexPosition shares. A refactor; the existing tests pass unchanged.
5. "0-based" coordinates (867af2c1). HexMapDataPoint's and HexMapMissingArea's x and y are now documented as able to be negative. Documentation only.

Not changed, as Anthony decided:

• Every absent area reads as withheld (his first point). A follow-up will have the sim API return the codes it withheld, so the app can tell a withheld area from one that is missing for another reason.
• The name files load with the v2 tabs. They stay a static import.
• A UK-wide breakdown without area codes. The breakdown contract requires a code on every record, so that case can't arise.

One review-code round on these five commits found no bugs. Its code-quality notes: the tests' on-screen spacing helper uses the same width-over-viewBox rule as the code, so it wouldn't catch a mistake in that rule; and the phone test covers one of the four v2 charts, which all share HexagonalMap's spacing.

Testing

• Focused vitest runs on Node 26 of all 13 test files the PR touches, plus the migration subpage, the local-area output hook and the breakdown adapter: 340 tests pass. make format, make lint and make typecheck pass.
• After the three review rounds, at 08f9cb07 on Node 26.10: the 13 touched test files pass (271 tests). make format changes nothing, and make lint and make typecheck pass.
• After the two fixes, at e83c161e on Node 26.10: the 16 test files the PR touches pass (344 tests). make format changes nothing, and make lint and make typecheck pass.
• After Pavel's review, at 867af2c1 on Node 26.10: the 16 test files the PR touches pass (349 tests). make format changes nothing, and make lint and make typecheck pass.
• Not checked in a browser.

To check by hand

1. On a UK report with constituency results, open the v2 constituency tab and choose Hex grid. The hexagons should be pointy-topped and touching, in the same arrangement as the v3 report's Local areas hex map.
2. On the v2 local-authority tab, Cumberland, Westmorland and Furness, and North Yorkshire should be three separate hexes.
3. On a report whose local-area breakdown has run, the hex maps should show every constituency and local authority, with the withheld ones striped, grey-edged and reading "Not reported" on hover. The note should give the same number of areas as are striped.
4. On a phone, or a narrow window, the v2 hex charts' withheld hexagons should show stripes, not a flat grey. On v3, zooming in should keep the stripes as close together as they are at the start.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
policyengine-calculator-next	Ready	Preview	Oct 27, 2026 8:38pm UTC
policyengine-website	Ready	Preview	Oct 27, 2026 8:38pm UTC

[PavelMakarchuk]

Thanks @anth-volk. I reviewed this at e83c161e. CI is green, and I found no blocking bugs. The all-or-none placement fixes the problem from my #1433 review. Placing the hex maps and counting the note with one rule (placeUKHexMap, withheldUKAreaCodes) is a good change.

Three points that I think need a fix or an answer before merge:

1. Every absent area reads as withheld by disclosure control (ukHexLayout.ts:117)
For a disclosure-controlled level, every layout area that the result does not return is hatched "Not reported", and the note says the disclosure rules are the cause. An area can be absent for another reason. For example, if a UK-wide breakdown has no Northern Ireland areas because those runs fail (PolicyEngine/policyengine-sim-api#858), the map labels them as withheld. Before this PR, only the note's count had this problem. Now the map shows it too. Can the breakdown tell the app which areas it withheld, or can we confirm that absent always means withheld?

2. The v2 hatching blends into flat grey on a phone (HexagonalMap.tsx:317)
The 4-unit minimum spacing gives 4 px only when one SVG unit is one pixel. The v2 hex charts don't use fillWidth, so they draw the fixed 600-unit viewBox. At 375 px wide that is about 0.57 px per unit, so the stripes are about 2 px apart. This is the flat grey that the comment wants to prevent, and it is on the scale's grey arm. You could set the minimum in screen pixels (use the measured width ÷ svgWidth), or turn on fillWidth for the v2 charts.

3. The stripes get larger with zoom on v3 (HexagonalMap.tsx:575)
The pattern is userSpaceOnUse inside the zoom layer. At zoom 20, a withheld hexagon shows only one or two wide bands. Dividing the pattern size by zoom.view.k would keep the stripe density the same at all zoom levels.

Smaller points (non-blocking):

• ukHexLayout.ts:148: a withheld hexagon gets its name from the boundary files, but a valued hexagon, the rankings and the finder get their names from the API. Nothing checks that the two sources stay the same.
• ukHexLayout.ts:11: the two name files (about 34 KB) now load with the v2 constituency and local-authority tabs, also for saved results that never need them. A dynamic import would prevent this.
• ukLocalAreaBreakdownAdapter.ts:158: a UK-wide breakdown with no area codes gave a count by name before, and now gives the uncounted note. This is fine if the breakdown always sends codes.
• ukHexLayout.ts:147: the position ? … : [] guard can't fail, because the codes come from the layout's own keys.
• HexMapDataPoint.ts:28: the comment says x and y are "0-based", but layout positions can be negative.

I haven't checked it in a browser yet.

[anth-volk]

Thanks @PavelMakarchuk. Changes are at 867af2c1.

1. Absent areas read as withheld. You're right: the breakdown doesn't say which areas it withheld, so the app infers it from absence. We'll fix that in a follow-up, where the sim API returns each level's withheld codes (the areas it estimated minus those it published), and the app hatches only those and shows any other missing area as "No data". The risk is low until then: PolicyEngine/policyengine-sim-api#858 is closed, a breakdown is one run (so a failure fails the whole result rather than dropping part of it), and every record must carry its code.

2. Hatching on a phone. Fixed in e4e754d9: the minimum gap is now 4 screen pixels, from the rendered width over the viewBox width. A test renders a v2 chart 375 px wide.

3. Stripes widening with zoom. Fixed in 3fbc1ec9: the pattern's size is divided by the zoom factor, tested from zoom 1 to 20.

Smaller points:

• Names from two sources: 4a674688 adds a test that both name files match the app's copies of .py's area lists, code by code.
• The name files loading with the v2 tabs: left as they are. A dynamic import would make placement asynchronous for a small saving.
• UK-wide breakdowns without codes: the contract requires constituency_code and local_authority_code on every record, so this can't arise.
• The guard: removed in 4203dfd7.
• "0-based": corrected in 867af2c1.

We haven't checked it in a browser yet either.