@thebase/ui 1.1.2 → 1.1.4

package/docs/theming.md

@@ -13,7 +13,7 @@ thebase.theme.set("dark");
 thebase.theme.set({ primary: "#0057d8", radius: "0.5rem" });
 ```
 
-BaseUI 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.
+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,9 +38,9 @@ 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.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`.
+`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.3`, 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 BaseUI component instead of wiring your own click handler:
+For a ready-made icon button, use the Base UI component instead of wiring your own click handler:
 
 ```html
 <button b-ui="theme-button" b-att-variant="outline" b-att-storage-key="my-app-theme" type="button"></button>
@@ -50,6 +50,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. BaseUI 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)`, 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 BaseUI 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 BaseUI 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/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.

package/docs/usage-guide.md

@@ -1,12 +1,12 @@
-# Usage Guide — Integrating BaseUI Into a Project
+# Usage Guide — Integrating the Base UI Into a Project
 
-This is the single entry point for adding BaseUI to a consumer project (a static page, a Base HUB website page, a server-rendered app, or your own Owl app). It sequences the existing reference docs into one path and gives copy-paste-ready examples — read the linked page for exhaustive detail on any step.
+This is the single entry point for adding the Base UI to a consumer project (a static page, a Base HUB website page, a server-rendered app, or your own application). It sequences the existing reference docs into one path and gives copy-paste-ready examples — read the linked page for exhaustive detail on any step.
 
 Audience: engineers and AI coding agents integrating `@thebase/ui` into a project that is **not** this repository.
 
 ## Quick start (copy-paste, works as-is)
 
-Save this as an `.html` file and open it — no build step, no server required. It installs BaseUI from the pinned CDN and renders a button, an input, and a card using the static `b-ui` markup API (the zero-build alternative). If you're building an Owl app, skip straight to the [pure Owl install](#2-install-pure-owl-api--recommended) below — it's the recommended way to consume BaseUI.
+Save this as an `.html` file and open it — no build step, no server required. It installs the Base UI from the pinned CDN and renders a button, an input, and a card using the base static markup (`b-ui`) API (the zero-build alternative). If you're building an application, skip straight to the [pure Base install](#2-install-pure-owl-api--recommended) below — it's the recommended way to consume the Base UI.
 
 ```html
 <!doctype html>
@@ -32,22 +32,22 @@ 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.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.
+`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.3`, 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 Owl app, use [step 2](#2-install-pure-owl-api--recommended) instead — that's the recommended path.
+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.
 
 ## 1. Decide which API you need
 
 | You are building... | Use | Install | Full reference |
 | --- | --- | --- | --- |
-| Your own Owl app that wants `<Button/>`, `<Card/>`, `<Dialog/>` as real component classes | The pure Owl component API (recommended) | CSS + the same `baseui.min.js`/`baseui.esm.js` (via `@base/owl`/`@base/component` import-map keys or a plain npm import) + `dist/baseui.templates.xml` | [Pure Owl Components](owl-components.md) |
-| Static HTML, a server-rendered page, or a Base HUB website page with no Owl runtime | The static `b-ui` markup API (alternative) | One CSS file + one `<script>` tag | [Installation](installation.md) |
+| Your own application that wants `<Button/>`, `<Card/>`, `<Dialog/>` as real component classes | The Base component API (recommended) | CSS + the same `baseui.min.js`/`baseui.esm.js` (via `@base/owl`/`@base/component` import-map keys or a plain npm import) + `dist/baseui.templates.xml` | [Base Components](owl-components.md) |
+| Static HTML, a server-rendered page, or a Base HUB website page with no Owl runtime | The base static markup (`b-ui`) API (alternative) | One CSS file + one `<script>` tag | [Installation](installation.md) |
 
-Both APIs come from the same package and the same CSS file, and can be mixed on one page. Prefer the pure Owl component API by default — real component classes, props, and slots compose more predictably than markup attributes. Reach for the static API only when the target page has no Owl runtime of its own (plain HTML, server-rendered templates, a Base HUB website page) and adding one isn't worthwhile just to use BaseUI.
+Both APIs come from the same package and the same CSS file, and can be mixed on one page. Prefer the Base component API by default — real component classes, props, and slots compose more predictably than markup attributes. Reach for the static API only when the target page has no Owl runtime of its own (plain HTML, server-rendered templates, a Base HUB website page) and adding one isn't worthwhile just to use the Base UI.
 
 **[VERIFY]** Before choosing, confirm whether the target project already runs Owl (check for `@odoo/owl` or `@base/owl` in its `package.json`), or whether it's a plain page you'd rather not add a component-mount step to. Use the static API for the latter.
 
-## 2. Install (pure Owl API — recommended)
+## 2. Install (pure Base API — recommended)
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
@@ -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.1`, 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.1.3`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
 
 ```html
 <script type="module">
@@ -87,12 +87,12 @@ Both APIs come from the same package and the same CSS file, and can be mixed on
 </script>
 ```
 
-`@base/owl`, `@base/component`, and `@base/theme` all resolve to the exact same `dist/baseui.esm.js` — the one file this whole guide installs for the static API too. For npm/bundler usage, skip the import map entirely and import everything straight from `@thebase/ui` (plus `@thebase/ui/dist/baseui.templates.xml` as a fetch target) — see [Pure Owl Components](owl-components.md#npm--bundler-usage).
+`@base/owl`, `@base/component`, and `@base/theme` all resolve to the exact same `dist/baseui.esm.js` — the one file this whole guide installs for the static API too. For npm/bundler usage, skip the import map entirely and import everything straight from `@thebase/ui` (plus `@thebase/ui/dist/baseui.templates.xml` as a fetch target) — see [Base Components](owl-components.md#npm--bundler-usage).
 
-Two rules that account for most integration failures — see [Pure Owl Components](owl-components.md#common-mistakes) for the worked example:
+Two rules that account for most integration failures — see [Base Components](owl-components.md#common-mistakes) for the worked example:
 
-1. `dist/baseui.templates.xml` must be loaded and passed to `mount()` before any BaseUI tag renders.
-2. Import Owl itself from `@base/owl`, never `@odoo/owl` — otherwise the consumer's `Component` class and BaseUI's are different runtime identities and mounting throws.
+1. `dist/baseui.templates.xml` must be loaded and passed to `mount()` before any Base UI tag renders.
+2. Import Owl itself from `@base/owl`, never `@odoo/owl` — otherwise the consumer's `Component` class and the Base UI's are different runtime identities and mounting throws.
 
 ## 3. Install (static `b-ui` API — alternative, no Owl runtime needed)
 
@@ -103,7 +103,7 @@ Two rules that account for most integration failures — see [Pure Owl Component
 <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.1`, 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.1.3`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
 
 **Option B — npm (bundler-based apps: Vite, webpack, etc.):**
 
@@ -116,11 +116,11 @@ import "@thebase/ui/baseui.css";
 import "@thebase/ui"; // side-effect import: registers window.thebase and auto-mounts on DOMContentLoaded
 ```
 
-`dist/baseui.min.js`/`baseui.esm.js` are fully self-contained — Bootstrap's JS bundle and the Owl runtime are embedded ahead of BaseUI's own code, in load order, inside this one file. No other script or import is needed for the static API.
+`dist/baseui.min.js`/`baseui.esm.js` are fully self-contained — Bootstrap's JS bundle and the Owl runtime are embedded ahead of the Base UI's own code, in load order, inside this one file. No other script or import is needed for the static API.
 
 Rule that applies to both options:
 
-- Production pages must use a pinned version (e.g. `@thebase/ui@1.1.1` or `@thebase/ui@1`), never `@latest`.
+- Production pages must use a pinned version (e.g. `@thebase/ui@1.1.3` or `@thebase/ui@1`), never `@latest`.
 
 Mount markup:
 
@@ -198,11 +198,11 @@ Full token list and the shadcn-aligned default palette: [Theming](theming.md).
 </button>
 ```
 
-Icons ship with the normal BaseUI assets — no separate script tag, and every Lucide icon name is available by kebab-case (`panel-left`), camelCase, or snake_case. Sizing, color, accessibility rules, and self-hosting: [Built-in Icons](icons.md).
+Icons ship with the normal the Base UI assets — no separate script tag, and every Lucide icon name is available by kebab-case (`panel-left`), camelCase, or snake_case. Sizing, color, accessibility rules, and self-hosting: [Built-in Icons](icons.md).
 
 ## 5b. PWA toolkit (optional) — generate manifest.webmanifest + sw.js
 
-Any BaseUI app can become an installable PWA without hand-writing a service worker. `@thebase/ui/pwa`
+Any Base UI app can become an installable PWA without hand-writing a service worker. `@thebase/ui/pwa`
 exports two pure functions, `buildManifest(config)` and `buildServiceWorker(config)`, that turn a
 config object into the exact manifest JSON and service-worker source a hand-written PWA needs
 (precache the app shell, network-first for same-origin requests, cache-first for the pinned CDN
@@ -219,7 +219,7 @@ export default {
   },
   serviceWorker: {
     cacheName: "my-app-cache-v1",
-    cdnVersion: "1.1.1", // pin to match the importmap in index.html
+    cdnVersion: "1.1.3", // 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"],
   },
 };
@@ -233,7 +233,10 @@ npx create-baseui-app pwa . --config baseui.pwa.config.js
 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
-mode, extra precache URLs) has the same defaults the `qr-page` example ships with. See
+mode, extra precache URLs) has defaults. The default logo and favicon set (`favicon.ico`, 16/32 px favicons,
+`apple-touch-icon.png`, `icon-192.png`, `icon-512.png`) is copied into `<path>/icons/` by the command (existing
+files are kept, so your own icons win). Serving icons from another folder? Set `iconsBase` (manifest and
+service worker) and `manifestUrl` (service worker) in the config. See
 `dist/types/pwa.d.ts` for the full config shape.
 
 ## 6. Copy a block instead of assembling from primitives
@@ -245,7 +248,7 @@ For common layouts (dashboard shells, sidebars, login/signup forms, charts), cop
 - [ ] Only `baseui.min.css` + `baseui.min.js` (or `baseui.esm.js`) are loaded — no separate `baseui.owl.*`/`bootstrap.bundle.min.js`/`baseui.components.esm.js` files needed, for either API.
 - [ ] `thebase.version` returns the expected pinned version in the browser console.
 - [ ] Initial static markup mounts without an extra call; injected markup mounts after `thebase.mountAll(root)`.
-- [ ] Pure Owl components render with no console errors (a missing-template error means step 2's `dist/baseui.templates.xml` load is missing or unawaited).
+- [ ] Base components render with no console errors (a missing-template error means step 2's `dist/baseui.templates.xml` load is missing or unawaited).
 - [ ] Toggling `b-theme` actually changes rendered colors (a no-op usually means CSS custom properties are being overridden by the consumer's own stylesheet loaded after `baseui.min.css`).
 - [ ] Look up the specific component in [`docs/components/`](components/) for its attributes, events, and accessibility notes before wiring it up.
 
@@ -256,10 +259,10 @@ For common layouts (dashboard shells, sidebars, login/signup forms, charts), cop
 | `ReferenceError: BaseUI is not defined` | The bundle script hasn't run yet, or its `<script>` tag is missing/mistyped. | Confirm the `<script src=".../baseui.min.js" defer>` tag is present and the network tab shows it loading (200, not 404). |
 | Components render unstyled (plain HTML, no Bootstrap look) | `baseui.min.css` isn't loaded, or loaded after your own stylesheet overrides it. | Load `baseui.min.css` in `<head>`, before any of your own CSS that touches the same elements. |
 | `tabs` (or another Owl-backed static component) silently does nothing | `baseui.min.js` didn't finish loading. | Confirm `baseui.min.js` loads (network tab, 200 not 404). |
-| Pure Owl mount throws `"X is not a Component. It must inherit from the Component class"` | Your app imports `@odoo/owl` directly somewhere instead of `@base/owl`. | Replace every `@odoo/owl` import with `@base/owl` in your own app code — both must resolve to the same `globalThis.owl` instance. |
-| Pure Owl component renders blank / throws a template-not-found error | `dist/baseui.templates.xml` was never fetched and passed to `mount()`. | Fetch the templates string and pass it as `{ templates }` to `mount()` (or `app.addTemplates(...)`) before rendering any BaseUI tag. |
+| Pure Base mount throws `"X is not a Component. It must inherit from the Component class"` | Your app imports `@odoo/owl` directly somewhere instead of `@base/owl`. | Replace every `@odoo/owl` import with `@base/owl` in your own app code — both must resolve to the same `globalThis.owl` instance. |
+| Base component renders blank / throws a template-not-found error | `dist/baseui.templates.xml` was never fetched and passed to `mount()`. | Fetch the templates string and pass it as `{ templates }` to `mount()` (or `app.addTemplates(...)`) before rendering any Base UI tag. |
 | New markup injected via AJAX/fetch doesn't turn into components | Auto-mount only covers markup present when the bundle initializes. | Call `thebase.mountAll(root)` after injecting new `[b-ui]` or `[b-icon]` markup — it's idempotent, safe to call repeatedly. |
-| `thebase.theme.set(...)` has no visible effect | A page stylesheet loaded after `baseui.min.css` re-hardcodes the same properties, or the element isn't a descendant of the themed root. | Load consumer CSS after BaseUI's, and confirm `b-theme` is set on `<html>` or an ancestor of the components you expect to change. |
+| `thebase.theme.set(...)` has no visible effect | A page stylesheet loaded after `baseui.min.css` re-hardcodes the same properties, or the element isn't a descendant of the themed root. | Load consumer CSS after the Base UI's, and confirm `b-theme` is set on `<html>` or an ancestor of the components you expect to change. |
 
 ## 9. Common mistakes
 
@@ -267,8 +270,8 @@ For common layouts (dashboard shells, sidebars, login/signup forms, charts), cop
 - Using `/latest/` CDN paths in production instead of a pinned version.
 - Assuming auto-mount watches the DOM forever — it does not; call `thebase.mountAll(root)` after injecting new `[b-ui]` markup client-side (e.g. from a fetched partial).
 - Mixing `@odoo/owl` imports into a project that also imports `@thebase/ui` — always go through `@base/owl`.
-- Expecting `thebase.mountAll()` to pick up Owl component tags (`<Button/>`) — it only mounts static `[b-ui]` markers; pure Owl components are registered and mounted through your own app's `static components` + `mount()`, per step 2.
+- Expecting `thebase.mountAll()` to pick up Owl component tags (`<Button/>`) — it only mounts static `[b-ui]` markers; Base components are registered and mounted through your own app's `static components` + `mount()`, per step 2.
 
 ## Related docs
 
-[Installation](installation.md) · [Runtime API](runtime-api.md) · [Theming](theming.md) · [Built-in Icons](icons.md) · [Pure Owl Components](owl-components.md) · [Blocks](blocks.md) · [Component Authoring](component-authoring.md) (for contributing to BaseUI itself, not for consuming it) · [Registry](registry.md) · [Component Reference index](components/button.md) (per-component pages live under `docs/components/`)
+[Installation](installation.md) · [Runtime API](runtime-api.md) · [Theming](theming.md) · [Built-in Icons](icons.md) · [Base Components](owl-components.md) · [Blocks](blocks.md) · [Component Authoring](component-authoring.md) (for contributing to the Base UI itself, not for consuming it) · [Registry](registry.md) · [Component Reference index](components/button.md) (per-component pages live under `docs/components/`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebase/ui",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "CDN-installable Owl and 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"
     },
+    "./apidoc": {
+      "types": "./dist/types/apidoc.d.ts",
+      "import": "./dist/baseui.apidoc.esm.js",
+      "default": "./dist/baseui.apidoc.min.js"
+    },
     "./pwa": {
       "types": "./dist/types/pwa.d.ts",
       "import": "./dist/baseui.pwa.esm.js"
@@ -39,9 +44,13 @@
     "dist/baseui.icons.esm.js",
     "dist/baseui.analytics.esm.js",
     "dist/baseui.analytics.min.js",
+    "dist/baseui.apidoc.esm.js",
+    "dist/baseui.apidoc.min.js",
     "dist/baseui.pwa.esm.js",
     "dist/baseui.templates.xml",
     "dist/icons",
+    "dist/pwa-icons",
+    "dist/apidoc",
     "dist/baseui.registry.json",
     "dist/runtime",
     "dist/themes",