@vanelsas/baredom 3.1.0 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 All notable changes to BareDOM will be documented in this file.
 
+## [3.4.0] - 2026-07-22
+
+The four popup-selection form controls — `x-select`, `x-date-picker`, `x-combobox`, and `x-multi-combobox` — become **real form controls**: they display inline validation errors and participate in native `<form>` submission and constraint validation via `ElementInternals`. Two internal refactors extract the resulting form-control policy into one shared, unit-tested place.
+
+### Added
+
+- **Inline validation errors** on `x-select`, `x-date-picker`, `x-combobox`, `x-multi-combobox` — a new `error` attribute (and matching `error` property) renders a message in an `error` CSS part (an assertive `role="alert"` live region), marks the host `data-invalid`, and sets `aria-invalid` / `aria-describedby` on the control. Inside `x-form` this is driven for you by `form.setFieldError(name, message)`.
+- **Form association** for those four controls — they now attach `ElementInternals`, submit their value under `name` (appearing in `FormData` with no hidden input), honour `required`, expose the `error` attribute as a `customError`, and respond to `form.reset()` and a disabling `<fieldset>`.
+- **Framework adapter form bindings** for the newly form-associated controls: `x-date-picker` gains Vue `v-model` / Angular `ControlValueAccessor` / Svelte `bind:value` / React & Solid controlled `value`; `x-multi-combobox` gains the same with an array (`string[]`) value via new array-aware adapter codegen.
+
+### Changed — behavior changes (please read)
+
+These are bug fixes — the controls advertised `name` / `required` but did not honour them — but they change runtime behavior for anyone already using these four inside a `<form>`:
+
+- **Native form participation.** Placed in a plain `<form>`, these controls now submit their value under `name` and appear in `FormData`. Previously they did not (unless manually wired); a hidden-input workaround for the same `name` will now double-submit.
+- **`required` and `error` now block submission**, and `form.reset()` now clears these fields. Previously `required` was inert and reset skipped them — a form that used to submit with an empty required select/combobox/date-picker will now be gated by `reportValidity()`.
+
+No attributes, properties, or events were removed or renamed; this is otherwise additive.
+
+### Changed — internal
+
+- **`baredom.utils.forms`** (new) — the ElementInternals constraint-validation policy and the inline error-display recipe, previously hand-implemented in each form control, are extracted into one namespace. Both the validity decision and the `aria-describedby` projection are pure functions split from their effects, and are now unit-tested (coverage the effecting versions never had). All six form-associated components (the four above plus `x-form-field`, `x-text-area`) compose the shared validity policy; the four popup controls also compose the shared error display.
+- **`custom-elements.json`** — regenerated to pick up the `error` fields and `x-search-field`'s `debounce` field that had drifted out of the committed manifest.
+
+### Notes
+
+- Adapter packages are versioned independently. This release ships alongside `react@2.2.0`, `angular@2.8.0`, `vue@0.2.0`, `svelte@0.2.0`, `solid@0.2.0` — each a minor bump carrying the new form bindings. See [`docs/RELEASING.md`](docs/RELEASING.md).
+
+## [3.3.0] - 2026-05-26
+
+Three new framework adapters ship alongside the existing React and Angular adapters: **Vue 3**, **Svelte 5**, and **SolidJS** are now officially supported. BareDOM users of every major JS framework can now install a typed wrapper package that adds framework-idiomatic props, events, and ref handling on top of the same underlying web components.
+
+The core library itself is functionally unchanged from 3.2.0 — `dist/` is byte-identical. This release ships an updated `README.md` (and an additional `CHANGELOG.md` entry) so the npm-registry view reflects the now-complete five-adapter ecosystem.
+
+### Added — framework adapters
+
+- **`@vanelsas/baredom-vue`** — Vue 3.4+ wrapper components. v-model bridging via the shared `form-control-metadata` single-source-of-truth, typed events, ref forwarding through `expose()`. Install: `npm install @vanelsas/baredom-vue`.
+- **`@vanelsas/baredom-svelte`** — Svelte 5+ wrapper components. `$bindable()` for form controls, `$effect()` for event binding, per-component `.svelte` + `.ts` shim files for named exports. Install: `npm install @vanelsas/baredom-svelte`.
+- **`@vanelsas/baredom-solid`** — Solid 1.9+ wrapper components. Function components with `splitProps`, `onMount`, `onCleanup`, `createEffect`. JSX is preserved for the consumer's Solid bundler. Install: `npm install @vanelsas/baredom-solid`.
+
+All three adapters auto-generate one typed component per BareDOM custom element (103 components total). Per-component bundles, controlled-input support via Vue v-model / Svelte `$bindable()` / Solid signals, typed `CustomEvent` payloads — all driven by the same Custom Elements Manifest that already powered the React and Angular adapters.
+
+### Changed
+
+- **`README.md`** — Restructured for the five-adapter era. New "Framework adapters" comparison table. "Why web components?" and "Design Principles" sections merged into a single "Why BareDOM?". Theming section trimmed (full guide lives in [`docs/x-theme.md`](docs/x-theme.md)). Quick-start replaced with a working HTML example. New top-level "Time-Travel Debugger" section surfacing [`x-trace-history`](docs/x-trace-history.md) — previously buried inside a value-prop bullet.
+- **[`docs/components.md`](docs/components.md)** — Full per-component catalogue (103 components across 11 categories) split out from the README. The previous README listed only 58 of the 103 components; the kinetics, organic, effects, and scroll clusters are now properly catalogued.
+- **`scripts/codegen_shared.bb`** (new) — Shared codegen module housing `resolve-event-name`, `prop-type->ts`, and `event-detail->ts`, previously copy-pasted across all four adapter generators (~270 lines of duplication eliminated). React's `controlled-components` map now derives from `scripts/form-control-metadata.bb`, closing a silent drift trap for new form controls.
+- **`CLAUDE.md`** — Registration checklist for new components now requires updating both `docs/components.md` and the `README.md` Components overview.
+- **CI** — New `.github/workflows/release-solid.yml` matching the per-adapter release pattern. [`docs/RELEASING.md`](docs/RELEASING.md) extended to cover the per-adapter release process and first-publish `NPM_TOKEN` permission considerations.
+
+### Fixed — adapter bugs
+
+- **`@vanelsas/baredom-angular`** — `x-select` CVA used the wrong change-event name. Shipped via PR #242.
+- **`@vanelsas/baredom-vue`** — Vue-reserved prop names (`key`, `ref`, `is`) were silently dropped by Vue. Reserved props are now renamed in the generated wrapper (e.g. `keyAttr`) and the underlying attribute is written imperatively. Shipped via PR #243.
+
+### Notes
+
+- Adapter packages are versioned independently and live at `@vanelsas/baredom-{react,angular,vue,svelte,solid}`. See [`docs/RELEASING.md`](docs/RELEASING.md) for the per-adapter release process.
+- The five published adapter versions at the time of this release: `react@2.1.0`, `angular@2.7.0`, `vue@0.1.0`, `svelte@0.1.0`, `solid@0.1.0`.
+
+## [3.2.0] - 2026-05-22
+
+Five new components, an element-highlight feature for the `x-trace-history` dev tool, two notable bug fixes, and an internal naming-consistency cleanup.
+
+### Added
+
+- **x-split-pane** — Resizable two-panel layout. A draggable divider re-proportions a `start` and an `end` panel along a horizontal or vertical axis. The divider position is a percentage held in the `position` attribute — the single source of truth — so layouts are fully serialisable and the component stays stateless. Nest panes for three or more panels.
+- **x-code** — Code-display component. Reads source code from its own light-DOM text content, tokenizes it with a built-in syntax highlighter, and renders a themable code block with optional line numbers, soft-wrapping, a header bar with a copy button, and a collapsible long-snippet mode.
+- **x-calendar** — Standalone, always-visible inline month calendar — a companion to `x-date-picker`. Supports single-date and date-range selection, localized weekday/month names, configurable first-day-of-week, a month/year quick-jump header, and an optional ISO week-number column. Dates are ISO 8601 strings.
+- **x-range-slider** — Dual-handle, form-associated, accessible range slider. Two draggable thumbs select a numeric `[start, end]` sub-range within `[min, max]`.
+- **x-rating** — Discrete, form-associated, accessible star-rating component. A row of star (or heart) icons selects a numeric rating, optionally in half-star increments; `readonly` mode displays an average rating such as `3.5`.
+- **`x-trace-history` element highlight** — Selecting a record in the dock now outlines the live web component that emitted it with a magenta accent overlay. The outline tracks the target through scroll/resize, smoothly scrolls offscreen targets into view (respecting `prefers-reduced-motion`), and clears when selection clears, when the dock unmounts, or when the originating element has been disconnected since the record was emitted. `document`-tag records produce no outline. The highlight machinery emits zero trace records, and the dock remains opt-in via `?baredom-trace-history` — never shipped in production.
+
+### Fixed
+
+- **x-card** — Interactive cards declared in HTML with an observed attribute set at upgrade time silently never installed their listeners, so `<x-card interactive>` never responded to clicks. `connected!`'s install guard conflated refs-init with listener-install; the install epoch now lives on its own `k-installed` field, gated independently of refs init.
+- **x-modal** — `x-modal-toggle` was dispatched on every connect because the open-transition epoch started at `nil` and always differed from the initial open state. The toggle decision is now folded into the main render-pipeline epoch and gated on `(some? old-m)`.
+
+### Changed
+
+- **Shared date utilities** — Date math extracted into a shared `baredom.utils.dates` namespace, consumed by `x-calendar` and `x-date-picker`.
+- **Internal naming consistency** — The top-level model transformer was renamed from `derive-state` to `normalize` across 23 component model layers and their tests, so every component uses the same name. No behaviour change.
+- **Dead-code removal** — Write-only instance fields (set but never read) removed from x-combobox, x-multi-combobox, x-welcome-tour, x-spotlight-card, x-stat, x-tab, and x-tabs.
+- **`x-trace-history` highlight refactor** — `apply-highlight!` decomposed into a phase-list dispatcher per the `render-orchestrator` pattern; `reposition!` now clears the stale cached component id when the target has been disconnected; the reduced-motion probe caches the live `MediaQueryList` instead of re-invoking `matchMedia` on every show.
+- **Angular adapter** — `@vanelsas/baredom-angular` dev dependencies bumped from Angular 17 to 21; `custom-elements.json` refreshed.
+- **CI** — `check_method_api.bb` taught about the `define-method!` helper introduced by the x-modal refactor, so wrapped method installations are no longer flagged as "declared but not installed".
+
 ## [3.1.0] - 2026-05-16
 
 A full-library audit cycle against the `x-icon` golden sample (PRs #222–#231). All 99 components now conform to the Hickey-level architecture standard documented in `CLAUDE.md`. No public API or behavioural changes.

package/README.md

@@ -40,221 +40,122 @@ All components can be explored in the [live demo](https://avanelsas.github.io/ba
 
 ## Why BareDOM?
 
-Like most Clojure/ClojureScript developers starting out with UIs, I went through the common phases of using Reagent and Re-frame—which are great utilities in their own right. However, as my UIs became larger and more complex, bundle sizes increased, and I found myself spending too much time rebuilding generic, reusable components from scratch.
-
-I started looking for a different approach and discovered Web Components. I built a few, but didn't have the spare time to develop a comprehensive set that could be used in any project. Then AI arrived. While experimenting with Claude Code, I realised that 1 + 1 could be 3. That is how BareDOM, my first open-source project, was born.
-
-I first built the usual suspects for web components, a basis to create a UI. I then thought about trying something more exciting, with animations, shapes, colours, and a whole range of web components that deal with morphing, kinetics and organic styles were born. I hope it brings you joy when using them in your web application!
-
-# Why web components?
-
-**Works in any stack.** Because components are native HTML elements, they work wherever HTML works — vanilla JavaScript, React, Vue, Svelte, Angular, server-rendered HTML, or a static page. No adapter layer, no wrapper library.
-
-**No framework lock-in.** Your components are not tied to the framework you are building with today. Migrate your app, keep your components.
-
-**Tree-shakeable by design.** Each component is a separate ES module. Import only what you use; bundle tools eliminate the rest automatically.
+**Works in any stack.** Components are native HTML elements — they work wherever HTML works (vanilla JS, React, Vue, Svelte, Angular, server-rendered HTML, static pages). Your components are not tied to the framework you build with today; migrate your app, keep your components.
 
-**Full theming with CSS custom properties.** Every visual detail — colours, spacing, radius, shadows, typography — is exposed as a `--x-<component>-<property>` CSS custom property. Override at any scope: globally, per-page, per-instance. Use [`<x-theme>`](./docs/x-theme.md) for centralised theming with built-in presets.
+**Stateless.** Every render is a pure function of attributes and properties — no hidden state, no signals, no virtual DOM. Inspect attributes in DevTools and you see the truth. (And when you need deeper traces, BareDOM ships a time-travel debugger — see below.)
 
-**Light and dark mode included.** All components adapt automatically to `prefers-color-scheme`. No JavaScript required, no class toggling.
+**Zero runtime, tree-shakeable.** Each component is a self-contained ES module compiled with Google Closure Advanced. The only JavaScript in your bundle is the components you import — no framework, no utility belt, no runtime library.
 
-**Accessibility built in.** ARIA roles, live regions, keyboard navigation, focus management, and `prefers-reduced-motion` support are part of the component, not an afterthought. You do not need to layer accessibility on top.
+**Predictable theming.** Every visual detail is exposed as a `--x-<component>-<property>` CSS custom property — override at any scope, or wrap in [`<x-theme>`](./docs/x-theme.md) for coordinated palettes with built-in presets. Light/dark mode adapts automatically via `prefers-color-scheme`.
 
-**Mobile-ready.** All components are tested on viewports from 320px up. Overlay panels cap their width to avoid overflow. Touch targets meet the 44px minimum on coarse-pointer devices. Pointer events are used throughout for unified mouse and touch input.
+**Accessible & mobile-first.** ARIA roles, keyboard navigation, focus management, and `prefers-reduced-motion` support are part of every component. All components are tested on viewports from 320px up; touch targets meet the 44px minimum on coarse-pointer devices, and pointer events handle mouse + touch uniformly.
 
 **Open Shadow DOM.** Shadow roots are `mode: "open"` — inspectable in DevTools, styleable via `::part()`, and testable with standard DOM APIs.
 
-**First-class TypeScript support.** Every component ships with auto-generated `.d.ts` type declarations and a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest). TypeScript consumers get typed element interfaces, typed custom events with detail payloads, and `HTMLElementTagNameMap` augmentation for `querySelector` type narrowing — all without installing a separate `@types` package.
+**TypeScript + Custom Elements Manifest.** Auto-generated `.d.ts` declarations ship with every component: typed element interfaces, typed custom events with detail payloads, and `HTMLElementTagNameMap` augmentation for `querySelector` narrowing. A standards-based [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) drives Storybook, VS Code Custom Data, and the BareDOM framework adapters themselves — if you build tooling on top of BareDOM, the manifest is the source of truth.
 
 ---
 
-## BareForge — Visual Page Builder
-
-[![GitHub](https://img.shields.io/github/stars/avanelsas/bareforge?style=social)](https://github.com/avanelsas/bareforge)
-
-[BareForge](https://github.com/avanelsas/bareforge) is a companion visual landing-page builder for BareDOM. Drag-and-drop BareDOM components onto a canvas, configure them in the inspector, and export a complete project.
-
-- **Drag-and-drop canvas** with snap-aware placement
-- **Inspector** with type-aware editors for every BareDOM component
-- **Theme editor** with all 8 BareDOM presets and per-token overrides
-- **Four export modes** — CDN, bundle, ClojureScript, and JavaScript
+## Installation
 
-Try the [live editor](https://avanelsas.github.io/bareforge/) or see the [repository](https://github.com/avanelsas/bareforge) for details.
+```bash
+npm install @vanelsas/baredom
+```
 
----
+Also available via [Clojars](./docs/installation.md#clojurescript-via-clojars) and [standalone ES modules](./docs/installation.md#vanilla-htmljs-via-es-modules). See the [full installation guide](./docs/installation.md).
 
-## Theming
+### Quick start
 
-Wrap any subtree in `<x-theme>` to apply a consistent palette across all components:
+A minimal page that renders a themed button and alert — no build step required:
 
 ```html
 <x-theme preset="ocean">
-  <x-button>Themed button</x-button>
-  <x-alert type="info" text="Themed alert"></x-alert>
+  <x-button>Click me</x-button>
+  <x-alert type="info" text="It works!"></x-alert>
 </x-theme>
+<script type="module">
+  import { init as initTheme }  from '@vanelsas/baredom/x-theme';
+  import { init as initButton } from '@vanelsas/baredom/x-button';
+  import { init as initAlert }  from '@vanelsas/baredom/x-alert';
+  initTheme(); initButton(); initAlert();
+</script>
 ```
 
-Ships with **8 built-in presets**: `default`, `ocean`, `forest`, `sunset`, `neo-brutalist`, `aurora`, `mono-ai`, `warm-mineral`. All presets include both light and dark mode values that work with `prefers-color-scheme`.
-
-For custom themes, register your own preset via JavaScript:
-
-```js
-import { registerPreset } from '@vanelsas/baredom/x-theme';
+For deeper usage by stack, see the [JavaScript Developer Guide](./docs/javascript-guide.md), [TypeScript Guide](./docs/typescript.md), or [ClojureScript Guide](./docs/clojurescript-guide.md).
 
-registerPreset('acme', {
-  light: { '--x-color-primary': '#e11d48', '--x-color-surface': '#fff' },
-  dark:  { '--x-color-primary': '#fb7185', '--x-color-surface': '#1a1a2e' }
-});
-```
+---
 
-```html
-<x-theme preset="acme">...</x-theme>
-```
+## Framework adapters
 
-Or override individual tokens via CSS:
+BareDOM components are native HTML elements — they work natively in any framework, with no adapter required. The published adapters below add typed props, typed custom events, and framework-idiomatic ergonomics on top of the same underlying components.
 
-```html
-<x-theme preset="default" style="--x-color-primary: #e11d48;">
-  ...
-</x-theme>
-```
+| Framework | Package | Minimum version | Docs |
+|-----------|---------|-----------------|------|
+| React 19+   | `@vanelsas/baredom-react`   | 2.6.0 | [README](./adapters/react/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-react) |
+| Vue 3.4+    | `@vanelsas/baredom-vue`     | 2.6.0 | [README](./adapters/vue/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-vue) |
+| Angular 17+ | `@vanelsas/baredom-angular` | 2.6.0 | [README](./adapters/angular/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-angular) |
+| Svelte 5+   | `@vanelsas/baredom-svelte`  | 2.6.0 | [README](./adapters/svelte/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-svelte) |
+| Solid 1.9+  | `@vanelsas/baredom-solid`   | 2.6.0 | [README](./adapters/solid/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-solid) |
 
-See [docs/x-theme.md](./docs/x-theme.md) for the full token list, preset details, and API reference.
+All adapters are auto-generated from the same Custom Elements Manifest, so adding a new BareDOM component updates every adapter in lockstep.
 
 ---
 
-## Installation
+## Components
 
-```bash
-npm install @vanelsas/baredom
-```
+**103 UI web components across 11 categories** — from foundational UI controls to morphing animations, organic effects, and scroll-driven storytelling.
 
-```js
-import { init } from '@vanelsas/baredom/x-button';
-init();
-```
+| Category | Count | Examples |
+|----------|------:|----------|
+| **Form**       | 23 | Button · Checkbox · Slider · Combobox · OTP Input · Color Picker |
+| **Feedback**   | 11 | Alert · Toast · Spinner · Progress · Skeleton · Notification Center |
+| **Navigation** | 8  | Navbar · Sidebar · Breadcrumbs · Tabs · Pagination · Menu |
+| **Layout**     | 10 | Card · Grid · Bento Grid · Split Pane · Container · Collapse |
+| **Data**       | 11 | Avatar · Table · Chart · Timeline · Calendar · Stat |
+| **Overlay**    | 9  | Modal · Drawer · Popover · Tooltip · Welcome Tour · Command Palette |
+| **Display**    | 6  | Icon · Image · Typography · Code · Kbd · Spotlight Card |
+| **Animation**  | 6  | Kinetic Canvas · Kinetic Typography · Morph Stack · Soft Body · Splash |
+| **Effects**    | 12 | Liquid Glass · Confetti · Neural Glow · Metaball Cursor · Organic Shape |
+| **Scroll**     | 5  | Scroll · Scroll Parallax · Scroll Stack · Scroll Story · Scroll Timeline |
+| **Utility**    | 2  | i18n · i18n Provider |
 
-Also available via [Clojars](./docs/installation.md#clojurescript-via-clojars) and [standalone ES modules](./docs/installation.md#vanilla-htmljs-via-es-modules). See the [full installation guide](./docs/installation.md).
+See [**docs/components.md**](./docs/components.md) for the full per-component catalogue with one-line descriptions and links to each component's API documentation.
 
 ---
 
-## Usage
+## Time-Travel Debugger
 
-BareDOM components are native HTML elements. Import, register, and use them in any framework or vanilla HTML.
+[`x-trace-history`](./docs/x-trace-history.md) is BareDOM's dev-only debugger. It records every CustomEvent dispatch, observed attribute change, instance-field write, and lifecycle callback as a navigable timeline with cause→effect navigation — so when a bug appears, you can step back to the exact event that caused it.
 
-- **JavaScript / TypeScript** — see the [JavaScript Developer Guide](./docs/javascript-guide.md)
-- **TypeScript types** — see the [TypeScript Guide](./docs/typescript.md)
-- **ClojureScript** — see the [ClojureScript Guide](./docs/clojurescript-guide.md)
-- **React** — see [`@vanelsas/baredom-react`](https://www.npmjs.com/package/@vanelsas/baredom-react)
-- **Angular** — see [`@vanelsas/baredom-angular`](https://www.npmjs.com/package/@vanelsas/baredom-angular)
+- **Zero production cost.** When inactive, the recorder pays a single nil-check per hook site and no per-event overhead.
+- **One-line activation.** `import "@vanelsas/baredom/x-trace-history"` and append `?baredom-trace-history` to the URL — a floating dock attaches to the viewport.
+- **Bug-share via URL.** Record a session, copy the URL, and the recipient sees the same timeline.
+- **Adapter-aware.** Works alongside the React, Vue, Angular, Svelte, and Solid adapters.
 
----
+See [`docs/x-trace-history.md`](./docs/x-trace-history.md) for the full guide — search, console API, recording sessions, import/export, and the JSON schema.
 
-## Components
+---
 
-### Form (17)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-button>`](./docs/x-button.md) | Action control. Variants: `primary`, `secondary`, `tertiary`, `ghost`, `danger`. Sizes: `sm`, `md`, `lg`. States: `disabled`, `loading`, `pressed`. Icon slots. |
-| [`<x-checkbox>`](./docs/x-checkbox.md) | Boolean input. Reflects `checked` and `indeterminate` states to attributes. |
-| [`<x-color-picker>`](./docs/x-color-picker.md) | Colour picker with 2D saturation/brightness area, hue strip, optional alpha, preset swatches, eyedropper, and clipboard copy. Inline or popover mode. |
-| [`<x-copy>`](./docs/x-copy.md) | Copy-to-clipboard utility button with success feedback. |
-| [`<x-currency-field>`](./docs/x-currency-field.md) | Formatted currency input with locale-aware masking. |
-| [`<x-date-picker>`](./docs/x-date-picker.md) | Calendar-based date selection with keyboard navigation. |
-| [`<x-fieldset>`](./docs/x-fieldset.md) | Groups related form controls with a styled legend. |
-| [`<x-file-download>`](./docs/x-file-download.md) | Download trigger that initiates a file transfer. |
-| [`<x-form>`](./docs/x-form.md) | Form wrapper with coordinated validation state. |
-| [`<x-form-field>`](./docs/x-form-field.md) | Label + input wrapper with error and hint text slots. |
-| [`<x-radio>`](./docs/x-radio.md) | Single-choice input within a radio group. |
-| [`<x-search-field>`](./docs/x-search-field.md) | Search input with integrated clear button and search icon. |
-| [`<x-select>`](./docs/x-select.md) | Dropdown select control with custom styling. |
-| [`<x-slider>`](./docs/x-slider.md) | Range slider with step, min/max, and value display. |
-| [`<x-stepper>`](./docs/x-stepper.md) | Multi-step form progress indicator with navigation. |
-| [`<x-switch>`](./docs/x-switch.md) | Toggle switch for boolean settings. |
-| [`<x-text-area>`](./docs/x-text-area.md) | Multi-line text input with auto-resize option. |
-
-### Feedback (10)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-alert>`](./docs/x-alert.md) | Semantic alert banner. Types: `info`, `success`, `warning`, `error`. Auto-dismiss with `timeout-ms`. Fires `x-alert-dismiss`. |
-| [`<x-badge>`](./docs/x-badge.md) | Small inline label for counts, states, and categories. |
-| [`<x-chip>`](./docs/x-chip.md) | Compact tag component, optionally removable. |
-| [`<x-notification-center>`](./docs/x-notification-center.md) | Notification hub for aggregating and managing in-app notifications. |
-| [`<x-progress>`](./docs/x-progress.md) | Linear progress bar with determinate and indeterminate modes. |
-| [`<x-progress-circle>`](./docs/x-progress-circle.md) | Circular progress indicator for compact spaces. |
-| [`<x-skeleton>`](./docs/x-skeleton.md) | Animated loading placeholder that mirrors content shape. |
-| [`<x-spinner>`](./docs/x-spinner.md) | Inline loading spinner with size and colour variants. |
-| [`<x-toast>`](./docs/x-toast.md) | Single transient notification with enter/exit animations and auto-dismiss. |
-| [`<x-toaster>`](./docs/x-toaster.md) | Toast manager. Positions a queue of `<x-toast>` elements, enforces `max-toasts`, and fires `x-toaster-dismiss`. |
-
-### Navigation (8)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-breadcrumbs>`](./docs/x-breadcrumbs.md) | Hierarchical path trail with separator customisation. |
-| [`<x-menu>`](./docs/x-menu.md) | Vertical menu container coordinating `<x-menu-item>` children. |
-| [`<x-menu-item>`](./docs/x-menu-item.md) | Individual menu entry with icon, label, description, and keyboard support. |
-| [`<x-navbar>`](./docs/x-navbar.md) | Top navigation bar with responsive slot layout. |
-| [`<x-pagination>`](./docs/x-pagination.md) | Page navigation controls with first/previous/next/last and page-size selection. |
-| [`<x-sidebar>`](./docs/x-sidebar.md) | Collapsible side navigation panel with collapse/expand animation. |
-| [`<x-tab>`](./docs/x-tab.md) | Individual tab within an `<x-tabs>` container. |
-| [`<x-tabs>`](./docs/x-tabs.md) | Tab container that coordinates `<x-tab>` children, manages active state, and fires change events. |
-
-### Layout (6)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-card>`](./docs/x-card.md) | Surface container. Variants: `elevated`, `outlined`, `filled`, `ghost`. Interactive mode available. |
-| [`<x-collapse>`](./docs/x-collapse.md) | Expandable/collapsible section with animated height transition. |
-| [`<x-container>`](./docs/x-container.md) | Responsive max-width container with configurable padding. |
-| [`<x-divider>`](./docs/x-divider.md) | Horizontal or vertical visual separator. |
-| [`<x-grid>`](./docs/x-grid.md) | CSS Grid layout component with responsive column configuration. |
-| [`<x-spacer>`](./docs/x-spacer.md) | Flexible spacing element for flexbox and grid layouts. |
-
-### Data (10)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-avatar>`](./docs/x-avatar.md) | User photo or initials display. Shape, size, and status dot variants. |
-| [`<x-avatar-group>`](./docs/x-avatar-group.md) | Overlapping avatar stack for representing multiple users. |
-| [`<x-carousel>`](./docs/x-carousel.md) | Accessible carousel with swipe/drag, arrows, dot indicators, autoplay, slide/fade transitions, and horizontal/vertical orientation. |
-| [`<x-chart>`](./docs/x-chart.md) | Data visualisation component for common chart types. |
-| [`<x-stat>`](./docs/x-stat.md) | KPI / metric card with value, label, trend, and icon slots. |
-| [`<x-table>`](./docs/x-table.md) | Data grid using CSS subgrid. Supports sorting, single/multi-select, striping, and accessible captions. |
-| [`<x-table-cell>`](./docs/x-table-cell.md) | Table cell for header and data modes, with sort indicator and alignment control. |
-| [`<x-table-row>`](./docs/x-table-row.md) | Table row with interactive selection and `x-table-row-select` event. |
-| [`<x-timeline>`](./docs/x-timeline.md) | Vertical timeline container that coordinates `<x-timeline-item>` children. |
-| [`<x-timeline-item>`](./docs/x-timeline-item.md) | Individual timeline event with time, icon, heading, and body slots. |
-
-### Overlay (7)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-cancel-dialogue>`](./docs/x-cancel-dialogue.md) | Confirmation modal for destructive cancel actions. |
-| [`<x-command-palette>`](./docs/x-command-palette.md) | Keyboard-accessible global search and command interface. |
-| [`<x-context-menu>`](./docs/x-context-menu.md) | Right-click / long-press contextual action menu. |
-| [`<x-drawer>`](./docs/x-drawer.md) | Off-canvas sliding panel, configurable from any edge. |
-| [`<x-dropdown>`](./docs/x-dropdown.md) | Positioned dropdown container for menus and selection. |
-| [`<x-modal>`](./docs/x-modal.md) | Centred dialog with backdrop, focus trap, and `Escape` to close. |
-| [`<x-popover>`](./docs/x-popover.md) | Anchored popover for tooltips, help text, and contextual UI. |
+## Theming
 
----
+Wrap any subtree in `<x-theme>` to apply a coordinated palette across every BareDOM component inside it. Eight presets ship in the box — `default`, `ocean`, `forest`, `sunset`, `neo-brutalist`, `aurora`, `mono-ai`, `warm-mineral` — each with light and dark variants that follow `prefers-color-scheme`.
 
-## Design Principles
+Register your own preset, override individual tokens via CSS, or nest themes for per-section palettes. See [`docs/x-theme.md`](./docs/x-theme.md) for the full API (presets, `registerPreset`, CSS overrides) and [`docs/THEMING.md`](./docs/THEMING.md) for the token catalogue.
 
-**Stateless.** No `atom`, no signal, no reactive state container lives inside a component. Every render is a pure function of the current attributes and properties. Debugging a component means inspecting attributes in DevTools — no hidden state to hunt for. For deeper investigations, the optional [`x-trace-history`](./docs/x-trace-history.md) dev tool ships as a separate ESM module and records every dispatch, attribute change, and lifecycle callback as a navigable timeline with cause→effect chains. Load it with `<script type="module" src="…/x-trace-history.js">` and activate via `?baredom-trace-history`; zero cost when the flag is absent.
+---
 
-**Standards-only.** BareDOM relies on Custom Elements v1, Shadow DOM v1, and ES modules — all natively supported in modern browsers. There are no polyfills required and no proprietary APIs to learn.
+## BareForge — Visual Page Builder
 
-**Zero runtime dependency.** Components are compiled to self-contained ES modules. The only JavaScript in your bundle is the component itself. No framework, no runtime library, no utility belt.
+[![GitHub](https://img.shields.io/github/stars/avanelsas/bareforge?style=social)](https://github.com/avanelsas/bareforge)
 
-**Accessible by default.** ARIA roles, live regions, keyboard interaction patterns, focus indicators, and `prefers-reduced-motion` support are written into every component that needs them — not optional add-ons.
+[BareForge](https://github.com/avanelsas/bareforge) is a companion visual landing-page builder for BareDOM. Drag-and-drop BareDOM components onto a canvas, configure them in the inspector, and export a complete project.
 
-**Predictable theming.** CSS custom properties follow a single naming convention: `--x-<component>-<property>`. Tokens are set on `:host` and cascade normally. You override them the same way you override any CSS property.
+- **Drag-and-drop canvas** with snap-aware placement
+- **Inspector** with type-aware editors for every BareDOM component
+- **Theme editor** with all 8 BareDOM presets and per-token overrides
+- **Four export modes** — CDN, bundle, ClojureScript, and JavaScript
 
-**Mobile-first.** Components use `dvh` viewport units, `calc(100vw - ...)` width caps, and `@media (pointer:coarse)` rules for touch-friendly sizing. No component overflows on a 320px screen.
+Try the [live editor](https://avanelsas.github.io/bareforge/) or see the [repository](https://github.com/avanelsas/bareforge) for details.
 
 ---
 
@@ -295,6 +196,16 @@ See the [development guide](./docs/development.md) for setting up the dev server
 
 ---
 
+## About
+
+Like most Clojure/ClojureScript developers starting out with UIs, I went through the common phases of using Reagent and Re-frame—which are great utilities in their own right. However, as my UIs became larger and more complex, bundle sizes increased, and I found myself spending too much time rebuilding generic, reusable components from scratch.
+
+I started looking for a different approach and discovered Web Components. I built a few, but didn't have the spare time to develop a comprehensive set that could be used in any project. Then AI arrived. While experimenting with Claude Code, I realised that 1 + 1 could be 3. That is how BareDOM, my first open-source project, was born.
+
+I first built the usual suspects for web components, a basis to create a UI. I then thought about trying something more exciting, with animations, shapes, colours, and a whole range of web components that deal with morphing, kinetics and organic styles were born. I hope it brings you joy when using them in your web application!
+
+---
+
 ## License
 
 MIT