@thebase/ui/docs/runtime-api.md

CDN-installable Owl and Bootstrap 5 UI component library.

# Runtime API

BaseUI exposes one browser global: `window.BaseUI`.

```js
BaseUI.version
BaseUI.register(name, definition)
BaseUI.component(name)
BaseUI.mount(selectorOrElement, options)
BaseUI.mountAll(rootElement)
BaseUI.destroy(rootElement)
BaseUI.theme.set("light")
BaseUI.theme.set("dark")
BaseUI.theme.set({ primary: "#0f6cbd" })
```

The static runtime calls `autoMount()` when imported through `dist/baseui.esm.js` or `dist/baseui.min.js`. Existing `[b-ui]` and `[b-icon]` markers are enhanced automatically once the DOM is ready.

`mountAll(rootElement)` scans `[b-ui]` and `[b-icon]` below the given root. Repeated calls are idempotent for already-mounted nodes, so it is safe to call after rendering an AJAX partial or replacing a small subtree. `mount(selectorOrElement, options)` mounts one element and returns its instance metadata when a registered component exists. `destroy(rootElement)` calls component cleanup handlers and dispatches `baseui:destroyed` before a mounted subtree is removed.

Mounted components dispatch lifecycle events on their root element:

- `baseui:mounted` with `{ name, instance }` in `event.detail`.
- `baseui:destroyed` with `{ name }` in `event.detail`.

`BaseUI.theme.set(...)` is the low-level setter. For persisted light/dark toggles, button-label synchronization, URL `?theme=` overrides, and iframe preview sync, import `createThemeController` from `@base/theme` in browser import maps or `@thebase/ui` in npm/bundler apps.

`BaseUI.mountAll()` is for static `b-ui`/`b-att-*` markers and `b-icon` markers only. It does not register Owl component tags (`<Button/>`, `<Card/>`, ...) and does not know about `@thebase/ui` or `dist/baseui.templates.xml`. To use pure Owl components, import their classes, fetch the templates XML, and list those classes in your own component's `static components`; see [Pure Owl Components](owl-components.md).

## `cn()` class-name helper

`cn(...classNames)` joins strings, arrays, and falsy values into one space-separated class string, flattening nested arrays and skipping anything falsy:

```js
import { cn } from "@thebase/ui";

cn("btn", isActive && "active", ["bu-button", className]);
// "btn active bu-button my-class" (when isActive is truthy and className is "my-class")
```

It's a standalone named export — `import { cn } from "@thebase/ui"` in npm/bundler apps, or `BaseUIBundle.cn` in the browser IIFE global — not a method on `BaseUI` itself. Use it to build your own components' class lists on top of BaseUI's conventions.

## `mergeStyle()` inline-style helper

`mergeStyle(...styles)` combines a component's own computed inline style with a caller-supplied `style` (string or object) into one `;`-joined declaration string, dropping empty/nullish entries. Object keys may be camelCase (converted to kebab-case); later entries win on conflicting properties since they're appended last:

```js
import { mergeStyle } from "@thebase/ui";

mergeStyle("--b-progress-value:50%", { color: "red" }, "opacity:0.5;");
// "--b-progress-value:50%;color:red;opacity:0.5"
```

It's a standalone named export — `import { mergeStyle } from "@thebase/ui"` in npm/bundler apps, or `BaseUIBundle.mergeStyle` in the browser IIFE global. Unlike `cn()`, which joins class names with a space, `mergeStyle()` joins CSS declarations with `;` — the two are not interchangeable.