@thebase/ui 0.0.4

package/docs/components/text-editor.md

@@ -0,0 +1,70 @@
+# Text Editor
+
+Use `b-ui="text-editor"` (or the pure Owl `TextEditor` component) for WYSIWYG rich-text editing backed by ProseMirror. The editor runtime is lazy-loaded from `dist/runtime/prosemirror-text-editor.js`, so the default BaseUI bundle stays small until an editor is actually mounted.
+
+Collaborative mode uses Yjs, y-prosemirror, and y-webrtc. Use `room` / `b-att-room` to put editors in the same peer-to-peer document, `password` / `b-att-password` for y-webrtc room encryption, and `signaling` / `b-att-signaling` to override signaling servers.
+
+## Pure Owl Component
+
+```js
+import { TextEditor } from "@base/component";
+```
+
+```base-ui
+<div class="d-flex flex-column gap-4">
+  <TextEditor
+    content="state.html"
+    placeholder="'Write something...'"
+    onChange="(html) => this.onContentChange(html)"
+  />
+
+  <TextEditor
+    content="state.html"
+    collaborative="true"
+    room="'docs/rich-text'"
+    user="{ name: 'Jean', color: '#2563eb' }"
+    onChange="(html) => this.onContentChange(html)"
+  />
+</div>
+```
+
+## Static Component
+
+```html
+<div b-ui="text-editor" b-att-placeholder="Write something...">
+  <template><h1>Draft</h1><p>Edit <strong>rich text</strong> here.</p></template>
+</div>
+```
+
+Enable peer-to-peer collaborative editing with Yjs + y-webrtc:
+
+```html
+<div
+  b-ui="text-editor"
+  b-att-collaborative="true"
+  b-att-room="docs/rich-text"
+  b-att-placeholder="Collaborate here..."
+>
+  <template><p>Shared draft.</p></template>
+</div>
+```
+
+## Options And Attributes
+
+- `b-att-src` / `src` — fetch initial HTML from a remote file.
+- `b-att-content` / `content` — initial HTML content. Static markup can also use a `<template>` or `<script type="text/html">` child.
+- `b-att-placeholder` / `placeholder` — empty-editor hint text.
+- `b-att-collaborative` / `collaborative` — set to `"true"` to connect through Yjs + y-webrtc.
+- `b-att-room` / `room` — y-webrtc room name for collaborative sessions (defaults to `baseui-text-editor`).
+- `b-att-password` / `password` — optional y-webrtc room password.
+- `b-att-signaling` / `signaling` — comma-separated signaling URLs for the static API, or an array prop for Owl.
+
+## Events
+
+- `baseui:text-editor-ready` — fired after ProseMirror mounts (`detail.collaborative`, `detail.room`).
+- `baseui:text-editor-change` — fired whenever the rich-text document emits a new HTML string (`detail.html`, `detail.previousHtml`).
+- `baseui:text-editor-error` — fired when fetching or editor mounting fails (`detail.error`).
+
+## Methods
+
+Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.

package/docs/components/textarea.md

@@ -0,0 +1,58 @@
+# Textarea
+
+Native multiline text input with BaseUI and Bootstrap styling.
+
+## Pure Owl component
+
+```js
+import { Textarea } from "@thebase/ui";
+```
+
+```base-ui
+<div class="d-flex flex-column gap-4" style="max-width: 28rem; width: 100%">
+  <Textarea placeholder="'Type your message here.'"/>
+
+  <div class="d-grid gap-3">
+    <Label htmlFor="'message'">Your message</Label>
+    <Textarea placeholder="'Type your message here.'" id="'message'"/>
+  </div>
+
+  <div class="d-grid gap-3">
+    <Label htmlFor="'message-2'">Your Message</Label>
+    <Textarea placeholder="'Type your message here.'" id="'message-2'"/>
+    <Typography variant="'small'" className="'text-muted'">Your message will be copied to the support team.</Typography>
+  </div>
+
+  <div class="d-grid gap-2">
+    <Textarea placeholder="'Type your message here.'"/>
+    <Button>Send message</Button>
+  </div>
+
+  <Textarea placeholder="'Type your message here.'" disabled="true"/>
+</div>
+```
+
+| Component | Prop | Type | Notes |
+| --- | --- | --- | --- |
+| `Textarea` | `value` | `String` | optional |
+| `Textarea` | `placeholder` | `String` | optional |
+| `Textarea` | `rows` | `Number` | optional |
+| `Textarea` | `disabled` | `Boolean` | optional |
+| `Textarea` | `readonly` | `Boolean` | optional |
+| `Textarea` | `resize` | `String` | optional |
+| `Textarea` | `className` | `String` | optional |
+| `Textarea` | `id` | `String` | optional, e.g. for `Label`'s `for` |
+| `Textarea` | `onInput` | `Function` | optional |
+| `Textarea` | `onChange` | `Function` | optional |
+
+See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+
+## Static component
+
+```base-ui
+<textarea b-ui="textarea" placeholder="Write a note"></textarea>
+```
+
+Options: `b-att-resize="none"`.
+
+Accessibility: pair with a `<label>` and use `aria-describedby` for helper or error text.

package/docs/components/theme-button.md

@@ -0,0 +1,69 @@
+# Theme Button
+
+Use `b-ui="theme-button"` for an icon-only light/dark theme toggle.
+
+## CDN install requirements
+
+Load BaseUI CSS and the BaseUI JavaScript bundle (`baseui.min.js`). The component uses the built-in Lucide icon renderer and the `@base/theme` helper bundled with BaseUI.
+
+## Pure Owl component
+
+```js
+import { ThemeButton } from "@thebase/ui";
+```
+
+```base-ui
+<ThemeButton variant="'outline'" storageKey="'baseui-theme'"/>
+```
+
+| Component | Prop | Type | Notes |
+| --- | --- | --- | --- |
+| `ThemeButton` | `variant` | `"default" \| "outline" \| "ghost" \| "destructive" \| "secondary" \| "link"` | optional, default `"outline"` |
+| `ThemeButton` | `size` | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` | optional |
+| `ThemeButton` | `storageKey` | `String` | optional |
+| `ThemeButton` | `className` | `String` | optional |
+| `ThemeButton` | `onChange` | `Function` | optional |
+
+See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+
+## Static component
+
+```base-ui
+<button b-ui="theme-button" b-att-variant="outline" type="button"></button>
+```
+
+## Enhanced usage
+
+The static bundle mounts initial `b-ui="theme-button"` markup automatically. Call `BaseUI.mount(element)` or `BaseUI.mountAll(root)` only when adding a theme button after the page has loaded. The component updates `b-theme` and `data-bs-theme` on the document root, persists the selected theme, and keeps its icon/ARIA label in sync.
+
+## Options and attributes
+
+Use `b-att-variant="default|outline|ghost|destructive|secondary|link"` and `b-att-size="default|xs|sm|lg|icon|icon-xs|icon-sm|icon-lg"` to match Button variants. Use `b-att-storage-key` when a page needs a custom persistence key.
+
+## Methods
+
+Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`. For direct theme control, import `createThemeController` from `@thebase/ui`.
+
+## Events
+
+Theme changes dispatch `baseui:theme-change` on `document` with `{ theme }` in `event.detail`.
+
+## CSS variables
+
+The component inherits Button and Icon tokens, including `--baseui-radius-lg`, `--baseui-primary`, `--baseui-border`, and `--baseui-icon-size`.
+
+## Accessibility behavior
+
+The visible content is a Lucide moon/sun icon. The button sets `aria-label`, `title`, and `aria-pressed`, and includes a visually hidden label for assistive technologies.
+
+## Examples
+
+See the example page headers for working `b-ui="theme-button"` navigation usage.
+
+## Browser support
+
+BaseUI targets modern evergreen browsers that support ES modules, CSS variables, and Bootstrap 5.3.
+
+## Test checklist
+
+Verify the icon changes from moon to sun, the root theme attributes update, keyboard activation works, and multiple mounted buttons stay synchronized.

package/docs/components/toast.md

@@ -0,0 +1,58 @@
+# Toast
+
+Use `b-ui="toast"` for transient status messages.
+
+## Pure Owl component
+
+```js
+import { Toast } from "@thebase/ui";
+```
+
+```base-ui
+<div style="max-width: 28rem" class="d-flex flex-column align-items-center gap-3 w-100">
+  <Button variant="'outline'" onClick="() => state.open = true">Show Toast</Button>
+  <Toast open="state.open" onOpenChange="(v) => state.open = v" className="'w-100'">
+    <div class="d-flex flex-column">
+      <span class="fw-medium">Event created</span>
+      <span class="text-body-secondary small">Sunday, December 3 at 9:00 AM</span>
+    </div>
+  </Toast>
+</div>
+```
+
+The toast stays hidden until `open`/`state` becomes truthy (never shows on mount) and auto-hides after `delay` ms once shown.
+
+| Component | Prop | Type | Notes |
+| --- | --- | --- | --- |
+| `Toast` | `open` | `Boolean` | optional, default `false` — never shown until set to `true` |
+| `Toast` | `variant` | `String` | optional |
+| `Toast` | `delay` | `Number` | optional, default `3000` — auto-hides after this many ms; pass `0` to disable auto-hide |
+| `Toast` | `className` | `String` | optional |
+| `Toast` | `onOpenChange` | `Function` | optional |
+
+See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+
+## Static component
+
+```base-ui
+<div b-ui="toast">
+  <button b-toast-close type="button">Close</button>
+  Saved successfully.
+</div>
+```
+
+The toast stays hidden until shown — omit `b-att-state="open"` and call `.show()` from a trigger button instead of setting it on mount. It auto-hides after `b-att-delay` ms once shown (default `3000`; set `b-att-delay="0"` to disable auto-hide):
+
+```base-ui
+<div class="d-flex flex-column align-items-center gap-3">
+  <button type="button" class="btn baseui-button btn-outline-secondary" onclick="document.getElementById('demo-toast').BaseUIToast.show()">Show Toast</button>
+  <div id="demo-toast" b-ui="toast" b-att-delay="3000">
+    <button b-toast-close type="button">Close</button>
+    Saved successfully.
+  </div>
+</div>
+```
+
+Programmatic API: after mount, call `element.BaseUIToast.show()` or `element.BaseUIToast.hide()`. Events: `baseui:open`, `baseui:close`.
+
+Toasts are backed by `bootstrap.Toast`: the root receives Bootstrap's `toast fade` classes, and visibility is driven by Bootstrap's own `show`/`showing` classes (not `hidden`). The close button(s) carry `data-bs-dismiss="toast"` in addition to the `b-toast-close`/`baseui-toast-close` selector, so Bootstrap's own delegated dismiss handler drives them.

package/docs/components/toggle-group.md

@@ -0,0 +1,81 @@
+# Toggle Group
+
+Use `b-ui="toggle-group"` for a CDN-ready toggle group component.
+
+## CDN install requirements
+
+Load the pinned BaseUI CSS and JavaScript files; no extra dependency is required for this component.
+
+## Pure Owl component
+
+```js
+import { ToggleGroup, ToggleGroupItem } from "@thebase/ui";
+```
+
+```base-ui
+<div style="max-width: 28rem">
+  <ToggleGroup>
+    <ToggleGroupItem value="'bold'">
+      <Icon name="'bold'" className="'h-4 w-4'"/>
+    </ToggleGroupItem>
+    <ToggleGroupItem value="'italic'">
+      <Icon name="'italic'" className="'h-4 w-4'"/>
+    </ToggleGroupItem>
+    <ToggleGroupItem value="'underline'">
+      <Icon name="'underline'" className="'h-4 w-4'"/>
+    </ToggleGroupItem>
+  </ToggleGroup>
+</div>
+```
+
+| Component | Prop | Type | Notes |
+| --- | --- | --- | --- |
+| `ToggleGroup` | `multiple` | `Boolean` | optional |
+| `ToggleGroup` | `onChange` | `Function` | optional |
+| `ToggleGroup` | `className` | `String` | optional |
+| `ToggleGroupItem` | `value` | `String` | required |
+| `ToggleGroupItem` | `className` | `String` | optional |
+
+See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+
+## Static component
+
+```base-ui
+<div b-ui="toggle-group">Toggle Group</div>
+```
+
+## Enhanced usage
+
+Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+
+## Options and attributes
+
+See `dist/baseui.registry.json` for the supported attribute list.
+
+## Methods
+
+Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+
+## Events
+
+Interactive components emit documented `baseui:*` events from their root element. Static components do not emit events.
+
+## CSS variables
+
+The component inherits BaseUI semantic tokens such as `--baseui-surface`, `--baseui-border`, `--baseui-primary`, and `--baseui-radius`.
+
+## Accessibility behavior
+
+The component preserves authored semantic HTML and adds ARIA roles or state attributes where enhancement is required.
+
+## Examples
+
+See `examples/index.html` for a working CDN-style page.
+
+## Browser support
+
+BaseUI targets modern evergreen browsers that support ES modules, CSS variables, and Bootstrap 5.3.
+
+## Test checklist
+
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.

package/docs/components/toggle.md

@@ -0,0 +1,82 @@
+# Toggle
+
+Use `b-ui="toggle"` for a CDN-ready toggle component.
+
+## CDN install requirements
+
+Load the pinned BaseUI CSS and JavaScript files; no extra dependency is required for this component.
+
+## Pure Owl component
+
+```js
+import { Toggle } from "@thebase/ui";
+```
+
+```base-ui
+<div class="d-flex flex-column gap-4" style="max-width: 28rem">
+  <div class="d-flex align-items-center gap-2">
+    <Toggle>Toggle</Toggle>
+  </div>
+  <div class="d-flex align-items-center gap-2">
+    <Toggle variant="'outline'"><Icon name="'italic'"/></Toggle>
+    <Toggle variant="'outline'"><Icon name="'bold'"/></Toggle>
+  </div>
+  <div class="d-flex align-items-center gap-2">
+    <Toggle><Icon name="'italic'"/> Italic</Toggle>
+  </div>
+  <div class="d-flex align-items-center gap-2">
+    <Toggle className="'disabled'" pressed="false"><Icon name="'italic'"/></Toggle>
+  </div>
+</div>
+```
+
+| Component | Prop | Type | Notes |
+| --- | --- | --- | --- |
+| `Toggle` | `pressed` | `Boolean` | optional |
+| `Toggle` | `variant` | `String` | optional |
+| `Toggle` | `className` | `String` | optional |
+| `Toggle` | `onChange` | `Function` | optional |
+
+See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+
+## Static component
+
+```base-ui
+<div b-ui="toggle">Toggle</div>
+```
+
+## Enhanced usage
+
+Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+
+## Options and attributes
+
+See `dist/baseui.registry.json` for the supported attribute list.
+
+## Methods
+
+Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+
+## Events
+
+Interactive components emit documented `baseui:*` events from their root element. Static components do not emit events.
+
+## CSS variables
+
+The component inherits BaseUI semantic tokens such as `--baseui-surface`, `--baseui-border`, `--baseui-primary`, and `--baseui-radius`.
+
+## Accessibility behavior
+
+The component preserves authored semantic HTML and adds ARIA roles or state attributes where enhancement is required.
+
+## Examples
+
+See `examples/index.html` for a working CDN-style page.
+
+## Browser support
+
+BaseUI targets modern evergreen browsers that support ES modules, CSS variables, and Bootstrap 5.3.
+
+## Test checklist
+
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.

package/docs/components/tooltip.md

@@ -0,0 +1,77 @@
+# Tooltip
+
+Use `b-ui="tooltip"` with either `b-att-content` or a tooltip content child.
+
+## Pure Owl component
+
+```js
+import { Tooltip } from "@thebase/ui";
+```
+
+```base-ui
+<div style="max-width: 28rem" class="w-100 d-flex align-items-center justify-content-center">
+  <Tooltip content="'Add to library'">
+    <t t-set-slot="trigger">
+      <Button variant="'outline'">Hover</Button>
+    </t>
+  </Tooltip>
+</div>
+```
+
+| Component | Prop | Type | Notes |
+| --- | --- | --- | --- |
+| `Tooltip` | `content` | `String` | optional; plain content shortcut, passed directly as the bootstrap `title` |
+| `Tooltip` | `state` | `String` | optional; `"open"`/`"on"`/`"active"` shows the tooltip once on mount (uncontrolled testing hook) |
+| `Tooltip` | `className` | `String` | optional |
+
+See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+
+Both the pure Owl and static forms are driven by a live `bootstrap.Tooltip` instance owned on the trigger element, with `trigger: "hover focus"` — **the visible popup is Bootstrap's own generated DOM (a `.tooltip`/`.tooltip-arrow`/`.tooltip-inner` node, positioned via Popper), appended to `document.body`, not rendered inline where you authored the tooltip.** Don't query for it as a descendant of the trigger; query `document.body.querySelector(".tooltip .tooltip-inner")` instead. Bootstrap sets `aria-describedby` on the trigger itself, but only while the tooltip is actually shown (removed again on hide) — BaseUI does not additionally set a static `aria-describedby` up front.
+
+The default slot's rendered markup is captured into an HTML string for Bootstrap's `title`/`html: true` options (Bootstrap can't consume live vnodes): the pure Owl component renders the slot into a hidden buffer element internal to its own template, reads its `innerHTML` on mount, and re-syncs the live popup via `.setContent({'.tooltip-inner': html})` whenever that HTML changes on a later render.
+
+## Static component
+
+```base-ui
+<span b-ui="tooltip" b-att-content="Helpful tip">
+  <button type="button">?</button>
+</span>
+```
+
+Tooltips show on hover and focus, then hide on mouse leave and blur — Bootstrap's own `trigger: "hover focus"` wires this, not manual event listeners. The static adapter reads `[b-tooltip-content]` (or the element built from `b-att-content`) once at mount time as the tooltip's HTML content, then removes that node from the DOM — Bootstrap owns showing/hiding the content from then on, so no `[b-tooltip-content]` element survives in the authored markup post-mount.
+
+## Enhanced usage
+
+Call `BaseUI.mount(element)` or rely on `BaseUI.mountAll()` after the script loads.
+
+## Options and attributes
+
+See `dist/baseui.registry.json` for the supported attribute list.
+
+## Methods
+
+Use the global runtime methods: `BaseUI.mount()`, `BaseUI.mountAll()`, and `BaseUI.destroy()`.
+
+## Events
+
+Interactive components emit documented `baseui:*` events from their root element. Listen for Bootstrap's own `shown.bs.tooltip`/`hidden.bs.tooltip` on the trigger element to react to show/hide; BaseUI mirrors those into `b-att-state` (`open`/`closed`) on the static root and `this.state.open` on the pure Owl component.
+
+## CSS variables
+
+The component inherits BaseUI semantic tokens such as `--baseui-surface`, `--baseui-border`, `--baseui-primary`, and `--baseui-radius`. The popup itself is styled by Bootstrap's own bundled `.tooltip`/`.tooltip-arrow`/`.tooltip-inner` CSS (loaded via `dist/baseui.min.css`), not BaseUI's own classes.
+
+## Accessibility behavior
+
+The component preserves authored semantic HTML and adds ARIA roles or state attributes where enhancement is required.
+
+## Examples
+
+See `examples/index.html` for a working CDN-style page.
+
+## Browser support
+
+BaseUI targets modern evergreen browsers that support ES modules, CSS variables, and Bootstrap 5.3.
+
+## Test checklist
+
+Verify light and dark themes, keyboard access for focusable controls, disabled or readonly states when applicable, and cleanup through `BaseUI.destroy()`.

package/docs/components/typography.md

@@ -0,0 +1,99 @@
+# Typography
+
+Small text helpers for plain content.
+
+## Pure Owl component
+
+```js
+import { Typography } from "@thebase/ui";
+```
+
+```base-ui
+<div style="max-width: 42rem" class="w-100">
+  <h1 class="fw-semibold display-6 mb-4">Taxing Laughter: The Joke Tax Chronicles</h1>
+  <p class="lh-lg mb-4">
+    Once upon a time, in a far-off land, there was a very lazy king who spent all day
+    lounging on his throne. One day, his advisors came to him with a problem: the
+    kingdom was running out of money.
+  </p>
+  <blockquote class="border-start border-4 ps-3 fst-italic mb-4">
+    "After all," he said, "everyone enjoys a good joke, so it's only fair that they should
+    pay for the privilege."
+  </blockquote>
+  <h2 class="fw-semibold border-bottom pb-2 mb-3 mt-5">The King's Plan</h2>
+  <p class="lh-lg mb-4">
+    The king thought long and hard, and finally came up with
+    <Typography variant="'code'" tag="'span'">a brilliant plan</Typography>: he would
+    tax the jokes in the kingdom.
+  </p>
+  <h3 class="fw-semibold mb-3 mt-5">The Joke Tax</h3>
+  <p class="lh-lg mb-3">
+    The king's subjects were not amused. They grumbled and complained, but the king was
+    firm:
+  </p>
+  <ul class="mb-4">
+    <li>1st level of puns: 5 gold coins</li>
+    <li>2nd level of jokes: 10 gold coins</li>
+    <li>3rd level of one-liners : 20 gold coins</li>
+  </ul>
+  <p class="lh-lg mb-4">
+    As a result, people stopped telling jokes, and the kingdom fell into a gloomy state.
+  </p>
+  <h4 class="fw-semibold mb-3 mt-5">People stopped telling jokes</h4>
+  <div class="table-responsive mb-4">
+    <table class="table table-bordered align-middle mb-0">
+      <thead>
+        <tr>
+          <th>King's Treasury</th>
+          <th>People's happiness</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>Empty</td>
+          <td>Overflowing</td>
+        </tr>
+        <tr>
+          <td>Modest</td>
+          <td>Satisfied</td>
+        </tr>
+        <tr>
+          <td>Full</td>
+          <td>Ecstatic</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+  <Typography variant="'lead'" className="'mb-4'">
+    A modal dialog that interrupts the user with important content and expects a
+    response.
+  </Typography>
+  <p class="mb-4">
+    Type
+    <Typography variant="'code'" tag="'span'">npx create-base-app@latest</Typography>
+    to create a new project.
+  </p>
+  <div class="mb-1">
+    <label class="fw-medium small">Email</label>
+  </div>
+  <Typography variant="'muted'">Enter your email address.</Typography>
+</div>
+```
+
+| Component | Prop | Type | Notes |
+| --- | --- | --- | --- |
+| `Typography` | `variant` | `String` | optional |
+| `Typography` | `className` | `String` | optional |
+
+See [Pure Owl Components](/examples/blocks.html#/docs/guide/owl-components) for how to load `@base/owl` and `dist/baseui.templates.xml`.
+
+## Static component
+
+```base-ui
+<p b-ui="typography" b-att-variant="lead">Readable intro text.</p>
+<span b-ui="typography" b-att-variant="code">baseui</span>
+```
+
+Options: `b-att-variant="body|lead|muted|code|kbd"`.
+
+Accessibility: choose semantic HTML elements first, then add BaseUI typography attributes for styling.