@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/components/region-theme/countryProfile.ts

@@ -0,0 +1,110 @@
+// CountryProfileData format, validation and a registry (spec:
+// wave-4/country-profile-data.md). Currency symbol, position, separators and
+// precision are never stored: they come from Intl for the profile's locale.
+import type { SourceCitation } from './format'
+
+export interface CountryProfile {
+  code: string
+  names: { en: string; local: string }
+  languages: Array<{ tag: string; name: string; official: boolean }>
+  locale: { default: string; dateStyle?: 'full' | 'long' | 'medium' | 'short' }
+  currency: { code: string }
+  address: {
+    /** Ordered lines of field keys. */
+    template: string[][]
+    required: string[]
+    postalCodePattern?: string
+  }
+  tax?: { consumptionTaxName?: string; businessIdName?: string; personalIdName?: string }
+  map: { geometryKey: string; subdivisionProperty: string; projection: 'mercator' | 'equal-area-composite' }
+  /** Country code of the matching RegionThemeData entry, when there is one. */
+  regionTheme?: string
+  sources: SourceCitation[]
+  version: string
+}
+
+/** Emoji flag from the two regional-indicator letters of the code (computed, never stored). */
+export function flagEmoji(code: string): string {
+  const up = code.toUpperCase()
+  if (!/^[A-Z]{2}$/.test(up)) return ''
+  return String.fromCodePoint(...[...up].map((ch) => 0x1f1e6 + ch.charCodeAt(0) - 65))
+}
+
+function isLocale(tag: string): boolean {
+  try {
+    return Intl.getCanonicalLocales(tag).length === 1
+  } catch {
+    return false
+  }
+}
+
+function isCurrency(code: string): boolean {
+  if (!/^[A-Z]{3}$/.test(code)) return false
+  const listed = (Intl as { supportedValuesOf?: (key: string) => string[] }).supportedValuesOf?.('currency')
+  if (listed) return listed.includes(code)
+  try {
+    new Intl.NumberFormat('en', { style: 'currency', currency: code })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Throws naming the field on the first problem. */
+export function validateCountryProfile(p: CountryProfile): void {
+  const at = typeof p?.code === 'string' ? p.code : '??'
+  const fail = (field: string, detail: string): never => {
+    throw new Error(`CountryProfileData ${at}: ${field} ${detail}`)
+  }
+  if (!/^[A-Z]{2}$/.test(p.code ?? '')) fail('code', 'must be an ISO 3166-1 alpha-2 code')
+  if (!p.names?.en?.trim() || !p.names?.local?.trim()) fail('names', 'need en and local')
+  if (!Array.isArray(p.languages) || !p.languages.length) fail('languages', 'must list at least one language')
+  for (const l of p.languages) if (!isLocale(l.tag)) fail('languages[].tag', `"${l.tag}" is not a BCP 47 tag`)
+  if (!isLocale(p.locale?.default ?? '')) fail('locale.default', 'must be a BCP 47 tag')
+  if (!isCurrency(p.currency?.code ?? '')) fail('currency.code', 'must be an ISO 4217 code')
+  if (!Array.isArray(p.address?.template) || !p.address.template.length) fail('address.template', 'must have at least one line')
+  const keys = new Set(p.address.template.flat())
+  for (const r of p.address.required ?? []) if (!keys.has(r)) fail('address.required', `"${r}" is not in the template`)
+  if (p.address.postalCodePattern !== undefined) {
+    try {
+      new RegExp(p.address.postalCodePattern)
+    } catch {
+      fail('address.postalCodePattern', 'is not a valid pattern')
+    }
+  }
+  if (!p.map?.geometryKey || !p.map.subdivisionProperty) fail('map', 'needs geometryKey and subdivisionProperty')
+  if (!Array.isArray(p.sources) || !p.sources.length) fail('sources', 'must cite at least one source')
+  const cited = new Set(p.sources.map((s) => s.field))
+  const groups = ['code', 'names', 'languages', 'locale', 'currency', 'address', 'map']
+  if (p.tax) groups.push('tax')
+  for (const g of groups) if (!cited.has(g)) fail('sources', `has no citation for "${g}"`)
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(p.version ?? '')) fail('version', 'must be an ISO date')
+}
+
+const profiles = new Map<string, CountryProfile>()
+
+/** Validates and stores a profile (replaces an earlier one with the same code). */
+export function registerCountryProfile(profile: CountryProfile): void {
+  validateCountryProfile(profile)
+  profiles.set(profile.code, profile)
+}
+export const getCountryProfile = (code: string) => profiles.get(code.trim().toUpperCase())
+export const listCountryProfiles = () => [...profiles.values()]
+export const unregisterCountryProfile = (code: string) => void profiles.delete(code.trim().toUpperCase())
+
+/** Money in the profile's default locale and currency, formatted by the platform. */
+export function formatProfileMoney(value: number, profile: CountryProfile): string {
+  return new Intl.NumberFormat(profile.locale.default, { style: 'currency', currency: profile.currency.code }).format(value)
+}
+
+/** Address lines following the profile template; empty fields leave no doubled separators. */
+export function formatProfileAddress(fields: Record<string, string | undefined | null>, profile: CountryProfile, separator = ', '): string[] {
+  return profile.address.template
+    .map((line) =>
+      line
+        .map((k) => (fields[k] ?? '').trim())
+        .filter(Boolean)
+        .join(separator),
+    )
+    .filter(Boolean)
+}

package/src/components/region-theme/data/br-profile.ts

@@ -0,0 +1,41 @@
+// Brazil (BR) country profile. Regenerated from public sources on 2026-09-26.
+// Currency presentation is not stored (derived from pt-BR through Intl).
+import { registerCountryProfile, type CountryProfile } from '../countryProfile'
+
+const RETRIEVED = '2026-09-26'
+
+export const brazilProfile: CountryProfile = {
+  code: 'BR',
+  names: { en: 'Brazil', local: 'Brasil' },
+  languages: [{ tag: 'pt-BR', name: 'português', official: true }],
+  locale: { default: 'pt-BR' },
+  currency: { code: 'BRL' },
+  address: {
+    // Logradouro, número e complemento / bairro / cidade e UF / CEP.
+    template: [['street', 'number', 'complement'], ['district'], ['city', 'state'], ['postalCode']],
+    required: ['street', 'city', 'state', 'postalCode'],
+    postalCodePattern: '^\\d{5}-?\\d{3}$',
+  },
+  tax: { businessIdName: 'CNPJ', personalIdName: 'CPF' },
+  map: { geometryKey: 'br-admin1', subdivisionProperty: 'code', projection: 'mercator' },
+  regionTheme: 'BR',
+  sources: [
+    { field: 'code', citation: 'ISO 3166-1, country code BR', url: 'https://www.iso.org/obp/ui/#iso:code:3166:BR', retrievedOn: RETRIEVED },
+    { field: 'names', citation: 'Unicode CLDR territory names (en: Brazil; pt: Brasil)', url: 'https://cldr.unicode.org/', retrievedOn: RETRIEVED },
+    { field: 'languages', citation: 'Unicode CLDR territory information (official language of BR: Portuguese); Constituição Federal de 1988, art. 13', url: 'https://www.planalto.gov.br/ccivil_03/constituicao/constituicao.htm', retrievedOn: RETRIEVED },
+    { field: 'locale', citation: 'Unicode CLDR locale pt-BR', url: 'https://cldr.unicode.org/', retrievedOn: RETRIEVED },
+    { field: 'currency', citation: 'ISO 4217, currency code BRL (Brazilian real)', url: 'https://www.iso.org/iso-4217-currency-codes.html', retrievedOn: RETRIEVED },
+    { field: 'address', citation: 'Correios, guidance on addressing (logradouro, número, complemento, bairro, cidade, UF, CEP of eight digits)', url: 'https://www.correios.com.br/', retrievedOn: RETRIEVED },
+    { field: 'tax', citation: 'Receita Federal do Brasil: CNPJ (legal entities) and CPF (individuals)', url: 'https://www.gov.br/receitafederal/', retrievedOn: RETRIEVED },
+    { field: 'map', citation: 'Host geometry from Natural Earth admin-1 boundaries (public domain); the library ships none', url: 'https://www.naturalearthdata.com/downloads/10m-cultural-vectors/', retrievedOn: RETRIEVED },
+  ],
+  version: RETRIEVED,
+}
+
+/**
+ * Registers Brazil. Defaults to this module's profile registry; hosts wiring
+ * the Formatters country registry pass its `registerCountry` instead.
+ */
+export function register(target: (profile: CountryProfile) => void = registerCountryProfile): void {
+  target(brazilProfile)
+}

package/src/components/region-theme/data/br.ts

@@ -0,0 +1,80 @@
+// Brazil (BR): first-level subdivisions, the 26 states and the Federal
+// District, and the five IBGE macro-regions. Regenerated from public sources
+// on 2026-09-26 (see `sources`); nothing here comes from any earlier library.
+//
+// Not shipped, on purpose: identity colours (the state flag laws give colour
+// names, not hex values, so any hex would be an invention), label points and
+// the map view (to be computed from public-domain boundaries with
+// `deriveGeometry()`; see ../geometry.ts). The registry works without them.
+import { registerRegionTheme } from '../registry'
+import type { RegionThemeEntry } from '../format'
+
+const RETRIEVED = '2026-09-26'
+
+export const brazilRegionTheme: RegionThemeEntry = {
+  country: 'BR',
+  subdivisionKind: 'state',
+  // ISO 3166-2:BR order (alphabetical by name).
+  subdivisions: [
+    { code: 'AC', name: { local: 'Acre' } },
+    { code: 'AL', name: { local: 'Alagoas' } },
+    { code: 'AP', name: { local: 'Amapá' } },
+    { code: 'AM', name: { local: 'Amazonas' } },
+    { code: 'BA', name: { local: 'Bahia' } },
+    { code: 'CE', name: { local: 'Ceará' } },
+    { code: 'DF', name: { local: 'Distrito Federal', en: 'Federal District' } },
+    { code: 'ES', name: { local: 'Espírito Santo' } },
+    { code: 'GO', name: { local: 'Goiás' } },
+    { code: 'MA', name: { local: 'Maranhão' } },
+    { code: 'MT', name: { local: 'Mato Grosso' } },
+    { code: 'MS', name: { local: 'Mato Grosso do Sul' } },
+    { code: 'MG', name: { local: 'Minas Gerais' } },
+    { code: 'PA', name: { local: 'Pará' } },
+    { code: 'PB', name: { local: 'Paraíba' } },
+    { code: 'PR', name: { local: 'Paraná' } },
+    { code: 'PE', name: { local: 'Pernambuco' } },
+    { code: 'PI', name: { local: 'Piauí' } },
+    { code: 'RJ', name: { local: 'Rio de Janeiro' } },
+    { code: 'RN', name: { local: 'Rio Grande do Norte' } },
+    { code: 'RS', name: { local: 'Rio Grande do Sul' } },
+    { code: 'RO', name: { local: 'Rondônia' } },
+    { code: 'RR', name: { local: 'Roraima' } },
+    { code: 'SC', name: { local: 'Santa Catarina' } },
+    { code: 'SP', name: { local: 'São Paulo' } },
+    { code: 'SE', name: { local: 'Sergipe' } },
+    { code: 'TO', name: { local: 'Tocantins' } },
+  ],
+  macroRegions: [
+    { id: 'north', labelKey: 'region.br.north', codes: ['AC', 'AP', 'AM', 'PA', 'RO', 'RR', 'TO'] },
+    { id: 'northeast', labelKey: 'region.br.northeast', codes: ['AL', 'BA', 'CE', 'MA', 'PB', 'PE', 'PI', 'RN', 'SE'] },
+    { id: 'central-west', labelKey: 'region.br.centralWest', codes: ['DF', 'GO', 'MT', 'MS'] },
+    { id: 'southeast', labelKey: 'region.br.southeast', codes: ['ES', 'MG', 'RJ', 'SP'] },
+    { id: 'south', labelKey: 'region.br.south', codes: ['PR', 'RS', 'SC'] },
+  ],
+  sources: [
+    {
+      field: 'codes',
+      citation: 'ISO 3166-2:BR, subdivision codes of Brazil (ISO 3166 Maintenance Agency); consulted through the public ISO 3166-2:BR listing',
+      url: 'https://www.iso.org/obp/ui/#iso:code:3166:BR',
+      retrievedOn: RETRIEVED,
+    },
+    {
+      field: 'names',
+      citation: 'IBGE, Divisão Territorial Brasileira (official names of the federative units), matching the ISO 3166-2:BR names',
+      url: 'https://www.ibge.gov.br/geociencias/organizacao-do-territorio/estrutura-territorial/23701-divisao-territorial-brasileira.html',
+      retrievedOn: RETRIEVED,
+    },
+    {
+      field: 'macroRegions',
+      citation: 'IBGE, Divisões Regionais do Brasil: the five Grandes Regiões (Norte, Nordeste, Centro-Oeste, Sudeste, Sul); membership cross-checked on the public summary at https://en.wikipedia.org/wiki/Regions_of_Brazil',
+      url: 'https://www.ibge.gov.br/geociencias/organizacao-do-territorio/divisao-regional/15778-divisoes-regionais-do-brasil.html',
+      retrievedOn: RETRIEVED,
+    },
+  ],
+  version: RETRIEVED,
+}
+
+/** Registers Brazil in the default registry (never on import). */
+export function register(): void {
+  registerRegionTheme(brazilRegionTheme)
+}

package/src/components/region-theme/format.ts

@@ -0,0 +1,120 @@
+// RegionThemeData format and its validation (spec: wave-4/region-theme-data.md).
+// Values in data modules are identity facts from public sources, never UI tokens.
+import type { SubdivisionKind } from '../../internal/messages/charts-geo'
+
+export type { SubdivisionKind } from '../../internal/messages/charts-geo'
+
+export type LonLat = [longitude: number, latitude: number]
+
+export interface SubdivisionRecord {
+  /** Part after the hyphen of the ISO 3166-2 code, upper case. */
+  code: string
+  name: { local: string; en?: string }
+  /** Two colours from the official flag or arms specification; absent when there is none. */
+  identity?: { primary: string; secondary: string }
+  /**
+   * A point inside the polygon for a label. Optional in this library: modules
+   * leave it out until it is computed from public boundary data with
+   * `deriveGeometry()` (see ./geometry.ts); nothing is guessed.
+   */
+  labelPoint?: LonLat
+}
+
+export interface SourceCitation {
+  /** Field group the citation covers: `codes`, `names`, `macroRegions`, `identity`, `labelPoint`, `view`. */
+  field: string
+  citation: string
+  url: string
+  /** ISO date the source was consulted. */
+  retrievedOn: string
+}
+
+export interface RegionThemeEntry {
+  country: string
+  subdivisionKind: SubdivisionKind
+  subdivisions: SubdivisionRecord[]
+  /** Default map view; derived from boundary data like `labelPoint`. */
+  view?: { centre: LonLat; zoomHint?: number }
+  macroRegions?: Array<{ id: string; labelKey: string; codes: string[] }>
+  flagUrlTemplate?: string
+  sources: SourceCitation[]
+  version: string
+}
+
+export const SUBDIVISION_KINDS: readonly SubdivisionKind[] = [
+  'state',
+  'province',
+  'region',
+  'department',
+  'governorate',
+  'prefecture',
+  'county',
+  'voivodeship',
+  'district',
+  'nation',
+]
+
+const HEX6 = /^#[0-9a-f]{6}$/i
+const ALPHA2 = /^[A-Z]{2}$/
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+const SUB_CODE = /^[A-Z0-9]{1,3}$/
+
+export class RegionThemeError extends Error {
+  constructor(
+    readonly country: string,
+    readonly field: string,
+    readonly code: string | undefined,
+    detail: string,
+  ) {
+    super(`RegionThemeData ${country || '??'}: ${field}${code ? ` (subdivision ${code})` : ''} ${detail}`)
+    this.name = 'RegionThemeError'
+  }
+}
+
+const inLon = (v: unknown) => typeof v === 'number' && v >= -180 && v <= 180
+const inLat = (v: unknown) => typeof v === 'number' && v >= -90 && v <= 90
+const isLonLat = (p: unknown): p is LonLat => Array.isArray(p) && p.length === 2 && inLon(p[0]) && inLat(p[1])
+
+/** Throws a RegionThemeError naming the country, field and subdivision on the first problem. */
+export function validateRegionThemeEntry(entry: RegionThemeEntry): void {
+  const c = typeof entry?.country === 'string' ? entry.country : ''
+  const fail = (field: string, detail: string, code?: string): never => {
+    throw new RegionThemeError(c, field, code, detail)
+  }
+  if (!ALPHA2.test(c)) fail('country', 'must be an ISO 3166-1 alpha-2 code in upper case')
+  if (!SUBDIVISION_KINDS.includes(entry.subdivisionKind)) fail('subdivisionKind', `must be one of ${SUBDIVISION_KINDS.join(', ')}`)
+  if (!Array.isArray(entry.subdivisions) || entry.subdivisions.length === 0) fail('subdivisions', 'must list at least one subdivision')
+  const seen = new Set<string>()
+  for (const s of entry.subdivisions) {
+    const code = typeof s?.code === 'string' ? s.code : ''
+    if (!SUB_CODE.test(code)) fail('subdivisions[].code', 'must be the upper-case part after the hyphen of the ISO 3166-2 code', code || undefined)
+    if (seen.has(code)) fail('subdivisions[].code', 'is duplicated', code)
+    seen.add(code)
+    if (typeof s.name?.local !== 'string' || !s.name.local.trim()) fail('subdivisions[].name.local', 'is required', code)
+    if (s.identity !== undefined) {
+      if (!HEX6.test(String(s.identity.primary))) fail('subdivisions[].identity.primary', 'must be a six-digit hex colour', code)
+      if (!HEX6.test(String(s.identity.secondary))) fail('subdivisions[].identity.secondary', 'must be a six-digit hex colour', code)
+    }
+    if (s.labelPoint !== undefined && !isLonLat(s.labelPoint)) fail('subdivisions[].labelPoint', 'must be [longitude, latitude]', code)
+  }
+  if (entry.view !== undefined && !isLonLat(entry.view.centre)) fail('view.centre', 'must be [longitude, latitude]')
+  for (const group of entry.macroRegions ?? []) {
+    if (!group.id || !group.labelKey) fail('macroRegions', 'need an id and a labelKey')
+    for (const code of group.codes ?? []) if (!seen.has(code)) fail('macroRegions[].codes', `lists an unknown subdivision in group ${group.id}`, code)
+  }
+  if (entry.flagUrlTemplate !== undefined && !entry.flagUrlTemplate.includes('{code}')) fail('flagUrlTemplate', 'must contain the {code} placeholder')
+  if (!Array.isArray(entry.sources) || entry.sources.length === 0) fail('sources', 'must cite at least one source')
+  for (const src of entry.sources) {
+    if (!src.field || !src.citation || !/^https?:\/\//.test(String(src.url)) || !ISO_DATE.test(String(src.retrievedOn))) {
+      fail('sources', `entry for "${src?.field ?? '?'}" needs field, citation, an http(s) url and an ISO retrievedOn date`)
+    }
+  }
+  const cited = new Set(entry.sources.map((s) => s.field))
+  const needs = ['codes', 'names']
+  if (entry.macroRegions?.length) needs.push('macroRegions')
+  if (entry.subdivisions.some((s) => s.identity)) needs.push('identity')
+  if (entry.subdivisions.some((s) => s.labelPoint)) needs.push('labelPoint')
+  if (entry.view) needs.push('view')
+  for (const field of needs) if (!cited.has(field)) fail('sources', `has no citation for the "${field}" field group`)
+  if (!ISO_DATE.test(entry.version)) fail('version', 'must be an ISO date')
+}

package/src/components/region-theme/geometry.ts

@@ -0,0 +1,67 @@
+// Documented loader for the geometry fields of RegionThemeData and
+// CountryProfileData. The library ships no boundaries and no coordinates:
+// the host serves a public-domain boundary file (for example Natural Earth
+// admin-1, https://www.naturalearthdata.com/downloads/10m-cultural-vectors/)
+// and this function computes label points and the country view from it, so no
+// value is typed by hand.
+import { geoArea, geoBounds, geoCentroid, geoContains } from 'd3-geo'
+import type { LonLat, RegionThemeEntry, SourceCitation } from './format'
+
+export interface BoundaryFeature {
+  type: 'Feature'
+  properties: Record<string, unknown> | null
+  geometry: { type: 'Polygon' | 'MultiPolygon'; coordinates: unknown } | null
+}
+export interface BoundaryCollection {
+  type: 'FeatureCollection'
+  features: BoundaryFeature[]
+}
+
+export interface DeriveOptions {
+  /** Feature property holding the subdivision code (default `code`). */
+  codeProperty?: string
+  /** Accepts `BR-SP` or `SP` in the property (default: strip a `XX-` prefix). */
+  normaliseCode?: (raw: string) => string
+  /** Citation added to `sources` for the derived fields. */
+  source: Omit<SourceCitation, 'field'>
+}
+
+type Geo = Parameters<typeof geoContains>[0]
+
+/** A point inside the feature: its centroid when inside, else the centre of its largest part. */
+export function labelPointOf(feature: BoundaryFeature): LonLat | undefined {
+  if (!feature.geometry) return undefined
+  const f = feature as unknown as Geo
+  const centroid = geoCentroid(f) as LonLat
+  if (geoContains(f, centroid)) return centroid
+  if (feature.geometry.type !== 'MultiPolygon') return undefined
+  const parts = (feature.geometry.coordinates as unknown[]).map((coordinates) => ({ type: 'Polygon', coordinates }) as unknown as Geo)
+  const largest = parts.sort((a, b) => geoArea(b) - geoArea(a))[0]
+  if (!largest) return undefined
+  const c = geoCentroid(largest) as LonLat
+  return geoContains(largest, c) ? c : undefined
+}
+
+/** Returns a copy of the entry with label points and the view computed from the boundaries. */
+export function deriveGeometry(entry: RegionThemeEntry, boundaries: BoundaryCollection, options: DeriveOptions): RegionThemeEntry {
+  const prop = options.codeProperty ?? 'code'
+  const norm = options.normaliseCode ?? ((raw: string) => raw.replace(/^[A-Z]{2}-/, '').toUpperCase())
+  const byCode = new Map<string, BoundaryFeature>()
+  for (const f of boundaries.features) {
+    const raw = f.properties?.[prop]
+    if (typeof raw === 'string') byCode.set(norm(raw), f)
+  }
+  const subdivisions = entry.subdivisions.map((s) => {
+    const f = byCode.get(s.code)
+    const point = f ? labelPointOf(f) : undefined
+    return point ? { ...s, labelPoint: point } : s
+  })
+  const [[w, south], [e, north]] = geoBounds(boundaries as unknown as Geo)
+  const view = { centre: [(w + e) / 2, (south + north) / 2] as LonLat }
+  return {
+    ...entry,
+    subdivisions,
+    view,
+    sources: [...entry.sources, { field: 'labelPoint', ...options.source }, { field: 'view', ...options.source }],
+  }
+}

package/src/components/region-theme/index.ts

@@ -0,0 +1,7 @@
+// RegionThemeRegistry, RegionThemeData format, CountryProfileData format and
+// the geometry loader. Country data modules are separate entry points under
+// ./data/ and are never imported here, so a host bundles only what it uses.
+export * from './format'
+export * from './registry'
+export * from './countryProfile'
+export * from './geometry'

package/src/components/region-theme/regionTheme.test.tsx

@@ -0,0 +1,200 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { brazilProfile, register as registerBrazilProfile } from './data/br-profile'
+import { brazilRegionTheme } from './data/br'
+import {
+  contrastRatio,
+  createRegionThemeRegistry,
+  deriveGeometry,
+  flagEmoji,
+  formatProfileAddress,
+  formatProfileMoney,
+  getCountryProfile,
+  RegionThemeProvider,
+  useRegionThemeRegistry,
+  validateCountryProfile,
+  validateRegionThemeEntry,
+  type RegionThemeEntry,
+} from './index'
+
+// Fixture regenerated from the public ISO 3166-2:BR list (26 states and the Federal District).
+const ISO_3166_2_BR = 'AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO'.split(' ')
+
+const fixture = (patch: Partial<RegionThemeEntry> = {}): RegionThemeEntry => ({
+  country: 'ZZ',
+  subdivisionKind: 'region',
+  subdivisions: [
+    { code: 'A', name: { local: 'Alpha' }, identity: { primary: '#0f3d5c', secondary: '#f2c230' } },
+    { code: 'B', name: { local: 'Beta' } },
+  ],
+  flagUrlTemplate: '/flags/zz/{code}.svg',
+  sources: [
+    { field: 'codes', citation: 'test', url: 'https://example.org', retrievedOn: '2026-09-26' },
+    { field: 'names', citation: 'test', url: 'https://example.org', retrievedOn: '2026-09-26' },
+    { field: 'identity', citation: 'test', url: 'https://example.org', retrievedOn: '2026-09-26' },
+  ],
+  version: '2026-09-26',
+  ...patch,
+})
+
+describe('RegionThemeRegistry', () => {
+  it('returns São Paulo once Brazil is registered, case-insensitively', () => {
+    const r = createRegionThemeRegistry()
+    r.register(brazilRegionTheme)
+    expect(r.getSubdivision('br', 'sp')).toEqual({ code: 'SP', name: { local: 'São Paulo' }, kind: 'state' })
+    expect(r.isKnownSubdivision('BR', 'df')).toBe(true)
+    expect(r.listSubdivisions('br')).toHaveLength(27)
+    expect(r.getMacroRegions('br')?.find((g) => g.id === 'southeast')?.codes).toEqual(['ES', 'MG', 'RJ', 'SP'])
+  })
+
+  it('answers nothing, without throwing, for an unregistered country', () => {
+    const r = createRegionThemeRegistry()
+    expect(r.getSubdivision('xx', 'a')).toBeUndefined()
+    expect(r.listSubdivisions('xx')).toBeUndefined()
+    expect(r.isKnownSubdivision('xx', 'a')).toBe(false)
+    expect(r.getIdentityColours('xx', 'a')).toBeUndefined()
+    expect(r.getIdentityTone('xx', 'a')).toBeUndefined()
+    expect(r.getLabelPoint('xx', 'a')).toBeUndefined()
+    expect(r.getCountryView('xx')).toBeUndefined()
+    expect(r.getMacroRegions('xx')).toBeUndefined()
+    expect(r.getFlagUrl('xx', 'a')).toBeUndefined()
+  })
+
+  it('rejects a colour that is not six-digit hex, naming the field and code, and stores nothing', () => {
+    const r = createRegionThemeRegistry()
+    const bad = fixture({ subdivisions: [{ code: 'A', name: { local: 'Alpha' }, identity: { primary: 'teal', secondary: '#ffffff' } }] })
+    expect(() => r.register(bad)).toThrow(/identity\.primary.*subdivision A/)
+    expect(r.countries()).toEqual([])
+  })
+
+  it('computes a light text colour on a dark primary, reaching 4.5:1', () => {
+    const r = createRegionThemeRegistry()
+    r.register(fixture())
+    const c = r.getIdentityColours('zz', 'a')!
+    expect(c.onPrimary).toBe('light')
+    expect(contrastRatio(c.primary, '#fcfdfd')).toBeGreaterThanOrEqual(4.5)
+    expect(r.getIdentityTone('zz', 'a')).toMatch(/^categorical-[1-8]$/)
+    expect(r.getIdentityColours('zz', 'b')).toBeUndefined()
+  })
+
+  it('keeps isolated registries apart and replaces a re-registered country', () => {
+    const a = createRegionThemeRegistry()
+    const b = createRegionThemeRegistry()
+    a.register(fixture())
+    expect(b.countries()).toEqual([])
+    a.register(fixture({ subdivisions: [{ code: 'C', name: { local: 'Gamma' } }], sources: fixture().sources.slice(0, 2) }))
+    expect(a.listSubdivisions('zz')).toHaveLength(1)
+    a.unregister('zz')
+    expect(a.countries()).toEqual([])
+  })
+
+  it('resolves flag URLs only for known codes', () => {
+    const r = createRegionThemeRegistry()
+    r.register(fixture())
+    expect(r.getFlagUrl('zz', 'a')).toBe('/flags/zz/A.svg')
+    expect(r.getFlagUrl('zz', 'q')).toBeUndefined()
+  })
+
+  it('gives components an isolated registry through the provider', () => {
+    const r = createRegionThemeRegistry()
+    r.register(brazilRegionTheme)
+    function Name() {
+      return <p>{useRegionThemeRegistry().getSubdivision('BR', 'PA')?.name.local}</p>
+    }
+    render(
+      <RegionThemeProvider registry={r}>
+        <Name />
+      </RegionThemeProvider>,
+    )
+    expect(screen.getByText('Pará')).toBeInTheDocument()
+  })
+})
+
+describe('RegionThemeData: Brazil', () => {
+  it('passes the format validation', () => {
+    expect(() => validateRegionThemeEntry(brazilRegionTheme)).not.toThrow()
+  })
+
+  it('has exactly the ISO 3166-2:BR codes, and every macro-region member is one of them once', () => {
+    expect(new Set(brazilRegionTheme.subdivisions.map((s) => s.code))).toEqual(new Set(ISO_3166_2_BR))
+    const members = brazilRegionTheme.macroRegions!.flatMap((g) => g.codes)
+    expect(members.sort()).toEqual([...ISO_3166_2_BR].sort())
+  })
+
+  it('cites a source for every field group it ships and invents no identity colours or coordinates', () => {
+    const cited = new Set(brazilRegionTheme.sources.map((s) => s.field))
+    for (const f of ['codes', 'names', 'macroRegions']) expect(cited.has(f)).toBe(true)
+    expect(brazilRegionTheme.subdivisions.every((s) => !s.identity && !s.labelPoint)).toBe(true)
+  })
+
+  it('derives label points inside the polygons and the view from host boundaries', () => {
+    const square = (code: string, x: number): { type: 'Feature'; properties: { code: string }; geometry: { type: 'Polygon'; coordinates: number[][][] } } => ({
+      type: 'Feature',
+      properties: { code: `BR-${code}` },
+      geometry: { type: 'Polygon', coordinates: [[[x, -20], [x, -18], [x + 2, -18], [x + 2, -20], [x, -20]]] },
+    })
+    const derived = deriveGeometry(
+      brazilRegionTheme,
+      { type: 'FeatureCollection', features: [square('SP', -50), square('RJ', -44)] },
+      { source: { citation: 'test boundaries', url: 'https://example.org', retrievedOn: '2026-09-26' } },
+    )
+    const sp = derived.subdivisions.find((s) => s.code === 'SP')!.labelPoint!
+    expect(sp[0]).toBeGreaterThan(-50)
+    expect(sp[0]).toBeLessThan(-48)
+    expect(derived.view?.centre[0]).toBeCloseTo(-46, 0)
+    expect(() => validateRegionThemeEntry(derived)).not.toThrow()
+    expect(brazilRegionTheme.subdivisions.find((s) => s.code === 'SP')!.labelPoint).toBeUndefined()
+  })
+
+  it('keeps country data out of the registry barrel (one module per country)', () => {
+    const barrel = readFileSync(join(__dirname, 'index.ts'), 'utf8')
+    expect(barrel).not.toMatch(/from\s+['"]\.\/data\//)
+  })
+})
+
+describe('CountryProfileData: Brazil', () => {
+  it('validates and registers', () => {
+    expect(() => validateCountryProfile(brazilProfile)).not.toThrow()
+    registerBrazilProfile()
+    expect(getCountryProfile('br')?.names.local).toBe('Brasil')
+    expect(flagEmoji('BR')).toBe('🇧🇷')
+  })
+
+  it('formats money exactly as the platform does for pt-BR and BRL', () => {
+    expect(formatProfileMoney(1234.5, brazilProfile)).toBe(new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }).format(1234.5))
+    expect(JSON.stringify(brazilProfile)).not.toMatch(/R\$/)
+  })
+
+  it('formats an address along the template without doubled separators', () => {
+    const lines = formatProfileAddress(
+      { street: 'Rua das Estações', number: '1000', complement: '', district: 'Centro', city: 'São Paulo', state: 'SP', postalCode: '01000-000' },
+      brazilProfile,
+    )
+    expect(lines).toEqual(['Rua das Estações, 1000', 'Centro', 'São Paulo, SP', '01000-000'])
+    expect(lines.join('\n')).not.toMatch(/, ,/)
+  })
+
+  it('rejects an invalid currency and a required field missing from the template', () => {
+    expect(() => validateCountryProfile({ ...brazilProfile, currency: { code: 'XXQ' } })).toThrow(/currency/)
+    expect(() => validateCountryProfile({ ...brazilProfile, address: { ...brazilProfile.address, required: ['planet'] } })).toThrow(/address\.required/)
+  })
+
+  it('cites every field group', () => {
+    const cited = new Set(brazilProfile.sources.map((s) => s.field))
+    for (const f of ['code', 'names', 'languages', 'locale', 'currency', 'address', 'map', 'tax']) expect(cited.has(f)).toBe(true)
+  })
+
+  it('renders subdivision names accessibly (axe)', async () => {
+    const { container } = render(
+      <ul aria-label="States">
+        {brazilRegionTheme.subdivisions.map((s) => (
+          <li key={s.code}>{s.name.local}</li>
+        ))}
+      </ul>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})