URL state: open a claim and carry the comparison filters (#177)

[PavelMakarchuk]

Closes #177.

Summary

• ?view=validation&claim=<claim_id> opens that claim's row, scrolls it to the centre and focuses it.
  • If the link has no country, or the wrong one, the app switches to the claim's country after the feed loads, with replaceState, so Back does not loop.
  • An unknown id opens nothing.
  • Opening or closing a row writes claim back to the URL, so a copied link opens the same claim.
• ?view=scorecard&program=snap&metric=participation_rate&geography=VT sets the comparison filters on load. Filter changes write back under the existing history rules: replaceState within a view, pushState for a new view or country.
  • Defaults stay out of the URL.
  • "Reset filters" and leaving the view clear the filter parameters.
• Validation. Each parameter travels only with its own view. Values outside their vocabularies are ignored, and the next write removes them:
  • claim is hex.
  • program and metric must be in the table's own option lists. These moved to filters.ts, so the parser and the table share them.
  • geography is a two-letter code or states.
  • '' and __empty__ never become filter values, so the Select sentinel keeps its meaning.
• view and country are written exactly as before; view=scorecard is kept for old links.

On the App v3 side, only scorecardEntryUrl / claimScorecardUrl need to change.

Known limits

• Only program, metric and geography go in the URL. Subgroup and status stay in the history entry, as the issue scoped it.
• Claims in the UK fiscal-event archives (the PMD scores, loaded per event) cannot be opened by id without fetching every archive. If App v3 links to them, this needs a claim-to-event index in the feed or an event= parameter first.
• If country= and the claim disagree, the claim's country wins.

Test plan

• bun test src: 61 pass (41 before), with new urlState.test.ts round trips, invalid values and claim selection, and populations.test.ts claimCountry
• bun run lint (only the 2 existing only-export-components warnings)
• bun run build
• Browser check: a UK claim link with no country switched country and opened the row; Back and Forward, filter links, reload and Reset worked; an unknown id was harmless; the console had no errors

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated
policyengine-scorecard	Ready	Preview	Oct 15, 2026 6:33pm UTC