@thebase/ui 1.1.1 → 1.1.3

package/dist/types/pwa.d.ts

@@ -0,0 +1,45 @@
+/** Optional PWA toolkit: builds manifest.webmanifest/sw.js content from a config object. */
+export interface BaseUIManifestConfig {
+  name: string;
+  /** Defaults to `name`. */
+  shortName?: string;
+  description?: string;
+  /** Defaults to "/". */
+  startUrl?: string;
+  /** Defaults to "/". */
+  scope?: string;
+  /** Defaults to "standalone". */
+  display?: string;
+  /** Defaults to "portrait-primary". */
+  orientation?: string;
+  /** Defaults to "#ffffff". */
+  backgroundColor?: string;
+  /** Defaults to "#0f172a". */
+  themeColor?: string;
+  /** Defaults to "en". */
+  lang?: string;
+  /** Folder URL holding the default logo files. Defaults to "/icons/". */
+  iconsBase?: string;
+  /** Defaults to the shipped logo: `icon-192.png` and `icon-512.png` under `iconsBase`. */
+  icons?: Array<{ src: string; sizes: string; type: string; purpose?: string }>;
+}
+
+export interface BaseUIServiceWorkerConfig {
+  /** Cache bucket name, e.g. "my-app-cache-v1" — bump the suffix to invalidate old caches. */
+  cacheName: string;
+  /** Pinned `@thebase/ui` version the generated sw.js precaches/serves from jsdelivr. */
+  cdnVersion: string;
+  /** Where the manifest is served from. Defaults to "/manifest.webmanifest". */
+  manifestUrl?: string;
+  /** Folder URL holding the default logo/favicon files to precache. Defaults to "/icons/". */
+  iconsBase?: string;
+  /** Same-origin app-shell paths to precache (JS/CSS/XML/icons/etc). */
+  appFiles?: string[];
+  /** Extra same-origin or cross-origin URLs to precache alongside `appFiles`. */
+  extraPrecacheUrls?: string[];
+}
+
+/** Default logo/favicon file names (in `dist/pwa-icons/`), precached from `/icons/` by default. */
+export const DEFAULT_ICON_FILES: string[];
+export function buildManifest(config: BaseUIManifestConfig): Record<string, unknown>;
+export function buildServiceWorker(config: BaseUIServiceWorkerConfig): string;

package/docs/analytics.md

@@ -13,12 +13,12 @@ init({ backendUrl: "https://stats.example.com" });
 ```html
 <!-- ES module from the CDN (or map it as "@base/analytics" in an import map) -->
 <script type="module">
-  import { init } from "https://cdn.jsdelivr.net/npm/@thebase/ui@1.1.1/dist/baseui.analytics.esm.js";
+  import { init } from "https://cdn.jsdelivr.net/npm/@thebase/ui@1.1.3/dist/baseui.analytics.esm.js";
   init({ backendUrl: "https://stats.example.com" });
 </script>
 
 <!-- Classic script tag: sets window.thebase.analytics (load order vs dist/baseui.min.js doesn't matter) -->
-<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@1.1.1/dist/baseui.analytics.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@1.1.3/dist/baseui.analytics.min.js"></script>
 <script>
   thebase.analytics.init({ backendUrl: "https://stats.example.com" });
 </script>
@@ -84,7 +84,7 @@ init({ backendUrl: "https://stats.example.com", customProperties: visitorContext
 | `lang` | `navigator.language`, e.g. `vi-VN`. |
 | `screen` | Viewport width bucket: `Mobile` (< 576 px), `Tablet` (< 992), `Laptop` (< 1440), `Desktop`. |
 
-The values are deliberately coarse: no exact pixels, nothing persistent. Backends can treat `tz`, `lang` and `screen` as visit dimensions instead of event props. To combine it with your own props, call it inside your function: `customProperties: (name) => ({ ...visitorContext(), plan: "pro" })`. The IP address and user agent never appear in the payload; the server reads them from the HTTP request (see [Receiving events](#receiving-events-backend)).
+The values are deliberately coarse: no exact pixels, nothing persistent. Backends can treat `tz`, `lang` and `screen` as visit dimensions instead of event props. To combine it with your own props, call it inside your function: `customProperties: (name) => ({ ...visitorContext(), plan: "pro" })`. Don't use `tz`, `lang` or `screen` as your own event prop names: event props override custom properties with the same key, so the visitor's value would be lost. Use something like `uiLang` instead. The IP address and user agent never appear in the payload; the server reads them from the HTTP request (see [Receiving events](#receiving-events-backend)).
 
 ## Engagement
 
@@ -228,7 +228,7 @@ curl -i -X POST http://localhost:8080/api/event -H 'Content-Type: text/plain' \
 
 [`examples/analytics/`](../examples/analytics/dashboard/?backend=http://localhost:8080) contains a working dashboard plus two complete sample backends: [`server-go`](../examples/analytics/server-go/main.go) (Fiber v3) and [`server-fastapi`](../examples/analytics/server-fastapi/main.py). Each one extends the receivers above with an in-memory store, a daily-salted cookieless visitor hash, a `GET /api/stats` endpoint, and static hosting for the dashboard.
 
-The dashboard ([`dashboard/`](../examples/analytics/dashboard/?backend=http://localhost:8080)) is a pure Owl app that loads `@thebase/ui@1.1.1` from jsDelivr: KPI `Card`s, an area `Chart`, top pages/sources/events `Table`s, site and period `NativeSelect`s, and a `ThemeButton`. It refreshes every 30 s and tracks its own visits through `@thebase/ui/analytics`, so a fresh backend has data straight away.
+The dashboard ([`dashboard/`](../examples/analytics/dashboard/?backend=http://localhost:8080)) is a pure Owl app that loads `@thebase/ui@1.1.3` from jsDelivr: KPI `Card`s, an area `Chart`, top pages/sources/events `Table`s, site and period `NativeSelect`s, and a `ThemeButton`. It refreshes every 30 s and tracks its own visits through `@thebase/ui/analytics`, so a fresh backend has data straight away.
 
 ```sh
 # Go (1.25+)

package/docs/blocks.md

@@ -13,7 +13,7 @@ Blocks are not standalone runtime components. Paste the markup and load the norm
 <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. Blocks are static markup, so they only need the static `b-ui` runtime above — see [Usage Guide](usage-guide.md) if the surrounding page is itself an Owl app and you'd rather compose the equivalent layout from [Pure Owl Components](owl-components.md).
+`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. Blocks are static markup, so they only need the static `b-ui` runtime above — see [Usage Guide](usage-guide.md) if the surrounding page is itself an Owl app and you'd rather compose the equivalent layout from [Pure Owl Components](owl-components.md).
 
 Use `b-block` to select the block style:
 
@@ -30,6 +30,7 @@ The docs/dev server serves the block gallery at `/blocks` through the shared `ex
 
 ## Included Blocks
 
+- `apidoc-01`: full-page API reference built from an OpenAPI 3 file with the pure Owl `ApiDoc` component (sidebar, schemas, Try It, Authorize); see [ApiDoc](components/apidoc.md).
 - `chart-01`: copyable usage block showing how to compose `b-ui="chart"` with chart slots, SVG primitives, tokens, and footer copy.
 - `dashboard-01`: dashboard shell with inset sidebar, header, metric cards, chart surface, and table area.
 - `sidebar-01` through `sidebar-16`: static conversions of the current shadcn/ui sidebar block family, including documentation sidebars, collapsible groups, inset navigation, mail, workspace, file explorer, calendar, dialog, right TOC, dual-sidebar, and sticky-header variants.

package/docs/components/apidoc.md

@@ -0,0 +1,66 @@
+# ApiDoc
+
+Use `b-ui="apidoc"` (or the pure Owl `ApiDoc` component) to render an **OpenAPI 3.0+ JSON** document as browsable API documentation: a grouped sidebar, per-operation parameters / request body / responses / callbacks, a **Try It** panel with request code samples in 17 languages, and an **Authorize** dialog (API key, HTTP basic, bearer, OpenID Connect token, OAuth2 implicit / authorization-code / password / client-credentials).
+
+Swagger 2.0 documents still render, but OpenAPI 3.x is the supported input: `requestBody`, `components.securitySchemes` (`http`, `apiKey`, `oauth2` `flows`, `openIdConnect`, `mutualTLS`), `servers` with variables, `webhooks`, `callbacks`, `links`, tag `parent`/`kind`, and `$ref` to components are all understood.
+
+Markdown in `info.description`, tag and operation descriptions is rendered with the [Markdown](markdown.md) component (fenced ` ```mermaid ` blocks become diagrams). The spec is trusted content — descriptions are rendered as Markdown/HTML, so do not point ApiDoc at a spec you do not control.
+
+## Pure Owl component
+
+```js
+import { ApiDoc } from "@base/component";
+```
+
+```html
+<ApiDoc src="'/openapi.json'" height="'100vh'" theme="'auto'" themeToggle="true" hash="true"/>
+```
+
+Pass an already-parsed document with `spec` instead of `src`:
+
+```html
+<ApiDoc spec="state.spec" serverUrl="'https://api.example.com'" tryIt="false"/>
+```
+
+## Static component
+
+```html
+<div b-ui="apidoc" b-att-src="/openapi.json" b-att-height="100vh" b-att-hash="true"></div>
+```
+
+The static adapter fetches `baseui.templates.xml` from the folder the BaseUI script was loaded from; set `b-att-templates` to override.
+
+## Props / attributes
+
+| Owl prop | Static attribute | Default | Meaning |
+| --- | --- | --- | --- |
+| `src` | `b-att-src` | — | URL of the OpenAPI JSON file. |
+| `spec` | — | — | Parsed OpenAPI object (alternative to `src`). |
+| `title` | `b-att-title` | `info.title` | Heading shown in the header and introduction. |
+| `serverUrl` | `b-att-server-url` | `servers` of the spec | Replaces the spec's servers (e.g. `location.origin`) so Try It targets one host. |
+| `theme` | `b-att-theme` | `auto` | `light`, `dark`, or `auto` (follows `data-bs-theme` on `<html>`, else the OS). |
+| `themeToggle` | `b-att-theme-toggle` | `false` | Shows a light/dark button in the header. |
+| `hash` | `b-att-hash` | `false` | Keep the open page in `location.hash` (`#/<operationId>`), so pages are linkable. Off by default so ApiDoc does not fight an app's own router. |
+| `operation` | `b-att-operation` | introduction | Operation id to open first (the lower-cased, dash-separated `operationId`). |
+| `tryIt` | `b-att-try-it` | `true` | Show the Try It panel (code samples + Send API Request). |
+| `authorize` | `b-att-authorize` | `true` | Show the Authorize button when the spec defines security schemes. |
+| `languages` | `b-att-languages` | all 17 | Which code-sample languages to offer, e.g. `['curl', 'node', 'python']` / `curl,node,python`. |
+| `language` | `b-att-language` | `curl` | Language selected first. |
+| `assetBase` | `b-att-asset-base` | `dist/apidoc` beside the BaseUI script | Folder that holds `img/*.svg` language logos. Empty string hides the logos. |
+| `oauthRedirectUri` | `b-att-oauth-redirect-uri` | `oauth2-redirect.html` next to the page | Popup landing page for the implicit / authorization-code flows (see `src/components/apidoc/oauth2-redirect.html`). |
+| `height` | `b-att-height` | `100vh` | CSS height of the component. |
+| `className`, `style` | — | — | Standard root class / inline style. |
+
+## Events
+
+| Owl callback | Static event | Detail |
+| --- | --- | --- |
+| `onLoad(doc)` | `baseui:load` | `{ info, operations }` once the spec is parsed. |
+| `onError(error)` | `baseui:error` | `{ error }` when the spec cannot be fetched or is not OpenAPI. |
+| `onNavigate(id)` | `baseui:navigate` | `{ id }` — `introduction` or an operation id. |
+
+## Notes
+
+- Credentials entered in Authorize live in the tab's `sessionStorage` (`apikey`, `oauthkey`) and are applied to every Try It request. Try It sends the request from the browser, so the API must allow CORS from the docs origin.
+- Language logos are copied to `dist/apidoc/img/` by `npm run build`; the CDN URL pattern is `https://cdn.jsdelivr.net/npm/@thebase/ui@<version>/dist/apidoc/img/`.
+- Styles are scoped under `.bu-apidoc` and use their own palette (`--line`, `--accent`, … on `.bu-apidoc`); override them on a wrapper selector to re-theme.

package/docs/components/input.md

@@ -14,9 +14,26 @@ import { Input } from "@thebase/ui";
 </div>
 ```
 
+```base-ui
+<div style="max-width: 28rem" class="w-100 pt-3">
+  <Input label="'First name'" value="'Odette'" supportingText="'As on your ID'" leadingIcon="'user'"/>
+</div>
+```
+
+```base-ui
+<div style="max-width: 28rem" class="w-100 pt-3">
+  <Input label="'Email'" value="'odette@'" errorText="'Enter a valid email'" leadingIcon="'mail'"/>
+</div>
+```
+
 | Prop | Type | Notes |
 | --- | --- | --- |
 | `value` | `String` | controlled value; the component never mutates it itself |
+| `label` | `String` | Material-style outlined field: label rests inside, floats onto the border when focused/filled (or when `placeholder` is set) |
+| `supportingText` | `String` | helper line under the field, linked via `aria-describedby` |
+| `errorText` | `String` | marks the field invalid, replaces `supportingText`, swaps the trailing icon for an error icon, sets `aria-invalid` |
+| `leadingIcon` / `trailingIcon` | `String` | Lucide icon names (outlined mode only) |
+| `maxLength` | `Number` | native limit; outlined mode also shows a `n/max` counter |
 | `placeholder` | `String` | |
 | `type` | `String` | native `<input type>` |
 | `disabled` | `Boolean` | |

package/docs/components/markdown.md

@@ -97,7 +97,7 @@ A fenced ` ```base-ui ` block renders as a live component, not a code sample:
 
 - `b-att-src` / `src` — fetch a remote Markdown file instead of using inline content.
 - `b-att-content` / `content` — a static `<script type="text/markdown">` child (or a `<template>`), `b-att-content`, or the element's own text content supplies the Markdown source when no `src` is set.
-- `b-att-mermaid` / `mermaid` — set to `"false"` to skip mermaid diagram rendering (defaults to enabled).
+- `b-att-mermaid` / `mermaid` — set to `"false"` to skip mermaid diagram rendering (defaults to enabled).  Diagrams use mermaid's dark theme when the nearest `data-bs-theme` (else the system preference) is dark.
 - `b-att-base-ui` / `baseUi` — set to `"false"` to skip live-mounting fenced ` ```base-ui ` blocks; they render as plain code instead (defaults to enabled).
 - `b-att-editable` / `editable` — set to `"true"` to mount Milkdown instead of read-only rendered HTML.
 - `b-att-collaborative` / `collaborative` — set to `"true"` to connect the editor through Yjs + y-webrtc.

package/docs/icons.md

@@ -22,7 +22,7 @@ Load the normal BaseUI 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.1`, or `@1` to take only non-breaking updates) instead of `@latest` for production. `b-icon` also works with the [pure Owl `Icon` component](components/icon.md) — the recommended API in an Owl app; 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.1.3`, or `@1` to take only non-breaking updates) instead of `@latest` for production. `b-icon` also works with the [pure Owl `Icon` component](components/icon.md) — the recommended API in an Owl app; 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
 
 BaseUI 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 BaseUI's own code, in load order (Bootstrap, then Owl, then BaseUI) — nothing else needs to load first. Both install paths below load this same file; the pure Owl component API is the recommended way to consume BaseUI in an Owl app, with the static `b-ui` markup 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.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.
+The snippets below use the `@latest` tag for readability. Pin an exact version instead (e.g. `@1.1.3`, 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.
 
 ## Pure Owl 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 BaseUI'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.1`, 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.1.3`, or `@1` to take only non-breaking updates) instead of `@latest` for production.
 
 For npm/self-hosted usage:
 

package/docs/owl-components.md

@@ -4,7 +4,7 @@ See the [Usage Guide](usage-guide.md) for when to reach for this API versus the
 
 BaseUI ships a second, additive public API alongside the static `b-ui` markers: real Owl component classes you import, compose with `static components`, and mount as part of your own Owl app. This page covers how to load and use it; see [Component Authoring](component-authoring.md) for how components implement both APIs from one source folder.
 
-As of 1.1.0, every component in the registry (all 65) has a pure Owl export — there are no static-only components left. Compound components export a root class plus sub-components (e.g. `Dialog`/`DialogTrigger`/`DialogContent`/...); check a component's `owlComponents` entry in `dist/baseui.registry.json`, or its doc page under [`docs/components/`](components/), for the exact export list. A few components have a deliberately reshaped pure Owl API versus their static markup-scanning adapter — see [Registry](registry.md#component-export-policy) for which ones and why.
+As of 1.1.0, every component in the registry (all 74) has a pure Owl export — there are no static-only components left. Compound components export a root class plus sub-components (e.g. `Dialog`/`DialogTrigger`/`DialogContent`/...); check a component's `owlComponents` entry in `dist/baseui.registry.json`, or its doc page under [`docs/components/`](components/), for the exact export list. A few components have a deliberately reshaped pure Owl API versus their static markup-scanning adapter — see [Registry](registry.md#component-export-policy) for which ones and why.
 
 ## What you need to load
 

package/docs/registry.md

@@ -20,7 +20,7 @@ BaseUI ships as bundled files only — there is no per-component source distribu
 
 Every component folder under `src/components/<name>/` is one of:
 
-1. **Both APIs** — has `<name>.js` (static `BaseUI.register(...)` adapter) *and* `<name>.component.js` (pure Owl `Component` class(es)). As of the Phase 8 rollout this is **all 65** registry components; there are no static-only exceptions left. A handful of components (`chart`, most notably) have lighter-fidelity pure Owl treatments than their static adapter — see their component doc page for the documented gap — but every registry component has a real Owl export.
+1. **Both APIs** — has `<name>.js` (static `BaseUI.register(...)` adapter) *and* `<name>.component.js` (pure Owl `Component` class(es)). As of the Phase 8 rollout this is **all 74** registry components; there are no static-only exceptions left. A handful of components (`chart`, most notably) have lighter-fidelity pure Owl treatments than their static adapter — see their component doc page for the documented gap — but every registry component has a real Owl export.
 2. Static-only components would report `"type": "static"` with no `owlComponents` field, but none currently exist in this registry.
 
 Per-component registry entries now include:

package/docs/theming.md

@@ -38,7 +38,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.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:
 

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.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.
 
@@ -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">
@@ -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.):**
 
@@ -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.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:
 
@@ -200,6 +200,45 @@ Full token list and the shadcn-aligned default palette: [Theming](theming.md).
 
 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).
 
+## 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`
+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
+build). Define the variables once, regenerate the files whenever they change:
+
+```js
+// baseui.pwa.config.js
+export default {
+  manifest: {
+    name: "My App",
+    shortName: "MyApp",
+    description: "One sentence about the app.",
+    themeColor: "#0f172a",
+  },
+  serviceWorker: {
+    cacheName: "my-app-cache-v1",
+    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"],
+  },
+};
+```
+
+```sh
+npx create-baseui-app pwa . --config baseui.pwa.config.js
+# writes ./manifest.webmanifest and ./sw.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 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
 
 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.1",
+  "version": "1.1.3",
   "description": "CDN-installable Owl and Bootstrap 5 UI component library.",
   "type": "module",
   "main": "./dist/baseui.min.js",
@@ -25,6 +25,10 @@
       "import": "./dist/baseui.analytics.esm.js",
       "default": "./dist/baseui.analytics.min.js"
     },
+    "./pwa": {
+      "types": "./dist/types/pwa.d.ts",
+      "import": "./dist/baseui.pwa.esm.js"
+    },
     "./dist/baseui.templates.xml": "./dist/baseui.templates.xml"
   },
   "files": [
@@ -35,8 +39,11 @@
     "dist/baseui.icons.esm.js",
     "dist/baseui.analytics.esm.js",
     "dist/baseui.analytics.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",