@enigmax/primitives 0.19.0 → 0.20.0

package/dist/{chunk-AU3H5WIY.js → chunk-LMZJBOZG.js}

@@ -22,9 +22,56 @@ function resetFlagConfig() {
 var FLAG_RATIO = { rect: 4 / 3, square: 1, circle: 1 };
 var EMOJI_FLAG = /^[\u{1F1E6}-\u{1F1FF}]{2}$/u;
 var LOCALE_TAG = /^([A-Za-z]{2,3})[-_]([A-Z]{2})$/;
-var FILE_CODE = /^[a-z]{2,}(?:[-_][a-z0-9]+)*$/;
+var FILE_CODE = /^[a-z]{2,}[-_][a-z0-9_-]+$/;
 var COUNTRY_CODE = /^[a-z]{2}$/;
-function normalizeFlagCode(value) {
+function fold(value) {
+  return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").replace(/['‘’ʼ`´]/g, "").toLowerCase().replace(/&/g, " and ").replace(/\bst\.?\s/g, "saint ").replace(/^the\s+/, "").replace(/[.,]/g, "").replace(/\s+/g, " ").trim();
+}
+var nameIndexes = /* @__PURE__ */ new Map();
+function canonicalRegion(code) {
+  try {
+    return new Intl.Locale(`und-${code}`).region?.toLowerCase() ?? code.toLowerCase();
+  } catch {
+    return code.toLowerCase();
+  }
+}
+function unknownRegionName(names) {
+  return names.of("ZZ");
+}
+function regionsByName(locale) {
+  const cached = nameIndexes.get(locale);
+  if (cached !== void 0) return cached;
+  let index = null;
+  try {
+    const names = new Intl.DisplayNames([locale], { type: "region" });
+    const unknown = unknownRegionName(names);
+    index = /* @__PURE__ */ new Map();
+    for (let first = 65; first <= 90; first++) {
+      for (let second = 65; second <= 90; second++) {
+        const code = String.fromCharCode(first, second);
+        const name = names.of(code);
+        if (!name || name === code || name === unknown) continue;
+        const key = fold(name);
+        if (!index.has(key)) index.set(key, canonicalRegion(code));
+      }
+    }
+  } catch {
+    index = null;
+  }
+  nameIndexes.set(locale, index);
+  return index;
+}
+function isKnownRegion(code) {
+  try {
+    const names = new Intl.DisplayNames(["en"], { type: "region" });
+    const upper = code.toUpperCase();
+    const name = names.of(upper);
+    return Boolean(name) && name !== upper && name !== unknownRegionName(names);
+  } catch {
+    return true;
+  }
+}
+function normalizeFlagCode(value, locale) {
   if (!value) return null;
   const raw = value.trim();
   if (!raw) return null;
@@ -32,10 +79,18 @@ function normalizeFlagCode(value) {
     const letters = [...raw].map((char) => String.fromCharCode((char.codePointAt(0) ?? 0) - 127462 + 97));
     return letters.join("");
   }
-  const locale = LOCALE_TAG.exec(raw);
-  if (locale) return locale[2].toLowerCase();
-  const code = raw.toLowerCase();
-  return FILE_CODE.test(code) ? code : null;
+  const tag = LOCALE_TAG.exec(raw);
+  if (tag) return tag[2].toLowerCase();
+  const lower = raw.toLowerCase();
+  if (COUNTRY_CODE.test(lower)) return isKnownRegion(lower) ? canonicalRegion(lower) : null;
+  if (FILE_CODE.test(lower)) return lower;
+  const folded = fold(raw);
+  for (const candidate of [locale, documentLocale(), "en", runtimeLocale()]) {
+    if (!candidate) continue;
+    const found = regionsByName(candidate)?.get(folded);
+    if (found) return found;
+  }
+  return null;
 }
 function flagName(code, locale) {
   const normalized = normalizeFlagCode(code);
@@ -49,6 +104,13 @@ function flagName(code, locale) {
     return null;
   }
 }
+function runtimeLocale() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale;
+  } catch {
+    return void 0;
+  }
+}
 function documentLocale() {
   if (typeof document === "undefined") return void 0;
   return document.documentElement.lang || void 0;
@@ -100,7 +162,7 @@ function flagAttributes(code, options = {}) {
     "data-enigma-flag": "",
     "data-flag-code": view.code,
     "data-flag-shape": view.shape,
-    ...label ? {} : { "aria-hidden": "true" }
+    ...label ? { title: label } : { "aria-hidden": "true" }
   };
 }
 

package/dist/{chunk-XNNQRA35.js → chunk-NPHRS2Q7.js}

@@ -1,4 +1,4 @@
-import { flagView } from './chunk-AU3H5WIY.js';
+import { flagView } from './chunk-LMZJBOZG.js';
 import { jsx } from 'react/jsx-runtime';
 
 function Flag({ code, label, decorative = false, locale, shape, format, source, basePath, size, fallback = null, ...rest }) {
@@ -14,6 +14,7 @@ function Flag({ code, label, decorative = false, locale, shape, format, source,
     {
       src: view.src,
       alt: name,
+      title: name || void 0,
       width: view.width,
       height: view.height,
       loading: "lazy",

package/dist/{flags-BBJc9unY.d.ts → flags-BQU1V9rE.d.ts}

@@ -71,12 +71,20 @@ declare const FLAG_RATIO: Record<FlagShape, number>;
 /**
  * Anything a codebase calls a country into the file name the sets use, or null.
  *
- * Null rather than a guess: a code this cannot resolve would otherwise become a 404 image
- * with no alt text, and a broken flag beside a country name is worse than no flag at all.
- * An emoji flag is accepted and converted, so migrating an existing picker is a rename of
- * the component and nothing else.
+ * What it accepts: a code (`es`, `ES`), a locale tag (`en-GB`, `es_ES`), a subdivision or
+ * named file (`gb-eng`, `au-nsw`, `easter_island`), the emoji flag you are replacing, and
+ * the country's NAME - in English or in the page's own language, accents optional, so
+ * `Spain`, `España` and `espana` all resolve. A name is what a database column or an API
+ * payload usually holds, and requiring the caller to convert it first is how a flag ends up
+ * not being rendered at all.
+ *
+ * Null rather than a guess, and that is the point of the strictness: `banana` used to pass
+ * as a file code and render as a 404 with no alt text, which is worse than no flag. A
+ * two-letter code is checked against the runtime's own region list, a bare word is resolved
+ * as a name or refused, and only a separator-carrying file name is taken on trust, because
+ * nothing can check those without shipping the whole directory listing.
  */
-declare function normalizeFlagCode(value: string | null | undefined): string | null;
+declare function normalizeFlagCode(value: string | null | undefined, locale?: string): string | null;
 /**
  * The country's name, in the reader's language, or null.
  *
@@ -127,6 +135,12 @@ interface FlagAttributeOptions extends FlagOptions {
  * `Intl.DisplayNames`. `label` replaces it and `decorative` drops it. Nothing is ever
  * invented - a subdivision the platform cannot name, or a runtime without `Intl`, renders
  * as decoration rather than putting a bare "ES" into a screen reader.
+ *
+ * The name goes on `title` as well as `alt`, because those two do different jobs and only
+ * one of them is visible: `alt` is what a screen reader reads and what shows when the image
+ * fails, while a POINTER tooltip comes from `title` and from nothing else. A flag with a
+ * name nobody can see on hover is the common complaint, and it is not an accessibility
+ * nicety - the flag is often the only thing in a cell. A decorative flag gets neither.
  */
 declare function flagAttributes(code: string | null | undefined, options?: FlagAttributeOptions): Record<string, string | number> | null;
 

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { E as EstimateOptions, G as GeneratePasswordOptions, P as PasswordAlphab
 export { N as Notification, a as NotificationAction, b as NotificationInput, c as NotificationTone, d as Notifications, e as NotificationsOptions, P as PromiseMessages, f as createNotifications } from './notifications-BpVV6sel.js';
 export { N as NetworkMonitor, a as NetworkState, S as SERVER_NETWORK_STATE, c as createNetworkMonitor } from './network-D2LsBG_k.js';
 export { R as RelativeTimeFormat, a as RelativeTimeOptions, b as RelativeTimePrecision, c as RelativeTimeStyle, d as RelativeTimeTense, e as RelativeTimeView, f as ensureZone, n as normalizeDate, p as parseDuration, r as relativeTimeAttributes, g as relativeTimeView } from './relative-time-YpRTG7YH.js';
-export { F as FLAG_CDN, a as FLAG_RATIO, b as FlagConfig, c as FlagFormat, d as FlagOptions, e as FlagShape, f as FlagSource, g as FlagView, h as configureFlags, i as flagAttributes, j as flagConfig, k as flagName, l as flagSrc, m as flagView, n as normalizeFlagCode, r as resetFlagConfig } from './flags-BBJc9unY.js';
+export { F as FLAG_CDN, a as FLAG_RATIO, b as FlagConfig, c as FlagFormat, d as FlagOptions, e as FlagShape, f as FlagSource, g as FlagView, h as configureFlags, i as flagAttributes, j as flagConfig, k as flagName, l as flagSrc, m as flagView, n as normalizeFlagCode, r as resetFlagConfig } from './flags-BQU1V9rE.js';
 export { P as PaletteKey, a as PositionedRow, R as RecentEntry, b as RecentStore, c as RecentStoreOptions, d as RowGroup, e as createRecentStore, g as groupRows, i as isPaletteShortcut, m as moveActive, r as recentKey, s as shortcutLabel } from './palette-D7iuQh_T.js';
 
 /**

package/dist/index.js

@@ -1,6 +1,6 @@
 export { createInput } from './chunk-KJINGUQN.js';
 export { estimatePasswordStrength, generatePassword } from './chunk-HC2ME5PU.js';
-export { FLAG_CDN, FLAG_RATIO, configureFlags, flagAttributes, flagConfig, flagName, flagSrc, flagView, normalizeFlagCode, resetFlagConfig } from './chunk-AU3H5WIY.js';
+export { FLAG_CDN, FLAG_RATIO, configureFlags, flagAttributes, flagConfig, flagName, flagSrc, flagView, normalizeFlagCode, resetFlagConfig } from './chunk-LMZJBOZG.js';
 export { createMarquee } from './chunk-UOSSNUSC.js';
 export { SERVER_NETWORK_STATE, createNetworkMonitor } from './chunk-2QFTRNAZ.js';
 export { createNotifications } from './chunk-SNYUBXWQ.js';

package/dist/next/index.d.ts

@@ -18,7 +18,7 @@ export { RelativeTime, RelativeTimeProps } from '../react/relative-time.js';
 export { R as RelativeTimeFormat, a as RelativeTimeOptions, b as RelativeTimePrecision, c as RelativeTimeStyle, d as RelativeTimeTense } from '../relative-time-YpRTG7YH.js';
 export { N as Notification, a as NotificationAction, b as NotificationInput, c as NotificationTone, e as NotificationsOptions } from '../notifications-BpVV6sel.js';
 export { Flag, FlagProps } from '../react/flag.js';
-export { c as FlagFormat, d as FlagOptions, e as FlagShape, f as FlagSource, h as configureFlags, i as flagAttributes, k as flagName, l as flagSrc, m as flagView, n as normalizeFlagCode } from '../flags-BBJc9unY.js';
+export { c as FlagFormat, d as FlagOptions, e as FlagShape, f as FlagSource, h as configureFlags, i as flagAttributes, k as flagName, l as flagSrc, m as flagView, n as normalizeFlagCode } from '../flags-BQU1V9rE.js';
 export { PaletteContent, PaletteContextValue, PaletteField, PaletteFooter, PaletteItem, PaletteList, PaletteListProps, PaletteRoot, PaletteRootProps, PaletteRow, PaletteSection, PaletteTrigger, SearchPalette, SearchPaletteProps, usePaletteContext } from '../react/palette.js';
 export { R as RecentEntry, b as RecentStore, e as createRecentStore, g as groupRows, i as isPaletteShortcut, m as moveActive, r as recentKey, s as shortcutLabel } from '../palette-D7iuQh_T.js';
 

package/dist/next/index.js

@@ -1,7 +1,7 @@
 "use client";
 export { useInput } from '../chunk-U3V4EHOB.js';
 export { PasswordStrength } from '../chunk-XQHCZAPJ.js';
-export { Flag } from '../chunk-XNNQRA35.js';
+export { Flag } from '../chunk-NPHRS2Q7.js';
 export { Toaster } from '../chunk-ZCUFYBPB.js';
 export { useMarquee } from '../chunk-ZWR2EXHQ.js';
 export { useSearch } from '../chunk-QQFNAKMY.js';
@@ -10,7 +10,7 @@ export { createNotificationQueue, defaultQueue, useNotifications } from '../chun
 export { RelativeTime } from '../chunk-OCMI7R6H.js';
 import '../chunk-KJINGUQN.js';
 export { estimatePasswordStrength, generatePassword } from '../chunk-HC2ME5PU.js';
-export { configureFlags, flagAttributes, flagName, flagSrc, flagView, normalizeFlagCode } from '../chunk-AU3H5WIY.js';
+export { configureFlags, flagAttributes, flagName, flagSrc, flagView, normalizeFlagCode } from '../chunk-LMZJBOZG.js';
 import '../chunk-UOSSNUSC.js';
 import '../chunk-2QFTRNAZ.js';
 import '../chunk-SNYUBXWQ.js';

package/dist/react/flag.d.ts

@@ -1,5 +1,5 @@
 import { ImgHTMLAttributes, ReactNode } from 'react';
-import { e as FlagShape, c as FlagFormat, f as FlagSource } from '../flags-BBJc9unY.js';
+import { e as FlagShape, c as FlagFormat, f as FlagSource } from '../flags-BQU1V9rE.js';
 
 interface FlagProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "width" | "height"> {
     /** `es`, `ES`, `en-GB`, `gb-eng`, or the emoji flag you are replacing. */

package/dist/react/flag.js

@@ -1,3 +1,3 @@
 "use client";
-export { Flag } from '../chunk-XNNQRA35.js';
-import '../chunk-AU3H5WIY.js';
+export { Flag } from '../chunk-NPHRS2Q7.js';
+import '../chunk-LMZJBOZG.js';

package/dist/react/index.d.ts

@@ -20,7 +20,7 @@ export { RelativeTime, RelativeTimeProps } from './relative-time.js';
 export { R as RelativeTimeFormat, a as RelativeTimeOptions, b as RelativeTimePrecision, c as RelativeTimeStyle, d as RelativeTimeTense } from '../relative-time-YpRTG7YH.js';
 export { N as Notification, a as NotificationAction, b as NotificationInput, c as NotificationTone, e as NotificationsOptions } from '../notifications-BpVV6sel.js';
 export { Flag, FlagProps } from './flag.js';
-export { c as FlagFormat, d as FlagOptions, e as FlagShape, f as FlagSource, h as configureFlags, i as flagAttributes, k as flagName, l as flagSrc, m as flagView, n as normalizeFlagCode } from '../flags-BBJc9unY.js';
+export { c as FlagFormat, d as FlagOptions, e as FlagShape, f as FlagSource, h as configureFlags, i as flagAttributes, k as flagName, l as flagSrc, m as flagView, n as normalizeFlagCode } from '../flags-BQU1V9rE.js';
 export { PaletteContent, PaletteContextValue, PaletteField, PaletteFooter, PaletteItem, PaletteList, PaletteListProps, PaletteRoot, PaletteRootProps, PaletteRow, PaletteSection, PaletteTrigger, SearchPalette, SearchPaletteProps, usePaletteContext } from './palette.js';
 export { R as RecentEntry, b as RecentStore, e as createRecentStore, g as groupRows, i as isPaletteShortcut, m as moveActive, r as recentKey, s as shortcutLabel } from '../palette-D7iuQh_T.js';
 

package/dist/react/index.js

@@ -1,7 +1,7 @@
 "use client";
 export { useInput } from '../chunk-U3V4EHOB.js';
 export { PasswordStrength } from '../chunk-XQHCZAPJ.js';
-export { Flag } from '../chunk-XNNQRA35.js';
+export { Flag } from '../chunk-NPHRS2Q7.js';
 export { Toaster } from '../chunk-ZCUFYBPB.js';
 export { useMarquee } from '../chunk-ZWR2EXHQ.js';
 export { useSearch } from '../chunk-QQFNAKMY.js';
@@ -10,7 +10,7 @@ export { createNotificationQueue, defaultQueue, useNotifications } from '../chun
 export { RelativeTime } from '../chunk-OCMI7R6H.js';
 import '../chunk-KJINGUQN.js';
 export { estimatePasswordStrength, generatePassword } from '../chunk-HC2ME5PU.js';
-export { configureFlags, flagAttributes, flagName, flagSrc, flagView, normalizeFlagCode } from '../chunk-AU3H5WIY.js';
+export { configureFlags, flagAttributes, flagName, flagSrc, flagView, normalizeFlagCode } from '../chunk-LMZJBOZG.js';
 import '../chunk-UOSSNUSC.js';
 import '../chunk-2QFTRNAZ.js';
 import '../chunk-SNYUBXWQ.js';

package/dist/react-router/index.d.ts

@@ -18,7 +18,7 @@ export { RelativeTime, RelativeTimeProps } from '../react/relative-time.js';
 export { R as RelativeTimeFormat, a as RelativeTimeOptions, b as RelativeTimePrecision, c as RelativeTimeStyle, d as RelativeTimeTense } from '../relative-time-YpRTG7YH.js';
 export { N as Notification, a as NotificationAction, b as NotificationInput, c as NotificationTone, e as NotificationsOptions } from '../notifications-BpVV6sel.js';
 export { Flag, FlagProps } from '../react/flag.js';
-export { c as FlagFormat, d as FlagOptions, e as FlagShape, f as FlagSource, h as configureFlags, i as flagAttributes, k as flagName, l as flagSrc, m as flagView, n as normalizeFlagCode } from '../flags-BBJc9unY.js';
+export { c as FlagFormat, d as FlagOptions, e as FlagShape, f as FlagSource, h as configureFlags, i as flagAttributes, k as flagName, l as flagSrc, m as flagView, n as normalizeFlagCode } from '../flags-BQU1V9rE.js';
 export { PaletteContent, PaletteContextValue, PaletteField, PaletteFooter, PaletteItem, PaletteList, PaletteListProps, PaletteRoot, PaletteRootProps, PaletteRow, PaletteSection, PaletteTrigger, SearchPalette, SearchPaletteProps, usePaletteContext } from '../react/palette.js';
 export { R as RecentEntry, b as RecentStore, e as createRecentStore, g as groupRows, i as isPaletteShortcut, m as moveActive, r as recentKey, s as shortcutLabel } from '../palette-D7iuQh_T.js';
 

package/dist/react-router/index.js

@@ -1,7 +1,7 @@
 "use client";
 export { useInput } from '../chunk-U3V4EHOB.js';
 export { PasswordStrength } from '../chunk-XQHCZAPJ.js';
-export { Flag } from '../chunk-XNNQRA35.js';
+export { Flag } from '../chunk-NPHRS2Q7.js';
 export { Toaster } from '../chunk-ZCUFYBPB.js';
 export { useMarquee } from '../chunk-ZWR2EXHQ.js';
 export { useSearch } from '../chunk-QQFNAKMY.js';
@@ -10,7 +10,7 @@ export { createNotificationQueue, defaultQueue, useNotifications } from '../chun
 export { RelativeTime } from '../chunk-OCMI7R6H.js';
 import '../chunk-KJINGUQN.js';
 export { estimatePasswordStrength, generatePassword } from '../chunk-HC2ME5PU.js';
-export { configureFlags, flagAttributes, flagName, flagSrc, flagView, normalizeFlagCode } from '../chunk-AU3H5WIY.js';
+export { configureFlags, flagAttributes, flagName, flagSrc, flagView, normalizeFlagCode } from '../chunk-LMZJBOZG.js';
 import '../chunk-UOSSNUSC.js';
 import '../chunk-2QFTRNAZ.js';
 import '../chunk-SNYUBXWQ.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Headless components: the behaviour, the timing and the accessibility, with no styles of their own. Framework-agnostic core plus thin adapters.",
   "type": "module",
   "sideEffects": [

package/src/core/flags.ts

@@ -106,20 +106,141 @@ const EMOJI_FLAG = /^[\u{1F1E6}-\u{1F1FF}]{2}$/u;
  * two the same string, and then one of them is always wrong.
  */
 const LOCALE_TAG = /^([A-Za-z]{2,3})[-_]([A-Z]{2})$/;
-/** What the sets actually name their files: `es`, `gb-eng`, `au-nsw`, `easter_island`. */
-const FILE_CODE = /^[a-z]{2,}(?:[-_][a-z0-9]+)*$/;
+/**
+ * A SUBDIVISION or a named file, which is the only shape that cannot be checked against
+ * anything: `gb-eng`, `au-nsw`, `es-ct`, `easter_island`. It must carry a separator - that
+ * is what distinguishes a file name from an ordinary word, and without it `banana` was
+ * accepted as a code and rendered as a 404.
+ */
+const FILE_CODE = /^[a-z]{2,}[-_][a-z0-9_-]+$/;
 /** A plain country: exactly the shape `Intl.DisplayNames` can put a name to. */
 const COUNTRY_CODE = /^[a-z]{2}$/;
 
+/**
+ * Accent-, case- and apostrophe-insensitive, so `espana`, `España` and `ESPAÑA` are one
+ * string - and so are `Cote d'Ivoire` and `Côte d’Ivoire`.
+ *
+ * The apostrophe matters more than it looks: CLDR writes the typographic one (U+2019) and
+ * every keyboard, database and API writes the straight one, so a lookup that kept them
+ * apart failed on exactly the countries whose names contain one.
+ */
+function fold(value: string): string {
+    return value
+        .normalize("NFD")
+        .replace(/\p{Diacritic}/gu, "")
+        .replace(/['‘’ʼ`´]/g, "")
+        .toLowerCase()
+        // Three spellings of the same name, and all three are mechanical - CLDR writes
+        // "St. Lucia" and "Trinidad & Tobago", while a form, a database and an API write
+        // "Saint Lucia" and "Trinidad and Tobago". Both sides of the lookup go through this,
+        // so it is a normalization rather than a table of alternative names.
+        .replace(/&/g, " and ")
+        .replace(/\bst\.?\s/g, "saint ")
+        .replace(/^the\s+/, "")
+        .replace(/[.,]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+
+/**
+ * Every two-letter region the runtime can name, folded, mapped back to its code.
+ *
+ * Built by asking `Intl.DisplayNames` for all 676 letter pairs and keeping the ones it has a
+ * name for - which is also how an unknown code is detected, since it echoes the input back.
+ * The runtime already holds this data, translated and maintained; shipping a table of 250
+ * country names would be a copy of it that goes stale.
+ *
+ * Memoized per locale and built only when something that is not a code arrives, so a page
+ * that passes codes never pays for it.
+ */
+const nameIndexes = new Map<string, Map<string, string> | null>();
+
+/**
+ * The code a region is FILED under.
+ *
+ * `Intl.Locale` canonicalizes a deprecated or alias subtag, which is the difference between
+ * a flag and a 404: `UK` is not the ISO code for the United Kingdom (`GB` is), `AN` became
+ * `CW`, `SU` became `RU`. All three have a name, so a name lookup that skipped this step
+ * resolved "United Kingdom" to `uk` and asked for a file that does not exist.
+ */
+function canonicalRegion(code: string): string {
+    try {
+        return new Intl.Locale(`und-${code}`).region?.toLowerCase() ?? code.toLowerCase();
+    } catch {
+        return code.toLowerCase();
+    }
+}
+
+/**
+ * The name the runtime uses for a region it does not know.
+ *
+ * `ZZ` IS that region by definition, so its name is the sentinel: any code the runtime
+ * cannot place comes back either echoing the code (`QQ`) or carrying this exact string, and
+ * both have to be refused. Comparing against `of("ZZ")` rather than the English words keeps
+ * that true in every language.
+ */
+function unknownRegionName(names: Intl.DisplayNames): string | undefined {
+    return names.of("ZZ");
+}
+
+function regionsByName(locale: string): Map<string, string> | null {
+    const cached = nameIndexes.get(locale);
+    if (cached !== undefined) return cached;
+
+    let index: Map<string, string> | null = null;
+    try {
+        const names = new Intl.DisplayNames([locale], { type: "region" });
+        const unknown = unknownRegionName(names);
+        index = new Map();
+        for (let first = 65; first <= 90; first++) {
+            for (let second = 65; second <= 90; second++) {
+                const code = String.fromCharCode(first, second);
+                const name = names.of(code);
+                if (!name || name === code || name === unknown) continue;
+                const key = fold(name);
+                // First wins, and the code is canonical, so an alias can neither overwrite
+                // the real entry nor become one.
+                if (!index.has(key)) index.set(key, canonicalRegion(code));
+            }
+        }
+    } catch {
+        index = null;   // No Intl, or no data for this locale.
+    }
+    nameIndexes.set(locale, index);
+    return index;
+}
+
+/** Whether the runtime knows this two-letter code as a region at all. */
+function isKnownRegion(code: string): boolean {
+    try {
+        const names = new Intl.DisplayNames(["en"], { type: "region" });
+        const upper = code.toUpperCase();
+        const name = names.of(upper);
+        return Boolean(name) && name !== upper && name !== unknownRegionName(names);
+    } catch {
+        // Without Intl there is nothing to check against, and refusing every code would be
+        // worse than passing one through: two letters is the shape of a flag file.
+        return true;
+    }
+}
+
 /**
  * Anything a codebase calls a country into the file name the sets use, or null.
  *
- * Null rather than a guess: a code this cannot resolve would otherwise become a 404 image
- * with no alt text, and a broken flag beside a country name is worse than no flag at all.
- * An emoji flag is accepted and converted, so migrating an existing picker is a rename of
- * the component and nothing else.
+ * What it accepts: a code (`es`, `ES`), a locale tag (`en-GB`, `es_ES`), a subdivision or
+ * named file (`gb-eng`, `au-nsw`, `easter_island`), the emoji flag you are replacing, and
+ * the country's NAME - in English or in the page's own language, accents optional, so
+ * `Spain`, `España` and `espana` all resolve. A name is what a database column or an API
+ * payload usually holds, and requiring the caller to convert it first is how a flag ends up
+ * not being rendered at all.
+ *
+ * Null rather than a guess, and that is the point of the strictness: `banana` used to pass
+ * as a file code and render as a 404 with no alt text, which is worse than no flag. A
+ * two-letter code is checked against the runtime's own region list, a bare word is resolved
+ * as a name or refused, and only a separator-carrying file name is taken on trust, because
+ * nothing can check those without shipping the whole directory listing.
  */
-export function normalizeFlagCode(value: string | null | undefined): string | null {
+export function normalizeFlagCode(value: string | null | undefined, locale?: string): string | null {
     if (!value) return null;
     const raw = value.trim();
     if (!raw) return null;
@@ -129,11 +250,25 @@ export function normalizeFlagCode(value: string | null | undefined): string | nu
         return letters.join("");
     }
 
-    const locale = LOCALE_TAG.exec(raw);
-    if (locale) return locale[2].toLowerCase();
+    const tag = LOCALE_TAG.exec(raw);
+    if (tag) return tag[2].toLowerCase();
 
-    const code = raw.toLowerCase();
-    return FILE_CODE.test(code) ? code : null;
+    const lower = raw.toLowerCase();
+    // Canonical, so `uk` reaches the file the United Kingdom is actually filed under.
+    if (COUNTRY_CODE.test(lower)) return isKnownRegion(lower) ? canonicalRegion(lower) : null;
+    if (FILE_CODE.test(lower)) return lower;
+
+    // A name, then, in this order: the locale you asked for, the page's own, English, and
+    // finally the runtime's. English is always tried because it is what an API or a database
+    // column holds even on a translated page; the runtime's is last so it can rescue a name
+    // nothing else placed without ever overriding a match that was more specific.
+    const folded = fold(raw);
+    for (const candidate of [locale, documentLocale(), "en", runtimeLocale()]) {
+        if (!candidate) continue;
+        const found = regionsByName(candidate)?.get(folded);
+        if (found) return found;
+    }
+    return null;
 }
 
 /**
@@ -161,6 +296,15 @@ export function flagName(code: string | null | undefined, locale?: string): stri
     }
 }
 
+/** Whatever language this runtime is set to - the browser's, or the server's. */
+function runtimeLocale(): string | undefined {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().locale;
+    } catch {
+        return undefined;
+    }
+}
+
 /** The page's own language, which is what a translated page wants the name written in. */
 function documentLocale(): string | undefined {
     if (typeof document === "undefined") return undefined;
@@ -246,6 +390,12 @@ export interface FlagAttributeOptions extends FlagOptions {
  * `Intl.DisplayNames`. `label` replaces it and `decorative` drops it. Nothing is ever
  * invented - a subdivision the platform cannot name, or a runtime without `Intl`, renders
  * as decoration rather than putting a bare "ES" into a screen reader.
+ *
+ * The name goes on `title` as well as `alt`, because those two do different jobs and only
+ * one of them is visible: `alt` is what a screen reader reads and what shows when the image
+ * fails, while a POINTER tooltip comes from `title` and from nothing else. A flag with a
+ * name nobody can see on hover is the common complaint, and it is not an accessibility
+ * nicety - the flag is often the only thing in a cell. A decorative flag gets neither.
  */
 export function flagAttributes(code: string | null | undefined, options: FlagAttributeOptions = {}): Record<string, string | number> | null {
     const view = flagView(code, options);
@@ -261,6 +411,6 @@ export function flagAttributes(code: string | null | undefined, options: FlagAtt
         "data-enigma-flag": "",
         "data-flag-code": view.code,
         "data-flag-shape": view.shape,
-        ...(label ? {} : { "aria-hidden": "true" })
+        ...(label ? { title: label } : { "aria-hidden": "true" })
     };
 }

package/src/react/flag.tsx

@@ -52,6 +52,9 @@ export function Flag({ code, label, decorative = false, locale, shape, format, s
         <img
             src={view.src}
             alt={name}
+            // `alt` is read; `title` is what a pointer shows. Only one of them is visible,
+            // and a flag whose name never appears on hover is the thing people report.
+            title={name || undefined}
             width={view.width}
             height={view.height}
             loading="lazy"