@thebase/ui 1.2.0 → 1.3.0

package/docs/components/textarea.md

@@ -1,11 +1,11 @@
 # Textarea
 
-Native multiline text input with Base UI and Bootstrap styling.
+Native multiline text input with Nodex UI and built-in styling.
 
 ## Base component
 
 ```js
-import { Textarea } from "@thebase/ui";
+import { Textarea } from "nodexui";
 ```
 
 ```base-ui
@@ -64,7 +64,7 @@ Set `useTip="1"` to move `supportingText` into a tooltip: a question-mark icon a
 | `Textarea` | slots `start` / `end` / `footer` | slot | content drawn inside the box; `footer` sits along the bottom edge |
 | `Textarea` | `label`, `supportingText`, `useTip`, `errorText`, `maxLength`, `invalid`, `placeholder` | `String` / `Boolean` | Material-style outlined field, same behaviour as [Input](/examples/blocks.html#/docs/components/input): the label floats onto the border, `errorText` replaces `supportingText`. Also inherited from a parent `Field`. |
 
-See [Base Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+See [Nodex UI Component](/examples/blocks.html#/docs/guide/owl-components) for how to load `nodexui` and `dist/nodexui.templates.xml`.
 
 ## Static component
 

package/docs/components/theme-button.md

@@ -4,12 +4,12 @@ Use `b-ui="theme-button"` for an icon-only light/dark theme toggle.
 
 ## CDN install requirements
 
-Load the Base UI CSS and the Base UI JavaScript bundle (`baseui.min.js`). The component uses the built-in Lucide icon renderer and the `@base/theme` helper bundled with Base UI.
+Load Nodex UI CSS and Nodex UI JavaScript bundle (`nodexui.min.js`). The component uses the built-in Lucide icon renderer and the `nodexui` helper bundled with Nodex UI.
 
 ## Base component
 
 ```js
-import { ThemeButton } from "@thebase/ui";
+import { ThemeButton } from "nodexui";
 ```
 
 ```base-ui
@@ -24,7 +24,7 @@ import { ThemeButton } from "@thebase/ui";
 | `ThemeButton` | `className` | `String` | optional |
 | `ThemeButton` | `onChange` | `Function` | optional |
 
-See [Base Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+See [Nodex UI Component](/examples/blocks.html#/docs/guide/owl-components) for how to load `nodexui` and `dist/nodexui.templates.xml`.
 
 ## Static component
 
@@ -42,11 +42,11 @@ Use `b-att-variant="default|outline|ghost|destructive|secondary|link"` and `b-at
 
 ## Methods
 
-Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`. For direct theme control, import `createThemeController` from `@thebase/ui`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`. For direct theme control, import `createThemeController` from `nodexui`.
 
 ## Events
 
-Theme changes dispatch `baseui:theme-change` on `document` with `{ theme }` in `event.detail`.
+Theme changes dispatch `nodexui:theme-change` on `document` with `{ theme }` in `event.detail`.
 
 ## CSS variables
 
@@ -62,7 +62,7 @@ See the example page headers for working `b-ui="theme-button"` navigation usage.
 
 ## Browser support
 
-The Base UI targets modern evergreen browsers that support ES modules, CSS variables, and Bootstrap 5.3.
+Nodex UI targets modern evergreen browsers that support ES modules, CSS variables.
 
 ## Test checklist
 

package/docs/components/toast.md

@@ -5,7 +5,7 @@ Use `b-ui="toast"` for transient status messages.
 ## Base component
 
 ```js
-import { Toast } from "@thebase/ui";
+import { Toast } from "nodexui";
 ```
 
 ```base-ui
@@ -35,7 +35,7 @@ The toast stays hidden until `open`/`state` becomes truthy (never shows on mount
 | `Toast` | `onOpenChange` | `Function` | optional |
 | `Toast` | `action` slot | — | optional — e.g. a `<Button/>`, rendered grouped next to the close button (`<t t-set-slot="action">...</t>`) |
 
-See [Base Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+See [Nodex UI Component](/examples/blocks.html#/docs/guide/owl-components) for how to load `nodexui` and `dist/nodexui.templates.xml`.
 
 ## Static component
 
@@ -54,7 +54,7 @@ The toast stays hidden until shown — omit `b-att-state="open"` and call `.show
 
 ```base-ui
 <div class="d-flex flex-column align-items-center gap-3">
-  <button type="button" class="btn b-button btn-outline-secondary" onclick="document.getElementById('demo-toast').BaseUIToast.show()">Show Toast</button>
+  <button type="button" class="btn b-button btn-outline-secondary" onclick="document.getElementById('demo-toast').NodexUIToast.show()">Show Toast</button>
   <div id="demo-toast" b-ui="toast" b-att-delay="3000">
     <div class="b-toast-content">
       <div class="fw-medium">Event created</div>
@@ -68,13 +68,13 @@ The toast stays hidden until shown — omit `b-att-state="open"` and call `.show
 </div>
 ```
 
-Programmatic API: after mount, call `element.BaseUIToast.show()` or `element.BaseUIToast.hide()`. Events: `baseui:open`, `baseui:close`.
+Programmatic API: after mount, call `element.NodexUIToast.show()` or `element.NodexUIToast.hide()`. Events: `nodexui:open`, `nodexui:close`.
 
-Toasts are backed by `bootstrap.Toast`: the root receives Bootstrap's `toast fade` classes, and visibility is driven by Bootstrap's own `show`/`showing` classes (not `hidden`). The close button(s) carry `data-bs-dismiss="toast"` in addition to the `b-toast-close`/`b-toast-close` selector, so Bootstrap's own delegated dismiss handler drives them.
+Toasts are backed by `bootstrap.Toast`: the root receives the built-in `toast fade` classes, and visibility is driven by the built-in `show`/`showing` classes (not `hidden`). The close button(s) carry `data-bs-dismiss="toast"` in addition to the `b-toast-close`/`b-toast-close` selector, so the built-in delegated dismiss handler drives them.
 
 ### Screen-corner placement
 
-Set `b-att-position` to `top-left`, `top-right`, `bottom-left`, or `bottom-right` to fix the toast to that corner of the viewport. The toast element itself gets the Bootstrap `toast-container position-fixed p-3 pe-auto` classes plus the matching edge utility classes (`top-0`/`bottom-0` + `start-0`/`end-0`) merged in — no wrapper element. Omit the attribute to leave the toast inline in the document flow (the previous, default behavior):
+Set `b-att-position` to `top-left`, `top-right`, `bottom-left`, or `bottom-right` to fix the toast to that corner of the viewport. The toast element itself gets the built-in `toast-container position-fixed p-3 pe-auto` classes plus the matching edge utility classes (`top-0`/`bottom-0` + `start-0`/`end-0`) merged in — no wrapper element. Omit the attribute to leave the toast inline in the document flow (the previous, default behavior):
 
 ```base-ui
 <div id="corner-toast" b-ui="toast" b-att-position="bottom-right" b-att-delay="3000">

package/docs/components/toggle-group.md

@@ -4,12 +4,12 @@ Use `b-ui="toggle-group"` for a CDN-ready toggle group component.
 
 ## CDN install requirements
 
-Load the pinned the Base UI CSS and JavaScript files; no extra dependency is required for this component.
+Load the pinned Nodex UI CSS and JavaScript files; no extra dependency is required for this component.
 
 ## Base component
 
 ```js
-import { ToggleGroup, ToggleGroupItem } from "@thebase/ui";
+import { ToggleGroup, ToggleGroupItem } from "nodexui";
 ```
 
 ```base-ui
@@ -36,7 +36,7 @@ import { ToggleGroup, ToggleGroupItem } from "@thebase/ui";
 | `ToggleGroupItem` | `value` | `String` | required |
 | `ToggleGroupItem` | `className` | `String` | optional |
 
-See [Base Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+See [Nodex UI Component](/examples/blocks.html#/docs/guide/owl-components) for how to load `nodexui` and `dist/nodexui.templates.xml`.
 
 ## Static component
 
@@ -50,7 +50,7 @@ Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script l
 
 ## Options and attributes
 
-See `dist/baseui.registry.json` for the supported attribute list.
+See `dist/nodexui.registry.json` for the supported attribute list.
 
 ## Methods
 
@@ -58,11 +58,11 @@ Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `th
 
 ## Events
 
-Interactive components emit documented `baseui:*` events from their root element. Static components do not emit events.
+Interactive components emit documented `nodexui:*` events from their root element. Static components do not emit events.
 
 ## CSS variables
 
-The component inherits the Base UI semantic tokens such as `--b-surface`, `--b-border`, `--b-primary`, and `--b-radius`.
+The component inherits Nodex UI semantic tokens such as `--b-surface`, `--b-border`, `--b-primary`, and `--b-radius`.
 
 ## Accessibility behavior
 
@@ -74,7 +74,7 @@ See `examples/index.html` for a working CDN-style page.
 
 ## Browser support
 
-The Base UI targets modern evergreen browsers that support ES modules, CSS variables, and Bootstrap 5.3.
+Nodex UI targets modern evergreen browsers that support ES modules, CSS variables.
 
 ## Test checklist
 

package/docs/components/toggle.md

@@ -4,12 +4,12 @@ Use `b-ui="toggle"` for a CDN-ready toggle component.
 
 ## CDN install requirements
 
-Load the pinned the Base UI CSS and JavaScript files; no extra dependency is required for this component.
+Load the pinned Nodex UI CSS and JavaScript files; no extra dependency is required for this component.
 
 ## Base component
 
 ```js
-import { Toggle } from "@thebase/ui";
+import { Toggle } from "nodexui";
 ```
 
 ```base-ui
@@ -37,7 +37,7 @@ import { Toggle } from "@thebase/ui";
 | `Toggle` | `className` | `String` | optional |
 | `Toggle` | `onChange` | `Function` | optional |
 
-See [Base Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+See [Nodex UI Component](/examples/blocks.html#/docs/guide/owl-components) for how to load `nodexui` and `dist/nodexui.templates.xml`.
 
 ## Static component
 
@@ -51,7 +51,7 @@ Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script l
 
 ## Options and attributes
 
-See `dist/baseui.registry.json` for the supported attribute list.
+See `dist/nodexui.registry.json` for the supported attribute list.
 
 ## Methods
 
@@ -59,11 +59,11 @@ Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `th
 
 ## Events
 
-Interactive components emit documented `baseui:*` events from their root element. Static components do not emit events.
+Interactive components emit documented `nodexui:*` events from their root element. Static components do not emit events.
 
 ## CSS variables
 
-The component inherits the Base UI semantic tokens such as `--b-surface`, `--b-border`, `--b-primary`, and `--b-radius`.
+The component inherits Nodex UI semantic tokens such as `--b-surface`, `--b-border`, `--b-primary`, and `--b-radius`.
 
 ## Accessibility behavior
 
@@ -75,7 +75,7 @@ See `examples/index.html` for a working CDN-style page.
 
 ## Browser support
 
-The Base UI targets modern evergreen browsers that support ES modules, CSS variables, and Bootstrap 5.3.
+Nodex UI targets modern evergreen browsers that support ES modules, CSS variables.
 
 ## Test checklist
 

package/docs/components/tooltip.md

@@ -5,7 +5,7 @@ Use `b-ui="tooltip"` with either `b-att-content` or a tooltip content child.
 ## Base component
 
 ```js
-import { Tooltip } from "@thebase/ui";
+import { Tooltip } from "nodexui";
 ```
 
 ```base-ui
@@ -24,11 +24,11 @@ import { Tooltip } from "@thebase/ui";
 | `Tooltip` | `state` | `String` | optional; `"open"`/`"on"`/`"active"` shows the tooltip once on mount (uncontrolled testing hook) |
 | `Tooltip` | `className` | `String` | optional |
 
-See [Base Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+See [Nodex UI Component](/examples/blocks.html#/docs/guide/owl-components) for how to load `nodexui` and `dist/nodexui.templates.xml`.
 
-Both the pure Base and static forms are driven by a live `bootstrap.Tooltip` instance owned on the trigger element, with `trigger: "hover focus"` — **the visible popup is Bootstrap's own generated DOM (a `.tooltip`/`.tooltip-arrow`/`.tooltip-inner` node, positioned via Popper), appended to `document.body`, not rendered inline where you authored the tooltip.** Don't query for it as a descendant of the trigger; query `document.body.querySelector(".tooltip .tooltip-inner")` instead. Bootstrap sets `aria-describedby` on the trigger itself, but only while the tooltip is actually shown (removed again on hide) — the Base UI does not additionally set a static `aria-describedby` up front.
+Both the pure Base and static forms are driven by a live `bootstrap.Tooltip` instance owned on the trigger element, with `trigger: "hover focus"` — **the visible popup is the built-in generated DOM (a `.tooltip`/`.tooltip-arrow`/`.tooltip-inner` node, positioned via Popper), appended to `document.body`, not rendered inline where you authored the tooltip.** Don't query for it as a descendant of the trigger; query `document.body.querySelector(".tooltip .tooltip-inner")` instead. base sets `aria-describedby` on the trigger itself, but only while the tooltip is actually shown (removed again on hide) — Nodex UI does not additionally set a static `aria-describedby` up front.
 
-The default slot's rendered markup is captured into an HTML string for Bootstrap's `title`/`html: true` options (Bootstrap can't consume live vnodes): the Base component renders the slot into a hidden buffer element internal to its own template, reads its `innerHTML` on mount, and re-syncs the live popup via `.setContent({'.tooltip-inner': html})` whenever that HTML changes on a later render.
+The default slot's rendered markup is captured into an HTML string for the built-in `title`/`html: true` options (the library can't consume live vnodes): the Base component renders the slot into a hidden buffer element internal to its own template, reads its `innerHTML` on mount, and re-syncs the live popup via `.setContent({'.tooltip-inner': html})` whenever that HTML changes on a later render.
 
 ## Static component
 
@@ -38,7 +38,7 @@ The default slot's rendered markup is captured into an HTML string for Bootstrap
 </span>
 ```
 
-Tooltips show on hover and focus, then hide on mouse leave and blur — Bootstrap's own `trigger: "hover focus"` wires this, not manual event listeners. The static adapter reads `[b-tooltip-content]` (or the element built from `b-att-content`) once at mount time as the tooltip's HTML content, then removes that node from the DOM — Bootstrap owns showing/hiding the content from then on, so no `[b-tooltip-content]` element survives in the authored markup post-mount.
+Tooltips show on hover and focus, then hide on mouse leave and blur — the built-in `trigger: "hover focus"` wires this, not manual event listeners. The static adapter reads `[b-tooltip-content]` (or the element built from `b-att-content`) once at mount time as the tooltip's HTML content, then removes that node from the DOM — the library owns showing/hiding the content from then on, so no `[b-tooltip-content]` element survives in the authored markup post-mount.
 
 ## Enhanced usage
 
@@ -46,7 +46,7 @@ Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script l
 
 ## Options and attributes
 
-See `dist/baseui.registry.json` for the supported attribute list.
+See `dist/nodexui.registry.json` for the supported attribute list.
 
 ## Methods
 
@@ -54,11 +54,11 @@ Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `th
 
 ## Events
 
-Interactive components emit documented `baseui:*` events from their root element. Listen for Bootstrap's own `shown.bs.tooltip`/`hidden.bs.tooltip` on the trigger element to react to show/hide; the Base UI mirrors those into `b-att-state` (`open`/`closed`) on the static root and `this.state.open` on the Base component.
+Interactive components emit documented `nodexui:*` events from their root element. Listen for the built-in `shown.bs.tooltip`/`hidden.bs.tooltip` on the trigger element to react to show/hide; Nodex UI mirrors those into `b-att-state` (`open`/`closed`) on the static root and `this.state.open` on the Base component.
 
 ## CSS variables
 
-The component inherits the Base UI semantic tokens such as `--b-surface`, `--b-border`, `--b-primary`, and `--b-radius`. The popup itself is styled by Bootstrap's own bundled `.tooltip`/`.tooltip-arrow`/`.tooltip-inner` CSS (loaded via `dist/baseui.min.css`), not the Base UI's own classes.
+The component inherits Nodex UI semantic tokens such as `--b-surface`, `--b-border`, `--b-primary`, and `--b-radius`. The popup itself is styled by the built-in bundled `.tooltip`/`.tooltip-arrow`/`.tooltip-inner` CSS (loaded via `dist/nodexui.min.css`), not Nodex UI's own classes.
 
 ## Accessibility behavior
 
@@ -70,7 +70,7 @@ See `examples/index.html` for a working CDN-style page.
 
 ## Browser support
 
-The Base UI targets modern evergreen browsers that support ES modules, CSS variables, and Bootstrap 5.3.
+Nodex UI targets modern evergreen browsers that support ES modules, CSS variables.
 
 ## Test checklist
 

package/docs/components/typography.md

@@ -5,7 +5,7 @@ Small text helpers for plain content.
 ## Base component
 
 ```js
-import { Typography } from "@thebase/ui";
+import { Typography } from "nodexui";
 ```
 
 ```base-ui
@@ -86,23 +86,23 @@ import { Typography } from "@thebase/ui";
 | `Typography` | `tag` | `String` | optional; defaults to `h1`-`h4`, `blockquote`, `small`, `ul` for those variants, else `p` |
 | `Typography` | `className` | `String` | optional |
 
-See [Base Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+See [Nodex UI Component](/examples/blocks.html#/docs/guide/owl-components) for how to load `nodexui` and `dist/nodexui.templates.xml`.
 
-## Bootstrap typography classes
+## built-in typography classes
 
-Base UI redefines the Bootstrap 5 typography classes to the shadcn typeset values
-(`src/styles/base-extensions.css`), in Be Vietnam Pro. Use plain Bootstrap markup:
+Nodex UI redefines the built-in typography classes to the shadcn typeset values
+(`src/styles/base-extensions.css`), in Be Vietnam Pro. Use plain built-in markup:
 
 | Element / class | Result |
 | --- | --- |
 | `h1` / `.h1` ... `h4` / `.h4` | 1.75rem, 1.25rem, 1.125rem, 1rem; weight 600; line-height 1.3 to 1.5 |
 | `h5` / `.h5`, `h6` / `.h6` | 0.875rem / 0.8125rem, weight 500, muted; `h6` is uppercase with 0.08em tracking |
-| `.display-1` ... `.display-6` | Bootstrap sizes, weight 600, line-height 1.2 |
+| `.display-1` ... `.display-6` | built-in sizes, weight 600, line-height 1.2 |
 | `.lead`, `.small`, `mark`, `del`, `abbr[title]` | muted lead text, `--b-text-sm`, shadcn highlight, muted strike-through, dotted underline |
 | `blockquote` / `.blockquote` | 2px start border, 1em inline padding, inherited size |
 | `hr`, `dt`, `dd`, `code`, `pre`, `kbd`, `caption` | shadcn rule, weights, muted-background code, keycap border |
 
-Bootstrap's bottom-margin rhythm is unchanged. For the shadcn flow model (margin-top only,
+the built-in bottom-margin rhythm is unchanged. For the shadcn flow model (margin-top only,
 1.25em between blocks, 1.75 line-height, styled lists, links and tables) wrap prose in
 `class="b-typeset"`; tune with `--b-typeset-flow` and `--b-typeset-leading`.
 
@@ -110,9 +110,9 @@ Bootstrap's bottom-margin rhythm is unchanged. For the shadcn flow model (margin
 
 ```base-ui
 <p b-ui="typography" b-att-variant="lead">Readable intro text.</p>
-<span b-ui="typography" b-att-variant="code">baseui</span>
+<span b-ui="typography" b-att-variant="code">nodexui</span>
 ```
 
 Options: `b-att-variant="body|lead|muted|code|kbd|h1|h2|h3|h4|blockquote|small|list"` (static markup keeps its own element, so write `<h2 b-ui="typography" b-att-variant="h2">`; the variant only adds the class).
 
-Accessibility: choose semantic HTML elements first, then add the Base UI typography attributes for styling.
+Accessibility: choose semantic HTML elements first, then add Nodex UI typography attributes for styling.

package/docs/i18n.md

@@ -0,0 +1,119 @@
+# i18n service
+
+Instructions for adding translations to a page or app with Nodex UI i18n service (`nodexui/i18n`). It is optional and standalone: no framework 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; the examples app does the same in `examples/i18n.js` and `examples/components/*/i18n/` (English and Vietnamese). Update catalogs with `node scripts/emvhub-i18n.mjs extract [--site=emvhub|examples/components] [newLang]`.
+
+## 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 "nodexui/i18n"` (file: `dist/nodexui.i18n.esm.js`) |
+| Import map | map `nodexui/i18n` to the ESM file, then `import … from "nodexui/i18n"` |
+| Script tag | `dist/nodexui.i18n.min.js` sets `window.thebase.i18n` |
+
+## 3. Quick start
+
+1. Map the module in your HTML:
+
+```html
+<script type="importmap">
+  { "imports": { "nodexui/i18n": "https://cdn.jsdelivr.net/npm/nodexui@<version>/dist/nodexui.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 "nodexui/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 "nodexui/i18n";
+
+init({ languages: [{ code: "en", label: "English" }, { code: "vi", label: "Tiếng Việt" }], storageKey: "my-lang" });
+export * from "nodexui/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/nodexui.pwa.config.js`). |

package/docs/icons.md

@@ -1,6 +1,6 @@
 # Built-in Icons
 
-The Base UI ships the full Lucide icon set as a built-in CDN-ready icon library. Icons use the `b-icon` attribute, render as CSS masks, and inherit `currentColor` from the surrounding button, link, menu item, block, or theme.
+Nodex UI ships the full Lucide icon set as a built-in CDN-ready icon library. Icons use the `b-icon` attribute, render as CSS masks, and inherit `currentColor` from the surrounding button, link, menu item, block, or theme.
 
 ```html
 <button b-ui="button" type="button">
@@ -15,20 +15,20 @@ The Base UI ships the full Lucide icon set as a built-in CDN-ready icon library.
 
 ## Install
 
-Load the normal the Base UI assets. No separate icon script is required.
+Load the normal Nodex UI assets. No separate icon script is required.
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
-<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.js" defer></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nodexui@latest/dist/nodexui.min.css">
+<script src="https://cdn.jsdelivr.net/npm/nodexui@latest/dist/nodexui.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.2.0`, 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/nodexui@latest/dist/...` mirrors the same files as an alternative CDN if jsDelivr is unreachable. Pin an exact version (e.g. `@1.3.0`, 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`.
 
 ## Markup
 
-Use the Lucide icon name in kebab-case, camelCase, snake_case, or space-separated form. The Base UI normalizes the name to the matching Lucide SVG file.
+Use the Lucide icon name in kebab-case, camelCase, snake_case, or space-separated form. Nodex UI normalizes the name to the matching Lucide SVG file.
 
 ```html
 <span b-icon="check"></span>
@@ -46,7 +46,7 @@ Use `b-icon-size` when the surrounding component should not control the icon siz
 
 ## Color
 
-Icons inherit `currentColor`, so set color on the parent element or let the Base UI component variants and themes do it.
+Icons inherit `currentColor`, so set color on the parent element or let Nodex UI component variants and themes do it.
 
 ```html
 <button b-ui="button" b-att-variant="destructive" type="button">
@@ -62,7 +62,7 @@ Icons inherit `currentColor`, so set color on the parent element or let the Base
 
 ## Accessibility
 
-Decorative icons should not have a label. The Base UI marks them with `aria-hidden="true"`.
+Decorative icons should not have a label. Nodex UI marks them with `aria-hidden="true"`.
 
 ```html
 <span b-icon="mail"></span>
@@ -84,7 +84,7 @@ Standalone meaningful icons can use `aria-label`.
 
 ## Self-hosting
 
-By default, icon URLs point to the pinned Lucide CDN configured in the registry. To serve icons from your own the Base UI build, point `b-icon-base-url` at the published icon folder.
+By default, icon URLs point to the pinned Lucide CDN configured in the registry. To serve icons from your own Nodex UI build, point `b-icon-base-url` at the published icon folder.
 
 ```html
 <span b-icon="search" b-icon-base-url="/dist/icons/lucide"></span>