docs: document country name matching in region maps

[igorlukanin]

Summary

Region maps join a query dimension to the boundary data by name or ISO code, and the World Countries boundaries use long-form names — so United States in a user's data did not match the United States of America polygon. That join is now tolerant of alternate spellings, and this documents the behavior.

Added a Country name matching section under Region map covering what resolves (long forms, endonyms, abbreviations, both ISO code properties, in either direction), the two guarantees worth knowing — matching is exact rather than approximate, and bare 2-letter codes only count as country codes when Property is set to an ISO code property — and that this applies to World countries only, not US states or Custom.

Test plan

• Prose-only change to an existing page; no new files, links, or frontmatter
• CI must pass

[claude]

Claude finished @igorlukanin's task in 1m 38s —— View job

---

Review complete — docs-only change, no blockers. 3 findings: 2 medium, 1 low (all inline).

Full review

• Read PR diff (git diff origin/master...HEAD)
• Read the full page for context and consistency
• Check conventions against docs-mintlify/CLAUDE.md and root CLAUDE.md
• Check for existing/stale review threads (none — nothing to resolve or dedupe against)
• Post review

Scope

Prose-only addition of one H3 section to an existing page in docs-mintlify (the active docs site) — 8 added lines, no new files, no docs.json change needed, no frontmatter change, no code. The usual code-review axes (security, performance, error handling, test coverage) don't apply here; the applicable axis is documentation accuracy and consistency.

What's good

• Correct site (docs-mintlify, not the deprecated /docs), correct heading level (H3 under the existing Region map H2), no stray H1.
• Follows the "edit an existing page, don't create one" guidance in docs-mintlify/CLAUDE.md, and stays concise — three paragraphs, no padded Overview/Best-practices scaffolding.
• Documents the negative cases, which is the part users actually need: exact-not-fuzzy matching, and the explicit "World countries only" scope limit for US states / Custom. Stating what doesn't resolve is what keeps this section from becoming a support ticket.
• Bold UI labels (Property, World countries, Custom) match how the rest of the page refers to settings-panel controls.

Findings

#	Severity	File:line	Issue
1	Medium	map.mdx:72-74	Paragraphs 1 and 2 contradict each other on US: para 1 calls US unconditionally interchangeable with United States, para 2 says bare 2-letter codes only count when Property is an ISO code property
2	Medium	map.mdx:78	The new H3 is inserted above the pre-existing choropleth-gradient paragraph, so that paragraph now renders inside the Country name matching subsection instead of the Region map intro
3	Low	map.mdx:74	colouring — British spelling; every other instance in this file and in docs-mintlify prose is American (colored, colors, Default color)

Details and suggested edits are in the inline comments.

Minor notes (not worth inline threads)

• Line 76: "must match the chosen Property exactly (ignoring case and surrounding whitespace)" is mildly self-undercutting — "exactly" then two exceptions. "must match the chosen Property, ignoring case and surrounding whitespace" reads cleaner, but this is taste.
• The DE example is well chosen (state code that collides with a country code), though it leans on the reader knowing DE is Delaware. Fine as is.

What I could not verify

The behavior being documented lives in the frontend/chart implementation, which isn't in this repo — rg for ISO3166 / world countries matches only this .mdx. I reviewed the section for internal consistency, conventions, and clarity, but I can't confirm the claims against the matching code: specifically whether an Alpha-3 ISO code property is exposed by the World countries source (para 1 promises 2- and 3-letter, while the Property example list at line 62 shows only ISO3166-1-Alpha-2), and whether reverse matching (name in data, code as Property) behaves as described. Someone with access to the implementation should sanity-check those two.

I did not run the Mintlify dev server or a linter — this is a prose-only .mdx edit with no components, links, or frontmatter touched, so there is nothing for either to catch beyond what CI already runs.

• [Branch](https://github.com/cube-js/cube/tree/igor/cub-3549-document-country-name-matching)

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Jul 29, 2026, 10:48 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟡 Building	–	Jul 29, 2026, 10:47 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @igorlukanin's task in 46s —— View job

---

Re-review after c16cc12 — all 3 prior findings fixed, no new issues. Approve-equivalent (docs-only).

Full review

• Read the updated page (map.mdx) after the fix commit
• Verify each of the 3 prior findings
• Check for stale review threads to resolve (all 3 already auto-resolved as outdated)
• Look for new issues introduced by the fixes
• Post updated review

Verification of prior findings

#	Prior issue	Status
1	Para 1 vs para 2 contradiction on US	✅ Fixed — US dropped from the interchangeable list at map.mdx:74; para 2 (map.mdx:76) now introduces it as "Bare 2-letter codes such as US…". The two paragraphs no longer disagree.
2	H3 inserted above the choropleth-gradient paragraph	✅ Fixed — the palette sentence is back in the Region map H2 intro at map.mdx:70, with ### Country name matching starting at map.mdx:72.
3	colouring British spelling	✅ Fixed — now coloring at map.mdx:76.

Bonus: the Alpha-3 gap I flagged as an aside is closed too — map.mdx:62 now lists ISO3166-1-Alpha-3 alongside ISO3166-1-Alpha-2, so the Property list and the "2- and 3-letter ISO code properties" claim at map.mdx:74 line up. The author confirmed the World countries source exposes both.

Thread housekeeping

All three of my threads were already resolved (GitHub marked them outdated once the lines moved) — nothing left to resolve, and no duplicate inline comments to skip.

New issues

None. The rewrite is a clean subtraction plus a move — no new claims were introduced, and the sentence flow reads correctly with US deferred to the second paragraph. Section structure is now: H2 intro (requirements list → allowed-properties note → auto-pick → palette) → ### Country name matching → ### Custom GeoJSON, which is consistent with how Point map is broken up earlier on the page.

Standing caveat (unchanged)

The matching behavior itself lives outside this repo, so I still can't verify the claims against the implementation — reverse matching (name in data, code as Property) in particular. The author's confirmation on Alpha-3 covers the one piece I could point at concretely. This is a prose-only .mdx change with no components, links, or frontmatter touched, so the code-review axes in the review config (security, performance, error handling, test coverage) don't apply; the Mintlify preview build is the relevant check and it's green.

• Branch •