@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/utils/chartAnnotations.ts

@@ -0,0 +1,326 @@
+// Pure helpers for chart annotations — the day-key matching + marker positioning
+// extracted from UiChartFrame so they're unit-testable and shareable by every
+// annotated chart (UiChartFrame's tooltip, the UiChartAnnotations marker overlay,
+// and the CWV / indexing charts that compose unovis directly).
+
+/**
+ * A single chart annotation — a thin vertical marker line + interactive dot.
+ * A plain UI shape any chart consumer can populate from any data source
+ * (timeline events, deploy markers, …); the design system never imports the
+ * domain that produces it.
+ */
+export interface ChartAnnotation {
+  /** X position as a Date, ISO string, or epoch-ms number matching the chart's x domain. */
+  x: number | string | Date
+  /** Short label shown in the marker's native title + the chart tooltip. */
+  label: string
+  /** Optional producer-owned explanation or value shown below the label. */
+  description?: string
+  /**
+   * Semantic tone that tints the marker (semantic CSS classes only).
+   * 'success' → bg-success  'error' → bg-error  'warning' → bg-warning
+   * 'neutral' (default) → bg-accented
+   */
+  tone?: 'success' | 'error' | 'warning' | 'neutral'
+  /** Compact semantic or explicitly sourced icon rendered beside the marker dot. */
+  icon?: string
+  /** Stable producer id — lets marker affordances (edit/delete) address the row. */
+  id?: string
+  /** Optional link opened from the marker tooltip. Only an http(s) URL renders; any other scheme is dropped. */
+  href?: string
+  /**
+   * User-authored marker: rendered with the editable glyph (square vs dot) and
+   * offered edit/delete affordances by consumers that support them.
+   */
+  editable?: boolean
+  /** Producer category token (e.g. 'release', 'custom') — opaque to the design system. */
+  category?: string
+  /** Original reporting day retained when a date annotation is re-anchored to an index x-axis. */
+  dayKey?: string
+  /** Optional producer image shown under the description, such as the page as the change left it. */
+  image?: { src: string, alt: string }
+}
+
+/**
+ * What ONE chart accepts, on top of whatever categories the caller treats as
+ * global (every chart gets those for free — see `annotationInScope`'s
+ * `rules.globalCategories`). Stays domain-opaque like `ChartAnnotation`
+ * itself: the design system knows the SHAPE of a per-chart declaration, never
+ * which category/kind strings a producer actually uses.
+ */
+export interface ChartAnnotationScope {
+  /** Non-global categories this chart accepts (e.g. an 'algo-update' producer). */
+  categories: readonly string[]
+  /** Topic allow-list scoped to `rules.kindBearingCategory`. Omit to accept every kind within it. */
+  kinds?: readonly string[]
+}
+
+/** The two facts a caller supplies about its own category vocabulary — see `annotationInScope`. */
+export interface ChartAnnotationScopeRules {
+  /** Categories every chart accepts regardless of `scope` (e.g. user notes, releases). */
+  globalCategories: readonly string[]
+  /** The one category whose annotations carry a producer `kind` for topic-level filtering. */
+  kindBearingCategory: string
+}
+
+/**
+ * True when `annotation` should render on a chart declaring `scope`. A chart
+ * silently accepting every category it was never asked for is the bug this
+ * closes (manual-review-2026-08 §Annotations: Search Console algorithm
+ * updates rendering on a performance chart) — a category outside both
+ * `rules.globalCategories` and `scope.categories` is rejected, full stop.
+ */
+export function annotationInScope(
+  annotation: { category?: string, kind?: string },
+  scope: ChartAnnotationScope,
+  rules: ChartAnnotationScopeRules,
+): boolean {
+  const category = annotation.category
+  if (category == null || rules.globalCategories.includes(category))
+    return true
+  if (!scope.categories.includes(category))
+    return false
+  if (category === rules.kindBearingCategory && scope.kinds)
+    return annotation.kind != null && scope.kinds.includes(annotation.kind)
+  return true
+}
+
+/** Marker icon count. Three is the visual ceiling; zero shows only the overflow count. */
+export type ChartAnnotationIconLimit = 0 | 1 | 2 | 3
+
+export interface ChartAnnotationOptions {
+  /** Annotation icons shown beside the marker before a +N overflow count. Default 3. */
+  maxIcons?: ChartAnnotationIconLimit
+}
+
+export interface ChartAnnotationControlItem<K extends string = string> {
+  key: K
+  label: string
+  icon: string
+  count?: number
+  enabled: boolean
+}
+
+export const DEFAULT_ANNOTATION_ICON_LIMIT: ChartAnnotationIconLimit = 3
+
+export function annotationIconPreview(
+  items: readonly ChartAnnotation[],
+  maxIcons: ChartAnnotationIconLimit = DEFAULT_ANNOTATION_ICON_LIMIT,
+): { visible: readonly ChartAnnotation[], overflowCount: number } {
+  return {
+    visible: items.slice(0, maxIcons),
+    overflowCount: Math.max(0, items.length - maxIcons),
+  }
+}
+
+/** Semantic tone → marker tailwind background class (line + dot). */
+export const ANNOTATION_TONE_CLASS: Record<NonNullable<ChartAnnotation['tone']>, string> = {
+  success: 'bg-success',
+  error: 'bg-error',
+  warning: 'bg-warning',
+  neutral: 'bg-accented',
+}
+
+function toMs(v: Date | string | number): number {
+  if (v instanceof Date)
+    return v.getTime()
+  if (typeof v === 'number')
+    return v
+  return new Date(v).getTime()
+}
+
+/**
+ * Normalise any x value to a `YYYY-MM-DD` day key.
+ *
+ * A `YYYY-MM-DD…` string keeps its own day verbatim (no Date round-trip, so no
+ * UTC shift); a `Date`/epoch-ms is keyed by its **UTC** day.
+ *
+ * TIMEZONE NOTE (ADR-0082): chart x-domains here are GSC reporting days
+ * (Pacific) rendered as UTC-midnight Dates, and an annotation's `x` is typically
+ * an event instant (`occurredAt`, a UTC Date). Marker placement and the tooltip
+ * match BOTH key off that UTC day, so the tooltip always matches the day the
+ * marker is drawn on — they stay mutually consistent. The only artefact: a
+ * detection-time event late in the Pacific evening keys one calendar day ahead
+ * of the viewer's local day, and its marker sits on that same (next) day.
+ */
+export function toChartDayKey(v: Date | string | number): string | null {
+  if (typeof v === 'string' && /^\d{4}-\d{2}-\d{2}/.test(v))
+    return v.slice(0, 10)
+  // A non-date x value (a category axis, "Mobile") has no day. `toISOString`
+  // throws a RangeError on an Invalid Date, which failed the whole chart render.
+  const ms = toMs(v)
+  return Number.isFinite(ms) ? new Date(ms).toISOString().slice(0, 10) : null
+}
+
+/** Annotations whose day matches the hovered x value (same `YYYY-MM-DD`). */
+export function annotationsOnDay<T extends { x: Date | string | number }>(
+  annotations: readonly T[],
+  hoverX: Date | string | number | null | undefined,
+): T[] {
+  if (hoverX == null || !annotations.length)
+    return []
+  const day = toChartDayKey(hoverX)
+  if (!day)
+    return []
+  return annotations.filter(a => toChartDayKey(a.x) === day)
+}
+
+/**
+ * The cheap diagnose line for a marker tooltip: "N days later, <metric> +X%".
+ * Computed from the series already on screen (3-day means around the marker
+ * day and `days` later) — the render-time half of the ROADMAP "tether" idea,
+ * with zero backend. Returns undefined when the series doesn't extend far
+ * enough past the marker or the baseline is zero.
+ */
+export function annotationImpactLine(
+  series: readonly { date: string, value: number }[],
+  markerX: Date | string | number,
+  metricLabel: string,
+  days = 7,
+): string | undefined {
+  if (series.length < days + 1)
+    return undefined
+  const day = toChartDayKey(markerX)
+  if (!day)
+    return undefined
+  const anchor = series.findIndex((row) => {
+    const rowDay = toChartDayKey(row.date)
+    return rowDay != null && rowDay >= day
+  })
+  if (anchor < 1 || anchor + days >= series.length)
+    return undefined
+  const mean = (end: number) => {
+    const slice = series.slice(Math.max(0, end - 2), end + 1)
+    return slice.reduce((sum, row) => sum + row.value, 0) / slice.length
+  }
+  // Baseline ends the day BEFORE the marker — the marker day itself already
+  // carries the event's effect and would dilute the delta.
+  const before = mean(anchor - 1)
+  const after = mean(anchor + days)
+  if (before <= 0)
+    return undefined
+  const pct = Math.round(((after - before) / before) * 100)
+  if (!Number.isFinite(pct))
+    return undefined
+  return `${days} days later, ${metricLabel} ${pct >= 0 ? '+' : ''}${pct}%`
+}
+
+/**
+ * The CSS `left` percentage for an annotation within a zero-horizontal-margin
+ * plot (wrap width == plot x-span). Clamped to [0,100]. Returns '50%' for a
+ * degenerate domain.
+ */
+export function annotationLeftPct(x: Date | string | number, domain: [Date | string | number, Date | string | number]): string {
+  const xMs = toMs(x)
+  const minMs = toMs(domain[0])
+  const maxMs = toMs(domain[1])
+  if (maxMs <= minMs)
+    return '50%'
+  const pct = Math.max(0, Math.min(100, ((xMs - minMs) / (maxMs - minMs)) * 100))
+  return `${pct.toFixed(4)}%`
+}
+
+/**
+ * Re-anchor annotations onto an INDEX-based x-axis (`x = (_d, i) => i`, e.g. the
+ * CWV + indexing charts, whose bars are evenly spaced by array index rather than
+ * by time). Maps each annotation's day to the data index sharing that day and
+ * drops annotations with no matching data point. Pair with `xDomain = [0, len-1]`
+ * so `UiChartAnnotations` positions markers on the right bar.
+ */
+export function indexAnnotationsByDay(
+  annotations: readonly ChartAnnotation[] | undefined,
+  days: readonly (string | null)[],
+): ChartAnnotation[] {
+  if (!annotations?.length || !days.length)
+    return []
+  const dayToIndex = new Map<string, number>()
+  days.forEach((d, i) => {
+    const key = d == null ? null : toChartDayKey(d)
+    if (key && !dayToIndex.has(key))
+      dayToIndex.set(key, i)
+  })
+  return annotations.flatMap((a) => {
+    const key = toChartDayKey(a.x)
+    const i = key ? dayToIndex.get(key) : undefined
+    return key == null || i == null ? [] : [{ ...a, x: i, dayKey: key }]
+  })
+}
+
+export interface ResolvedAnnotationMarker {
+  id: number
+  label: string
+  description?: string
+  leftPct: string
+  toneClass: string
+}
+
+/** Resolve annotations to positioned markers; [] when no domain (silently skipped). */
+export interface ResolvedAnnotationMarkerGroup {
+  /** The shared day key (`YYYY-MM-DD`) — one marker per day. */
+  id: string
+  leftPct: string
+  /** Dominant tone across the day's annotations (error > warning > success > neutral). */
+  toneClass: string
+  count: number
+  /** True when any of the day's annotations is user-editable. */
+  editable: boolean
+  items: ChartAnnotation[]
+}
+
+const TONE_RANK: Record<NonNullable<ChartAnnotation['tone']>, number> = {
+  error: 3,
+  warning: 2,
+  success: 1,
+  neutral: 0,
+}
+
+/**
+ * Day-grouped markers: annotations sharing a calendar day collapse into ONE
+ * marker (a "+N" count pill signals the stack; the tooltip lists every item)
+ * instead of piling identical lines on the same pixel column.
+ */
+export function resolveAnnotationMarkerGroups(
+  annotations: readonly ChartAnnotation[] | undefined,
+  xDomain: [Date | string | number, Date | string | number] | undefined,
+): ResolvedAnnotationMarkerGroup[] {
+  if (!annotations?.length || !xDomain)
+    return []
+  const byDay = new Map<string, ChartAnnotation[]>()
+  for (const ann of annotations) {
+    // An index-anchored annotation always carries its dayKey. Without one, a
+    // non-date x still renders as its own marker, keyed by its raw value.
+    const day = ann.dayKey ?? toChartDayKey(ann.x) ?? String(ann.x)
+    const bucket = byDay.get(day)
+    if (bucket)
+      bucket.push(ann)
+    else
+      byDay.set(day, [ann])
+  }
+  return Array.from(byDay.entries(), ([day, items]) => {
+    const tone = items.reduce<NonNullable<ChartAnnotation['tone']>>((acc, item) =>
+      TONE_RANK[item.tone ?? 'neutral'] > TONE_RANK[acc] ? (item.tone ?? 'neutral') : acc, 'neutral')
+    return {
+      id: day,
+      leftPct: annotationLeftPct(items[0]!.x, xDomain),
+      toneClass: ANNOTATION_TONE_CLASS[tone],
+      count: items.length,
+      editable: items.some(item => item.editable === true),
+      items,
+    }
+  })
+}
+
+export function resolveAnnotationMarkers(
+  annotations: readonly ChartAnnotation[] | undefined,
+  xDomain: [Date | string | number, Date | string | number] | undefined,
+): ResolvedAnnotationMarker[] {
+  if (!annotations?.length || !xDomain)
+    return []
+  return annotations.map((ann, i) => ({
+    id: i,
+    label: ann.label,
+    ...(ann.description ? { description: ann.description } : {}),
+    leftPct: annotationLeftPct(ann.x, xDomain),
+    toneClass: ANNOTATION_TONE_CLASS[ann.tone ?? 'neutral'],
+  }))
+}

package/app/utils/countries.ts

@@ -0,0 +1,337 @@
+import type { UiIcon } from '../shared/ui-icons'
+import { DISPLAY_LOCALE } from '../composables/formatting'
+
+// ISO 3166-1 alpha-3 to alpha-2 and country names
+export const countryData: Record<string, { alpha2: string, name: string }> = {
+  deu: { alpha2: 'de', name: 'Germany' },
+  fra: { alpha2: 'fr', name: 'France' },
+  ind: { alpha2: 'in', name: 'India' },
+  usa: { alpha2: 'us', name: 'United States' },
+  gbr: { alpha2: 'gb', name: 'United Kingdom' },
+  nld: { alpha2: 'nl', name: 'Netherlands' },
+  pol: { alpha2: 'pl', name: 'Poland' },
+  rus: { alpha2: 'ru', name: 'Russia' },
+  esp: { alpha2: 'es', name: 'Spain' },
+  ita: { alpha2: 'it', name: 'Italy' },
+  bra: { alpha2: 'br', name: 'Brazil' },
+  can: { alpha2: 'ca', name: 'Canada' },
+  aus: { alpha2: 'au', name: 'Australia' },
+  jpn: { alpha2: 'jp', name: 'Japan' },
+  chn: { alpha2: 'cn', name: 'China' },
+  kor: { alpha2: 'kr', name: 'South Korea' },
+  mex: { alpha2: 'mx', name: 'Mexico' },
+  arg: { alpha2: 'ar', name: 'Argentina' },
+  tur: { alpha2: 'tr', name: 'Turkey' },
+  sau: { alpha2: 'sa', name: 'Saudi Arabia' },
+  zaf: { alpha2: 'za', name: 'South Africa' },
+  egy: { alpha2: 'eg', name: 'Egypt' },
+  nga: { alpha2: 'ng', name: 'Nigeria' },
+  ken: { alpha2: 'ke', name: 'Kenya' },
+  idn: { alpha2: 'id', name: 'Indonesia' },
+  tha: { alpha2: 'th', name: 'Thailand' },
+  vnm: { alpha2: 'vn', name: 'Vietnam' },
+  phl: { alpha2: 'ph', name: 'Philippines' },
+  mys: { alpha2: 'my', name: 'Malaysia' },
+  sgp: { alpha2: 'sg', name: 'Singapore' },
+  pak: { alpha2: 'pk', name: 'Pakistan' },
+  bgd: { alpha2: 'bd', name: 'Bangladesh' },
+  ukr: { alpha2: 'ua', name: 'Ukraine' },
+  rou: { alpha2: 'ro', name: 'Romania' },
+  cze: { alpha2: 'cz', name: 'Czechia' },
+  hun: { alpha2: 'hu', name: 'Hungary' },
+  aut: { alpha2: 'at', name: 'Austria' },
+  che: { alpha2: 'ch', name: 'Switzerland' },
+  bel: { alpha2: 'be', name: 'Belgium' },
+  swe: { alpha2: 'se', name: 'Sweden' },
+  nor: { alpha2: 'no', name: 'Norway' },
+  dnk: { alpha2: 'dk', name: 'Denmark' },
+  fin: { alpha2: 'fi', name: 'Finland' },
+  prt: { alpha2: 'pt', name: 'Portugal' },
+  grc: { alpha2: 'gr', name: 'Greece' },
+  irl: { alpha2: 'ie', name: 'Ireland' },
+  nzl: { alpha2: 'nz', name: 'New Zealand' },
+  isr: { alpha2: 'il', name: 'Israel' },
+  are: { alpha2: 'ae', name: 'UAE' },
+  col: { alpha2: 'co', name: 'Colombia' },
+  chl: { alpha2: 'cl', name: 'Chile' },
+  per: { alpha2: 'pe', name: 'Peru' },
+  ven: { alpha2: 've', name: 'Venezuela' },
+  irn: { alpha2: 'ir', name: 'Iran' },
+  irq: { alpha2: 'iq', name: 'Iraq' },
+  twn: { alpha2: 'tw', name: 'Taiwan' },
+  hkg: { alpha2: 'hk', name: 'Hong Kong' },
+  mac: { alpha2: 'mo', name: 'Macau' },
+  svk: { alpha2: 'sk', name: 'Slovakia' },
+  bgr: { alpha2: 'bg', name: 'Bulgaria' },
+  hrv: { alpha2: 'hr', name: 'Croatia' },
+  srb: { alpha2: 'rs', name: 'Serbia' },
+  svn: { alpha2: 'si', name: 'Slovenia' },
+  ltu: { alpha2: 'lt', name: 'Lithuania' },
+  lva: { alpha2: 'lv', name: 'Latvia' },
+  est: { alpha2: 'ee', name: 'Estonia' },
+  blr: { alpha2: 'by', name: 'Belarus' },
+  kaz: { alpha2: 'kz', name: 'Kazakhstan' },
+  uzb: { alpha2: 'uz', name: 'Uzbekistan' },
+  aze: { alpha2: 'az', name: 'Azerbaijan' },
+  geo: { alpha2: 'ge', name: 'Georgia' },
+  arm: { alpha2: 'am', name: 'Armenia' },
+  // Remaining ISO 3166-1 countries + common GSC-reported territories. GSC emits
+  // alpha-3 (lowercase) for every country, so an incomplete map left the long
+  // tail rendering as raw codes (`lbn`, `isl`) with a globe instead of a flag.
+  afg: { alpha2: 'af', name: 'Afghanistan' },
+  alb: { alpha2: 'al', name: 'Albania' },
+  dza: { alpha2: 'dz', name: 'Algeria' },
+  and: { alpha2: 'ad', name: 'Andorra' },
+  ago: { alpha2: 'ao', name: 'Angola' },
+  atg: { alpha2: 'ag', name: 'Antigua and Barbuda' },
+  bhs: { alpha2: 'bs', name: 'Bahamas' },
+  bhr: { alpha2: 'bh', name: 'Bahrain' },
+  brb: { alpha2: 'bb', name: 'Barbados' },
+  ben: { alpha2: 'bj', name: 'Benin' },
+  btn: { alpha2: 'bt', name: 'Bhutan' },
+  bol: { alpha2: 'bo', name: 'Bolivia' },
+  bih: { alpha2: 'ba', name: 'Bosnia and Herzegovina' },
+  bwa: { alpha2: 'bw', name: 'Botswana' },
+  brn: { alpha2: 'bn', name: 'Brunei' },
+  bfa: { alpha2: 'bf', name: 'Burkina Faso' },
+  bdi: { alpha2: 'bi', name: 'Burundi' },
+  khm: { alpha2: 'kh', name: 'Cambodia' },
+  cmr: { alpha2: 'cm', name: 'Cameroon' },
+  cpv: { alpha2: 'cv', name: 'Cape Verde' },
+  caf: { alpha2: 'cf', name: 'Central African Republic' },
+  tcd: { alpha2: 'td', name: 'Chad' },
+  com: { alpha2: 'km', name: 'Comoros' },
+  cog: { alpha2: 'cg', name: 'Congo' },
+  cod: { alpha2: 'cd', name: 'DR Congo' },
+  cri: { alpha2: 'cr', name: 'Costa Rica' },
+  civ: { alpha2: 'ci', name: 'Côte d\'Ivoire' },
+  cub: { alpha2: 'cu', name: 'Cuba' },
+  cyp: { alpha2: 'cy', name: 'Cyprus' },
+  dji: { alpha2: 'dj', name: 'Djibouti' },
+  dma: { alpha2: 'dm', name: 'Dominica' },
+  dom: { alpha2: 'do', name: 'Dominican Republic' },
+  ecu: { alpha2: 'ec', name: 'Ecuador' },
+  slv: { alpha2: 'sv', name: 'El Salvador' },
+  gnq: { alpha2: 'gq', name: 'Equatorial Guinea' },
+  eri: { alpha2: 'er', name: 'Eritrea' },
+  swz: { alpha2: 'sz', name: 'Eswatini' },
+  eth: { alpha2: 'et', name: 'Ethiopia' },
+  fji: { alpha2: 'fj', name: 'Fiji' },
+  gab: { alpha2: 'ga', name: 'Gabon' },
+  gmb: { alpha2: 'gm', name: 'Gambia' },
+  gha: { alpha2: 'gh', name: 'Ghana' },
+  gib: { alpha2: 'gi', name: 'Gibraltar' },
+  grd: { alpha2: 'gd', name: 'Grenada' },
+  gtm: { alpha2: 'gt', name: 'Guatemala' },
+  gin: { alpha2: 'gn', name: 'Guinea' },
+  gnb: { alpha2: 'gw', name: 'Guinea-Bissau' },
+  guy: { alpha2: 'gy', name: 'Guyana' },
+  hti: { alpha2: 'ht', name: 'Haiti' },
+  hnd: { alpha2: 'hn', name: 'Honduras' },
+  isl: { alpha2: 'is', name: 'Iceland' },
+  jam: { alpha2: 'jm', name: 'Jamaica' },
+  jor: { alpha2: 'jo', name: 'Jordan' },
+  kwt: { alpha2: 'kw', name: 'Kuwait' },
+  kgz: { alpha2: 'kg', name: 'Kyrgyzstan' },
+  lao: { alpha2: 'la', name: 'Laos' },
+  lbn: { alpha2: 'lb', name: 'Lebanon' },
+  lso: { alpha2: 'ls', name: 'Lesotho' },
+  lbr: { alpha2: 'lr', name: 'Liberia' },
+  lby: { alpha2: 'ly', name: 'Libya' },
+  lie: { alpha2: 'li', name: 'Liechtenstein' },
+  lux: { alpha2: 'lu', name: 'Luxembourg' },
+  mkd: { alpha2: 'mk', name: 'North Macedonia' },
+  mdg: { alpha2: 'mg', name: 'Madagascar' },
+  mwi: { alpha2: 'mw', name: 'Malawi' },
+  mdv: { alpha2: 'mv', name: 'Maldives' },
+  mli: { alpha2: 'ml', name: 'Mali' },
+  mlt: { alpha2: 'mt', name: 'Malta' },
+  mrt: { alpha2: 'mr', name: 'Mauritania' },
+  mus: { alpha2: 'mu', name: 'Mauritius' },
+  mda: { alpha2: 'md', name: 'Moldova' },
+  mco: { alpha2: 'mc', name: 'Monaco' },
+  mng: { alpha2: 'mn', name: 'Mongolia' },
+  mne: { alpha2: 'me', name: 'Montenegro' },
+  mar: { alpha2: 'ma', name: 'Morocco' },
+  moz: { alpha2: 'mz', name: 'Mozambique' },
+  mmr: { alpha2: 'mm', name: 'Myanmar' },
+  nam: { alpha2: 'na', name: 'Namibia' },
+  npl: { alpha2: 'np', name: 'Nepal' },
+  nic: { alpha2: 'ni', name: 'Nicaragua' },
+  ner: { alpha2: 'ne', name: 'Niger' },
+  omn: { alpha2: 'om', name: 'Oman' },
+  pan: { alpha2: 'pa', name: 'Panama' },
+  png: { alpha2: 'pg', name: 'Papua New Guinea' },
+  pry: { alpha2: 'py', name: 'Paraguay' },
+  pse: { alpha2: 'ps', name: 'Palestine' },
+  pri: { alpha2: 'pr', name: 'Puerto Rico' },
+  qat: { alpha2: 'qa', name: 'Qatar' },
+  rwa: { alpha2: 'rw', name: 'Rwanda' },
+  kna: { alpha2: 'kn', name: 'Saint Kitts and Nevis' },
+  lca: { alpha2: 'lc', name: 'Saint Lucia' },
+  vct: { alpha2: 'vc', name: 'Saint Vincent and the Grenadines' },
+  wsm: { alpha2: 'ws', name: 'Samoa' },
+  smr: { alpha2: 'sm', name: 'San Marino' },
+  stp: { alpha2: 'st', name: 'São Tomé and Príncipe' },
+  sen: { alpha2: 'sn', name: 'Senegal' },
+  syc: { alpha2: 'sc', name: 'Seychelles' },
+  sle: { alpha2: 'sl', name: 'Sierra Leone' },
+  slb: { alpha2: 'sb', name: 'Solomon Islands' },
+  som: { alpha2: 'so', name: 'Somalia' },
+  ssd: { alpha2: 'ss', name: 'South Sudan' },
+  lka: { alpha2: 'lk', name: 'Sri Lanka' },
+  sdn: { alpha2: 'sd', name: 'Sudan' },
+  sur: { alpha2: 'sr', name: 'Suriname' },
+  syr: { alpha2: 'sy', name: 'Syria' },
+  tjk: { alpha2: 'tj', name: 'Tajikistan' },
+  tza: { alpha2: 'tz', name: 'Tanzania' },
+  tls: { alpha2: 'tl', name: 'Timor-Leste' },
+  tgo: { alpha2: 'tg', name: 'Togo' },
+  ton: { alpha2: 'to', name: 'Tonga' },
+  tto: { alpha2: 'tt', name: 'Trinidad and Tobago' },
+  tun: { alpha2: 'tn', name: 'Tunisia' },
+  tkm: { alpha2: 'tm', name: 'Turkmenistan' },
+  uga: { alpha2: 'ug', name: 'Uganda' },
+  ury: { alpha2: 'uy', name: 'Uruguay' },
+  vut: { alpha2: 'vu', name: 'Vanuatu' },
+  yem: { alpha2: 'ye', name: 'Yemen' },
+  zmb: { alpha2: 'zm', name: 'Zambia' },
+  zwe: { alpha2: 'zw', name: 'Zimbabwe' },
+  // Dependencies, overseas territories and the remaining sovereign states the
+  // list above skipped. GSC reports on the full ISO 3166-1 set, so anything
+  // absent here rendered as a raw id (`reu`, `blz`) beside a globe. `name` is
+  // the offline fallback only — `getCountryName` prefers `Intl.DisplayNames`,
+  // and these English strings were generated FROM that same CLDR data so the
+  // two agree. Every alpha-2 below has a `i-circle-flags-*` glyph (checked
+  // against @iconify-json/circle-flags).
+  abw: { alpha2: 'aw', name: 'Aruba' },
+  aia: { alpha2: 'ai', name: 'Anguilla' },
+  ala: { alpha2: 'ax', name: 'Åland Islands' },
+  asm: { alpha2: 'as', name: 'American Samoa' },
+  ata: { alpha2: 'aq', name: 'Antarctica' },
+  atf: { alpha2: 'tf', name: 'French Southern Territories' },
+  bes: { alpha2: 'bq', name: 'Caribbean Netherlands' },
+  blm: { alpha2: 'bl', name: 'St. Barthélemy' },
+  blz: { alpha2: 'bz', name: 'Belize' },
+  bmu: { alpha2: 'bm', name: 'Bermuda' },
+  bvt: { alpha2: 'bv', name: 'Bouvet Island' },
+  cck: { alpha2: 'cc', name: 'Cocos (Keeling) Islands' },
+  cok: { alpha2: 'ck', name: 'Cook Islands' },
+  cuw: { alpha2: 'cw', name: 'Curaçao' },
+  cxr: { alpha2: 'cx', name: 'Christmas Island' },
+  cym: { alpha2: 'ky', name: 'Cayman Islands' },
+  esh: { alpha2: 'eh', name: 'Western Sahara' },
+  flk: { alpha2: 'fk', name: 'Falkland Islands' },
+  fro: { alpha2: 'fo', name: 'Faroe Islands' },
+  fsm: { alpha2: 'fm', name: 'Micronesia' },
+  ggy: { alpha2: 'gg', name: 'Guernsey' },
+  glp: { alpha2: 'gp', name: 'Guadeloupe' },
+  grl: { alpha2: 'gl', name: 'Greenland' },
+  guf: { alpha2: 'gf', name: 'French Guiana' },
+  gum: { alpha2: 'gu', name: 'Guam' },
+  hmd: { alpha2: 'hm', name: 'Heard & McDonald Islands' },
+  imn: { alpha2: 'im', name: 'Isle of Man' },
+  iot: { alpha2: 'io', name: 'British Indian Ocean Territory' },
+  jey: { alpha2: 'je', name: 'Jersey' },
+  kir: { alpha2: 'ki', name: 'Kiribati' },
+  maf: { alpha2: 'mf', name: 'St. Martin' },
+  mhl: { alpha2: 'mh', name: 'Marshall Islands' },
+  mnp: { alpha2: 'mp', name: 'Northern Mariana Islands' },
+  msr: { alpha2: 'ms', name: 'Montserrat' },
+  mtq: { alpha2: 'mq', name: 'Martinique' },
+  myt: { alpha2: 'yt', name: 'Mayotte' },
+  ncl: { alpha2: 'nc', name: 'New Caledonia' },
+  nfk: { alpha2: 'nf', name: 'Norfolk Island' },
+  niu: { alpha2: 'nu', name: 'Niue' },
+  nru: { alpha2: 'nr', name: 'Nauru' },
+  pcn: { alpha2: 'pn', name: 'Pitcairn Islands' },
+  plw: { alpha2: 'pw', name: 'Palau' },
+  prk: { alpha2: 'kp', name: 'North Korea' },
+  pyf: { alpha2: 'pf', name: 'French Polynesia' },
+  reu: { alpha2: 're', name: 'Réunion' },
+  sgs: { alpha2: 'gs', name: 'South Georgia & South Sandwich Islands' },
+  shn: { alpha2: 'sh', name: 'St. Helena' },
+  sjm: { alpha2: 'sj', name: 'Svalbard & Jan Mayen' },
+  spm: { alpha2: 'pm', name: 'St. Pierre & Miquelon' },
+  sxm: { alpha2: 'sx', name: 'Sint Maarten' },
+  tca: { alpha2: 'tc', name: 'Turks & Caicos Islands' },
+  tkl: { alpha2: 'tk', name: 'Tokelau' },
+  tuv: { alpha2: 'tv', name: 'Tuvalu' },
+  umi: { alpha2: 'um', name: 'U.S. Outlying Islands' },
+  vat: { alpha2: 'va', name: 'Vatican City' },
+  vgb: { alpha2: 'vg', name: 'British Virgin Islands' },
+  vir: { alpha2: 'vi', name: 'U.S. Virgin Islands' },
+  wlf: { alpha2: 'wf', name: 'Wallis & Futuna' },
+  // Kosovo has no ISO 3166-1 assignment; GSC emits the user-assigned `xkk`,
+  // which resolves to the `xk` region CLDR and Iconify both carry. Kept to the
+  // one spelling GSC actually sends — a second alias would render as a
+  // duplicate "Kosovo" row in every dropdown built from `Object.values`.
+  xkk: { alpha2: 'xk', name: 'Kosovo' },
+  // GSC's sentinel for traffic it cannot attribute to a region. It appears in
+  // essentially every property and is a real category, not an error — so it
+  // gets a name, and `UNKNOWN_REGION_CODES` keeps it off the flag path.
+  zzz: { alpha2: 'zz', name: 'Unknown region' },
+}
+
+/** Codes that name "we don't know", in every spelling a caller might pass. */
+const UNKNOWN_REGION_CODES = new Set(['zz', 'zzz'])
+
+// Convert country code to circle-flags icon name
+export function countryCodeToFlagIcon(code: string): UiIcon {
+  if (!code)
+    return 'globe'
+  const lowerCode = code.toLowerCase()
+  // There is no `zz` flag (nor should there be) — the globe IS the answer.
+  if (UNKNOWN_REGION_CODES.has(lowerCode))
+    return 'globe'
+  const data = countryData[lowerCode]
+  const alpha2 = data?.alpha2 || (lowerCode.length === 2 ? lowerCode : null)
+  if (!alpha2)
+    return 'globe'
+  return `i-circle-flags-${alpha2}`
+}
+
+// Localized region-name lookup. The bundled `name` field is English-only, so
+// prefer `Intl.DisplayNames` in the pinned display locale (formatting.ts): the
+// runtime locale differs between server and browser and broke hydration
+// and fall back to the map → raw code when the runtime lacks region data.
+let regionDisplay: Intl.DisplayNames | null | undefined
+function getRegionDisplay(): Intl.DisplayNames | null {
+  if (regionDisplay !== undefined)
+    return regionDisplay
+  try {
+    regionDisplay = new Intl.DisplayNames(DISPLAY_LOCALE, { type: 'region' })
+  }
+  catch {
+    regionDisplay = null // runtime without region display data
+  }
+  return regionDisplay
+}
+
+// Get country display name from code
+export function getCountryName(code: string, fallback?: string): string {
+  if (!code)
+    return fallback || 'Unknown'
+  const lowerCode = code.toLowerCase()
+  // Ahead of the Intl lookup on purpose: CLDR titles this "Unknown Region",
+  // which reads as a proper noun in a list of real ones.
+  if (UNKNOWN_REGION_CODES.has(lowerCode))
+    return 'Unknown region'
+  const data = countryData[lowerCode]
+  // MUST be uppercased before `.of()`. V8 does not canonicalise the region
+  // subtag: `.of('us')` returns the string `'us'` while `.of('US')` returns
+  // "United States". `countryData` stores alpha-2 lowercase (it feeds the
+  // `i-circle-flags-*` name), so passing it straight through made every
+  // mapped country render as its own lowercase code.
+  const alpha2 = (data?.alpha2 || (code.length === 2 ? code : '')).toUpperCase() || null
+  if (alpha2) {
+    // `.of()` echoes the input back when it can't resolve the region.
+    const localized = getRegionDisplay()?.of(alpha2)
+    if (localized && localized.toUpperCase() !== alpha2)
+      return localized
+  }
+  return data?.name || fallback || code.toUpperCase()
+}
+
+// Shorter aliases used at call sites.
+export { countryCodeToFlagIcon as countryFlag, getCountryName as countryName }