@enigmax/primitives 0.15.0 → 0.17.0

package/dist/{chunk-53DQY6LP.js → chunk-4GLYRF4B.js}

@@ -346,11 +346,11 @@ function createInput(input, options = {}) {
     return typeof opts.reveal === "object" ? opts.reveal : {};
   }
   function revealAction() {
-    const config = revealConfig();
+    const config2 = revealConfig();
     return {
       name: "reveal",
-      label: (current) => current.revealed ? config.hideLabel ?? "Hide password" : config.showLabel ?? "Show password",
-      icon: (current) => current.revealed ? config.hideIcon ?? EYE_OFF : config.showIcon ?? EYE,
+      label: (current) => current.revealed ? config2.hideLabel ?? "Hide password" : config2.showLabel ?? "Show password",
+      icon: (current) => current.revealed ? config2.hideIcon ?? EYE_OFF : config2.showIcon ?? EYE,
       pressed: (current) => current.revealed,
       onSelect: () => setRevealed(!revealed)
     };
@@ -1161,4 +1161,99 @@ function relativeTimeAttributes(view, options = {}) {
   return out;
 }
 
-export { INPUT_ICON_PATHS, SERVER_NETWORK_STATE, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, generatePassword, iconMarkup, normalizeDate, parseDuration, relativeTimeAttributes, relativeTimeView };
+// src/core/flags.ts
+var FLAG_ICONS_VERSION = "7.5.0";
+var CIRCLE_FLAGS_REF = "gh-pages";
+var DEFAULTS2 = {
+  shape: "rect",
+  format: "svg",
+  source: "cdn",
+  basePath: "/flags",
+  size: 16
+};
+var config = { ...DEFAULTS2 };
+function configureFlags(patch) {
+  config = { ...config, ...patch };
+  return config;
+}
+function flagConfig() {
+  return config;
+}
+function resetFlagConfig() {
+  config = { ...DEFAULTS2 };
+  return config;
+}
+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]+)*$/;
+function normalizeFlagCode(value) {
+  if (!value) return null;
+  const raw = value.trim();
+  if (!raw) return null;
+  if (EMOJI_FLAG.test(raw)) {
+    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;
+}
+function cdnUrl(code, shape) {
+  if (shape === "circle") return `https://cdn.jsdelivr.net/gh/HatScripts/circle-flags@${CIRCLE_FLAGS_REF}/flags/${code}.svg`;
+  const size = shape === "square" ? "1x1" : "4x3";
+  return `https://cdn.jsdelivr.net/npm/flag-icons@${FLAG_ICONS_VERSION}/flags/${size}/${code}.svg`;
+}
+var warnedAboutFormat = false;
+function flagSrc(code, options = {}) {
+  const settings = { ...config, ...options };
+  const normalized = normalizeFlagCode(code);
+  if (!normalized) return null;
+  const remoteCdn = settings.source === "cdn";
+  let format2 = settings.format;
+  if (remoteCdn && format2 !== "svg") {
+    if (!warnedAboutFormat && typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+      warnedAboutFormat = true;
+      console.warn(`[enigma/flags] The flag CDNs publish SVG only, so "${format2}" was served as SVG. Download a local set for raster formats: enigma add flags --flags local --flag-formats ${format2}`);
+    }
+    format2 = "svg";
+  }
+  if (remoteCdn) return cdnUrl(normalized, settings.shape);
+  const base = (settings.source === "local" ? settings.basePath : settings.source).replace(/\/+$/, "");
+  return `${base}/${settings.shape}/${normalized}.${format2}`;
+}
+function flagView(code, options = {}) {
+  const settings = { ...config, ...options };
+  const normalized = normalizeFlagCode(code);
+  const src = flagSrc(normalized, options);
+  if (!normalized || !src) return null;
+  const height = Math.max(1, Math.round(settings.size));
+  return {
+    code: normalized,
+    src,
+    shape: settings.shape,
+    format: settings.source === "cdn" ? "svg" : settings.format,
+    width: Math.round(height * FLAG_RATIO[settings.shape]),
+    height
+  };
+}
+function flagAttributes(code, options = {}) {
+  const view = flagView(code, options);
+  if (!view) return null;
+  const label = options.label?.trim();
+  return {
+    src: view.src,
+    alt: label ?? "",
+    width: view.width,
+    height: view.height,
+    loading: "lazy",
+    decoding: "async",
+    "data-enigma-flag": "",
+    "data-flag-code": view.code,
+    "data-flag-shape": view.shape,
+    ...label ? {} : { "aria-hidden": "true" }
+  };
+}
+
+export { CIRCLE_FLAGS_REF, FLAG_ICONS_VERSION, FLAG_RATIO, INPUT_ICON_PATHS, SERVER_NETWORK_STATE, configureFlags, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, flagAttributes, flagConfig, flagSrc, flagView, generatePassword, iconMarkup, normalizeDate, normalizeFlagCode, parseDuration, relativeTimeAttributes, relativeTimeView, resetFlagConfig };

package/dist/{chunk-U2KYYMBJ.js → chunk-JFNND6P4.js}

@@ -1,4 +1,4 @@
-import { generatePassword, estimatePasswordStrength, INPUT_ICON_PATHS, createNotifications, createButton, createMarquee, createInput, createNetworkMonitor, SERVER_NETWORK_STATE, relativeTimeView, relativeTimeAttributes } from './chunk-53DQY6LP.js';
+import { generatePassword, estimatePasswordStrength, INPUT_ICON_PATHS, createNotifications, createButton, createMarquee, createInput, createNetworkMonitor, SERVER_NETWORK_STATE, relativeTimeView, relativeTimeAttributes, flagView } from './chunk-4GLYRF4B.js';
 import { createSearch } from './chunk-UZFEEFMF.js';
 import { forwardRef, createElement, useRef, useState, useId, useCallback, useEffect, useMemo, useSyncExternalStore, useLayoutEffect } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -720,5 +720,30 @@ function RelativeTime({
   const { prefix: prefixAttribute, ...attributes } = relativeTimeAttributes(view, options);
   return createElement("relative-time", { ...attributes, ...marks, ...rest, ref: applyPrefix }, view.label);
 }
+function Flag({ code, label, shape, format, source, basePath, size, fallback = null, ...rest }) {
+  const options = { shape, format, source, basePath, size };
+  for (const key of Object.keys(options)) {
+    if (options[key] === void 0) delete options[key];
+  }
+  const view = flagView(code, options);
+  if (!view) return fallback;
+  const name = label?.trim();
+  return /* @__PURE__ */ jsx(
+    "img",
+    {
+      src: view.src,
+      alt: name ?? "",
+      width: view.width,
+      height: view.height,
+      loading: "lazy",
+      decoding: "async",
+      "aria-hidden": name ? void 0 : true,
+      "data-enigma-flag": "",
+      "data-flag-code": view.code,
+      "data-flag-shape": view.shape,
+      ...rest
+    }
+  );
+}
 
-export { Button, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch };
+export { Button, Flag, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch };

package/dist/index.d.ts

@@ -514,4 +514,110 @@ declare function relativeTimeView(value: string | number | Date | null | undefin
  */
 declare function relativeTimeAttributes(view: RelativeTimeView, options?: RelativeTimeOptions): Record<string, string>;
 
-export { type ButtonCooldown, type ButtonElement, type ButtonInstance, type ButtonOptions, type ButtonState, type EstimateOptions, type GeneratePasswordOptions, INPUT_ICON_PATHS, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, type NetworkMonitor, type NetworkState, type Notification, type NotificationAction, type NotificationInput, type NotificationTone, type Notifications, type NotificationsOptions, type PasswordAlphabet, type PasswordScore, type PasswordStrengthReport, type PromiseMessages, type RelativeTimeFormat, type RelativeTimeOptions, type RelativeTimePrecision, type RelativeTimeStyle, type RelativeTimeTense, type RelativeTimeView, SERVER_NETWORK_STATE, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, generatePassword, iconMarkup, normalizeDate, parseDuration, relativeTimeAttributes, relativeTimeView };
+/**
+ * Country flags as ASSETS, which is the only form of them that renders everywhere.
+ *
+ * The emoji flag is the thing this replaces. It is a pair of regional-indicator code
+ * points, and the glyph for that pair exists only where the platform ships one: Windows
+ * has never shipped country flags in Segoe UI Emoji, so `\u{1F1EA}\u{1F1F8}` renders as
+ * the letters "ES" for the largest desktop platform there is - and a language picker built
+ * out of them looks broken to those readers, with nothing in the code to explain why.
+ * There is no font stack that fixes it, so the fix is not a font: it is an image.
+ *
+ * Two upstream sets, both SVG, both installable or served from a CDN:
+ *
+ * - `rect` / `square` - lipis/flag-icons (`flags/4x3`, `flags/1x1`), the classic
+ *   rectangular set, 271 flags plus subdivisions.
+ * - `circle` - HatScripts/circle-flags (`flags/*.svg` on its gh-pages branch), 445 round
+ *   flags, which is what a flag next to an avatar or inside a chip usually wants.
+ *
+ * Nothing here touches the DOM, so it renders on a server.
+ */
+type FlagShape = "rect" | "square" | "circle";
+/**
+ * `svg` is the only format the two upstreams publish, so it is the only one a CDN can
+ * serve. `png` and `webp` exist for a LOCAL set (`enigma add flags --flags local
+ * --flag-formats webp`), which rasterises what it downloads, and for a mirror of your own.
+ */
+type FlagFormat = "svg" | "png" | "webp";
+/**
+ * Where the files come from.
+ *
+ * - `"cdn"` - jsDelivr, straight from the two upstream projects. Nothing to install.
+ * - `"local"` - files under `basePath` in your own public directory.
+ * - any URL - a mirror of your own with the same layout as the local one
+ *   (`<base>/<shape>/<code>.<format>`), which is exactly the tree the downloader writes.
+ */
+type FlagSource = "cdn" | "local" | (string & {});
+/** Pinned so an upgrade upstream is a decision here, never a surprise in production. */
+declare const FLAG_ICONS_VERSION = "7.5.0";
+/** circle-flags publishes from a branch, not a tag; gh-pages is its default branch. */
+declare const CIRCLE_FLAGS_REF = "gh-pages";
+interface FlagOptions {
+    shape?: FlagShape;
+    format?: FlagFormat;
+    source?: FlagSource;
+    /** Where a local set is served from. Default `/flags`. */
+    basePath?: string;
+    /** Rendered HEIGHT in px. The width follows the shape's ratio. Default 16. */
+    size?: number;
+}
+interface FlagConfig extends Required<Omit<FlagOptions, "size">> {
+    size: number;
+}
+/**
+ * Set the defaults for every flag on the page, once, at startup.
+ *
+ * This is what makes the CDN/local decision a one-line change rather than a prop on every
+ * call site: `configureFlags({ source: "local" })` moves the whole app onto the files the
+ * downloader wrote, and nothing else in the codebase mentions where a flag comes from.
+ */
+declare function configureFlags(patch: Partial<FlagConfig>): FlagConfig;
+declare function flagConfig(): FlagConfig;
+/** Test seam and a way back to the shipped defaults. */
+declare function resetFlagConfig(): FlagConfig;
+/** Width / height of each shape. The circle set is square; only `rect` is 4:3. */
+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.
+ */
+declare function normalizeFlagCode(value: string | null | undefined): string | null;
+/** Everything a renderer needs, computed in one pass. Null when the code is unusable. */
+interface FlagView {
+    /** The upstream file name, e.g. `es`, `gb-eng`. */
+    code: string;
+    src: string;
+    shape: FlagShape;
+    format: FlagFormat;
+    width: number;
+    height: number;
+}
+/**
+ * The URL for one flag. Null when the code cannot be resolved.
+ *
+ * A raster format asked of the CDN falls back to SVG rather than producing a 404: neither
+ * upstream publishes anything but SVG, so `format: "webp"` is only meaningful against a
+ * local set or a mirror. It says so once, in development, instead of silently disagreeing
+ * with what the call site asked for.
+ */
+declare function flagSrc(code: string | null | undefined, options?: FlagOptions): string | null;
+/** `flagSrc` plus the resolved geometry, for a renderer that has to size the box. */
+declare function flagView(code: string | null | undefined, options?: FlagOptions): FlagView | null;
+/**
+ * Attributes for a plain `<img>`, for vanilla, Astro and any template language.
+ *
+ * `label` is the accessible name and there is no default for it: a flag with no label is
+ * DECORATIVE (empty alt, `aria-hidden`), which is correct beside a country name and is the
+ * common case. Inventing one from the code would put "ES" or "es" into a screen reader,
+ * and a country name guessed in the reader's wrong language is worse than silence.
+ */
+declare function flagAttributes(code: string | null | undefined, options?: FlagOptions & {
+    label?: string;
+}): Record<string, string | number> | null;
+
+export { type ButtonCooldown, type ButtonElement, type ButtonInstance, type ButtonOptions, type ButtonState, CIRCLE_FLAGS_REF, type EstimateOptions, FLAG_ICONS_VERSION, FLAG_RATIO, type FlagConfig, type FlagFormat, type FlagOptions, type FlagShape, type FlagSource, type FlagView, type GeneratePasswordOptions, INPUT_ICON_PATHS, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, type NetworkMonitor, type NetworkState, type Notification, type NotificationAction, type NotificationInput, type NotificationTone, type Notifications, type NotificationsOptions, type PasswordAlphabet, type PasswordScore, type PasswordStrengthReport, type PromiseMessages, type RelativeTimeFormat, type RelativeTimeOptions, type RelativeTimePrecision, type RelativeTimeStyle, type RelativeTimeTense, type RelativeTimeView, SERVER_NETWORK_STATE, configureFlags, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, flagAttributes, flagConfig, flagSrc, flagView, generatePassword, iconMarkup, normalizeDate, normalizeFlagCode, parseDuration, relativeTimeAttributes, relativeTimeView, resetFlagConfig };

package/dist/index.js

@@ -1,2 +1,2 @@
-export { INPUT_ICON_PATHS, SERVER_NETWORK_STATE, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, generatePassword, iconMarkup, normalizeDate, parseDuration, relativeTimeAttributes, relativeTimeView } from './chunk-53DQY6LP.js';
+export { CIRCLE_FLAGS_REF, FLAG_ICONS_VERSION, FLAG_RATIO, INPUT_ICON_PATHS, SERVER_NETWORK_STATE, configureFlags, createButton, createInput, createMarquee, createNetworkMonitor, createNotifications, ensureZone, estimatePasswordStrength, flagAttributes, flagConfig, flagSrc, flagView, generatePassword, iconMarkup, normalizeDate, normalizeFlagCode, parseDuration, relativeTimeAttributes, relativeTimeView, resetFlagConfig } from './chunk-4GLYRF4B.js';
 export { createSearch } from './chunk-UZFEEFMF.js';

package/dist/next/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ButtonProps } from '../react/index.js';
-export { BreachChecker, BreachState, BreachStatus, FieldAction, Input, InputProps, PasswordStrength, PasswordStrengthProps, RelativeTime, RelativeTimeProps, ToastControls, ToastPosition, Toaster, ToasterProps, UseButtonResult, UseInputResult, UseMarqueeResult, UseNotificationsResult, UseSearchResult, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../react/index.js';
-export { ButtonOptions, ButtonState, EstimateOptions, GeneratePasswordOptions, InputAction, InputIcon, InputOptions, MarqueeHover, MarqueeInstance, MarqueeOptions, NetworkState, PasswordScore, PasswordStrengthReport, estimatePasswordStrength, generatePassword } from '../index.js';
+export { BreachChecker, BreachState, BreachStatus, FieldAction, Flag, FlagProps, Input, InputProps, PasswordStrength, PasswordStrengthProps, RelativeTime, RelativeTimeProps, ToastControls, ToastPosition, Toaster, ToasterProps, UseButtonResult, UseInputResult, UseMarqueeResult, UseNotificationsResult, UseSearchResult, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../react/index.js';
+export { ButtonOptions, ButtonState, EstimateOptions, FlagFormat, FlagOptions, FlagShape, FlagSource, GeneratePasswordOptions, InputAction, InputIcon, InputOptions, MarqueeHover, MarqueeInstance, MarqueeOptions, NetworkState, PasswordScore, PasswordStrengthReport, configureFlags, estimatePasswordStrength, flagAttributes, flagSrc, flagView, generatePassword, normalizeFlagCode } from '../index.js';
 export { F as FuseConstructor, b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 
 /**

package/dist/next/index.js

@@ -1,7 +1,7 @@
 "use client";
-import { Button } from '../chunk-U2KYYMBJ.js';
-export { Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-U2KYYMBJ.js';
-export { estimatePasswordStrength, generatePassword } from '../chunk-53DQY6LP.js';
+import { Button } from '../chunk-JFNND6P4.js';
+export { Flag, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-JFNND6P4.js';
+export { configureFlags, estimatePasswordStrength, flagAttributes, flagSrc, flagView, generatePassword, normalizeFlagCode } from '../chunk-4GLYRF4B.js';
 import '../chunk-UZFEEFMF.js';
 import Link from 'next/link';
 import { forwardRef, createElement } from 'react';

package/dist/react/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
-import { ComponentPropsWithoutRef, ElementType, ReactNode, RefObject, CSSProperties, HTMLAttributes } from 'react';
-import { ButtonOptions, ButtonState, MarqueeOptions, InputOptions, GeneratePasswordOptions, EstimateOptions, PasswordStrengthReport, Notifications, Notification, NotificationsOptions, NetworkState, RelativeTimeOptions } from '../index.js';
-export { InputAction, InputIcon, MarqueeHover, MarqueeInstance, PasswordScore, estimatePasswordStrength, generatePassword } from '../index.js';
+import { ComponentPropsWithoutRef, ElementType, ReactNode, RefObject, CSSProperties, HTMLAttributes, ImgHTMLAttributes } from 'react';
+import { ButtonOptions, ButtonState, MarqueeOptions, InputOptions, GeneratePasswordOptions, EstimateOptions, PasswordStrengthReport, Notifications, Notification, NotificationsOptions, NetworkState, RelativeTimeOptions, FlagShape, FlagFormat, FlagSource } from '../index.js';
+export { FlagOptions, InputAction, InputIcon, MarqueeHover, MarqueeInstance, PasswordScore, configureFlags, estimatePasswordStrength, flagAttributes, flagSrc, flagView, generatePassword, normalizeFlagCode } from '../index.js';
 import { b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 export { F as FuseConstructor } from '../search-CsO3L1Lw.js';
 
@@ -373,4 +373,30 @@ interface RelativeTimeProps extends RelativeTimeOptions, Omit<HTMLAttributes<HTM
 }
 declare function RelativeTime({ date, fallback, capitalize, capitalizeFirst, now, format, tense, precision, threshold, prefix, formatStyle, locale, timeZone, second, minute, hour, weekday, day, month, year, timeZoneName, noTitle, numericBeyondThreshold, ...rest }: RelativeTimeProps): ReactNode;
 
-export { type BreachChecker, type BreachState, type BreachStatus, Button, ButtonOptions, type ButtonProps, ButtonState, EstimateOptions, type FieldAction, GeneratePasswordOptions, Input, InputOptions, type InputProps, MarqueeOptions, NetworkState, PasswordStrength, type PasswordStrengthProps, PasswordStrengthReport, RelativeTime, type RelativeTimeProps, SearchMatch, SearchOptions, type ToastControls, type ToastPosition, Toaster, type ToasterProps, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseNotificationsResult, type UseSearchResult, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch };
+interface FlagProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "width" | "height"> {
+    /** `es`, `ES`, `en-GB`, `gb-eng`, or the emoji flag you are replacing. */
+    code: string | null | undefined;
+    /**
+     * The accessible name. Leave it out and the flag is decorative, which is what it is
+     * beside a country name - the reader hears the name once instead of twice.
+     */
+    label?: string;
+    shape?: FlagShape;
+    format?: FlagFormat;
+    source?: FlagSource;
+    basePath?: string;
+    /** Rendered height in px. The width follows the shape. Default 16. */
+    size?: number;
+    /** Rendered when the code resolves to nothing. Nothing, by default. */
+    fallback?: ReactNode;
+}
+/**
+ * `<Flag code="es" />` - a country flag as an image, at the size you asked for, from the
+ * source the app configured once.
+ *
+ * The defaults come from `configureFlags`, so moving the whole application from the CDN to
+ * a downloaded set is one line at startup and no change at any call site.
+ */
+declare function Flag({ code, label, shape, format, source, basePath, size, fallback, ...rest }: FlagProps): ReactNode;
+
+export { type BreachChecker, type BreachState, type BreachStatus, Button, ButtonOptions, type ButtonProps, ButtonState, EstimateOptions, type FieldAction, Flag, FlagFormat, type FlagProps, FlagShape, FlagSource, GeneratePasswordOptions, Input, InputOptions, type InputProps, MarqueeOptions, NetworkState, PasswordStrength, type PasswordStrengthProps, PasswordStrengthReport, RelativeTime, type RelativeTimeProps, SearchMatch, SearchOptions, type ToastControls, type ToastPosition, Toaster, type ToasterProps, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseNotificationsResult, type UseSearchResult, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch };

package/dist/react/index.js

@@ -1,4 +1,4 @@
 "use client";
-export { Button, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-U2KYYMBJ.js';
-export { estimatePasswordStrength, generatePassword } from '../chunk-53DQY6LP.js';
+export { Button, Flag, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-JFNND6P4.js';
+export { configureFlags, estimatePasswordStrength, flagAttributes, flagSrc, flagView, generatePassword, normalizeFlagCode } from '../chunk-4GLYRF4B.js';
 import '../chunk-UZFEEFMF.js';

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

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ButtonProps } from '../react/index.js';
-export { BreachChecker, BreachState, BreachStatus, FieldAction, Input, InputProps, PasswordStrength, PasswordStrengthProps, RelativeTime, RelativeTimeProps, ToastControls, ToastPosition, Toaster, ToasterProps, UseButtonResult, UseInputResult, UseMarqueeResult, UseNotificationsResult, UseSearchResult, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../react/index.js';
-export { ButtonOptions, ButtonState, EstimateOptions, GeneratePasswordOptions, InputAction, InputIcon, InputOptions, MarqueeHover, MarqueeInstance, MarqueeOptions, NetworkState, PasswordScore, PasswordStrengthReport, estimatePasswordStrength, generatePassword } from '../index.js';
+export { BreachChecker, BreachState, BreachStatus, FieldAction, Flag, FlagProps, Input, InputProps, PasswordStrength, PasswordStrengthProps, RelativeTime, RelativeTimeProps, ToastControls, ToastPosition, Toaster, ToasterProps, UseButtonResult, UseInputResult, UseMarqueeResult, UseNotificationsResult, UseSearchResult, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../react/index.js';
+export { ButtonOptions, ButtonState, EstimateOptions, FlagFormat, FlagOptions, FlagShape, FlagSource, GeneratePasswordOptions, InputAction, InputIcon, InputOptions, MarqueeHover, MarqueeInstance, MarqueeOptions, NetworkState, PasswordScore, PasswordStrengthReport, configureFlags, estimatePasswordStrength, flagAttributes, flagSrc, flagView, generatePassword, normalizeFlagCode } from '../index.js';
 export { F as FuseConstructor, b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLElement>>;

package/dist/react-router/index.js

@@ -1,7 +1,7 @@
 "use client";
-import { Button } from '../chunk-U2KYYMBJ.js';
-export { Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-U2KYYMBJ.js';
-export { estimatePasswordStrength, generatePassword } from '../chunk-53DQY6LP.js';
+import { Button } from '../chunk-JFNND6P4.js';
+export { Flag, Input, PasswordStrength, RelativeTime, Toaster, createNotificationQueue, defaultQueue, getLinkComponent, setLinkComponent, useButton, useInput, useMarquee, useNetworkState, useNotifications, useSearch } from '../chunk-JFNND6P4.js';
+export { configureFlags, estimatePasswordStrength, flagAttributes, flagSrc, flagView, generatePassword, normalizeFlagCode } from '../chunk-4GLYRF4B.js';
 import '../chunk-UZFEEFMF.js';
 import { Link } from 'react-router';
 import { forwardRef, createElement } from 'react';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enigmax/primitives",
-  "version": "0.15.0",
+  "version": "0.17.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",
   "main": "./dist/index.js",
@@ -92,6 +92,8 @@
   "keywords": [
     "carousel",
     "enigma",
+    "flag-icons",
+    "flags",
     "fuse",
     "headless",
     "input",

package/recipes/logo-marquee/index.tsx

@@ -14,9 +14,22 @@ import { useMarquee, type MarqueeHover } from "@enigmax/primitives/react";
  */
 
 export type LogoItem =
+    /**
+     * A URL, which is the whole entry for most logos:
+     * `logos={["/logos/claude.svg", "/logos/openai.svg"]}`.
+     *
+     * It carries no `alt` - an alt guessed from a file name is a fabricated one, and a
+     * wrong alt is worse than an empty one. Use the object form where a mark needs a name.
+     */
+    | string
     | { kind: "img"; src: string; alt?: string; /** Override the shared height for one that reads small. */ height?: number; }
     | { kind: "node"; node: ReactNode; key?: string; };
 
+/** The object form of whatever was passed. A bare URL is an image with no alt. */
+function normalize(item: LogoItem): Exclude<LogoItem, string> {
+    return typeof item === "string" ? { kind: "img", src: item } : item;
+}
+
 export interface LogoMarqueeProps {
     logos: LogoItem[];
     /**
@@ -61,7 +74,9 @@ export function LogoMarquee({
 }: LogoMarqueeProps) {
     const { laneRef, trackRef, copies, dragging } = useMarquee({ speed, hover, reverse });
 
-    const render = (item: LogoItem, index: number): ReactNode => (
+    const render = (raw: LogoItem, index: number): ReactNode => {
+        const item = normalize(raw);
+        return (
         <span className="logo-marquee__item" key={item.kind === "node" ? item.key ?? index : index}>
             {item.kind === "img"
                 ? <img
@@ -77,7 +92,8 @@ export function LogoMarquee({
                 />
                 : item.node}
         </span>
-    );
+        );
+    };
 
     return (
         <div

package/registry.json

@@ -417,6 +417,68 @@
       ],
       "docs": "docs/notes/primitives.md#button"
     },
+    {
+      "name": "flags",
+      "title": "Country flags",
+      "description": "A flag as an image, from the CDN or from files you downloaded, in the rectangular set or the round one. Emoji flags are the thing this replaces: Windows ships no glyph for them, so a picker built out of emoji renders as bare letters for most desktop readers.",
+      "targets": [
+        "vanilla",
+        "astro",
+        "react"
+      ],
+      "entry": {
+        "vanilla": "@enigmax/primitives",
+        "astro": "@enigmax/primitives",
+        "react": "@enigmax/primitives/react"
+      },
+      "exports": {
+        "vanilla": [
+          "flagAttributes",
+          "flagSrc",
+          "configureFlags"
+        ],
+        "astro": [
+          "flagAttributes",
+          "flagSrc",
+          "configureFlags"
+        ],
+        "react": [
+          "Flag",
+          "configureFlags"
+        ]
+      },
+      "files": [
+        {
+          "path": "src/core/flags.ts",
+          "dest": "flags/flags.ts",
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/flag.tsx",
+          "dest": "flags/index.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/flags": "./flags"
+          },
+          "main": true
+        }
+      ],
+      "styles": false,
+      "themeHooks": [
+        "[data-enigma-flag]",
+        "[data-enigma-flag][data-flag-shape=rect]",
+        "[data-enigma-flag][data-flag-shape=square]",
+        "[data-enigma-flag][data-flag-shape=circle]"
+      ],
+      "assets": "flags",
+      "docs": "docs/notes/primitives.md#flags"
+    },
     {
       "name": "notifications",
       "title": "Notification queue",

package/src/core/flags.ts

@@ -0,0 +1,220 @@
+/**
+ * Country flags as ASSETS, which is the only form of them that renders everywhere.
+ *
+ * The emoji flag is the thing this replaces. It is a pair of regional-indicator code
+ * points, and the glyph for that pair exists only where the platform ships one: Windows
+ * has never shipped country flags in Segoe UI Emoji, so `\u{1F1EA}\u{1F1F8}` renders as
+ * the letters "ES" for the largest desktop platform there is - and a language picker built
+ * out of them looks broken to those readers, with nothing in the code to explain why.
+ * There is no font stack that fixes it, so the fix is not a font: it is an image.
+ *
+ * Two upstream sets, both SVG, both installable or served from a CDN:
+ *
+ * - `rect` / `square` - lipis/flag-icons (`flags/4x3`, `flags/1x1`), the classic
+ *   rectangular set, 271 flags plus subdivisions.
+ * - `circle` - HatScripts/circle-flags (`flags/*.svg` on its gh-pages branch), 445 round
+ *   flags, which is what a flag next to an avatar or inside a chip usually wants.
+ *
+ * Nothing here touches the DOM, so it renders on a server.
+ */
+
+export type FlagShape = "rect" | "square" | "circle";
+
+/**
+ * `svg` is the only format the two upstreams publish, so it is the only one a CDN can
+ * serve. `png` and `webp` exist for a LOCAL set (`enigma add flags --flags local
+ * --flag-formats webp`), which rasterises what it downloads, and for a mirror of your own.
+ */
+export type FlagFormat = "svg" | "png" | "webp";
+
+/**
+ * Where the files come from.
+ *
+ * - `"cdn"` - jsDelivr, straight from the two upstream projects. Nothing to install.
+ * - `"local"` - files under `basePath` in your own public directory.
+ * - any URL - a mirror of your own with the same layout as the local one
+ *   (`<base>/<shape>/<code>.<format>`), which is exactly the tree the downloader writes.
+ */
+export type FlagSource = "cdn" | "local" | (string & {});
+
+/** Pinned so an upgrade upstream is a decision here, never a surprise in production. */
+export const FLAG_ICONS_VERSION = "7.5.0";
+/** circle-flags publishes from a branch, not a tag; gh-pages is its default branch. */
+export const CIRCLE_FLAGS_REF = "gh-pages";
+
+export interface FlagOptions {
+    shape?: FlagShape;
+    format?: FlagFormat;
+    source?: FlagSource;
+    /** Where a local set is served from. Default `/flags`. */
+    basePath?: string;
+    /** Rendered HEIGHT in px. The width follows the shape's ratio. Default 16. */
+    size?: number;
+}
+
+export interface FlagConfig extends Required<Omit<FlagOptions, "size">> {
+    size: number;
+}
+
+const DEFAULTS: FlagConfig = {
+    shape: "rect",
+    format: "svg",
+    source: "cdn",
+    basePath: "/flags",
+    size: 16
+};
+
+let config: FlagConfig = { ...DEFAULTS };
+
+/**
+ * Set the defaults for every flag on the page, once, at startup.
+ *
+ * This is what makes the CDN/local decision a one-line change rather than a prop on every
+ * call site: `configureFlags({ source: "local" })` moves the whole app onto the files the
+ * downloader wrote, and nothing else in the codebase mentions where a flag comes from.
+ */
+export function configureFlags(patch: Partial<FlagConfig>): FlagConfig {
+    config = { ...config, ...patch };
+    return config;
+}
+
+export function flagConfig(): FlagConfig {
+    return config;
+}
+
+/** Test seam and a way back to the shipped defaults. */
+export function resetFlagConfig(): FlagConfig {
+    config = { ...DEFAULTS };
+    return config;
+}
+
+/** Width / height of each shape. The circle set is square; only `rect` is 4:3. */
+export const FLAG_RATIO: Record<FlagShape, number> = { rect: 4 / 3, square: 1, circle: 1 };
+
+const EMOJI_FLAG = /^[\u{1F1E6}-\u{1F1FF}]{2}$/u;
+/**
+ * A BCP 47 tag whose region is spelled the way the standard spells it: UPPERCASE. That
+ * casing is the whole discriminator, and it has to be read before the value is lowercased -
+ * `es-ES` is Spanish-in-Spain and means the flag `es`, while `es-ct` is a subdivision code
+ * both sets publish (Catalonia) and means the file `es-ct`. Lowercasing first makes those
+ * 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 two sets actually name their files: `es`, `gb-eng`, `au-nsw`, `easter_island`. */
+const FILE_CODE = /^[a-z]{2,}(?:[-_][a-z0-9]+)*$/;
+
+/**
+ * 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.
+ */
+export function normalizeFlagCode(value: string | null | undefined): string | null {
+    if (!value) return null;
+    const raw = value.trim();
+    if (!raw) return null;
+
+    if (EMOJI_FLAG.test(raw)) {
+        const letters = [...raw].map((char) => String.fromCharCode((char.codePointAt(0) ?? 0) - 0x1f1e6 + 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;
+}
+
+/** Everything a renderer needs, computed in one pass. Null when the code is unusable. */
+export interface FlagView {
+    /** The upstream file name, e.g. `es`, `gb-eng`. */
+    code: string;
+    src: string;
+    shape: FlagShape;
+    format: FlagFormat;
+    width: number;
+    height: number;
+}
+
+function cdnUrl(code: string, shape: FlagShape): string {
+    if (shape === "circle") return `https://cdn.jsdelivr.net/gh/HatScripts/circle-flags@${CIRCLE_FLAGS_REF}/flags/${code}.svg`;
+    const size = shape === "square" ? "1x1" : "4x3";
+    return `https://cdn.jsdelivr.net/npm/flag-icons@${FLAG_ICONS_VERSION}/flags/${size}/${code}.svg`;
+}
+
+/** One warning per process, not one per flag: a list of 200 would print 200 times. */
+let warnedAboutFormat = false;
+
+/**
+ * The URL for one flag. Null when the code cannot be resolved.
+ *
+ * A raster format asked of the CDN falls back to SVG rather than producing a 404: neither
+ * upstream publishes anything but SVG, so `format: "webp"` is only meaningful against a
+ * local set or a mirror. It says so once, in development, instead of silently disagreeing
+ * with what the call site asked for.
+ */
+export function flagSrc(code: string | null | undefined, options: FlagOptions = {}): string | null {
+    const settings = { ...config, ...options };
+    const normalized = normalizeFlagCode(code);
+    if (!normalized) return null;
+
+    const remoteCdn = settings.source === "cdn";
+    let format = settings.format;
+    if (remoteCdn && format !== "svg") {
+        if (!warnedAboutFormat && typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+            warnedAboutFormat = true;
+            console.warn(`[enigma/flags] The flag CDNs publish SVG only, so "${format}" was served as SVG. Download a local set for raster formats: enigma add flags --flags local --flag-formats ${format}`);
+        }
+        format = "svg";
+    }
+    if (remoteCdn) return cdnUrl(normalized, settings.shape);
+
+    const base = (settings.source === "local" ? settings.basePath : settings.source).replace(/\/+$/, "");
+    return `${base}/${settings.shape}/${normalized}.${format}`;
+}
+
+/** `flagSrc` plus the resolved geometry, for a renderer that has to size the box. */
+export function flagView(code: string | null | undefined, options: FlagOptions = {}): FlagView | null {
+    const settings = { ...config, ...options };
+    const normalized = normalizeFlagCode(code);
+    const src = flagSrc(normalized, options);
+    if (!normalized || !src) return null;
+    const height = Math.max(1, Math.round(settings.size));
+    return {
+        code: normalized,
+        src,
+        shape: settings.shape,
+        format: settings.source === "cdn" ? "svg" : settings.format,
+        width: Math.round(height * FLAG_RATIO[settings.shape]),
+        height
+    };
+}
+
+/**
+ * Attributes for a plain `<img>`, for vanilla, Astro and any template language.
+ *
+ * `label` is the accessible name and there is no default for it: a flag with no label is
+ * DECORATIVE (empty alt, `aria-hidden`), which is correct beside a country name and is the
+ * common case. Inventing one from the code would put "ES" or "es" into a screen reader,
+ * and a country name guessed in the reader's wrong language is worse than silence.
+ */
+export function flagAttributes(code: string | null | undefined, options: FlagOptions & { label?: string; } = {}): Record<string, string | number> | null {
+    const view = flagView(code, options);
+    if (!view) return null;
+    const label = options.label?.trim();
+    return {
+        src: view.src,
+        alt: label ?? "",
+        width: view.width,
+        height: view.height,
+        loading: "lazy",
+        decoding: "async",
+        "data-enigma-flag": "",
+        "data-flag-code": view.code,
+        "data-flag-shape": view.shape,
+        ...(label ? {} : { "aria-hidden": "true" })
+    };
+}

package/src/index.ts

@@ -27,3 +27,21 @@ export {
     type RelativeTimePrecision,
     type RelativeTimeStyle
 } from "@/core/relative-time";
+export {
+    flagSrc,
+    flagView,
+    flagAttributes,
+    normalizeFlagCode,
+    configureFlags,
+    flagConfig,
+    resetFlagConfig,
+    FLAG_RATIO,
+    FLAG_ICONS_VERSION,
+    CIRCLE_FLAGS_REF,
+    type FlagOptions,
+    type FlagConfig,
+    type FlagView,
+    type FlagShape,
+    type FlagFormat,
+    type FlagSource
+} from "@/core/flags";

package/src/react/flag.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { type ImgHTMLAttributes, type ReactNode } from "react";
+import { flagView, type FlagOptions, type FlagShape, type FlagFormat, type FlagSource } from "@/core/flags";
+
+export interface FlagProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "width" | "height"> {
+    /** `es`, `ES`, `en-GB`, `gb-eng`, or the emoji flag you are replacing. */
+    code: string | null | undefined;
+    /**
+     * The accessible name. Leave it out and the flag is decorative, which is what it is
+     * beside a country name - the reader hears the name once instead of twice.
+     */
+    label?: string;
+    shape?: FlagShape;
+    format?: FlagFormat;
+    source?: FlagSource;
+    basePath?: string;
+    /** Rendered height in px. The width follows the shape. Default 16. */
+    size?: number;
+    /** Rendered when the code resolves to nothing. Nothing, by default. */
+    fallback?: ReactNode;
+}
+
+/**
+ * `<Flag code="es" />` - a country flag as an image, at the size you asked for, from the
+ * source the app configured once.
+ *
+ * The defaults come from `configureFlags`, so moving the whole application from the CDN to
+ * a downloaded set is one line at startup and no change at any call site.
+ */
+export function Flag({ code, label, shape, format, source, basePath, size, fallback = null, ...rest }: FlagProps): ReactNode {
+    const options: FlagOptions = { shape, format, source, basePath, size };
+    // An explicit `undefined` prop must not beat the configured default, so the unset ones
+    // are dropped rather than spread over the config.
+    for (const key of Object.keys(options) as (keyof FlagOptions)[]) {
+        if (options[key] === undefined) delete options[key];
+    }
+
+    const view = flagView(code, options);
+    if (!view) return fallback;
+
+    const name = label?.trim();
+    return (
+        <img
+            src={view.src}
+            alt={name ?? ""}
+            width={view.width}
+            height={view.height}
+            loading="lazy"
+            decoding="async"
+            aria-hidden={name ? undefined : true}
+            data-enigma-flag=""
+            data-flag-code={view.code}
+            data-flag-shape={view.shape}
+            {...rest}
+        />
+    );
+}

package/src/react/index.ts

@@ -33,3 +33,15 @@ export { Toaster, type ToasterProps, type ToastPosition, type ToastControls } fr
 export { useNetworkState } from "@/react/use-network-state";
 export { type NetworkState } from "@/core/network";
 export { RelativeTime, type RelativeTimeProps } from "@/react/relative-time";
+export { Flag, type FlagProps } from "@/react/flag";
+export {
+    flagSrc,
+    flagView,
+    flagAttributes,
+    normalizeFlagCode,
+    configureFlags,
+    type FlagOptions,
+    type FlagShape,
+    type FlagFormat,
+    type FlagSource
+} from "@/core/flags";