@thebase/ui 0.0.4 → 0.0.6

package/docs/usage-guide.md

@@ -6,7 +6,7 @@ Audience: engineers and AI coding agents integrating `@thebase/ui` into a projec
 
 ## 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.
+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.
 
 ```html
 <!doctype html>
@@ -14,8 +14,8 @@ Save this as an `.html` file and open it — no build step, no server required.
 <head>
   <meta charset="utf-8">
   <title>BaseUI quick start</title>
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.min.js" defer></script>
+  <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>
 </head>
 <body>
   <div b-ui="card" style="max-width: 24rem; margin: 2rem auto;">
@@ -32,30 +32,79 @@ Save this as an `.html` file and open it — no build step, no server required.
 </html>
 ```
 
-`https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/...` is the real, pinned jsDelivr URL for the published `@thebase/ui` npm package — swap the version segment when you upgrade. 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. `@0.0.4`) 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 `BaseUI.mountAll()` automatically on `DOMContentLoaded`, so initial `[b-ui]` and `[b-icon]` markup mounts without an extra script. Call `BaseUI.mountAll(root)` yourself only after injecting new markup or when mounting a specific fragment. If the consumer is itself an Owl app, skip to [step 3](#3-install-pure-owl-api--only-if-the-consumer-is-an-owl-app).
+The static bundle calls `BaseUI.mountAll()` automatically on `DOMContentLoaded`, so initial `[b-ui]` and `[b-icon]` markup mounts without an extra script. Call `BaseUI.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.
 
 ## 1. Decide which API you need
 
 | You are building... | Use | Install | Full reference |
 | --- | --- | --- | --- |
-| Static HTML, a server-rendered page, or a Base HUB website page | The static `b-ui` markup API | One CSS file + one `<script>` tag | [Installation](installation.md) |
-| Your own Owl app that wants `<Button/>`, `<Card/>`, `<Dialog/>` as real component classes | The pure Owl component API | 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) |
+| 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) |
 
-Both APIs come from the same package and the same CSS file, and can be mixed on one page. Most consumer projects only need the static API — reach for the pure Owl API only when the consuming app is itself an Owl app.
+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.
 
-**[VERIFY]** Before choosing, confirm whether the target project already runs Owl (check for `@odoo/owl` or `@base/owl` in its `package.json`). Do not add the pure Owl API to a project that has no Owl runtime of its own — that's what the static API is for.
+**[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 (static `b-ui` API — the common case)
+## 2. Install (pure Owl API — recommended)
+
+```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>
+```
+
+`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. `@0.0.4`) instead of `@latest` for production.
+
+```html
+<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>
+```
+
+`@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).
+
+Two rules that account for most integration failures — see [Pure Owl 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.
+
+## 3. Install (static `b-ui` API — alternative, no Owl runtime needed)
 
 **Option A — CDN (static HTML, no build step):**
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.min.css">
-<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.min.js" defer></script>
+<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>
 ```
 
+`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. `@0.0.4`) instead of `@latest` for production.
+
 **Option B — npm (bundler-based apps: Vite, webpack, etc.):**
 
 ```sh
@@ -71,7 +120,7 @@ import "@thebase/ui"; // side-effect import: registers window.BaseUI and auto-mo
 
 Rule that applies to both options:
 
-- Production pages must use a pinned version path (`/baseui/1.1.0/...`), never `/latest/`.
+- Production pages must use a pinned version (e.g. `@thebase/ui@0.0.4`), never `@latest`.
 
 Mount markup:
 
@@ -113,51 +162,6 @@ Copy-paste starting points for the components you'll reach for first. Every comp
 <span b-icon="search"></span>
 ```
 
-## 3. Install (pure Owl API — only if the consumer is an Owl app)
-
-```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.min.css">
-<script type="importmap">
-{
-  "imports": {
-    "@base/owl": "https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.esm.js",
-    "@base/component": "https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.esm.js",
-    "@base/theme": "https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.esm.js",
-    "@base/templates": "https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.templates.xml"
-  }
-}
-</script>
-```
-
-```html
-<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>
-```
-
-`@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).
-
-Two rules that account for most integration failures — see [Pure Owl 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.
-
 ## 4. Theme the install
 
 ```html
@@ -205,7 +209,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.
 - [ ] `BaseUI.version` returns the expected pinned version in the browser console.
 - [ ] Initial static markup mounts without an extra call; injected markup mounts after `BaseUI.mountAll(root)`.
-- [ ] Pure Owl components render with no console errors (a missing-template error means step 3's `dist/baseui.templates.xml` load is missing or unawaited).
+- [ ] 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).
 - [ ] 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.
 
@@ -227,7 +231,7 @@ 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 `BaseUI.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 `BaseUI.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 3.
+- Expecting `BaseUI.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.
 
 ## Related docs
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@thebase/ui",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "CDN-installable Owl and Bootstrap 5 UI component library.",
   "type": "module",
   "main": "./dist/baseui.min.js",
+  "bin": {
+    "create-baseui-app": "./bin/create-baseui-app.mjs"
+  },
   "module": "./dist/baseui.esm.js",
   "style": "./dist/baseui.min.css",
   "types": "./dist/types/index.d.ts",
@@ -20,6 +23,7 @@
     "./dist/baseui.templates.xml": "./dist/baseui.templates.xml"
   },
   "files": [
+    "bin/create-baseui-app.mjs",
     "dist/baseui.min.css",
     "dist/baseui.esm.js",
     "dist/baseui.min.js",
@@ -27,6 +31,7 @@
     "dist/baseui.templates.xml",
     "dist/icons",
     "dist/baseui.registry.json",
+    "dist/runtime",
     "dist/themes",
     "dist/types",
     "docs/*.md",
@@ -57,9 +62,10 @@
     "access": "public"
   },
   "dependencies": {
+    "@milkdown/crepe": "^7.22.1",
     "@milkdown/kit": "^7.22.1",
     "@milkdown/plugin-collab": "^7.22.1",
-    "y-prosemirror": "^1.3.7",
+    "@milkdown/plugin-emoji": "^7.22.1",
     "y-protocols": "^1.0.7",
     "y-webrtc": "^10.3.0",
     "yjs": "^13.6.32"