@thebase/ui 1.1.7 → 1.2.1

package/docs/i18n.md

@@ -0,0 +1,119 @@
+# i18n service
+
+Instructions for adding translations to a page or app with the Base UI i18n service (`@thebase/ui/i18n`). It is optional and standalone: no Owl, Bootstrap or component runtime, and it is not part of the main bundles.
+
+- **Audience:** developers adding a language switcher or translating an existing page.
+- **Runnable example:** `examples/i18n/` (open `/examples/i18n/` from `npm run dev`).
+- **Real-world use:** `emvhub/i18n.js` and the `i18n/*.po` folders beside each emvhub module.
+
+## 1. How it works
+
+You write every text in the default language and wrap it in `t()`. Each module keeps its translations in an `i18n/<code>.po` folder next to it and loads them with `loadCatalog(import.meta.url)`. The service picks one language per page load and fills a shared lookup; `t()` returns the translation, or the original text when none exists.
+
+```mermaid
+flowchart LR
+  A["init(config)"] --> B["loadCatalog(import.meta.url)"]
+  B --> C{"Pick language"}
+  C -->|"?lang= → saved choice → browser → default"| D["Fetch ./i18n/code.po"]
+  D --> E["Finished entries join the lookup"]
+  E --> F["t(text) returns translation"]
+  G["setLanguage(code)"] -->|"saves choice, reloads"| B
+```
+
+## 2. Install
+
+| How you load it | Use |
+| --- | --- |
+| ES module | `import { init, t, loadCatalog } from "@thebase/ui/i18n"` (file: `dist/baseui.i18n.esm.js`) |
+| Import map | map `@base/i18n` to the ESM file, then `import … from "@base/i18n"` |
+| Script tag | `dist/baseui.i18n.min.js` sets `window.thebase.i18n` |
+
+## 3. Quick start
+
+1. Map the module in your HTML:
+
+```html
+<script type="importmap">
+  { "imports": { "@base/i18n": "https://cdn.jsdelivr.net/npm/@thebase/ui@<version>/dist/baseui.i18n.esm.js" } }
+</script>
+```
+
+2. Configure once, then load the catalog next to your module:
+
+```js
+import { init, t, loadCatalog, languages, currentLanguage, setLanguage, translateHead } from "@base/i18n";
+
+init({ languages: [{ code: "en", label: "English" }, { code: "vi", label: "Tiếng Việt" }], storageKey: "my-lang" });
+await loadCatalog(import.meta.url); // fetches ./i18n/vi.po when Vietnamese is picked
+translateHead();
+document.querySelector("h1").textContent = t("Hello {name}", { name: "An" });
+```
+
+3. Add `i18n/vi.po` beside the module:
+
+```po
+msgid ""
+msgstr "Language: vi\n"
+
+msgid "Hello {name}"
+msgstr "Xin chào {name}"
+```
+
+## 4. API reference
+
+| Function | Purpose |
+| --- | --- |
+| `init(options)` | Sets languages and defaults. Call once, before the first `loadCatalog()`; it throws afterwards. |
+| `loadCatalog(moduleUrl)` | Picks the language on the first call, then fetches `<catalogDir>/<code>.po` next to `moduleUrl` once. Returns a promise; await it before using `t()`. No request is made for the default language. |
+| `t(text, params?)` | Returns the translation or the original text; replaces `{name}` placeholders from `params`. |
+| `languages()` | The configured `{ code, label }` list, for a switcher. |
+| `currentLanguage()` | The code in use, to mark the active switcher item. |
+| `setLanguage(code)` | Saves the choice and reloads the page with `?lang=<code>`. |
+| `translateHead()` | Translates `document.title` and the meta description. |
+| `parsePo(text)` | Parses `.po` text into a `Map` of original text → `{ id, str, fuzzy }` (useful in tooling and tests). |
+
+### `init()` options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `languages` | `[{ code: "en", label: "English" }]` | Languages the page can show; `code` is the `.po` file name, `label` is shown in the language's own words. |
+| `defaultLanguage` | first language | The language your texts are written in; no catalog is loaded for it. |
+| `storageKey` | `"thebase-lang"` | `localStorage` key that remembers the visitor's choice. |
+| `queryParam` | `"lang"` | URL parameter that forces a language. |
+| `catalogDir` | `"i18n"` | Folder beside each module that holds the `.po` files. |
+| `headDescription` | `meta[name="description"]` | Selector of the tag `translateHead()` translates. |
+
+Language order: URL parameter, saved choice, browser languages (first two letters), default.
+
+## 5. Writing `.po` files
+
+- One block per text: `msgid` (original, exact match) and `msgstr` (translation). Long texts may continue on following quoted lines.
+- Entries with an empty `msgstr` or a `#, fuzzy` flag are ignored, so unfinished work never reaches visitors.
+- Text matching is exact and case-sensitive. Changing a source string in code means updating its `msgid`.
+- Keep placeholders identical in both: `{name}` in the `msgid` must appear as `{name}` in the `msgstr`.
+- Never build a sentence from joined fragments; use one text with placeholders.
+
+## 6. Multi-module apps
+
+Each module loads its own catalog, but language selection and `init()` must happen once and first. Create one local file that every module imports:
+
+```js
+// i18n.js
+import { init } from "@base/i18n";
+
+init({ languages: [{ code: "en", label: "English" }, { code: "vi", label: "Tiếng Việt" }], storageKey: "my-lang" });
+export * from "@base/i18n";
+```
+
+Because ES modules evaluate dependencies first, `init()` runs before any module's top-level `await loadCatalog(import.meta.url)`. A module that shares another folder's texts loads both: `await Promise.all([loadCatalog(import.meta.url), loadCatalog(new URL("../lib/", import.meta.url))])`.
+
+## 7. Gotchas
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `init() must be called before the first loadCatalog()` | A module loaded a catalog first. Route all imports through the single local file above. |
+| Texts stay in English | The `msgid` differs from the code string, the entry is fuzzy or empty, or the `.po` URL 404s (check `catalogDir` and `moduleUrl`). Failed fetches are silent by design. |
+| Module-level texts untranslated | `t()` ran before `await loadCatalog(...)` finished. Await it at the top of the module. |
+| Switching language reloads the page | By design: every text is redrawn in the new language. |
+| Choice not remembered | Storage is blocked; the `?lang=` link still works for that visit. |
+| Offline/PWA | Precache each `i18n/<code>.po` in your service worker (see `emvhub/baseui.pwa.config.js`). |

package/docs/icons.md

@@ -22,7 +22,7 @@ Load the normal the Base UI assets. No separate icon script is required.
 <script src="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.js" defer></script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.7`, or `@1` to take only non-breaking updates) instead of `@latest` for production. `b-icon` also works with the [pure Base `Icon` component](components/icon.md) — the recommended API in an application; the classic script above is for pages using the static `b-ui` API.
+`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.2.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production. `b-icon` also works with the [pure Base `Icon` component](components/icon.md) — the recommended API in an application; the classic script above is for pages using the static `b-ui` API.
 
 The build publishes every Lucide SVG to `dist/icons/lucide/` and writes the generated icon manifest to `dist/icons/lucide.json`.
 

package/docs/installation.md

@@ -4,7 +4,7 @@ See the [Usage Guide](usage-guide.md) for the end-to-end integration path (choos
 
 The Base UI is distributed as one CSS file and one JavaScript file for browser use. `dist/baseui.min.js` is fully self-contained: Bootstrap's JS bundle (Popper.js included) and the Owl runtime are embedded ahead of the Base UI's own code, in load order (Bootstrap, then Owl, then the Base UI) — nothing else needs to load first. Both install paths below load this same file; the Base component API is the recommended way to consume the Base UI in an application, with the base static markup (`b-ui`) API available as a lighter-weight alternative for non-Owl pages.
 
-The snippets below use the `@latest` tag for readability. Pin an exact version instead (e.g. `@1.1.7`, or `@1` to take only non-breaking updates) for any production page — `@latest` can silently change what your page loads the moment a new version is published.
+The snippets below use the `@latest` tag for readability. Pin an exact version instead (e.g. `@1.2.1`, or `@1` to take only non-breaking updates) for any production page — `@latest` can silently change what your page loads the moment a new version is published.
 
 ## Base component install (recommended)
 
@@ -43,7 +43,7 @@ For static HTML, a server-rendered page, or a Base HUB website page that has no
 
 Bootstrap 5 is the bundled baseline CSS framework, and its JS bundle now drives the Base UI's interactive components directly.
 
-`@thebase/ui` is published on npm, so [unpkg](https://unpkg.com/@thebase/ui@latest/) mirrors the same files as an alternative CDN (`https://unpkg.com/@thebase/ui@latest/dist/baseui.min.css` / `baseui.min.js`) if jsDelivr is unreachable in your environment. Pin an exact version (e.g. `@1.1.7`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
+`@thebase/ui` is published on npm, so [unpkg](https://unpkg.com/@thebase/ui@latest/) mirrors the same files as an alternative CDN (`https://unpkg.com/@thebase/ui@latest/dist/baseui.min.css` / `baseui.min.js`) if jsDelivr is unreachable in your environment. Pin an exact version (e.g. `@1.2.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
 
 For npm/self-hosted usage:
 
@@ -77,6 +77,7 @@ Production pages should use pinned version URLs. `latest` is for demos and exper
 | Owl templates XML | `@thebase/ui/dist/baseui.templates.xml` | `@base/templates` | `dist/baseui.templates.xml` |
 | Registry metadata | `@thebase/ui/registry` | none; fetch the JSON file | `dist/baseui.registry.json` |
 | Optional analytics service (`init`, `track`) | `@thebase/ui/analytics` | none; import the file URL or load the `<script>` build (sets `window.thebase.analytics`) | `dist/baseui.analytics.esm.js`, `dist/baseui.analytics.min.js` |
+| Optional i18n service (`init`, `t`, `loadCatalog`) | `@thebase/ui/i18n` | `@base/i18n` (as in `emvhub/index.html`); or load the `<script>` build (sets `window.thebase.i18n`) | `dist/baseui.i18n.esm.js`, `dist/baseui.i18n.min.js` |
 | Standalone ApiDoc (`mountApiDoc`) | `@thebase/ui/apidoc` | none; embeds Owl + its templates, still needs `baseui.min.css`; set `assetBase` for the language logos | `dist/baseui.apidoc.esm.js`, `dist/baseui.apidoc.min.js` |
 
 `@base/templates` points to XML, not JavaScript. Resolve and fetch it (`fetch(import.meta.resolve("@base/templates"))`) before mounting an application that uses the Base UI component classes.

package/docs/owl-components.md

@@ -55,7 +55,7 @@ Everything — the static `b-ui` runtime, the Owl framework, every Base componen
 </script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. For a self-hosted build, replace the CDN host with your own served path (e.g. `/dist/baseui.esm.js`). These snippets use `@latest` for readability; pin an exact version (e.g. `@1.1.6`, or `@1` to take only non-breaking updates) in production so a new release can't change what your page loads.
+`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. For a self-hosted build, replace the CDN host with your own served path (e.g. `/dist/baseui.esm.js`). These snippets use `@latest` for readability; pin an exact version (e.g. `@1.2.1`, or `@1` to take only non-breaking updates) in production so a new release can't change what your page loads.
 
 No `@odoo/owl` import appears anywhere in that snippet — `@base/owl` is the only Owl entry point the Base UI components and consumer apps need. Because `@base/owl`, `@base/component`, and `@base/theme` all point at the exact same `dist/baseui.esm.js` URL, the browser fetches and evaluates it once and every key shares the same module instance — no separate classic `<script>` needs to load first to set up a shared global.
 

package/docs/registry.md

@@ -14,6 +14,7 @@ The Base UI ships as bundled files only — there is no per-component source dis
 - `baseui.icons.esm.js` — the 2000+ generated `Icon<Name>` components (`IconEye`, `IconSearch`, ...), split out because they'd blow the main bundle's size budget. The one deliberate exception to "everything is one bundle".
 - `baseui.templates.xml` — every Base component's compiled `<templates>` body, concatenated into one file. Load this into the Owl `App`'s `templates` config before mounting; `.xml` files under `src/components/` are authoring sources, not something a consumer app loads directly.
 - `baseui.analytics.esm.js` / `baseui.analytics.min.js` — the optional, standalone cookieless analytics service (`@thebase/ui/analytics`). Not part of the main bundles and needs no other Base UI file; see [Analytics](analytics.md).
+- `baseui.i18n.esm.js` / `baseui.i18n.min.js` — the optional, standalone gettext-style i18n service (`@thebase/ui/i18n`). Not part of the main bundles and needs no other Base UI file; see [i18n](i18n.md).
 - `icons/lucide.json` — the built-in icon manifest.
 
 ## Component export policy

package/docs/runtime-api.md

@@ -14,9 +14,11 @@ thebase.theme.set("dark")
 thebase.theme.set({ primary: "#0f6cbd" })
 thebase.analytics.init({ domain, endpoint })
 thebase.track(eventName, options)
+thebase.i18n.init({ languages, defaultLanguage })
+thebase.i18n.t(text, params)
 ```
 
-`thebase.analytics` is set only when the optional `dist/baseui.analytics.min.js` is loaded (it is not in the main bundles), and `thebase.track` is bound once it is initialized — see [Analytics](analytics.md).
+`thebase.analytics` is set only when the optional `dist/baseui.analytics.min.js` is loaded (it is not in the main bundles), and `thebase.track` is bound once it is initialized — see [Analytics](analytics.md). Likewise `thebase.i18n` is set only when the optional `dist/baseui.i18n.min.js` is loaded — see [i18n](i18n.md).
 
 The static runtime calls `autoMount()` when imported through `dist/baseui.esm.js` or `dist/baseui.min.js`. Existing `[b-ui]` and `[b-icon]` markers are enhanced automatically once the DOM is ready.
 
@@ -38,8 +40,8 @@ Mounted components dispatch lifecycle events on their root element:
 ```js
 import { cn } from "@thebase/ui";
 
-cn("btn", isActive && "active", ["bu-button", className]);
-// "btn active bu-button my-class" (when isActive is truthy and className is "my-class")
+cn("btn", isActive && "active", ["b-button", className]);
+// "btn active b-button my-class" (when isActive is truthy and className is "my-class")
 ```
 
 It's a standalone named export — `import { cn } from "@thebase/ui"` in npm/bundler apps, or `BaseUIBundle.cn` in the browser IIFE global — not a method on `BaseUI` itself. Use it to build your own components' class lists on top of the Base UI's conventions.

package/docs/theming.md

@@ -13,6 +13,36 @@ thebase.theme.set("dark");
 thebase.theme.set({ primary: "#0057d8", radius: "0.5rem" });
 ```
 
+## Make your own theme
+
+`dist/baseui.min.css` is the only stylesheet an app loads; it already includes the default light and dark themes. A custom theme is two small files, `baseui-light.css` and `baseui-dark.css` (readable copies in `dist/themes/`, minified `.min.css` versions beside them), loaded after it.
+
+1. Build one visually in the **theme creator** (the **Theme** tab of the examples app (`examples/index.html#/theme`)): pick a base colour, accent and radius, preview Base UI live in light or dark, then download `baseui-light.css` and `baseui-dark.css`.
+2. Or download the two files from `dist/themes/` (or copy `src/themes/`) and edit the values by hand.
+3. Load them after the Base UI stylesheet:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@1.2.1/dist/baseui.min.css">
+<link rel="stylesheet" href="/css/baseui-light.css">
+<link rel="stylesheet" href="/css/baseui-dark.css">
+```
+
+Each file declares the same variables on its own selector (`light`: `:root`, `[b-theme="light"]`, `.light`; `dark`: `[b-theme="dark"]`, `.dark`), so loading yours after the defaults replaces them. Edit only the values; keep the selectors and variable names. The tokens you will usually change:
+
+| Token | Controls |
+| --- | --- |
+| `--b-background`, `--b-foreground` | Page background and text |
+| `--b-surface`, `--b-card`, `--b-popover` (+ `-foreground`) | Raised surfaces |
+| `--b-primary`, `--b-primary-rgb`, `--b-primary-foreground` | Primary buttons, links, active states (keep `-rgb` in sync with the colour) |
+| `--b-secondary`, `--b-muted`, `--b-accent` (+ `-foreground`) | Subtle fills and hover states |
+| `--b-danger`, `--b-success`, `--b-warning`, `--b-info` (each with `-rgb` and `-foreground`) | Error/destructive, success, warning and info states: buttons (`.btn-success` …), badges, alerts, Bootstrap `text-*`/`bg-*` helpers |
+| `--b-border`, `--b-input`, `--b-ring` | Borders, field outlines, focus ring |
+| `--b-chart-1` … `--b-chart-5`, `--b-sidebar-*` | Charts and the sidebar |
+| `--base-radius` | Corner roundness; every `--b-radius-*` step is derived from it |
+| `--b-overlay` | Backdrop behind dialogs and sheets |
+
+To change a few values without a full theme, override them on `:root` / `[b-theme="dark"]` in your own CSS, or at runtime with `thebase.theme.set({ primary: "#0057d8", radius: "0.5rem" })`.
+
 The Base UI maps semantic tokens such as `--b-background`, `--b-primary`, `--b-border`, and `--b-radius` into Bootstrap 5 variables. Radius tokens are sourced from the shorter public alias family `--base-radius`, `--base-radius-sm`, `--base-radius-md`, `--base-radius-lg`, `--base-radius-xl`, `--base-radius-2xl`, `--base-radius-3xl`, `--base-radius-4xl`, and `--base-radius-full`, then mirrored to `--b-radius*` for component CSS.
 
 For a reusable theme toggle with persistence, URL override, button-label sync, and iframe preview sync, import the theme helper:
@@ -38,7 +68,7 @@ For a reusable theme toggle with persistence, URL override, button-label sync, a
 </script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/baseui.esm.js` mirrors the same file as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.7`, or `@1` to take only non-breaking updates) instead of `@latest` for production. Npm/bundler consumers can import the same API from `@thebase/ui`.
+`https://unpkg.com/@thebase/ui@latest/dist/baseui.esm.js` mirrors the same file as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.2.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production. Npm/bundler consumers can import the same API from `@thebase/ui`.
 
 For a ready-made icon button, use the Base UI component instead of wiring your own click handler:
 
@@ -50,6 +80,6 @@ The documentation and example pages use the same theme infrastructure. Owl examp
 
 ## Design tokens
 
-The default light/dark palettes and radius follow the current [shadcn/ui](https://ui.shadcn.com) Base UI neutral theme: black/neutral primary on white in light mode, neutral-900/50 foreground-background inversion in dark mode, neutral `--b-secondary`/`--b-muted`/`--b-accent` surfaces, `--base-radius: var(--radius, 0.625rem)`, and a derived radius scale (`--base-radius-sm|md|lg|xl`, mirrored as `--b-radius-sm|md|lg|xl`) and shadow scale (`--b-shadow-sm|md|lg`) for consistent elevation across popovers, menus, dialogs, and toasts. The Base UI reads an existing upstream `--radius` value when present, but it does not redefine `--radius` back to `--b-radius`; that one-way bridge avoids CSS custom-property cycles. `--b-card`/`--b-popover` alias `--b-surface` for shadcn-token-name parity.
+The default light/dark palettes and radius follow the current [shadcn/ui](https://ui.shadcn.com) Base UI neutral theme: black/neutral primary on white in light mode, neutral-900/50 foreground-background inversion in dark mode, neutral `--b-secondary`/`--b-muted`/`--b-accent` surfaces, `--base-radius: var(--radius, 0.625rem)` (set in the theme files), and a derived radius scale (`--base-radius-sm|md|lg|xl`, mirrored as `--b-radius-sm|md|lg|xl`) and shadow scale (`--b-shadow-sm|md|lg`) for consistent elevation across popovers, menus, dialogs, and toasts. The Base UI reads an existing upstream `--radius` value when present, but it does not redefine `--radius` back to `--b-radius`; that one-way bridge avoids CSS custom-property cycles. `--b-card`/`--b-popover` alias `--b-surface` for shadcn-token-name parity.
 
-Because the Base UI ships Bootstrap's stock precompiled CSS, most `.btn-*`/badge colors are not driven by `--bs-*` variables directly — `src/styles/baseui.css` re-points the `.btn-primary`/`.btn-secondary`/`.btn-danger`/`.btn-outline-secondary`/`.btn-light` variants at the Base UI tokens so `thebase.theme.set(...)` overrides actually render. Badges use their own `bu-badge-*` classes (`src/components/badge/badge.css`) instead of Bootstrap's `text-bg-*`, which hardcode non-overridable colors.
+Because the Base UI ships Bootstrap's stock precompiled CSS, most `.btn-*`/badge colors are not driven by `--bs-*` variables directly — `src/styles/base-extensions.css` re-points the `.btn-primary`/`.btn-secondary`/`.btn-danger`/`.btn-outline-secondary`/`.btn-light` variants at the Base UI tokens so `thebase.theme.set(...)` overrides actually render. Badges use their own `b-badge-*` classes (`src/components/badge/badge.css`) instead of Bootstrap's `text-bg-*`, which hardcode non-overridable colors.

package/docs/usage-guide.md

@@ -32,7 +32,7 @@ Save this as an `.html` file and open it — no build step, no server required.
 </html>
 ```
 
-`https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/...` is the real jsDelivr URL for the published `@thebase/ui` npm package's `latest` tag, used here for a copy-paste-and-go quick start. Pin an exact version instead (e.g. `@1.1.7`, or `@1` to take only non-breaking updates) for production, so a new release can't change what your page loads. See [Installation](installation.md) for jsDelivr/unpkg/npm/self-hosted paths.
+`https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/...` is the real jsDelivr URL for the published `@thebase/ui` npm package's `latest` tag, used here for a copy-paste-and-go quick start. Pin an exact version instead (e.g. `@1.2.1`, or `@1` to take only non-breaking updates) for production, so a new release can't change what your page loads. See [Installation](installation.md) for jsDelivr/unpkg/npm/self-hosted paths.
 
 The static bundle calls `thebase.mountAll()` automatically on `DOMContentLoaded`, so initial `[b-ui]` and `[b-icon]` markup mounts without an extra script. Call `thebase.mountAll(root)` yourself only after injecting new markup or when mounting a specific fragment. If the consumer is itself an application, use [step 2](#2-install-pure-owl-api--recommended) instead — that's the recommended path.
 
@@ -63,7 +63,7 @@ Both APIs come from the same package and the same CSS file, and can be mixed on
 </script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. Pin an exact version (e.g. `@1.1.7`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
+`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable — swap the host in each URL above. Pin an exact version (e.g. `@1.2.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
 
 ```html
 <script type="module">
@@ -103,7 +103,7 @@ Two rules that account for most integration failures — see [Base Components](o
 <script src="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.js" defer></script>
 ```
 
-`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.1.7`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
+`https://unpkg.com/@thebase/ui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.2.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
 
 **Option B — npm (bundler-based apps: Vite, webpack, etc.):**
 
@@ -120,7 +120,7 @@ import "@thebase/ui"; // side-effect import: registers window.thebase and auto-m
 
 Rule that applies to both options:
 
-- Production pages must use a pinned version (e.g. `@thebase/ui@1.1.7` or `@thebase/ui@1`), never `@latest`.
+- Production pages must use a pinned version (e.g. `@thebase/ui@1.2.1` or `@thebase/ui@1`), never `@latest`.
 
 Mount markup:
 
@@ -219,7 +219,7 @@ export default {
   },
   serviceWorker: {
     cacheName: "my-app-cache-v1",
-    cdnVersion: "1.1.7", // pin to match the importmap in index.html
+    cdnVersion: "1.2.1", // pin to match the importmap in index.html
     appFiles: ["/app.css", "/app.js", "/app.xml", "/favicon.svg", "/icons/icon-192.png", "/icons/icon-512.png"],
   },
 };
@@ -227,9 +227,17 @@ export default {
 
 ```sh
 npx create-baseui-app pwa . --config baseui.pwa.config.js
-# writes ./manifest.webmanifest and ./sw.js
+# writes ./manifest.webmanifest, ./sw.js, ./sw-register.js and ./version.json
 ```
 
+**Auto-reload on a new deploy.** The generated `sw.js` fetches `version.json` (never cached) on activate, on
+every page navigation and when the page posts `"check-version"`. When the value differs from the last one it
+saw, it wipes the caches, re-precaches the app shell and posts `"version-changed"` to every open page.
+`sw-register.js` (load it with `<script type="module" src="/sw-register.js">`, replacing your own
+`serviceWorker.register`) registers the worker, reloads on that message and re-checks when the tab becomes
+visible. `version.json` is a content hash of `sw.js`, the manifest and every `appFiles` entry found under
+`<path>`, so re-run the `pwa` command as the last step of every deploy.
+
 Re-run the command whenever `appFiles`, the CDN pin, or manifest fields change — both output files are
 fully regenerated, never hand-patched. Only `manifest.name`, `serviceWorker.cacheName`, and
 `serviceWorker.cdnVersion` are required; everything else (icons, theme/background color, display
@@ -239,6 +247,15 @@ files are kept, so your own icons win). Serving icons from another folder? Set `
 service worker) and `manifestUrl` (service worker) in the config. See
 `dist/types/pwa.d.ts` for the full config shape.
 
+**Default in every scaffolded project.** `create-baseui-app create|init` projects ship
+`plugins: [baseuiPwa({ name })]` (from `@thebase/ui/vite`) in `vite.config.js`. Each `vite build` then emits
+`manifest.webmanifest`, `sw.js`, `sw-register.js`, `version.json` (hash of the built bundle) and the default
+icons into `dist/`, and injects the manifest link, theme color and register script into every page — no
+config file, no extra command. Every deploy with changed code therefore reloads open pages automatically.
+`vite dev` is untouched. Options: `name`, `description`, `themeColor` and the other manifest fields, plus
+`cdnVersion` (only for apps that load BaseUI from the CDN). For an existing project, add the plugin to
+`vite.config.js` (`convert` prints this hint). Remove the plugin to opt out.
+
 ## 6. Copy a block instead of assembling from primitives
 
 For common layouts (dashboard shells, sidebars, login/signup forms, charts), copy a ready-made block from the gallery instead of composing primitives by hand: [Blocks](blocks.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebase/ui",
-  "version": "1.1.7",
+  "version": "1.2.1",
   "description": "CDN-installable Bootstrap 5 UI component library.",
   "type": "module",
   "main": "./dist/baseui.min.js",
@@ -25,6 +25,11 @@
       "import": "./dist/baseui.analytics.esm.js",
       "default": "./dist/baseui.analytics.min.js"
     },
+    "./i18n": {
+      "types": "./dist/types/i18n.d.ts",
+      "import": "./dist/baseui.i18n.esm.js",
+      "default": "./dist/baseui.i18n.min.js"
+    },
     "./apidoc": {
       "types": "./dist/types/apidoc.d.ts",
       "import": "./dist/baseui.apidoc.esm.js",
@@ -34,6 +39,10 @@
       "types": "./dist/types/pwa.d.ts",
       "import": "./dist/baseui.pwa.esm.js"
     },
+    "./vite": {
+      "types": "./dist/types/vite.d.ts",
+      "import": "./dist/baseui.vite.esm.js"
+    },
     "./dist/baseui.templates.xml": "./dist/baseui.templates.xml"
   },
   "files": [
@@ -44,9 +53,12 @@
     "dist/baseui.icons.esm.js",
     "dist/baseui.analytics.esm.js",
     "dist/baseui.analytics.min.js",
+    "dist/baseui.i18n.esm.js",
+    "dist/baseui.i18n.min.js",
     "dist/baseui.apidoc.esm.js",
     "dist/baseui.apidoc.min.js",
     "dist/baseui.pwa.esm.js",
+    "dist/baseui.vite.esm.js",
     "dist/baseui.templates.xml",
     "dist/icons",
     "dist/pwa-icons",