@enigmax/primitives 0.19.1 → 0.21.0

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 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;
 
-    const code = raw.toLowerCase();
-    return FILE_CODE.test(code) ? code : null;
+    // 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;

package/src/react/toast-styles.ts

@@ -0,0 +1,247 @@
+/**
+ * The toast theme, as a string, because `<Toaster />` injects it.
+ *
+ * A toast is the one component where "bring your own CSS" is the wrong default: it is
+ * rendered into a portal at the edge of the screen, it stacks, and it animates - so a
+ * consumer who forgets the stylesheet does not get an unstyled toast, they get a pile of
+ * text in the corner. `<Toaster styles={false} />` turns it off for anyone who wants their
+ * own, and the injected sheet is PREPENDED to `<head>` so any stylesheet in the document
+ * outranks it by source order without needing a single `!important`.
+ *
+ * This module is the source of truth for `recipes/toast/styles.css` too, which
+ * `scripts/sync-recipes.mjs` writes from it - one look, whether it is injected or copied.
+ *
+ * The geometry is the stacked-card pattern: the newest toast is the front one, older ones
+ * sit behind it scaled down and clipped to the front one's height, and hovering the stack
+ * fans them out by the summed height of the ones in front. Every number below is one of
+ * those two states.
+ */
+export const TOAST_STYLES = `
+[data-enigma-toaster] {
+    --enigma-toast-width: 356px;
+    --enigma-toast-edge: 24px;
+    --enigma-toast-gap: 14px;
+    --enigma-toast-peek: 14px;
+    --enigma-toast-scale-step: 0.06;
+    --enigma-toast-radius: 12px;
+    --enigma-toast-enter: 420ms;
+    --enigma-toast-exit: 350ms;
+
+    --enigma-toast-bg: #101010;
+    --enigma-toast-border: #2a2a2a;
+    --enigma-toast-text: #f5f5f5;
+    --enigma-toast-muted: #a3a3a3;
+    --enigma-toast-shadow: 0 6px 22px rgb(0 0 0 / 34%);
+
+    --enigma-toast-success: hsl(150 80% 72%);
+    --enigma-toast-success-bg: hsl(150 38% 9%);
+    --enigma-toast-success-border: hsl(147 55% 18%);
+    --enigma-toast-error: hsl(358 100% 82%);
+    --enigma-toast-error-bg: hsl(358 42% 12%);
+    --enigma-toast-error-border: hsl(357 55% 24%);
+    --enigma-toast-info: hsl(216 87% 74%);
+    --enigma-toast-info-bg: hsl(215 45% 11%);
+    --enigma-toast-info-border: hsl(223 50% 24%);
+    --enigma-toast-warning: hsl(46 87% 70%);
+    --enigma-toast-warning-bg: hsl(40 55% 9%);
+    --enigma-toast-warning-border: hsl(40 55% 20%);
+
+    position: fixed;
+    z-index: 999999;
+    width: var(--enigma-toast-width);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    outline: none;
+    font-family: inherit;
+    font-size: 13px;
+    /* The stack is a positioning context: every toast is absolute inside it, which is what
+       lets the ones behind be clipped to the front one's height. */
+    transition: transform 350ms ease;
+}
+
+@media (prefers-color-scheme: light) {
+    [data-enigma-toaster] {
+        --enigma-toast-bg: #ffffff;
+        --enigma-toast-border: #e5e5e5;
+        --enigma-toast-text: #171717;
+        --enigma-toast-muted: #737373;
+        --enigma-toast-shadow: 0 6px 22px rgb(0 0 0 / 12%);
+        --enigma-toast-success-bg: hsl(143 85% 96%);
+        --enigma-toast-success-border: hsl(145 92% 87%);
+        --enigma-toast-success: hsl(140 100% 27%);
+        --enigma-toast-error-bg: hsl(359 100% 97%);
+        --enigma-toast-error-border: hsl(359 100% 94%);
+        --enigma-toast-error: hsl(360 100% 45%);
+        --enigma-toast-info-bg: hsl(208 100% 97%);
+        --enigma-toast-info-border: hsl(221 91% 93%);
+        --enigma-toast-info: hsl(210 92% 45%);
+        --enigma-toast-warning-bg: hsl(49 100% 97%);
+        --enigma-toast-warning-border: hsl(49 91% 84%);
+        --enigma-toast-warning: hsl(31 92% 45%);
+    }
+}
+
+[data-enigma-toaster][data-position^="top"] { top: var(--enigma-toast-edge); }
+[data-enigma-toaster][data-position^="bottom"] { bottom: var(--enigma-toast-edge); }
+[data-enigma-toaster][data-position$="-right"] { right: var(--enigma-toast-edge); }
+[data-enigma-toaster][data-position$="-left"] { left: var(--enigma-toast-edge); }
+[data-enigma-toaster][data-position$="-center"] { left: 50%; transform: translateX(-50%); }
+/* The whole stack lifts a little when it fans out, so the front toast does not sit on the
+   exact pixel it did a moment ago. */
+[data-enigma-toaster][data-expanded][data-position^="bottom"] { transform: translateY(-6px); }
+[data-enigma-toaster][data-expanded][data-position^="top"] { transform: translateY(6px); }
+[data-enigma-toaster][data-expanded][data-position="bottom-center"] { transform: translateX(-50%) translateY(-6px); }
+[data-enigma-toaster][data-expanded][data-position="top-center"] { transform: translateX(-50%) translateY(6px); }
+
+[data-enigma-toast] {
+    position: absolute;
+    left: 0;
+    right: 0;
+    width: 100%;
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 15px 16px;
+    color: var(--enigma-toast-text);
+    background: var(--enigma-toast-bg);
+    border: 1px solid var(--enigma-toast-border);
+    border-radius: var(--enigma-toast-radius);
+    box-shadow: var(--enigma-toast-shadow);
+    overflow-wrap: anywhere;
+    touch-action: none;
+    outline: none;
+    z-index: var(--enigma-toast-z, 1);
+    transition:
+        transform var(--enigma-toast-enter) cubic-bezier(0.21, 1.02, 0.73, 1),
+        opacity var(--enigma-toast-exit),
+        height 350ms;
+}
+
+[data-enigma-toaster][data-position^="bottom"] [data-enigma-toast] { bottom: 0; transform-origin: bottom center; }
+[data-enigma-toaster][data-position^="top"] [data-enigma-toast] { top: 0; transform-origin: top center; }
+
+/* Enter from off screen, in the direction the stack is pinned to. */
+[data-enigma-toaster][data-position^="bottom"] [data-enigma-toast] { transform: translateY(110%); opacity: 0; }
+[data-enigma-toaster][data-position^="top"] [data-enigma-toast] { transform: translateY(-110%); opacity: 0; }
+/* Scoped to the toaster so it OUTRANKS the enter rules above, which are scoped the same
+   way: at equal specificity the later rule wins, and a mounted toast that lost this one sat
+   at its entry offset forever - visible, and 110% of its own height off the bottom. */
+[data-enigma-toaster] [data-enigma-toast][data-mounted] { opacity: 1; transform: translateY(0); }
+
+/* Collapsed: the ones behind are clipped to the FRONT toast's height and scaled back, so
+   the stack reads as depth rather than as a list. Their content is hidden but present -
+   removing it would make the box jump when the stack expands. */
+[data-enigma-toaster]:not([data-expanded]) [data-enigma-toast][data-mounted]:not([data-front]) {
+    height: var(--enigma-toast-front-height);
+    transform: translateY(calc(var(--enigma-toast-before) * var(--enigma-toast-peek) * -1))
+        scale(calc(1 - var(--enigma-toast-before) * var(--enigma-toast-scale-step)));
+}
+[data-enigma-toaster][data-position^="top"]:not([data-expanded]) [data-enigma-toast][data-mounted]:not([data-front]) {
+    transform: translateY(calc(var(--enigma-toast-before) * var(--enigma-toast-peek)))
+        scale(calc(1 - var(--enigma-toast-before) * var(--enigma-toast-scale-step)));
+}
+[data-enigma-toaster]:not([data-expanded]) [data-enigma-toast]:not([data-front]) > * { opacity: 0; }
+[data-enigma-toast] > * { transition: opacity 350ms; }
+
+/* Expanded: each toast is lifted by the summed height of the ones in front of it. */
+[data-enigma-toaster][data-expanded][data-position^="bottom"] [data-enigma-toast][data-mounted] {
+    transform: translateY(calc(var(--enigma-toast-offset) * -1));
+}
+[data-enigma-toaster][data-expanded][data-position^="top"] [data-enigma-toast][data-mounted] {
+    transform: translateY(var(--enigma-toast-offset));
+}
+
+/* Past the visible count it is still in the DOM, still counted, and not on screen. */
+[data-enigma-toast][data-hidden] { opacity: 0; pointer-events: none; }
+
+[data-enigma-toast][data-state="leaving"] { opacity: 0; }
+[data-enigma-toaster]:not([data-expanded]) [data-enigma-toast][data-state="leaving"] { transform: translateY(150%) scale(0.9); }
+[data-enigma-toaster][data-expanded][data-position^="bottom"] [data-enigma-toast][data-state="leaving"] {
+    transform: translateY(calc(var(--enigma-toast-offset) * -1 + 110%));
+}
+
+/* While a finger is down the toast tracks it exactly: a transition here would lag behind the
+   pointer, which reads as a broken gesture rather than a smooth one. */
+[data-enigma-toast][data-swiping] {
+    transition: opacity 200ms;
+    transform: translateX(var(--enigma-toast-swipe, 0px));
+}
+
+[data-enigma-toast]:focus-visible { box-shadow: var(--enigma-toast-shadow), 0 0 0 2px var(--enigma-toast-info); }
+
+[data-enigma-toast][data-tone="success"] {
+    color: var(--enigma-toast-success);
+    background: var(--enigma-toast-success-bg);
+    border-color: var(--enigma-toast-success-border);
+}
+[data-enigma-toast][data-tone="error"] {
+    color: var(--enigma-toast-error);
+    background: var(--enigma-toast-error-bg);
+    border-color: var(--enigma-toast-error-border);
+}
+[data-enigma-toast][data-tone="info"] {
+    color: var(--enigma-toast-info);
+    background: var(--enigma-toast-info-bg);
+    border-color: var(--enigma-toast-info-border);
+}
+[data-enigma-toast][data-tone="warning"] {
+    color: var(--enigma-toast-warning);
+    background: var(--enigma-toast-warning-bg);
+    border-color: var(--enigma-toast-warning-border);
+}
+
+[data-enigma-toast-icon] { display: flex; flex-shrink: 0; width: 20px; height: 20px; }
+[data-enigma-toast-icon] svg { width: 20px; height: 20px; display: block; }
+[data-enigma-toast-icon][data-tone="loading"] svg { animation: enigma-toast-spin 900ms linear infinite; }
+@keyframes enigma-toast-spin { to { transform: rotate(360deg); } }
+
+[data-enigma-toast-content] { display: flex; flex-direction: column; gap: 3px; min-width: 0; flex: 1; }
+[data-enigma-toast-title] { margin: 0; font-weight: 600; line-height: 1.4; }
+[data-enigma-toast-body] { margin: 0; font-size: 12px; line-height: 1.45; opacity: 0.75; }
+
+[data-enigma-toast-action] {
+    flex-shrink: 0;
+    padding: 5px 10px;
+    font: inherit;
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--enigma-toast-bg);
+    background: currentColor;
+    border: 0;
+    border-radius: 6px;
+    cursor: pointer;
+}
+
+[data-enigma-toast-close] {
+    flex-shrink: 0;
+    display: grid;
+    place-items: center;
+    width: 20px;
+    height: 20px;
+    padding: 0;
+    color: inherit;
+    background: none;
+    border: 0;
+    border-radius: 5px;
+    cursor: pointer;
+    /* Shown on hover or focus, so it never covers the message while it is being read - but
+       always reachable by keyboard, which display:none would take away. */
+    opacity: 0;
+    transition: opacity 120ms ease-out;
+}
+[data-enigma-toast]:hover [data-enigma-toast-close],
+[data-enigma-toast-close]:focus-visible { opacity: 0.7; }
+[data-enigma-toast-close]:hover { opacity: 1; }
+
+@media (max-width: 600px) {
+    [data-enigma-toaster] { right: 14px; left: 14px; width: auto; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    /* The movement goes, the state change stays: a toast still appears and still leaves. */
+    [data-enigma-toast], [data-enigma-toast] > * { transition: opacity 200ms !important; }
+    [data-enigma-toast][data-mounted] { transform: none !important; }
+}
+`;