@aceshooting/lyra-flags 1.3.0 → 1.4.0

package/README.md

@@ -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:
@@ -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

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@aceshooting/lyra-flags",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Waving country/territory flag SVGs — optional companion asset package for <lyra-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"
   },
@@ -24,6 +32,13 @@
     "node": ">=20"
   },
   "sideEffects": false,
+  "scripts": {
+    "generate": "node scripts/generate-index.mjs",
+    "optimize": "node scripts/optimize-flags.mjs",
+    "build-compact": "node scripts/build-compact.mjs",
+    "test": "node scripts/test.mjs",
+    "prepack": "pnpm run generate"
+  },
   "files": [
     "flags",
     "index.js",
@@ -39,15 +54,10 @@
     },
     "./flags/*": "./flags/*"
   },
+  "packageManager": "pnpm@11.13.0",
   "devDependencies": {
     "@resvg/resvg-js": "^2.6.2",
     "sharp": "^0.35.3",
-    "svgo": "^4.0.1"
-  },
-  "scripts": {
-    "generate": "node scripts/generate-index.mjs",
-    "optimize": "node scripts/optimize-flags.mjs",
-    "build-compact": "node scripts/build-compact.mjs",
-    "test": "node scripts/test.mjs"
+    "svgo": "^4.0.2"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Aceshooting
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.