@thebase/ui 1.0.0 → 1.1.1

package/dist/baseui.registry.json

@@ -18,6 +18,8 @@
     "baseui.icons.esm.js",
     "baseui.templates.xml",
     "baseui.block-viewer.esm.js",
+    "baseui.analytics.esm.js",
+    "baseui.analytics.min.js",
     "icons/lucide.json"
   ],
   "icons": {
@@ -1660,11 +1662,13 @@
   "integrity": {
     "baseui.min.css": "sha384-hYFwlV6T/ONYzawtDGDFUoruqgNwYl9AVvLDHx24IWgKSMXqwACo/nX04I3gnyT9",
     "bootstrap.bundle.min.js": "sha384-RMbllTJcplkCRnELNTOc5Kz/3AvFDE/rNlJqWqfgmRWruobClBdfwvl10akQZkR1",
-    "baseui.min.js": "sha384-dgJ6Mbk5+apdFpV1iU/Lnp4CQWZXgBpsUn3r7oh8DHH2rNqIqNmsHKPVub5ZEq+D",
-    "baseui.esm.js": "sha384-AP0mGX4n1avSDWoAUakm71/JAR0vvd6n2qR39RI8nssDriB8lhN4wXZijA6XfVeJ",
-    "baseui.icons.esm.js": "sha384-M30zHGB1h8ys1b2YBuLR7J3VzcYqft9L+wVI/EM1P8h8fY5Y2h1woOQzyE5DZ+lp",
+    "baseui.min.js": "sha384-m91LivkZ3FsaSmngFXfmaGHxfBokU/tEXFAuYz3PIjeXuKMcJjdRmOEk596O8S8u",
+    "baseui.esm.js": "sha384-v3JjyzSIh67awBXIDScUTR40lyCHyuOue1zwObQHjH4OjOj9Cg3mPMkto3LVcVO7",
+    "baseui.icons.esm.js": "sha384-hj39VMhzcFvmYnjob2hlioMOAqwAXCURGreF6s9RitXFp/iYi7rUdqtfCI+ICQeS",
     "baseui.templates.xml": "sha384-XkqmfurKcEF6WuIQHWAbnZfW6oz19n7SDVRDU3g0hc3qOr4kPd/qfNGcTmcDDIgQ",
-    "baseui.block-viewer.esm.js": "sha384-rQ7YMxLWDA+ccC/JwTcOV8DKUjZTZofqJwNX8xrKTpZbsBVRa4taXLOLpRQ6poR4",
+    "baseui.block-viewer.esm.js": "sha384-XlIb3jDxt6Q75dbC4rLctTdPU6u0vJFcbxp9Gl6VKOkhjpz3wRBe0E3dWd80425L",
+    "baseui.analytics.esm.js": "sha384-M6TVmchmceTvpSzgI+DNA6zAn9xmz9a+YEexCLslSo/Ngxyp2kmzs9fm+PxWy+Da",
+    "baseui.analytics.min.js": "sha384-B0hBkVDbT7gmDmUMazlN4Nc1KnYGSpL+IcW2hd8840knx73HGImPgGs84MvS3hKE",
     "icons/lucide.json": "sha384-mc5mzpmq9eOgZVa2IcjrL33Ty4nMXE8aoZMfy+lgkC/jMQ4aYnk2S58mFsSGFnW1",
     "themes/baseui-light.css": "sha384-/TosvycgVJ5aZ7EOWd4cr8Zen4nayAC/iA9BgGdXKH0LuHSnZk4guDaWM5WPC7yy",
     "themes/baseui-dark.css": "sha384-zF9Rhfjpv90sxuJ2WK7GBPCltN6mkebzK1w9EzQGY9DYHiX3eIX/fcE7fXzfIZVF"

package/dist/types/analytics.d.ts

@@ -0,0 +1,76 @@
+/** Cookieless analytics service (ported from @plausible-analytics/tracker 0.4.6). */
+export interface BaseUIAnalytics {
+  /** Sets up the tracker. Can be called once. */
+  init(config: BaseUIAnalyticsConfig): void;
+  /** Tracks an event; requires `init` to be called first. */
+  track(eventName: string, options?: BaseUIAnalyticsEventOptions): void;
+  /** File types tracked by default when `fileDownloads` is enabled. */
+  DEFAULT_FILE_TYPES: string[];
+  /** Coarse visitor setup (timezone, language, screen bucket); pass as `customProperties`. */
+  visitorContext(): BaseUIVisitorContext;
+}
+export interface BaseUIVisitorContext {
+  /** IANA timezone, e.g. "Europe/Paris" (browsers may report legacy aliases like "Asia/Saigon"). */
+  tz: string;
+  /** `navigator.language`, e.g. "vi-VN". */
+  lang: string;
+  /** Viewport width bucket: < 576, < 992, < 1440, otherwise Desktop. */
+  screen: "Mobile" | "Tablet" | "Laptop" | "Desktop";
+}
+
+export interface BaseUIAnalyticsConfig {
+  /** Analytics backend origin, e.g. "https://stats.example.com" — events go to `<backendUrl><apiPath>`. Required unless `endpoint` is given. */
+  backendUrl?: string;
+  /** Path appended to `backendUrl`. Defaults to "/api/event". */
+  apiPath?: string;
+  /** Full event URL (http(s):// or a same-site /path); overrides `backendUrl` and `apiPath`. */
+  endpoint?: string;
+  /** Site name reported with every event. Defaults to `location.hostname`. */
+  domain?: string;
+  /** Capture pageviews automatically (incl. pushState/popstate). Defaults to true. */
+  autoCapturePageviews?: boolean;
+  /** Page uses hash-based routing. Defaults to false. */
+  hashBasedRouting?: boolean;
+  /** Track outbound link clicks. Defaults to false. */
+  outboundLinks?: boolean;
+  /** Track file downloads, optionally with a custom extension list. Defaults to false. */
+  fileDownloads?: boolean | { fileExtensions: string[] };
+  /** Track form submissions. Defaults to false. */
+  formSubmissions?: boolean;
+  /** Capture events on localhost. Defaults to false. */
+  captureOnLocalhost?: boolean;
+  /** Log ignored events to the console. Defaults to true. */
+  logging?: boolean;
+  /** Properties added to every event, or a function returning them per event name. */
+  customProperties?: Record<string, string> | ((eventName: string) => Record<string, string>);
+  /** Rewrite the payload before sending; return a falsy value to drop the event. */
+  transformRequest?: (payload: BaseUIAnalyticsPayload) => BaseUIAnalyticsPayload | null;
+  /** Bind the tracker to `window.thebase.track`. Defaults to true. */
+  bindToWindow?: boolean;
+}
+
+export interface BaseUIAnalyticsEventOptions {
+  props?: Record<string, string>;
+  /** Non-interactive events don't count towards bounce rate. Defaults to true. */
+  interactive?: boolean;
+  revenue?: { amount: number | string; currency: string };
+  /** Called with `{ status }`, `{ error }`, or undefined when the event was ignored. */
+  callback?: (result?: { status: number } | { error: unknown }) => void;
+  /** Overrides the page URL (defaults to `location.href`). */
+  url?: string;
+}
+
+export type BaseUIAnalyticsPayload = {
+  n: string;
+  u: string;
+  d: string;
+  r?: string | null;
+  p?: Record<string, string>;
+  $?: { amount: number | string; currency: string };
+  i?: boolean;
+} & Record<string, unknown>;
+
+export const DEFAULT_FILE_TYPES: string[];
+export function init(config: BaseUIAnalyticsConfig): void;
+export function track(eventName: string, options?: BaseUIAnalyticsEventOptions): void;
+export function visitorContext(): BaseUIVisitorContext;

package/dist/types/index.d.ts

@@ -25,6 +25,10 @@ export interface BaseUIApi {
     };
   };
   theme: { set(modeOrTokens: string | Record<string, string>): void };
+  /** Set by dist/baseui.analytics.min.js (the optional analytics service). */
+  analytics?: import("./analytics").BaseUIAnalytics;
+  /** Bound by `analytics.init()` (unless `bindToWindow: false`). */
+  track?: import("./analytics").BaseUIAnalytics["track"];
 }
 
 export interface BaseUIThemeController {

package/docs/analytics.md

@@ -0,0 +1,267 @@
+# Analytics
+
+BaseUI ships a cookieless web-analytics service, ported from [`@plausible-analytics/tracker`](https://www.npmjs.com/package/@plausible-analytics/tracker) 0.4.6 (MIT; notice in `LICENSE`). Nothing is collected until the page calls `init({ backendUrl })`. Available from `@thebase/ui` 1.1.0.
+
+It is an optional, standalone feature: it is **not** part of `dist/baseui.min.js`/`dist/baseui.esm.js`, and it needs neither of them (no Owl, Bootstrap or component runtime). Load it on its own, with or without the rest of BaseUI (~5.6 KB minified):
+
+```js
+// npm / bundler
+import { init, track } from "@thebase/ui/analytics";
+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";
+  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>
+  thebase.analytics.init({ backendUrl: "https://stats.example.com" });
+</script>
+```
+
+Types ship as `dist/types/analytics.d.ts` (resolved automatically for `@thebase/ui/analytics`).
+
+`init()` can be called once. It sends the first pageview, then follows `history.pushState`/`popstate` navigations (or `hashchange` with `hashBasedRouting: true`).
+
+## Options
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `backendUrl` | required¹ | Analytics backend origin, e.g. `https://stats.example.com`. Events are POSTed (`text/plain` JSON, no CORS preflight) to `<backendUrl><apiPath>`; a trailing `/` is fine. |
+| `apiPath` | `/api/event` | Path appended to `backendUrl` (leading `/` optional), e.g. `/v1/collect`. |
+| `endpoint` | — | Full event URL instead of `backendUrl` + `apiPath` (`http(s)://…` or a same-site `/path`, e.g. behind a proxy). |
+| `domain` | `location.hostname` | Site name reported with every event. |
+| `autoCapturePageviews` | `true` | Send pageviews automatically. |
+| `hashBasedRouting` | `false` | Treat `#` changes as navigations. |
+| `outboundLinks` | `false` | Track clicks on links to other hosts as `Outbound Link: Click`. |
+| `fileDownloads` | `false` | Track download links as `File Download`; pass `{ fileExtensions: [...] }` to replace `analytics.DEFAULT_FILE_TYPES`. |
+| `formSubmissions` | `false` | Track valid form submits as `Form: Submission`. |
+| `captureOnLocalhost` | `false` | Also send from `localhost`/`127.x`/`file:`. |
+| `logging` | `true` | `console.warn` when an event is ignored. |
+| `customProperties` | — | Props added to every event (object, or `(eventName) => object`). |
+| `transformRequest` | — | Rewrite the payload; return a falsy value to drop the event. |
+| `bindToWindow` | `true` | Bind the tracker to `window.thebase.track`. |
+
+¹ One of `backendUrl` or `endpoint` is required. `init()` throws if neither is given, or if the URL has no `http(s)://` scheme and doesn't start with `/` (e.g. `stats.example.com`), since that would silently post to a path on your own site.
+
+Your backend should answer with `Access-Control-Allow-Origin` for your site. The event is delivered either way (there is no preflight), but without that header the browser hides the response and `callback` receives `{ error }`.
+
+## Custom events
+
+```js
+thebase.track("Signup", { props: { plan: "pro" }, revenue: { amount: 10, currency: "USD" } });
+```
+
+`track(name, options)` accepts `props`, `revenue`, `interactive: false` (excluded from bounce rate), `url` (override the page URL), and `callback(result)` — called with `{ status }`, `{ error }`, or `undefined` when the event was ignored.
+
+Or tag markup with classes — no JavaScript needed:
+
+```html
+<button class="thebase-event-name=Signup thebase-event-plan=pro">Sign up</button>
+<form class="thebase-event-name=Lead">...</form>
+```
+
+`+` in a class value becomes a space; `thebase-revenue-amount=10 thebase-revenue-currency=USD` attaches revenue.
+
+## Visitor context
+
+`visitorContext()` returns coarse facts about the visitor's setup. Pass it as `customProperties` to attach them to every event (available from 1.1.1):
+
+```js
+import { init, visitorContext } from "@thebase/ui/analytics";
+init({ backendUrl: "https://stats.example.com", customProperties: visitorContext });
+// every event's props now include { tz: "Asia/Ho_Chi_Minh", lang: "vi-VN", screen: "Mobile" }
+```
+
+| Prop | Value |
+| --- | --- |
+| `tz` | `Intl.DateTimeFormat().resolvedOptions().timeZone`. Some browsers report legacy aliases (Chromium sends `Asia/Saigon`), so backends should canonicalize. |
+| `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)).
+
+## Engagement
+
+After each pageview the service measures time on screen and maximum scroll depth, and sends an `engagement` event (`e` = ms, `sd` = %) when the tab is hidden, loses focus, or navigates — only if the visitor scrolled further or spent at least 3 seconds since the last report.
+
+## Ignored visits
+
+Events are dropped (and `callback()` gets `undefined`) on localhost unless `captureOnLocalhost` is set, in automated browsers (`navigator.webdriver`, Cypress, PhantomJS, Nightmare — unless `window.__thebase` is set), or when `localStorage.thebase_ignore === "true"` (set that on your own devices to exclude them).
+
+## Receiving events (backend)
+
+Any HTTP server can collect events. It needs one route — `POST <backendUrl><apiPath>` (default `/api/event`) — that:
+
+1. Reads the **raw body** as JSON. The tracker sends `Content-Type: text/plain` to avoid a CORS preflight, so framework helpers that only parse `application/json` bodies won't decode it.
+2. Rejects bodies missing `n`, `u` or `d`, and caps the body size (events are well under 1 KB).
+3. Answers quickly (`202 Accepted`, no body) with `Access-Control-Allow-Origin` for your site. Store or queue the event after you reply, or send it to a queue, so the visitor's browser never waits on the database.
+
+### Payload
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `n` | string | Event name: `pageview`, `engagement`, or a custom name (`Signup`, `Outbound Link: Click`, `File Download`, `Form: Submission`, …). |
+| `u` | string | Page URL. |
+| `d` | string | Site `domain`. |
+| `r` | string \| null | `document.referrer` (pageviews and custom events). |
+| `p` | object | Custom properties (`props` + `customProperties`); values are usually strings. |
+| `$` | object | Revenue, e.g. `{ "amount": 10, "currency": "USD" }` (`amount` is a string when it comes from a class tag). |
+| `i` | `false` | Present only for non-interactive events (excluded from bounce rate). |
+| `h` | `1` | Present only with `hashBasedRouting`. |
+| `sd` | number | `engagement` only: max scroll depth, %. |
+| `e` | number | `engagement` only: engaged time, ms. |
+| `v` | number | Tracker version (currently `36`). |
+
+The payload carries no visitor ID or cookie. To count unique visitors, derive one on the server, e.g. `sha256(dailySalt + domain + clientIP + userAgent)`. Rotate the salt every day and never store the raw IP. If the server sits behind a proxy or load balancer, configure it to trust the proxy's `X-Forwarded-For` header so it sees the visitor's IP instead of the proxy's.
+
+### Go — Fiber v3
+
+Requires Go 1.25+ and `go get github.com/gofiber/fiber/v3` (tested with v3.5.0).
+
+```go
+package main
+
+import (
+	"encoding/json"
+	"log"
+
+	"github.com/gofiber/fiber/v3"
+	"github.com/gofiber/fiber/v3/middleware/cors"
+)
+
+// Event is the compact payload POSTed by @thebase/ui/analytics.
+type Event struct {
+	Name        string         `json:"n"`
+	URL         string         `json:"u"`
+	Domain      string         `json:"d"`
+	Referrer    *string        `json:"r"`
+	Props       map[string]any `json:"p"`
+	Revenue     map[string]any `json:"$"`
+	Interactive *bool          `json:"i"`
+	HashRouting int            `json:"h"`
+	ScrollDepth *int           `json:"sd"`
+	EngagedMs   *int64         `json:"e"`
+	Version     int            `json:"v"`
+}
+
+func main() {
+	app := fiber.New(fiber.Config{BodyLimit: 16 * 1024})
+	app.Use(cors.New(cors.Config{AllowOrigins: []string{"https://www.example.com"}}))
+
+	app.Post("/api/event", func(c fiber.Ctx) error {
+		// Body is text/plain, so decode it directly instead of c.Bind().JSON().
+		var ev Event
+		if err := json.Unmarshal(c.Body(), &ev); err != nil || ev.Name == "" || ev.URL == "" || ev.Domain == "" {
+			return c.SendStatus(fiber.StatusBadRequest)
+		}
+		log.Printf("%s %s %s ip=%s ua=%q", ev.Domain, ev.Name, ev.URL, c.IP(), c.Get(fiber.HeaderUserAgent))
+		// TODO: enqueue/store ev.
+		return c.SendStatus(fiber.StatusAccepted)
+	})
+
+	log.Fatal(app.Listen(":8080"))
+}
+```
+
+### Python — FastAPI
+
+Requires Python 3.10+ and `pip install "fastapi[standard]"` (tested with FastAPI 0.142.2 / Pydantic 2.13). Run with `fastapi run main.py`.
+
+```python
+from typing import Any
+
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field, ValidationError
+
+app = FastAPI()
+app.add_middleware(CORSMiddleware, allow_origins=["https://www.example.com"], allow_methods=["POST"])
+
+
+class Event(BaseModel):
+    """Compact payload POSTed by @thebase/ui/analytics."""
+
+    name: str = Field(alias="n", min_length=1)
+    url: str = Field(alias="u", min_length=1)
+    domain: str = Field(alias="d", min_length=1)
+    referrer: str | None = Field(None, alias="r")
+    props: dict[str, Any] | None = Field(None, alias="p")
+    revenue: dict[str, Any] | None = Field(None, alias="$")
+    interactive: bool | None = Field(None, alias="i")
+    hash_routing: int | None = Field(None, alias="h")
+    scroll_depth: int | None = Field(None, alias="sd")
+    engaged_ms: int | None = Field(None, alias="e")
+    version: int = Field(alias="v")
+
+
+@app.post("/api/event", status_code=202)
+async def collect(request: Request) -> Response:
+    # Body is text/plain, so parse the raw bytes instead of declaring `event: Event` as a parameter.
+    body = await request.body()
+    if len(body) > 16 * 1024:
+        return Response(status_code=413)
+    try:
+        event = Event.model_validate_json(body)
+    except ValidationError:
+        return Response(status_code=400)
+    ip = request.client.host if request.client else None
+    print(event.domain, event.name, event.url, ip, request.headers.get("user-agent"))
+    # TODO: enqueue/store event.
+    return Response(status_code=202)
+```
+
+Point the tracker at either server with `init({ backendUrl: "https://stats.example.com" })`. To smoke-test the server, run:
+
+```sh
+curl -i -X POST http://localhost:8080/api/event -H 'Content-Type: text/plain' \
+  -d '{"n":"pageview","v":36,"u":"https://www.example.com/","d":"www.example.com","r":null}'
+# HTTP/1.1 202 Accepted
+```
+
+## Sample dashboard
+
+[`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.
+
+```sh
+# Go (1.25+)
+cd examples/analytics/server-go && DEMO_SEED=1 go run .
+
+# or Python (3.10+)
+cd examples/analytics/server-fastapi && pip install -r requirements.txt && DEMO_SEED=1 fastapi run main.py --port 8080
+```
+
+Open <http://localhost:8080/>, the backend serves the dashboard itself. If you are browsing these docs from `npm run dev` (port 5173), the [dashboard link](../examples/analytics/dashboard/?backend=http://localhost:8080) also works once a backend is running on port 8080; until then it shows a "Can't load stats" message. `DEMO_SEED=1` preloads 30 days of synthetic traffic for `demo.example.com`. Other environment variables:
+- `ADDR`: the Go listen address.
+- `ALLOWED_ORIGINS`: a comma-separated CORS allow-list (default `*`).
+- `DASHBOARD_DIR`: the folder served at `/`.
+
+To serve the dashboard from somewhere else, open it with `?backend=https://stats.example.com`.
+
+`GET /api/stats?domain=<site>&days=<1..90>` (default: the busiest site, 7 days, UTC) returns:
+
+```json
+{
+  "domain": "demo.example.com",
+  "domains": ["demo.example.com", "www.example.com"],
+  "days": 7,
+  "totals": { "visitors": 643, "pageviews": 1582, "events": 124, "avgTimeSec": 62.7, "avgScrollDepth": 63.4 },
+  "timeseries": [{ "date": "2026-09-28", "visitors": 105, "pageviews": 261 }],
+  "topPages":   [{ "name": "/pricing", "visitors": 296, "count": 373 }],
+  "topSources": [{ "name": "google.com", "visitors": 186, "count": 186 }],
+  "topEvents":  [{ "name": "Signup", "visitors": 40, "count": 40 }]
+}
+```
+
+The sample servers are demos, not production stores:
+- Events live in memory only and are lost on restart.
+- `/api/stats` has no authentication.
+
+Before going live, persist events (e.g. PostgreSQL or ClickHouse), put `/api/stats` behind auth, and restrict `ALLOWED_ORIGINS`.

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.0.0`, 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.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).
 
 Use `b-block` to select the block style:
 

package/docs/components/avatar.md

@@ -37,7 +37,7 @@ See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for
 
 ## Enhanced usage
 
-Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script loads.
 
 ## Options and attributes
 
@@ -45,7 +45,7 @@ See `dist/baseui.registry.json` for the supported attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.
 
 ## Events
 
@@ -69,4 +69,4 @@ BaseUI targets modern evergreen browsers that support ES modules, CSS variables,
 
 ## Test checklist
 
-Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `thebase.destroy()`.

package/docs/components/block-viewer.md

@@ -37,7 +37,7 @@ import { BlockViewer } from "@base/component";
 </body>
 ```
 
-`BaseUI.mountAll()` (called automatically on `DOMContentLoaded`) mounts the `b-ui="block-viewer"` element as a full Owl app, using the block's own inline template as its live preview and its serialized text as the "Code" panel.
+`thebase.mountAll()` (called automatically on `DOMContentLoaded`) mounts the `b-ui="block-viewer"` element as a full Owl app, using the block's own inline template as its live preview and its serialized text as the "Code" panel.
 
 ## Options and attributes
 
@@ -49,4 +49,4 @@ See `dist/baseui.registry.json` for the full attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.

package/docs/components/calendar.md

@@ -36,7 +36,7 @@ See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for
 
 ## Enhanced usage
 
-Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script loads.
 
 ## Options and attributes
 
@@ -44,7 +44,7 @@ See `dist/baseui.registry.json` for the supported attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.
 
 ## Events
 
@@ -68,4 +68,4 @@ BaseUI targets modern evergreen browsers that support ES modules, CSS variables,
 
 ## Test checklist
 
-Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `thebase.destroy()`.

package/docs/components/carousel.md

@@ -86,7 +86,7 @@ The static adapter builds the `.carousel-inner`/`.carousel-item` wrapper structu
 
 ## Enhanced usage
 
-Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script loads.
 
 ## Options and attributes
 
@@ -94,7 +94,7 @@ See `dist/baseui.registry.json` for the supported attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.
 
 ## Events
 
@@ -118,4 +118,4 @@ BaseUI targets modern evergreen browsers that support ES modules, CSS variables,
 
 ## Test checklist
 
-Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `thebase.destroy()`.

package/docs/components/chart.md

@@ -94,7 +94,7 @@ See `examples/charts/area.html` for the local copy of the shadcn area chart gall
 
 ## Enhanced usage
 
-Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script loads.
 
 ## Options and attributes
 
@@ -102,7 +102,7 @@ See `dist/baseui.registry.json` for the supported attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.
 
 ## Events
 
@@ -126,4 +126,4 @@ BaseUI targets modern evergreen browsers that support ES modules, CSS variables,
 
 ## Test checklist
 
-Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `thebase.destroy()`.

package/docs/components/combobox.md

@@ -43,7 +43,7 @@ See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for
 
 ## Enhanced usage
 
-Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script loads.
 
 ## Options and attributes
 
@@ -51,7 +51,7 @@ See `dist/baseui.registry.json` for the supported attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.
 
 ## Events
 
@@ -75,4 +75,4 @@ BaseUI targets modern evergreen browsers that support ES modules, CSS variables,
 
 ## Test checklist
 
-Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `thebase.destroy()`.

package/docs/components/command.md

@@ -46,7 +46,7 @@ See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for
 
 ## Enhanced usage
 
-Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script loads.
 
 ## Options and attributes
 
@@ -54,7 +54,7 @@ See `dist/baseui.registry.json` for the supported attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.
 
 ## Events
 
@@ -78,4 +78,4 @@ BaseUI targets modern evergreen browsers that support ES modules, CSS variables,
 
 ## Test checklist
 
-Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `thebase.destroy()`.

package/docs/components/context-menu.md

@@ -48,7 +48,7 @@ See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for
 
 ## Enhanced usage
 
-Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script loads.
 
 ## Options and attributes
 
@@ -56,7 +56,7 @@ See `dist/baseui.registry.json` for the supported attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.
 
 ## Events
 
@@ -80,4 +80,4 @@ BaseUI targets modern evergreen browsers that support ES modules, CSS variables,
 
 ## Test checklist
 
-Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `thebase.destroy()`.

package/docs/components/data-table.md

@@ -74,7 +74,7 @@ See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for
 
 ## Enhanced usage
 
-Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script loads.
 
 ## Options and attributes
 
@@ -82,7 +82,7 @@ See `dist/baseui.registry.json` for the supported attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.
 
 ## Events
 
@@ -154,4 +154,4 @@ BaseUI targets modern evergreen browsers that support ES modules, CSS variables,
 
 ## Test checklist
 
-Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `thebase.destroy()`.

package/docs/components/date-picker.md

@@ -36,7 +36,7 @@ See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for
 
 ## Enhanced usage
 
-Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+Call `thebase.mount(element)` or rely on `thebase.mountAll()` after the script loads.
 
 ## Options and attributes
 
@@ -44,7 +44,7 @@ See `dist/baseui.registry.json` for the supported attribute list.
 
 ## Methods
 
-Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+Use the global runtime methods: `thebase.mount()`, `thebase.mountAll()`, and `thebase.destroy()`.
 
 ## Events
 
@@ -68,4 +68,4 @@ BaseUI targets modern evergreen browsers that support ES modules, CSS variables,
 
 ## Test checklist
 
-Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `thebase.destroy()`.

package/docs/components/icon.md

@@ -46,8 +46,8 @@ For install patterns, accessibility guidance, self-hosting, and JavaScript examp
 ## JavaScript API
 
 ```js
-BaseUI.icons.lucide.url("panel-left");
-BaseUI.icons.lucide.render(document.querySelector("#icon"), "check", { size: "18px" });
+thebase.icons.lucide.url("panel-left");
+thebase.icons.lucide.render(document.querySelector("#icon"), "check", { size: "18px" });
 ```
 
 By default, icon URLs point to `https://cdn.jsdelivr.net/npm/lucide-static@1.31.0/icons`. The build also publishes every SVG under `dist/icons/lucide/` plus a generated `dist/icons/lucide.json` manifest for self-hosted CDN deployments.