@thebase/ui 1.1.3 → 1.1.4

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>
@@ -34,20 +34,20 @@ Save this as an `.html` file and open it — no build step, no server required.
 
 `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">
@@ -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)
 
@@ -116,7 +116,7 @@ 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:
 
@@ -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
@@ -248,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.
 
@@ -259,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
 
@@ -270,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.3",
+  "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,6 +44,8 @@
     "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",