@asafarim/shared-i18n 0.8.0 → 0.9.0

package/demo/README.md

@@ -0,0 +1,119 @@
+# @asafarim/shared-i18n Demo
+
+Interactive demo for [@asafarim/shared-i18n](../README.md). Showcases **both** `LanguageSwitcher` and `CountryLanguageSelector` imported from a single package, with Benelux + UK locale-aware URL routing.
+
+Live: [https://alisafari-it.github.io/shared-i18n/](https://alisafari-it.github.io/shared-i18n/)
+
+## Local Development
+
+```bash
+# From workspace root — build the package first
+pnpm install
+pnpm run build          # builds @asafarim/shared-i18n (including CSS copy)
+
+# Start the demo dev server
+cd demo
+pnpm run dev            # http://localhost:5173/shared-i18n/
+```
+
+## Demo Pages
+
+### Overview (`/be-en/overview`)
+- Hero with live locale / URL preview
+- Two-column feature comparison between `LanguageSwitcher` and `CountryLanguageSelector`
+- Routing contract explanation
+
+### Get Started (`/be-en/get-started`)
+- Step-by-step guide: install → CSS import → `initI18n` → add both selectors
+- Code snippets for `resolveLocaleFromLanguage` adapter pattern
+- Pro tips
+
+### Language Switchers (`/be-en/language-switchers`)
+All six `LanguageSwitcher` variants with live `resolveLocaleFromLanguage` wiring:
+- Buttons, select, icon-dropdown (all / limited languages)
+- Icon-dropdown with labels
+- Toggle button (2 languages)
+- **Comparison table** and country-awareness explanation
+- Inline notice when language falls back to a different country
+
+### Country Language Selectors (`/be-en/country-language-selectors`)
+All `CountryLanguageSelector` variants controlled by the same locale:
+- Image flags / emoji flags × compact / full / flag-only triggers
+- Custom `renderTrigger` render prop example
+- Popover `align="start"` variant
+- Live status bar (country, language, slug, URL)
+
+### Routing Lab (`/be-en/routing-lab`)
+Side-by-side demo:
+- Left: `LanguageSwitcher` + `resolveLocaleFromLanguage` adapter with fallback notices
+- Right: `CountryLanguageSelector` direct full-locale output
+- Scripted scenario cards that apply predefined transitions
+
+## Countries Covered
+
+| Code | Country | Languages |
+|------|---------|-----------|
+| BE | Belgium | en, nl, fr, de |
+| NL | Netherlands | nl, en |
+| LU | Luxembourg | lb, fr, de, en |
+| GB | United Kingdom | en |
+
+## URL Structure
+
+```
+/shared-i18n/<country-lower>-<language-lower>/<page>
+
+Examples:
+  /shared-i18n/be-en/overview
+  /shared-i18n/nl-nl/language-switchers
+  /shared-i18n/lu-fr/country-language-selectors
+  /shared-i18n/gb-en/routing-lab
+```
+
+Changing locale preserves the active page; changing page preserves the active locale. Invalid slugs fall back to `be-en/overview`.
+
+## Architecture
+
+```
+demo/src/
+├── App.tsx                          # URL-driven router, locale ↔ i18n sync
+├── main.tsx                         # initI18n + CSS import
+├── index.css                        # Premium app-shell design
+├── data/
+│   └── countries.ts                 # Benelux + UK country list (Country[])
+├── i18n/
+│   ├── localeRouting.ts             # DemoPage type, slug helpers, parsePathname
+│   └── localeAdapter.ts             # resolveLocaleFromLanguage helper
+├── components/
+│   ├── LanguageBar.tsx              # Navbar: two CLS controls, theme toggle
+│   ├── OverviewSection.tsx          # Overview feature cards
+│   ├── GetStartedSection.tsx        # Accordion steps
+│   ├── LanguageSwitchersPage.tsx    # All LanguageSwitcher variants + comparison table
+│   ├── CountryLanguageSelectorsPage.tsx  # All CLS variants
+│   ├── RoutingLabPage.tsx           # Side-by-side LS vs CLS routing demo
+│   ├── KeyTable.tsx                 # Translation key inspector
+│   ├── StatusCard.tsx               # i18n live status
+│   └── Logo.tsx                     # Brand logo
+└── locales/
+    ├── en/demo.json
+    ├── nl/demo.json
+    ├── fr/demo.json
+    ├── de/demo.json
+    └── it/demo.json
+```
+
+## Key Technologies
+
+- **React 19** + **TypeScript**
+- **Vite 6** — build tool and dev server
+- **i18next** + **react-i18next** — translation engine
+- **@asafarim/shared-i18n** — LanguageSwitcher, CountryLanguageSelector, all hooks
+- **@asafarim/design-tokens** — Design system
+
+## GitHub Pages Deployment
+
+The demo uses a `public/404.html` + `index.html` script pattern to handle SPA deep links on GitHub Pages. See those files for the implementation.
+
+## License
+
+MIT

package/demo/index.html

@@ -2,9 +2,20 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="./public/favicon.svg" />
+    <link rel="icon" type="image/svg+xml" href="./favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Shared i18n demo</title>
+    <script>
+      // SPA GitHub Pages fallback decoder. Pairs with public/404.html.
+      (function (l) {
+        if (l.search[1] === '/') {
+          var decoded = l.search.slice(1).split('&').map(function (s) {
+            return s.replace(/~and~/g, '&');
+          }).join('?');
+          window.history.replaceState(null, '', l.pathname.slice(0, -1) + decoded + l.hash);
+        }
+      }(window.location));
+    </script>
   </head>
   <body>
     <div id="root"></div>

package/demo/node_modules/.bin/kill-port

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/kill-port@2.0.1/node_modules/kill-port/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/kill-port@2.0.1/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/kill-port@2.0.1/node_modules/kill-port/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/kill-port@2.0.1/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../kill-port/cli.js" "$@"
+else
+  exec node  "$basedir/../kill-port/cli.js" "$@"
+fi

package/demo/node_modules/.bin/tsc

@@ -2,20 +2,16 @@
 basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
 
 case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../../../node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/tsc" "$@"
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
 else
-  exec node  "$basedir/../../../node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/tsc" "$@"
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
 fi

package/demo/node_modules/.bin/tsserver

@@ -2,20 +2,16 @@
 basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
 
 case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/typescript@5.8.3/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../../../node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/tsserver" "$@"
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
 else
-  exec node  "$basedir/../../../node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/bin/tsserver" "$@"
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
 fi

package/demo/node_modules/.bin/vite

@@ -2,20 +2,16 @@
 basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
 
 case `uname` in
-    *CYGWIN*|*MINGW*|*MSYS*)
-        if command -v cygpath > /dev/null 2>&1; then
-            basedir=`cygpath -w "$basedir"`
-        fi
-    ;;
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/bin/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/bin/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules:/mnt/c/repos/my-tools/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/bin/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules:/home/runner/work/shared-i18n/shared-i18n/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -x "$basedir/node" ]; then
-  exec "$basedir/node"  "$basedir/../../../node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/bin/vite.js" "$@"
+  exec "$basedir/node"  "$basedir/../vite/bin/vite.js" "$@"
 else
-  exec node  "$basedir/../../../node_modules/.pnpm/vite@6.4.1_@types+node@24.10.4/node_modules/vite/bin/vite.js" "$@"
+  exec node  "$basedir/../vite/bin/vite.js" "$@"
 fi

package/demo/package.json

@@ -1,14 +1,16 @@
 {
   "name": "shared-i18n-demo",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "predev": "kill-port 5173",
+    "postdev": "echo 'Demo running at http://localhost:5173/shared-i18n/'"
   },
   "dependencies": {
-    "@asafarim/country-language-selector": "^0.2.3",
+    "@asafarim/country-language-selector": "^0.4.1",
     "@asafarim/design-tokens": "^0.5.0",
     "@asafarim/shared-i18n": "workspace:*",
     "react": "^19.0.0",
@@ -19,7 +21,8 @@
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.0",
     "typescript": "~5.8.3",
-    "vite": "^6.0.0"
+    "vite": "^6.0.0",
+    "kill-port": "^2.0.1"
   },
   "publishConfig": {
     "access": "public"

package/demo/public/404.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Shared i18n demo</title>
+    <script>
+      // SPA GitHub Pages fallback (rafgraph/spa-github-pages).
+      // Single-page apps for GitHub Pages — MIT license.
+      // Rewrites a deep URL into a single query string and redirects to the
+      // SPA index, which decodes it back into history.
+      var pathSegmentsToKeep = 1; // keep the `/shared-i18n` base path
+
+      var l = window.location;
+      l.replace(
+        l.protocol + '//' + l.hostname + (l.port ? ':' + l.port : '') +
+        l.pathname.split('/').slice(0, 1 + pathSegmentsToKeep).join('/') + '/?/' +
+        l.pathname.slice(1).split('/').slice(pathSegmentsToKeep).join('/').replace(/&/g, '~and~') +
+        (l.search ? '&' + l.search.slice(1).replace(/&/g, '~and~') : '') +
+        l.hash
+      );
+    </script>
+  </head>
+  <body></body>
+</html>

package/demo/public/favicon.svg

@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
-  <rect width="100" height="100" fill="#4F46E5"/>
-  <text x="50" y="65" font-size="60" font-weight="bold" text-anchor="middle" fill="white">i18n</text>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect width="100" height="100" fill="#4F46E5"/>
+  <text x="50" y="65" font-size="60" font-weight="bold" text-anchor="middle" fill="white">i18n</text>
+</svg>

package/demo/public/logo.svg

@@ -1,24 +1,24 @@
-<svg width="180" height="180" viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <defs>
-    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" stop-color="#3A5AFE" />
-      <stop offset="100%" stop-color="#14B8A6" />
-    </linearGradient>
-    <linearGradient id="accent" x1="0%" y1="0%" x2="0%" y2="100%">
-      <stop offset="0%" stop-color="#FFFFFF" stop-opacity="0.9" />
-      <stop offset="100%" stop-color="#FFFFFF" stop-opacity="0.2" />
-    </linearGradient>
-    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%" color-interpolation-filters="sRGB">
-      <feDropShadow dx="0" dy="8" stdDeviation="12" flood-color="#0B1220" flood-opacity="0.28" />
-    </filter>
-  </defs>
-  <rect width="180" height="180" rx="32" fill="url(#bg)" filter="url(#shadow)" />
-  <g transform="translate(45 45)">
-    <path d="M45 0C20.147 0 0 20.147 0 45C0 69.853 20.147 90 45 90C69.853 90 90 69.853 90 45C90 20.147 69.853 0 45 0ZM45 72C29.088 72 15.75 58.662 15.75 42.75C15.75 26.838 29.088 13.5 45 13.5C60.912 13.5 74.25 26.838 74.25 42.75C74.25 58.662 60.912 72 45 72Z" fill="white" opacity="0.2" />
-    <path d="M24 27H66C70.971 27 75 31.029 75 36V54C75 58.971 70.971 63 66 63H24C19.029 63 15 58.971 15 54V36C15 31.029 19.029 27 24 27Z" fill="url(#accent)" />
-    <path d="M36 54V45C36 40.029 40.029 36 45 36C49.971 36 54 40.029 54 45V54" stroke="#0B1220" stroke-width="4" stroke-linecap="round" />
-    <circle cx="45" cy="21" r="6" fill="white" />
-    <path d="M33 69H57" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.7" />
-    <path d="M27 15H63" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.4" />
-  </g>
-</svg>
+<svg width="180" height="180" viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#3A5AFE" />
+      <stop offset="100%" stop-color="#14B8A6" />
+    </linearGradient>
+    <linearGradient id="accent" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" stop-color="#FFFFFF" stop-opacity="0.9" />
+      <stop offset="100%" stop-color="#FFFFFF" stop-opacity="0.2" />
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%" color-interpolation-filters="sRGB">
+      <feDropShadow dx="0" dy="8" stdDeviation="12" flood-color="#0B1220" flood-opacity="0.28" />
+    </filter>
+  </defs>
+  <rect width="180" height="180" rx="32" fill="url(#bg)" filter="url(#shadow)" />
+  <g transform="translate(45 45)">
+    <path d="M45 0C20.147 0 0 20.147 0 45C0 69.853 20.147 90 45 90C69.853 90 90 69.853 90 45C90 20.147 69.853 0 45 0ZM45 72C29.088 72 15.75 58.662 15.75 42.75C15.75 26.838 29.088 13.5 45 13.5C60.912 13.5 74.25 26.838 74.25 42.75C74.25 58.662 60.912 72 45 72Z" fill="white" opacity="0.2" />
+    <path d="M24 27H66C70.971 27 75 31.029 75 36V54C75 58.971 70.971 63 66 63H24C19.029 63 15 58.971 15 54V36C15 31.029 19.029 27 24 27Z" fill="url(#accent)" />
+    <path d="M36 54V45C36 40.029 40.029 36 45 36C49.971 36 54 40.029 54 45V54" stroke="#0B1220" stroke-width="4" stroke-linecap="round" />
+    <circle cx="45" cy="21" r="6" fill="white" />
+    <path d="M33 69H57" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.7" />
+    <path d="M27 15H63" stroke="white" stroke-width="4" stroke-linecap="round" opacity="0.4" />
+  </g>
+</svg>