@aceshooting/lyra-flags 1.3.0 → 2.0.0

package/README.md

@@ -1,7 +1,7 @@
 # @aceshooting/lyra-flags
 
 Waving country/territory flag SVGs (249 codes) — the optional companion asset package for
-`<lyra-flag>` in [`lyra-ui`](https://github.com/aceshooting/lyra-ui/tree/main/packages/lyra-ui).
+`<lr-flag>` in [`lyra-ui`](https://github.com/aceshooting/lyra-ui/tree/main/packages/lyra-ui).
 
 ## Install
 
@@ -10,11 +10,11 @@ pnpm add @aceshooting/lyra-flags
 ```
 
 `lyra-ui` declares this as an **optional peer dependency** — installing `lyra-ui` alone never
-pulls this package in. Add it explicitly if your app uses `<lyra-flag>`.
+pulls this package in. Add it explicitly if your app uses `<lr-flag>`.
 
 ## Usage
 
-You normally never call this directly; `<lyra-flag>` resolves it internally. Direct usage:
+You normally never call this directly; `<lr-flag>` resolves it internally. Direct usage:
 
 ```js
 import { flagUrl } from '@aceshooting/lyra-flags';
@@ -22,10 +22,12 @@ import { flagUrl } from '@aceshooting/lyra-flags';
 await flagUrl('fr'); // -> resolved URL of flags/fr.svg
 ```
 
-`flagUrl()` is genuinely code-split per flag — each code is its own dynamically-`import()`ed
-chunk, so calling `flagUrl('fr')` only ever fetches `fr`'s asset, never the other 248. That's why
-it's `async`: this is a real, separate lazy-load per code, not a lookup into one eagerly-bundled
-map (verified with a real Vite build: referencing 2 codes shipped ~28 KB total, not all 249).
+`flagUrl()` selects one dynamically imported loader per flag, so a browser only fetches the
+requested flag at runtime. Because the package exports a loader entry for every code, a production
+bundler may still emit the complete reachable lazy-chunk graph even when the initial entry only
+imports `flagUrl`; lazy network fetching and build-time pruning are separate concerns. Use a
+literal `@aceshooting/lyra-flags/flags/<code>.svg` asset import, or copy only the required assets,
+when the deployment artifact itself must contain a small allowlist.
 
 For the opposite case — a consumer that genuinely wants every flag up front (e.g. a flag-picker
 listing every country) — use `flagUrls()` instead:
@@ -42,12 +44,12 @@ A minority of flags (65 of 249) embed a detailed coat of arms, seal, or emblem i
 artwork (e.g. `es`, `pt`, `sv`) — full illustrative vector detail that isn't visually
 distinguishable at icon scale but costs real transfer bytes regardless (the worst case, `sv`, is
 741 KB raw). Those 65 codes ship **three tiers**, each the best representation for a size band; pick
-one with `flagUrl(code, { variant })` or `<lyra-flag variant="...">`:
+one with `flagUrl(code, { variant })` or `<lr-flag variant="...">`:
 
 - **`compact`** — a tiny WebP raster (~1–3 KB) for icon-scale use (menu items, language selectors,
   dense lists; ~12–28px), where the emblem is a sub-pixel smudge anyway. At that size a downscaled
   raster is both crisper *and* far smaller than hundreds of sub-pixel vector paths.
-- **`standard`** (the default — what `flagUrl(code)` / `<lyra-flag country="...">` resolve to) — an
+- **`standard`** (the default — what `flagUrl(code)` / `<lr-flag country="...">` resolve to) — an
   aggressively-but-losslessly SVGO-optimized vector for card/row sizes (~28–96px). Every flag is
   under 80 KB, with no fidelity loss perceptible at that scale.
 - **`detailed`** — the pristine, unmodified original vector, for rendering larger than icon scale
@@ -62,9 +64,9 @@ await flagUrl('es', { variant: 'compact' });  // -> WebP raster       (~2 KB)
 await flagUrl('es', { variant: 'detailed' }); // -> pristine original (~415 KB)
 ```
 
-Every tier is code-split per flag **and** per tier: a bundled app that only ever requests
-`variant: 'compact'` for a handful of codes ships only those few compact WebPs — never their
-standard or detailed variants, and never the other flags.
+Every tier has a separate loader per flag **and** per tier. At runtime a compact request fetches
+only its compact asset; a bundler can nevertheless emit all statically reachable tier chunks. Use
+literal subpath asset imports when the deployment artifact must be pruned to a small allowlist.
 
 Maintainers, after adding/replacing source art: `pnpm run optimize` (re-derives the standard tier
 from the pristine `flags/detailed/` originals) → `pnpm run build-compact` (renders the compact WebP

package/flags/generated.js

@@ -5,8 +5,9 @@
 /**
  * Lazy map of ISO 3166-1 alpha-2 (or territory) code -> flag SVG URL loader. Each entry is a
  * `() => import('./loaders/xx.js')` with a literal (non-templated) specifier, so bundlers
- * code-split every flag into its own chunk and never fetch/inline a given flag until its
- * specific loader is actually called. This is what `flagUrl()` uses. See index.js — and
+ * code-split every flag into its own lazy loader and never fetch a given flag until its
+ * specific loader is actually called. Bundlers may still emit the complete reachable lazy
+ * graph; this is what `flagUrl()` uses. See index.js — and
  * critically, do NOT add an eager (`new URL()`-per-code) export to *this* file; see
  * generate-index.mjs for why that defeats the whole point.
  * @type {Record<string, () => Promise<string>>}

package/index.js

@@ -3,7 +3,9 @@ import { FLAG_LOADERS_DETAILED } from './flags/generated-detailed.js';
 import { FLAG_LOADERS_COMPACT } from './flags/generated-compact.js';
 
 /**
- * Resolves the URL of a flag SVG shipped in this package, fetching only that one flag.
+ * Resolves the URL of one flag SVG. The browser fetches only the requested flag at runtime; a
+ * bundler may still emit the complete reachable lazy-chunk graph because every supported code is
+ * represented by a literal loader import. See the package README for artifact-pruning options.
  *
  * Backing story: this used to be a synchronous lookup into `FLAG_URLS`, a single object literal
  * with one `new URL('./xx.svg', import.meta.url)` per code, evaluated eagerly the moment the
@@ -25,9 +27,8 @@ import { FLAG_LOADERS_COMPACT } from './flags/generated-compact.js';
  * `import`s the eager map, so loading it doesn't drag in `flags/eager.js` too. A dynamic
  * `import()` of a literal specifier is exactly the pattern bundlers use to create a genuinely
  * separate, lazily-fetched chunk per file — calling `flagUrl('fr')` only ever triggers a network
- * fetch for `fr`'s chunk, never the other 248 (confirmed with a real Vite build: referencing 2
- * codes produced 2 non-trivial chunks and shipped only those 2 flag assets; the rest were
- * unfetched, never-imported build outputs). Every loader module (see `flags/loaders/*.js`) itself
+ * fetch for `fr`'s chunk; the other flags are not fetched until requested. Every loader module
+ * (see `flags/loaders/*.js`) itself
  * uses `new URL(literal, import.meta.url)`, and every `import()` here uses a literal `.js`
  * specifier — never a bundler-specific suffix like `?url` — so this still works completely
  * unbundled (a plain browser `<script type="module">`, Node, `@web/test-runner`'s unbundled
@@ -46,7 +47,7 @@ import { FLAG_LOADERS_COMPACT } from './flags/generated-compact.js';
  * @param {{ variant?: 'compact' | 'standard' | 'detailed' }} [options]
  * @returns {Promise<string | undefined>} The flag's URL. For a `code` with no matching shipped
  *   flag, resolves `undefined` (same non-crashing "no image" outcome as the old code's
- *   now-404ing URL, for `<lyra-flag>`'s `<img src>` use).
+ *   now-404ing URL, for `<lr-flag>`'s `<img src>` use).
  */
 export function flagUrl(code, options) {
   if (options?.variant === 'detailed' && FLAG_LOADERS_DETAILED[code]) {

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@aceshooting/lyra-flags",
-  "version": "1.3.0",
-  "description": "Waving country/territory flag SVGs — optional companion asset package for <lyra-flag> in lyra-ui.",
+  "version": "2.0.0",
+  "description": "Waving country/territory flag SVGs — optional companion asset package for <lr-flag> in lyra-ui.",
+  "keywords": [
+    "flag-icons",
+    "flags",
+    "country-flags",
+    "svg",
+    "i18n",
+    "web-components"
+  ],
   "license": "SEE LICENSE IN README.md",
   "type": "module",
   "author": {
@@ -13,7 +21,7 @@
     "url": "git+https://github.com/aceshooting/lyra-ui.git",
     "directory": "packages/lyra-flags"
   },
-  "homepage": "https://github.com/aceshooting/lyra-ui#readme",
+  "homepage": "https://www.lyra-ui.com/",
   "bugs": {
     "url": "https://github.com/aceshooting/lyra-ui/issues"
   },
@@ -42,7 +50,7 @@
   "devDependencies": {
     "@resvg/resvg-js": "^2.6.2",
     "sharp": "^0.35.3",
-    "svgo": "^4.0.1"
+    "svgo": "^4.0.2"
   },
   "scripts": {
     "generate": "node scripts/generate-index.mjs",