@thebase/ui/README.md

CDN-installable Owl and Bootstrap 5 UI component library.

# The Base UI

The Base UI is a CDN-installable UI kit built with Bootstrap 5 styling and Owl-enhanced behavior. The primary way to consume it is as **pure Owl components** (`<Button/>`-style imports into your own Owl app); the static `b-ui` markup adapter is the alternative for plain static HTML, server-rendered pages, and Base HUB website pages that have no Owl app of their own.

Its strong points: **no build step** — every component runs straight from a CDN `<script>`/import map, nothing to compile; **modular component design** — each component is a self-contained unit you import or mark up individually, not a monolith; **vanilla JavaScript/TypeScript** — no framework lock-in, no JSX, no compiler-specific syntax to learn; and this combination makes it well suited to building **WYSIWYG website builders**, where components must mount, unmount, and re-render dynamically from user-driven markup or drag-and-drop edits rather than a fixed build-time component tree.

Both APIs load straight from a CDN — jsDelivr or unpkg — no build step, no self-hosting required. The snippets below use the `@latest` tag for readability; pin an exact version instead (e.g. `@0.0.11`) for any production page, since `@latest` can change what your page loads the moment a new version ships. Pure Owl usage:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
<script type="importmap">
{
  "imports": {
    "@base/owl": "https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.esm.js",
    "@base/component": "https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.esm.js",
    "@base/theme": "https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.esm.js",
    "@base/templates": "https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.templates.xml"
  }
}
</script>
<script type="module">
  import { Component, mount, xml } from "@base/owl";
  import { Button, Card, CardBody, CardHeader, CardTitle } from "@base/component";

  const templates = await fetch(import.meta.resolve("@base/templates")).then((r) => r.text());

  class Root extends Component {
    static components = { Button, Card, CardBody, CardHeader, CardTitle };
    static template = xml`
      <Card>
        <CardHeader><CardTitle>Hello</CardTitle></CardHeader>
        <CardBody>
          <Button variant="'default'" label="'Save'" onClick="() => console.log('saved')"/>
        </CardBody>
      </Card>`;
  }

  await mount(Root, document.getElementById("app"), { templates });
</script>
```

[unpkg](https://unpkg.com/@thebase/ui@latest/) mirrors the same files as an alternative CDN — swap any `cdn.jsdelivr.net/npm` URL above for `unpkg.com` (e.g. `https://unpkg.com/@thebase/ui@latest/dist/baseui.esm.js`) if jsDelivr is unreachable in your environment. See [Pure Owl Components](docs/owl-components.md) for the full API, npm/bundler usage, and mixing with the static adapter.

If you have no Owl app, use the static `b-ui` markup adapter instead — one stylesheet and one script tag, no import map:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.js" defer></script>
```

`dist/baseui.min.js`/`baseui.esm.js` are fully self-contained and back both APIs above: Bootstrap's JS bundle, the Owl runtime, every pure Owl component class, and the theme helper are all embedded in load order (Bootstrap, then Owl, then BaseUI) — one file, nothing else to load first. There is no separate `baseui.owl.*`/`baseui.components.esm.js`/`baseui.theme.esm.js`. (`dist/bootstrap.bundle.min.js` still ships standalone, unmodified, for a project that wants vendored Bootstrap JS on its own — BaseUI itself never needs it loaded separately.)

BaseUI exposes every component (73 in the current registry) as a real Owl component class — see [Pure Owl Components](docs/owl-components.md) for the complete API, npm/bundler usage, and mixing with the static adapter.

For app-level theme controls, import `createThemeController`/`BaseUITheme` as `@base/theme` in browser import maps (pointing at the same `dist/baseui.esm.js`) or straight from `@thebase/ui` in npm/bundler apps, to create persisted light/dark toggles like the documentation pages use.

Every component ships both APIs from `src/components/<name>/`: the static `b-ui` adapter (`<name>.js`, using `b-att-*` attributes and `baseui:*` events) and a pure Owl component class (`<name>.component.js`, exported from `@thebase/ui/components`). A few components' pure Owl treatment is intentionally lighter or reshaped versus their static markup-driven adapter — most notably `chart` (a slotted container; static Chart.js bootstrapping stays a `b-ui`-only concern) and the data-driven `data-table`/`combobox`/`command`/`calendar` (props-driven instead of slot/markup-driven). See each component's doc page under `docs/components/` for specifics.

## Release notes

See [CHANGELOG.md](CHANGELOG.md) for the full version history. Current published version: **0.0.11**.

## Project Documents

Use these documents as the canonical project map:

- [Usage Guide](docs/usage-guide.md) is the single entry point for integrating BaseUI into a consumer project — start here, then follow its links into the reference docs below.
- [Installation](docs/installation.md) covers CDN, npm, self-hosted usage, icon assets, pinned versions, and release guardrails.
- [Runtime API](docs/runtime-api.md) documents the `window.BaseUI` global, mounting lifecycle, theming API, and destroy behavior.
- [Registry](docs/registry.md) explains `dist/baseui.registry.json`, build files, block metadata, component metadata, and integrity hashes.
- [Theming](docs/theming.md) describes `b-theme`, runtime theme overrides, shadcn-aligned tokens, Bootstrap variable mapping, and shared example theme persistence.
- [Built-in Icons](docs/icons.md) covers the Lucide icon library, `b-icon` markup, accessibility rules, self-hosted icon paths, and JavaScript helpers.
- [Component Authoring](docs/component-authoring.md) defines the `src/components/<name>/` source contract, component registration rules, event naming, cleanup requirements, and CSS scoping policy. Repo-only — not published to npm (see below).
- [Pure Owl Components](docs/owl-components.md) covers the pure Owl component API (`@thebase/ui` + `dist/baseui.templates.xml`), what to load, and common mistakes.
- [Blocks](docs/blocks.md) documents copyable static shadcn-style blocks, source stylesheet ownership under `examples/blocks/`, gallery/viewer URLs, and block icon rules.
- [Component Reference](docs/components/button.md) starts the per-component documentation set in `docs/components/`; each component page includes usage, attributes, events, accessibility notes, and test guidance where relevant.
- [Frontend Implementation Plan](.agents/planning/2026-08-11-frontend-baseui-bootstrap-owl-implementation-plan.md) records the completed BaseUI 1.0.0 delivery checklist and earlier decisions for engineering context.
- [Historical Product Plan](.agents/knowledge/baseUI/2026-08-11-baseui-bootstrap-owl-plan.md) preserves the original Bootstrap 5 + Owl product brief; use current `docs/` and registry files when they disagree with older planning assumptions.

The links above work as-is when browsing this repo. `docs/*.md` and `docs/components/` also ship inside the published npm package (see `files` in `package.json`), so the same docs are reachable straight from a CDN without cloning the repo — no HTML rendering, just the raw Markdown source:

```text
https://unpkg.com/@thebase/ui@latest/docs/usage-guide.md
https://unpkg.com/@thebase/ui@latest/docs/components/button.md
https://cdn.jsdelivr.net/npm/@thebase/ui@latest/docs/usage-guide.md
```

Drop the version (`@thebase/ui/docs/...`) to always resolve to latest, or pin a version the way the rest of this README recommends pinning `dist/` assets. `docs/v2/` (the vendored general Owl framework reference) and `docs/component-authoring.md` (BaseUI's own component-authoring contract) are intentionally **not** published — they're development-time references for working inside this repo, not something a consumer needs to use the library.

## Development

```sh
npm install
npm run build
npm run dev
```

Open `examples/index.html` through the dev server to test the browser build.

`examples/index.html` is the single Owl app shell for docs, the component gallery, the block gallery, icons, and the chart catalog, all reachable through one `main-nav` and hash routes (`#/docs`, `#/components`, `#/blocks`, `#/icons`, `#/chart`). Old bookmarked URLs like `/docs` and `/blocks` redirect to their hash-route equivalent. Each block has a shadcn-style Preview/Code/responsive viewer plus its source stylesheet colocated in `examples/blocks/`. `examples/charts/index.html` mirrors the current shadcn chart catalog with interactive BaseUI examples for area, bar, line, pie, radar, radial, and tooltip charts, and is embedded inline at `#/chart`.

BaseUI includes the full Lucide SVG icon set as a built-in icon library. Use `<span b-icon="search"></span>` in HTML, or `BaseUI.icons.lucide.url("search")` from JavaScript. Builds publish all SVGs to `dist/icons/lucide/` and an index at `dist/icons/lucide.json`.

## Package Scripts

- `npm run dev` starts a static server for examples and built `dist/` assets.
- `npm run build` creates CDN and npm artifacts in `dist/`.
- `npm run lint` checks JavaScript and CSS policy.
- `npm run test` runs runtime tests.
- `npm publish` runs `prepublishOnly` first.

## Distribution

The npm package publishes the built `dist/` artifacts plus package metadata. The browser build bundles Bootstrap CSS, and `dist/baseui.min.js`/`baseui.esm.js` embed Bootstrap's JS bundle, the Owl runtime, every pure Owl component class, and the theme helper directly (Bootstrap then Owl then BaseUI, in that load order) — consumers install BaseUI with one stylesheet and one script tag for either API. Bootstrap's JS drives every component that has a Bootstrap JS equivalent (modal, dropdown, collapse, tab, toast, carousel, tooltip, popover, alert); BaseUI's `.behavior.js`/`runtime/*.js` helpers wrap Bootstrap's JS API instead of reimplementing it, for both the static and pure-Owl APIs. `dist/bootstrap.bundle.min.js` also ships standalone (unmodified) and `dist/baseui.icons.esm.js` stays a separate, deliberate exception (2000+ generated icon components would blow the main bundle's size budget) — everything else is one file. Every shipped CSS/JS artifact is minified — there are no unminified twins to keep in sync.

The published tarball also carries `docs/*.md` and `docs/components/` (see the "Project Documents" section above), `README.md`, `CHANGELOG.md`, and `LICENSE` — `docs/v2/` and `docs/component-authoring.md` are deliberately excluded from `package.json`'s `files` list since they're development-time-only references for working inside this repo.