@heyramzi/ui 3.3.1 → 3.5.0

package/COMPONENTS.md

@@ -63,6 +63,7 @@ Generic pieces built on the primitives, imported from `@heyramzi/ui/components/<
 
 - `copy` — CopyButton, copyText, copyRichText, htmlToPlainText, Copied
 - `data-table` — SortableHead, Pagination, InfiniteScroll, RowContextMenu, TableSkeleton, and the sort, page and filter helpers
+- `flag` — Flag, FLAG_CODES, flagCode: a country flag from an ISO 3166-1 alpha-2 code (plus XK for Kosovo), 1em tall at 3:2, one lazy `<img>` of `/flags/<CODE>.svg` each. Add `flagAssets()` from `@heyramzi/ui/vite` to the app's Vite plugins to serve the 250 SVGs (country-flag-icons, MIT, licence beside them). Decorative unless `label` is set. An unknown code renders nothing; to keep a row's layout, wrap it in `<span class="inline-block aspect-[3/2] h-[1em]">`
 - `hold-to-confirm` — HoldToConfirm, press and hold to confirm
 - `language-flag` — LanguageFlag, LANGUAGE_FLAGS (code to `/flags/*.svg`, also a SegmentedFilter option's `image`)
 - `list-page` — ListPageShell, MasterDetail, GroupedList, RailRow and the rest of the master-detail page kit, DetailPanel, ToolbarSearch, toolbarTriggerClass, NoticeBar, EmptyState, FilterPopover, setSectionHost

package/dist/components/copy/clipboard.js

@@ -32,7 +32,7 @@ export function htmlToPlainText(html) {
 	if (typeof document === "undefined") {
 		return html.replace(/<br\s*\/?>/gi, "\n").replace(/<\/p>/gi, "\n\n").replace(/<\/li>/gi, "\n").replace(/<li>/gi, "• ").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").trim();
 	}
-	const div = document.createElement("div");
-	div.innerHTML = html;
-	return div.textContent || div.innerText || "";
+	// A DOMParser document has no browsing context, so nothing in the markup loads or runs.
+	// An element from document.createElement belongs to the live page: an <img onerror> fires.
+	return new DOMParser().parseFromString(html, "text/html").body.textContent ?? "";
 }

package/dist/components/docs/index.js

@@ -3,5 +3,6 @@
 * A surface supplies a title and a body, and never lays a document out itself.
 */
 export { default as DocPage } from "../../../src/components/docs/doc-page.svelte";
+export { default as DocumentView } from "../../../src/components/docs/document-view.svelte";
 export { default as OnThisPage } from "../../../src/components/docs/on-this-page.svelte";
 export { ScrollSpy, READ_LINE } from "./scroll-spy.svelte.js";

package/dist/components/flag/codes.js

@@ -0,0 +1,13 @@
+/** Where the host serves the flag files. `flagAssets()` from `@heyramzi/ui/vite` serves them there. */
+export const FLAG_BASE = "/flags";
+/**
+* The 249 ISO 3166-1 alpha-2 codes plus XK (Kosovo, user-assigned but in common use), each with
+* a file in `./flags`, from country-flag-icons 1.6.20 (MIT).
+*/
+export const FLAG_CODES = ("AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR " + "BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ " + "EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW " + "GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY " + "KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV " + "MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY " + "QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG " + "TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS XK YE YT ZA ZM ZW").split(" ");
+const KNOWN = new Set(FLAG_CODES);
+/** The code in capitals when a flag exists for it, else null. */
+export function flagCode(code) {
+	const upper = code?.trim().toUpperCase() ?? "";
+	return KNOWN.has(upper) ? upper : null;
+}

package/dist/components/flag/index.js

@@ -0,0 +1,2 @@
+export { default as Flag } from "../../../src/components/flag/flag.svelte";
+export { FLAG_BASE, FLAG_CODES, flagCode } from "./codes.js";

package/dist/slides/export/pdf.js

@@ -38,6 +38,13 @@ export async function printPage(page, options = {}) {
 	}
 	await page.evaluate(() => document.fonts.ready.then(() => undefined));
 	if (options.settle) await page.waitForTimeout(options.settle);
+	// WHY: a lazy or still-loading image read as broken while the PDF printed it (testimonial photos, 11 Nov 2026).
+	await page.evaluate(() => Promise.all([...document.images].map((img) => {
+		img.loading = "eager";
+		if (img.complete) return undefined;
+		const loaded = img.decode().catch(() => undefined);
+		return Promise.race([loaded, new Promise((resolve) => setTimeout(resolve, 15e3))]);
+	})).then(() => undefined));
 	const brokenImages = await page.evaluate(() => [...document.images].filter((img) => !img.complete || img.naturalWidth === 0).map((img) => img.src));
 	const { size } = options;
 	const pdf = await page.pdf({

package/dist/vite/flags.js

@@ -0,0 +1,46 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// From src/vite in the repo, or dist/vite in the published package.
+const here = dirname(fileURLToPath(import.meta.url));
+const FLAGS_DIR = [join(here, "../components/flag/flags"), join(here, "../../src/components/flag/flags")].find((dir) => existsSync(dir));
+/**
+* Serves the `Flag` SVGs at `/flags/<CODE>.svg`: from the package in dev and preview, and as
+* one static file each in the client build. Add it to `plugins` in `vite.config.ts`.
+*/
+export function flagAssets(options = {}) {
+	const base = (options.base ?? "/flags").replace(/\/$/, "");
+	if (!FLAGS_DIR) throw new Error("@heyramzi/ui: the flag SVGs are missing from the package");
+	const dir = FLAGS_DIR;
+	const files = readdirSync(dir).filter((name) => /^[A-Z]{2}\.svg$/.test(name));
+	const known = new Set(files);
+	let ssrBuild = false;
+	// Returns nothing: Vite calls a function returned from configureServer as a post hook.
+	const serve = (server) => {
+		server.middlewares.use((req, res, next) => {
+			const path = req.url?.split("?")[0] ?? "";
+			const name = path.startsWith(`${base}/`) ? path.slice(base.length + 1) : "";
+			if (!known.has(name)) return next();
+			res.setHeader("Content-Type", "image/svg+xml");
+			res.setHeader("Cache-Control", "public, max-age=86400");
+			res.end(readFileSync(join(dir, name)));
+		});
+	};
+	return {
+		name: "heyramzi-ui:flags",
+		configResolved(config) {
+			ssrBuild = Boolean(config.build.ssr);
+		},
+		configureServer: serve,
+		configurePreviewServer: serve,
+		generateBundle() {
+			const consumer = this.environment?.config?.consumer;
+			if (consumer ? consumer !== "client" : ssrBuild) return;
+			for (const name of files) this.emitFile({
+				type: "asset",
+				fileName: `${base.replace(/^\//, "")}/${name}`,
+				source: readFileSync(join(dir, name))
+			});
+		}
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/ui",
-  "version": "3.3.1",
+  "version": "3.5.0",
   "description": "Svelte 5 UI for apps: primitives, effects and animations, plus work (tasks and docs), charts, slides, an editor, onboarding and a canvas as subpaths.",
   "homepage": "https://ui.heyramzi.com",
   "license": "MIT",
@@ -115,6 +115,11 @@
       "node": "./dist/effects/magnetic/magnetic.js",
       "default": "./src/effects/magnetic/magnetic.ts"
     },
+    "./vite": {
+      "types": "./src/vite/flags.ts",
+      "node": "./dist/vite/flags.js",
+      "default": "./src/vite/flags.ts"
+    },
     "./icons/sf-symbols": {
       "svelte": "./src/icons/sf-symbols.ts",
       "types": "./src/icons/sf-symbols.ts",
@@ -389,6 +394,6 @@
     "sync": "pnpm sync:transitions && pnpm sync:shadcn",
     "sync:check": "node scripts/sync-transitions.mjs --check && node scripts/sync-shadcn.mjs --check",
     "check": "svelte-check --tsconfig ./tsconfig.json",
-    "build": "node ../../../vibe-kit/scripts/build-dist.mjs"
+    "build": "node ../../../upsys/kit/scripts/build-dist.mjs"
   }
 }

package/src/charts/chart-plot.svelte

@@ -82,25 +82,28 @@
 	{#if count > 0}
 		<p class="hr-sr-only" aria-live="polite">{announce}</p>
 	{/if}
-	<table class="hr-sr-only">
-		<caption>{label}</caption>
-		<thead>
-			<tr>
-				<th scope="col">{table.xLabel}</th>
-				{#each table.columns as column, j (j)}
-					<th scope="col">{column}</th>
-				{/each}
-			</tr>
-		</thead>
-		<tbody>
-			{#each table.rows as row, i (i)}
+	<!-- A table ignores width: 1px and spills past the page, so the clipping box is a div. -->
+	<div class="hr-sr-only">
+		<table>
+			<caption>{label}</caption>
+			<thead>
 				<tr>
-					<th scope="row">{row.x}</th>
-					{#each row.cells as cell, j (j)}
-						<td>{cell}</td>
+					<th scope="col">{table.xLabel}</th>
+					{#each table.columns as column, j (j)}
+						<th scope="col">{column}</th>
 					{/each}
 				</tr>
-			{/each}
-		</tbody>
-	</table>
+			</thead>
+			<tbody>
+				{#each table.rows as row, i (i)}
+					<tr>
+						<th scope="row">{row.x}</th>
+						{#each row.cells as cell, j (j)}
+							<td>{cell}</td>
+						{/each}
+					</tr>
+				{/each}
+			</tbody>
+		</table>
+	</div>
 {/if}

package/src/components/copy/clipboard.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
-import { copyRichText, copyText } from "./clipboard.js";
+import { copyRichText, copyText, htmlToPlainText } from "./clipboard.js";
 
 // Mock navigator.clipboard
 const mockClipboard = {
@@ -204,3 +204,19 @@ describe("htmlToPlainText (server-side)", () => {
     expect(mockWriteText).toHaveBeenCalledWith("Hello World & Friends <3>");
   });
 });
+
+describe("htmlToPlainText (browser)", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("parses into an inert document, so an onerror in the markup never runs", async () => {
+    const win = window as Window & { __fired?: boolean };
+    win.__fired = false;
+    const createElement = vi.spyOn(document, "createElement");
+    expect(htmlToPlainText('<img src="x" onerror="window.__fired=true">hi')).toBe("hi");
+    await new Promise((done) => setTimeout(done, 10));
+    expect(win.__fired).toBe(false);
+    // jsdom loads no images, so the onerror can't fire here either way: the live-document
+    // element the old code built is what a real browser runs the handler on.
+    expect(createElement).not.toHaveBeenCalled();
+  });
+});

package/src/components/copy/clipboard.ts

@@ -47,7 +47,7 @@ export function htmlToPlainText(html: string): string {
       .replace(/>/g, ">")
       .trim();
   }
-  const div = document.createElement("div");
-  div.innerHTML = html;
-  return div.textContent || div.innerText || "";
+  // A DOMParser document has no browsing context, so nothing in the markup loads or runs.
+  // An element from document.createElement belongs to the live page: an <img onerror> fires.
+  return new DOMParser().parseFromString(html, "text/html").body.textContent ?? "";
 }

package/src/components/docs/document-view.svelte

@@ -0,0 +1,232 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import type { Component, Snippet } from "svelte";
+	import { untrack } from "svelte";
+	import DocPage from "./doc-page.svelte";
+	import type { DocHeading } from "./scroll-spy.svelte.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface Props {
+		title: string;
+		/** Breadcrumb, as a reader would say it: "Marketing / Reports". */
+		section?: string;
+		/** Already worded and localised: "Updated 30 Jul 2026". */
+		updated?: string;
+		icon?: Component<{
+			class?: string;
+			weight?: "bold";
+			"aria-hidden"?: boolean | "true" | "false";
+		}>;
+		actions?: Snippet;
+		/** The body's h2s, anchored by id, for the "On this page" rail. */
+		headings?: DocHeading[];
+		contentsLabel: string;
+		/** The rendered body. Trusted HTML from the consumer's own parser, never user input. */
+		html: string;
+		/** Changes when another document is shown: the pane returns to the top and the body re-enters. */
+		resetKey: string;
+		measure?: "prose" | "wide";
+		/** Runs on the body after every swap (icons, diagrams). Returns its cleanup. */
+		enhance?: (root: HTMLElement) => void | (() => void);
+		class?: string;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		title,
+		section,
+		updated,
+		icon,
+		actions,
+		headings = [],
+		contentsLabel,
+		html,
+		resetKey,
+		measure = "prose",
+		enhance,
+		class: className = "",
+	}: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let body = $state<HTMLElement | null>(null);
+
+	// =========================
+	// EFFECTS
+	// =========================
+	$effect(() => {
+		void html;
+		const root = body;
+		if (!root || !enhance) return;
+		return untrack(() => enhance(root)) ?? undefined;
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- Inline, not framed: a link is an ordinary anchor, so the router swaps only this body. -->
+<DocPage
+	{title}
+	{section}
+	{updated}
+	{icon}
+	{actions}
+	{headings}
+	{contentsLabel}
+	{resetKey}
+	{measure}
+>
+	{#key resetKey}
+		<div bind:this={body} class="document-view t-enter {className}">
+			<!-- eslint-disable-next-line svelte/no-at-html-tags -- trusted, parsed server-side -->
+			{@html html}
+		</div>
+	{/key}
+</DocPage>
+
+<!-- =========================== -->
+<!-- STYLES -->
+<!-- =========================== -->
+<!-- In the components layer at zero specificity, so a consumer's own document stylesheet wins without !important. -->
+<style>
+	@layer theme, base, components, utilities;
+
+	@layer components {
+		:global {
+			:where(.document-view) {
+				color: var(--color-foreground);
+				font-size: 0.9375rem;
+				line-height: 1.65;
+				overflow-wrap: anywhere;
+			}
+			:where(.document-view) :where(h1, h2, h3, h4) {
+				font-family: var(--font-heading);
+				color: var(--color-foreground);
+				line-height: 1.25;
+				text-wrap: balance;
+				scroll-margin-top: 6rem;
+			}
+			:where(.document-view) :where(h1:first-child) {
+				display: none;
+			}
+			:where(.document-view) :where(h2) {
+				margin: 2.5rem 0 0.75rem;
+				font-size: 1.25rem;
+				font-weight: 700;
+				letter-spacing: -0.01em;
+			}
+			:where(.document-view) :where(h3) {
+				margin: 1.75rem 0 0.5rem;
+				font-size: 1rem;
+				font-weight: 600;
+			}
+			:where(.document-view) > :where(:first-child, h1:first-child + *) {
+				margin-top: 0;
+			}
+			:where(.document-view) :where(p, ul, ol, blockquote, pre, table) {
+				margin: 0 0 1rem;
+			}
+			:where(.document-view) :where(ul, ol) {
+				padding-left: 1.25rem;
+			}
+			:where(.document-view) :where(li + li) {
+				margin-top: 0.25rem;
+			}
+			:where(.document-view) :where(a) {
+				color: var(--color-brand);
+				text-decoration: underline;
+				text-decoration-color: color-mix(in oklch, currentColor 35%, transparent);
+				text-underline-offset: 0.16em;
+				transition: text-decoration-color var(--duration-fast) ease-out;
+			}
+			@media (hover: hover) and (pointer: fine) {
+				:where(.document-view) :where(a:hover) {
+					text-decoration-color: currentColor;
+				}
+			}
+			/* A wikilink to a page that does not exist yet reads as text, not as a dead link. */
+			:where(.document-view) :where(.wikilink.missing, a.missing) {
+				color: var(--color-muted-foreground);
+				text-decoration-style: dashed;
+			}
+			:where(.document-view) :where(code) {
+				font-family: var(--font-mono);
+				font-size: 0.85em;
+				padding: 0.1em 0.35em;
+				border-radius: var(--radius-sm, 0.375rem);
+				background: var(--color-muted);
+			}
+			:where(.document-view) :where(pre) {
+				overflow-x: auto;
+				padding: 0.875rem 1rem;
+				border: 1px solid var(--color-border);
+				border-radius: var(--radius-lg);
+				background: var(--color-muted);
+				font-size: 0.8125rem;
+				line-height: 1.55;
+			}
+			:where(.document-view) :where(pre code) {
+				padding: 0;
+				background: none;
+				font-size: inherit;
+			}
+			:where(.document-view) :where(blockquote) {
+				padding: 0.75rem 1rem;
+				border-radius: var(--radius-md);
+				background: var(--color-muted);
+				color: var(--color-muted-foreground);
+			}
+			:where(.document-view) :where(blockquote > :last-child) {
+				margin-bottom: 0;
+			}
+			:where(.document-view) :where(.callout) {
+				margin: 0 0 1rem;
+				padding: 0.75rem 1rem;
+				border: 1px solid var(--color-border);
+				border-radius: var(--radius-lg);
+				background: var(--color-card);
+			}
+			:where(.document-view) :where(table) {
+				display: block;
+				max-width: 100%;
+				overflow-x: auto;
+				border-collapse: collapse;
+				font-size: 0.875rem;
+				font-variant-numeric: tabular-nums;
+			}
+			:where(.document-view) :where(th, td) {
+				padding: 0.5rem 0.75rem;
+				border-bottom: 1px solid var(--color-border);
+				text-align: left;
+				vertical-align: top;
+			}
+			:where(.document-view) :where(th) {
+				font-weight: 600;
+				color: var(--color-muted-foreground);
+			}
+			:where(.document-view) :where(hr) {
+				margin: 2rem 0;
+				border: 0;
+				border-top: 1px solid var(--color-border);
+			}
+			:where(.document-view) :where(img) {
+				max-width: 100%;
+				height: auto;
+				border-radius: var(--radius-md);
+			}
+			@media (prefers-reduced-motion: reduce) {
+				:where(.document-view) :where(a) {
+					transition: none;
+				}
+			}
+		}
+	}
+</style>

package/src/components/docs/document-view.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { Component, Snippet } from "svelte";
+import type { DocHeading } from "./scroll-spy.svelte.js";
+interface Props {
+    title: string;
+    /** Breadcrumb, as a reader would say it: "Marketing / Reports". */
+    section?: string;
+    /** Already worded and localised: "Updated 30 Jul 2026". */
+    updated?: string;
+    icon?: Component<{
+        class?: string;
+        weight?: "bold";
+        "aria-hidden"?: boolean | "true" | "false";
+    }>;
+    actions?: Snippet;
+    /** The body's h2s, anchored by id, for the "On this page" rail. */
+    headings?: DocHeading[];
+    contentsLabel: string;
+    /** The rendered body. Trusted HTML from the consumer's own parser, never user input. */
+    html: string;
+    /** Changes when another document is shown: the pane returns to the top and the body re-enters. */
+    resetKey: string;
+    measure?: "prose" | "wide";
+    /** Runs on the body after every swap (icons, diagrams). Returns its cleanup. */
+    enhance?: (root: HTMLElement) => void | (() => void);
+    class?: string;
+}
+declare const $$Component: Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/docs/index.ts

@@ -3,6 +3,7 @@
  * A surface supplies a title and a body, and never lays a document out itself.
  */
 export { default as DocPage } from "./doc-page.svelte";
+export { default as DocumentView } from "./document-view.svelte";
 export { default as OnThisPage } from "./on-this-page.svelte";
 export {
   ScrollSpy,

package/src/components/flag/codes.test.ts

@@ -0,0 +1,30 @@
+import { readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vite-plus/test";
+import { FLAG_CODES, flagCode } from "./codes.js";
+
+const dir = join(dirname(fileURLToPath(import.meta.url)), "flags");
+
+describe("flag codes", () => {
+  it("lists exactly the SVG files shipped", () => {
+    const files = readdirSync(dir)
+      .filter((name) => name.endsWith(".svg"))
+      .map((name) => name.slice(0, -4));
+    expect(FLAG_CODES.toSorted()).toEqual(files.toSorted());
+    expect(FLAG_CODES).toHaveLength(250);
+  });
+
+  it("knows Kosovo, which ISO 3166-1 leaves user-assigned", () => {
+    expect(flagCode("xk")).toBe("XK");
+  });
+
+  it("takes any case and refuses what it has no file for", () => {
+    expect(flagCode("jp")).toBe("JP");
+    expect(flagCode(" Pl ")).toBe("PL");
+    expect(flagCode("")).toBeNull();
+    expect(flagCode(undefined)).toBeNull();
+    expect(flagCode("ZZ")).toBeNull();
+    expect(flagCode("../FR")).toBeNull();
+  });
+});

package/src/components/flag/codes.ts

@@ -0,0 +1,25 @@
+/** Where the host serves the flag files. `flagAssets()` from `@heyramzi/ui/vite` serves them there. */
+export const FLAG_BASE = "/flags";
+
+/**
+ * The 249 ISO 3166-1 alpha-2 codes plus XK (Kosovo, user-assigned but in common use), each with
+ * a file in `./flags`, from country-flag-icons 1.6.20 (MIT).
+ */
+export const FLAG_CODES: readonly string[] = (
+  "AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR " +
+  "BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ " +
+  "EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW " +
+  "GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY " +
+  "KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV " +
+  "MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY " +
+  "QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG " +
+  "TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS XK YE YT ZA ZM ZW"
+).split(" ");
+
+const KNOWN = new Set(FLAG_CODES);
+
+/** The code in capitals when a flag exists for it, else null. */
+export function flagCode(code: string | null | undefined): string | null {
+  const upper = code?.trim().toUpperCase() ?? "";
+  return KNOWN.has(upper) ? upper : null;
+}

package/src/components/flag/flag.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { cn } from "../../lib/utils.js";
+	import { FLAG_BASE, flagCode } from "./codes.js";
+
+	// =========================
+	// PROPS
+	// =========================
+	interface Props {
+		/** ISO 3166-1 alpha-2 code, or XK for Kosovo, any case. Unknown or empty renders nothing. */
+		code: string | null | undefined;
+		/** Names the flag for a reader. Leave it out when the country name sits beside it. */
+		label?: string;
+		/** Where the host serves `<CODE>.svg`. */
+		base?: string;
+		class?: string;
+	}
+
+	let { code, label, base = FLAG_BASE, class: className }: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let file = $derived(flagCode(code));
+	// A file the host doesn't serve hides the flag instead of showing a broken image.
+	let failedFor = $state<string | null>(null);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{#if file && failedFor !== file}
+	<img
+		src="{base}/{file}.svg"
+		alt={label ?? ""}
+		aria-hidden={label ? undefined : "true"}
+		width="3"
+		height="2"
+		loading="lazy"
+		decoding="async"
+		draggable="false"
+		onerror={() => (failedFor = file)}
+		class={cn(
+			"inline-block aspect-[3/2] h-[1em] w-auto max-w-none shrink-0 object-cover align-[-0.125em]",
+			"rounded-[min(var(--radius-sm),0.15em)] outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/15",
+			className,
+		)}
+	/>
+{/if}

package/src/components/flag/flag.svelte.d.ts

@@ -0,0 +1,12 @@
+interface Props {
+    /** ISO 3166-1 alpha-2 code, or XK for Kosovo, any case. Unknown or empty renders nothing. */
+    code: string | null | undefined;
+    /** Names the flag for a reader. Leave it out when the country name sits beside it. */
+    label?: string;
+    /** Where the host serves `<CODE>.svg`. */
+    base?: string;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/flag/flags/AD.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 513 342"><path fill="#fedd00" d="M0 0h513v342H0z"/><path fill="#10069f" d="M0 0h171v342H0z"/><path fill="#d50032" d="M342 0h171v342H342z"/><path fill="#D80027" d="M198.9 113.6H256v64.8h-57.1z"/><g stroke="#D80027" stroke-width="7"><path d="M267.6 113.6v64.7M284.2 113.6v64.7M300.8 113.6v64.7"/></g><g stroke="#D80027" stroke-width="5"><path d="M247.4 178.4v64.7M234.1 178.4v64.7M220.8 178.5v53.9M207.1 178.5v47.1"/></g><path fill="#FFDA44" d="m199.9 146 27.6-32.4 28.5 32.3-28.1 32.4z"/><path fill="#BC8B00" d="M182.2 95.9v92.2c0 34.3 27.3 54.2 48.6 64.5-.8 1.4 25.1 8.3 25.1 8.3s25.9-6.9 25.1-8.3c21.4-10.3 48.6-30.1 48.6-64.5V95.9H182.2zm129.9 92.2c0 16.9-10 29.4-32.8 43.9-8.6 5.5-17.5 9-23.3 11-5.8-2-14.7-5.5-23.3-11-22.8-14.5-32.8-28-32.8-43.9v-74.5h112.2v74.5z"/><path fill="#D80027" d="M264.4 188.9h29.5v8.6h-29.5zM264.4 206.5h29.5v8.6h-29.5z"/></svg>

package/src/components/flag/flags/AE.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 513 342"><path fill="#FFF" d="M0 0h513v342H0z"/><path fill="#00843d" d="M0 0h513v114H0z"/><path d="M0 228h513v114H0z"/><path fill="#c8102e" d="M0 0h171v342H0z"/></svg>

package/src/components/flag/flags/AF.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 513 342"><path fill="#D32011" d="M0 0h513v342H0z"/><path fill="#007A36" d="M342 0h171v342H342z"/><path d="M0 0h171v342H0z"/><path fill="#FFF" d="M256.5 131.3c-17.5 0-31.8 14.3-31.8 31.8v47.7h63.6v-47.7c0-17.7-14.3-31.8-31.8-31.8z"/><path fill="#FFF" d="M256.5 93c-43.1 0-78 34.9-78 78s34.9 77.9 78 77.9 78-34.9 78-78-34.9-77.9-78-77.9zm0 142.4c-35.6 0-64.5-28.9-64.5-64.5s28.9-64.5 64.5-64.5 64.5 29 64.5 64.6c0 35.6-28.9 64.4-64.5 64.4z"/></svg>

package/src/components/flag/flags/AG.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 513 342"><path d="M0 0h513v342H0z"/><path fill="#0072c6" d="M88.8 136.5c-2.2 12.9-3.4 26.2-3.4 39.8 0 13.6 1.2 27 3.4 39.8L256 228.3l167.2-12.1c2.2-12.9 3.4-26.2 3.4-39.8s-1.2-27-3.4-39.8"/><path fill="#FFF" d="M423.2 219H88.8c15.8 69.8 84.7 122.3 167.2 122.3S407.4 288.8 423.2 219z"/><path fill="#FFDA44" d="M365.9 136.5H146.1l44.9-21.1-23.9-43.5 48.8 9.4L222 32l34 36.2L290 32l6.1 49.3 48.8-9.4-23.9 43.5z"/><g fill="#ce1126"><path d="M256.5 342 0 0v342z"/><path d="M513 342V0L256 342z"/></g></svg>

package/src/components/flag/flags/AI.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 513 342"><path fill="#012169" d="M0 0h513v342H0z"/><path fill="#FFF" d="M454.8 265.38c7.94-10.93 13.24-24.27 13.24-40.42V104.89a59.754 59.754 0 0 1-36.02 12.01c-19.64 0-37.07-9.43-48.03-24.01-10.95 14.58-28.39 24.01-48.03 24.01-13.52 0-25.99-4.47-36.02-12v120.06c0 16.16 5.3 29.5 13.24 40.42H454.8z"/><path fill="#9cf" d="M310.23 260.98C332.65 296.96 384 309 384 309s51.35-12.04 73.77-48.02H310.23z"/><g fill="#f90"><path d="M396.66 172.21c.32 1.42 8.72 10.17 17.56 20.15 1.39 1.57-8.74 12.63-6.91 12.59 4.75-.12 19.27-17.26 19.34 6.65.05 15.94-30 27.51-30 27.51h17.47l.65 14.96s4.97-13.34 7.59-16.57c8.1-9.97 20.18-30.07 34.59-27.1 14.41 2.97-13.66-13.92-13.66-13.92s-5.2-15.19-16.63-16.97c-10.06-1.57-14.29-2.51-26.64-7.3-1.68-.65-3.88-2.32-3.36 0z"/><path d="M359.69 198.69c1.07-.99 4.46-12.63 8.69-25.28.67-1.99 15.31 1.27 14.35-.3-2.47-4.06-24.58-8.08-3.9-20.08 13.79-8 38.82 12.27 38.82 12.27l-8.72-15.14 12.64-8.03s-14.05 2.35-18.14 1.69c-12.68-2.04-36.13-2.48-40.75-16.45-4.62-13.97-5.25 18.79-5.25 18.79s-10.56 12.08-6.4 22.88c3.66 9.5 4.96 13.64 6.97 26.73.29 1.79-.06 4.53 1.69 2.92z"/><path d="M395.67 219.87c-1.39-.43-13.16 2.49-26.22 5.18-2.06.42-6.59-13.88-7.47-12.26-2.27 4.17 5.36 25.31-15.41 13.45-13.84-7.91-8.89-39.73-8.89-39.73l-8.71 15.14-13.29-6.9s9.09 10.96 10.57 14.84c4.6 11.99 16 32.49 6.24 43.49-9.76 11.01 18.88-4.9 18.88-4.9s15.76 3.07 23-5.96c6.38-7.94 9.3-11.14 19.61-19.45 1.43-1.12 3.97-2.19 1.69-2.9z"/></g><path fill="#012169" d="M0 0h256.5v171H0z"/><g fill="#FFF"><path d="M256.5 0v30.6l-45.3 25.2h45.3v59.4h-59.2l59.2 32.9V171h-26.7l-73.7-40.9V171h-55.7v-48.7L12.8 171H0v-30.6l45.3-25.2H0V55.8h59.2L0 22.9V0h26.7l73.7 40.9V0h55.7v48.7L243.7 0z"/><path d="M156.1 115.2 256.5 171v-15.8l-72-40zM100.4 55.8 0 0v15.8l72 40z"/></g><g fill="#D80027"><path d="M144.3 0h-32.1v69.5H0v32h112.2V171h32.1v-69.5h112.2v-32H144.3z"/><path d="M156.1 115.2 256.5 171v-15.8l-72-40zM72 115.2l-72 40V171l100.4-55.8zM100.4 55.8 0 0v15.8l72 40zM184.5 55.8l72-40V0L156.1 55.8z"/></g></svg>

package/src/components/flag/flags/AL.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 90 60"><path fill="#ED2024" d="M0 0h90v60H0z"/><path fill="#212121" d="M32.5 12.2v16l7.1 2.5-5 4.9 2.4 3 5.3-5.5 1.2 2.3-3 4.9 3.6 5.6-1.8 2.6 2.8 3.6 2.7-3.7-1.5-2.6 3-5.8-2.7-4.6 1.2-2.3 5.2 5.5 2.5-2.9-5.2-5.1 7.2-2.6V12.2l-5.2 1.9-.1 3.8-3.3.3v-2.6l1.7-2.3 5.6-2.2-2.3-.4 1.4-1.2.9.4-.8-1.4L54 9l-1-1.1L47.5 9l1.4 1.1-3.8 4.9-3.8-4.8 1.3-1.1-5-1.2L36.2 9l-1.5-.4-.8 1.4.9-.6 1.6 1.1-2.3.5 5.5 2 1.6 2.3v2.9l-3.3-.3v-3.6z"/><g fill="#212121"><path d="M26.2 25h6.4v2.5h-6.4zM26.2 20.9h6.4v2.7h-6.4zM26.2 16.7h6.4v2.6h-6.4zM26.2 12.7h6.4v2.5h-6.4z"/></g><g fill="#212121"><path d="M57.4 25h6.4v2.5h-6.4zM57.4 20.9h6.4v2.7h-6.4zM57.4 16.7h6.4v2.6h-6.4zM57.4 12.7h6.4v2.5h-6.4z"/></g><path fill="#212121" d="M53.4 36.1h6.4V38h-6.4zM30.2 36.1h6.4V38h-6.4z"/></svg>

package/src/components/flag/flags/AM.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 513 342"><path fill="#0052B4" d="M0 0h513v342H0z"/><path fill="#D80027" d="M0 0h513v114H0z"/><path fill="#FF9811" d="M0 228h513v114H0z"/></svg>