@vanelsas/baredom 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to BareDOM will be documented in this file.
 
+## [2.6.0] - 2026-04-30
+
+### Added
+
+- **Cancelable change-request events** — Seven input components now fire a cancelable `change-request` event before applying user-initiated value changes. Call `preventDefault()` to block the update (enables controlled component patterns in framework adapters). Components: x-slider, x-text-area, x-select, x-combobox, x-currency-field, x-tabs, x-pagination.
+
+### Fixed
+
+- **x-context-menu** — Escape key and click-outside now correctly dismiss the menu. Handlers moved from the overlay layer (which has `pointer-events: none`) to document-level listeners.
+- **x-button** — Fixed missing press events on mobile Safari. Added `touch-action: manipulation` and `-webkit-tap-highlight-color: transparent` to the internal button element (reset by `all: unset`).
+- **x-carousel demo** — Control panel now uses correct BareDOM event names (`x-switch-change`, `x-form-field-input`, `select-change`, `press`) instead of native DOM events.
+- **x-welcome-tour test** — Added missing `^js` type hint to fix Closure Advanced compilation warning.
+- **x-combobox** — Fixed undefined category in demo gallery (changed from `"input"` to `"form"`).
+
 ## [2.5.0] - 2026-04-29
 
 ### Added

package/README.md

@@ -157,228 +157,25 @@ See [docs/x-theme.md](./docs/x-theme.md) for the full token list, preset details
 
 ## Installation
 
-> **Using JavaScript?** See the [JavaScript Developer Guide](./docs/javascript-guide.md) for npm/ESM setup, event handling, theming, and framework integration examples (React, Vue, Svelte).
-
-BareDOM can be consumed three ways: as a **ClojureScript source dependency** (Clojars), as **standalone ES module files** (no build tool required), or as an **npm package**.
-
-### Option A — ClojureScript via Clojars
-
-Add BareDOM to your `deps.edn`:
-
-```clojure
-{:deps {com.github.avanelsas/baredom {:mvn/version "2.5.0"}}}
-```
-
-Or in your `shadow-cljs.edn` dependencies:
-
-```clojure
-:dependencies [[com.github.avanelsas/baredom "2.5.0"]]
-```
-
-Then require component namespaces directly and call their `init!` function once at startup:
-
-```clojure
-(ns my-app.core
-  (:require
-   [baredom.exports.x-button  :as x-button]
-   [baredom.exports.x-alert   :as x-alert]
-   [baredom.exports.x-toaster :as x-toaster]
-   [baredom.exports.x-toast   :as x-toast]))
-
-(defn- register-components! []
-  (x-button/init)
-  (x-alert/init)
-  (x-toaster/init)
-  (x-toast/init))
-```
-
-Call `register-components!` once in your `init!` entry point. Registration is idempotent — calling `init` on an already-registered element is a no-op.
-
-### Option B — Vanilla HTML/JS via ES modules
-
-No build tool, no npm, no ClojureScript required. Copy the `dist/` folder (from a release or after running `npm run build`) to your web server and load components directly with `<script type="module">`:
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>BareDOM Example</title>
-</head>
-<body>
-  <x-button variant="primary">Click me</x-button>
-  <x-alert type="success" text="It works!"></x-alert>
-
-  <script type="module">
-    import { init as initButton } from './dist/x-button.js';
-    import { init as initAlert }  from './dist/x-alert.js';
-
-    initButton();
-    initAlert();
-  </script>
-</body>
-</html>
-```
-
-Each component is a separate ES module. Import only the components you use — the browser loads only those files plus the shared `base.js` runtime.
-
-### Option C — npm
-
-Add the npm package to your `package.json`:
-
-```json
-{
-  "dependencies": {
-    "@vanelsas/baredom": "^2.5.0"
-  }
-}
+```bash
+npm install @vanelsas/baredom
 ```
 
-Then `npm install`. shadow-cljs resolves npm packages automatically via `node_modules`. From ClojureScript:
-
-```clojure
-(ns my-app.core
-  (:require
-   ["@vanelsas/baredom/x-button"  :as x-button]
-   ["@vanelsas/baredom/x-alert"   :as x-alert]
-   ["@vanelsas/baredom/x-toaster" :as x-toaster]
-   ["@vanelsas/baredom/x-toast"   :as x-toast]))
-
-(defn- register-components! []
-  (.init x-button)
-  (.init x-alert)
-  (.init x-toaster)
-  (.init x-toast))
+```js
+import { init } from '@vanelsas/baredom/x-button';
+init();
 ```
 
-Call `register-components!` once in your `init!` entry point. Registration is idempotent — calling `.init` on an already-registered element is a no-op.
+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).
 
 ---
 
 ## Usage
 
-### 1. Register components
-
-Whichever installation method you chose above, the pattern is the same: require/import each component you need and call its `init` function once before any rendering. Only the components you register are active on the page.
-
-### 2. Add a renderer
-
-BareDOM components are plain DOM elements. You need no framework to use them — only a small renderer that turns ClojureScript hiccup vectors into DOM nodes and keeps them in sync with your state.
-
-The `bare-demo/` project includes a complete renderer (~120 lines) with DOM reconciliation that you can copy into any ClojureScript project. See [`bare-demo/src/bare_demo/renderer.cljs`](./bare-demo/src/bare_demo/renderer.cljs). No Node.js required — just Java and the Clojure CLI.
-
-What the renderer provides:
-
-- **Hiccup syntax** — describe UI as nested vectors: `[:tag {:attr val} children]`
-- **Prop handling** — `:on-*` keys become event listeners; `true`/`false` toggle boolean attributes; everything else calls `setAttribute`
-- **DOM reconciliation** — on re-render, the existing DOM is patched in place. Elements are never destroyed and recreated, so Web Components keep their lifecycle, shadow DOM, focus state, and animations intact.
-- **`mount!`** — renders the view and attaches `add-watch` to a state atom so every `swap!` triggers a reconciliation pass
-
-### 3. Write views with hiccup syntax
-
-Views are plain ClojureScript functions that return nested vectors. The first element of each vector is a keyword matching the element tag name. An optional map of props follows, then children.
-
-```clojure
-;; String and number attributes
-[:x-button {:variant "primary"} "Save changes"]
-[:x-button {:variant "secondary" :size "sm"} "Cancel"]
-
-;; Boolean attributes — true sets the attribute, false/nil removes it
-[:x-button {:variant "danger" :disabled true} "Delete"]
-[:x-button {:variant "primary" :loading true} "Saving…"]
-[:x-checkbox {:checked true}]
-[:x-checkbox {:indeterminate true}]
-
-;; Nesting
-[:x-grid {:columns "2" :gap "md"}
- [:x-card "First card"]
- [:x-card "Second card"]]
-
-[:x-grid {:columns "4" :gap "md"}
- [:x-stat {:label "Revenue" :value "$48,295" :trend "up" :variant "positive"}]
- [:x-stat {:label "Users"   :value "12,483"  :trend "up"}]
- [:x-stat {:label "Orders"  :value "1,429"   :trend "neutral"}]
- [:x-stat {:label "Churn"   :value "2.4%"    :trend "down" :variant "danger"}]]
-
-;; Slots — use the :slot attribute to target named slots
-[:x-navbar {:label "My App"}
- [:span {:slot "brand" :style "font-weight:700"} "My App"]
- [:div  {:slot "actions"}
-  [:x-button {:variant "ghost" :size "sm"} "Sign out"]]]
-```
-
-### 4. Handle events and manage state
-
-Event listeners are declared inline using `:on-<event-name>` keys. The key is stripped of `on-` and the remainder becomes the event name passed to `addEventListener`. Custom component events follow the same pattern — use the full event name after `on-`.
-
-```clojure
-(defonce app-state (atom {:active-tab "overview"
-                          :sidebar-collapsed false}))
-
-;; Standard DOM event
-[:x-button
- {:variant  "ghost"
-  :on-click (fn [_] (swap! app-state update :sidebar-collapsed not))}
- "Toggle sidebar"]
-
-;; Custom component event — :on-value-change listens for "value-change"
-[:x-tabs
- {:value           (:active-tab @app-state)
-  :on-value-change (fn [e]
-                     (swap! app-state assoc
-                            :active-tab (.. e -detail -value)))}
- [:x-tab {:value "overview"}   "Overview"]
- [:x-tab {:value "components"} "Components"]
- [:x-tab {:value "settings"}   "Settings"]]
-
-;; Custom event with detail payload
-[:x-alert
- {:type "success" :text "Changes saved." :dismissible true
-  :on-x-alert-dismiss (fn [e]
-                        (js/console.log "dismissed by:" (.. e -detail -reason)))}]
-
-;; Sidebar with open/collapse state
-[:x-sidebar
- {:open      (:sidebar-open @app-state)
-  :collapsed (:sidebar-collapsed @app-state)
-  :placement "left"
-  :on-toggle (fn [e]
-               (swap! app-state assoc :sidebar-open (.. e -detail -open)))}
- ;; ... nav items ...
- ]
-```
-
-Wire everything together in your `init!`:
-
-```clojure
-(defn view []
-  [:x-container {:size "xl" :padding "lg"}
-   ;; ... your UI built from component vectors ...
-   ])
-
-(defn init! []
-  (register-components!)
-  (renderer/mount! (.getElementById js/document "app") view app-state))
-```
-
-`mount!` calls `view` immediately and re-calls it on every `swap!` or `reset!` to `app-state`. On each re-render the reconciler diffs the new hiccup tree against the live DOM and applies only the changes needed — attribute updates, text changes, children added or removed. Existing elements stay in place.
-
-### Theming
-
-Override CSS custom properties at any scope:
+BareDOM components are native HTML elements. Import, register, and use them in any framework or vanilla HTML.
 
-```css
-/* Global overrides */
-:root {
-  --x-button-radius: 4px;
-  --x-alert-radius:  8px;
-}
-
-/* Per-instance override */
-#sidebar-save-btn {
-  --x-button-bg-primary: #0a5c99;
-}
-```
+- **JavaScript / TypeScript** — see the [JavaScript Developer Guide](./docs/javascript-guide.md)
+- **ClojureScript** — see the [ClojureScript Guide](./docs/clojurescript-guide.md)
 
 ---
 
@@ -521,91 +318,9 @@ No polyfills are included or required for these targets.
 
 ---
 
-## Component Demo
-
-BareDOM ships with a built-in demo that lets you browse and interact with every component in isolation. It is intended for developer convenience when working on the library itself.
-
-```bash
-npm install
-npx shadow-cljs watch app
-```
-
-Then open `http://localhost:8000`. The dev server serves `public/index.html` and hot-reloads on every source change. Each component is demonstrated in its own section with controls for toggling attributes, properties, and variants.
-
-### Debug Mode
-
-BareDOM includes a visual debug overlay for development. It highlights every component on the page, shows tag names on hover, and lets you inspect and edit live state — no browser extension required.
-
-**Activate** by adding `?baredom-debug` to any dev URL:
-
-```
-http://localhost:8000?baredom-debug
-```
-
-Or toggle from the browser console at any time:
-
-```js
-window.BAREDOM_DEBUG = true
-```
-
-When active, debug mode provides:
-
-- **Dashed blue outlines** around every BareDOM component
-- **Tag labels** that appear on hover (top-right corner)
-- **Inspection panel** — click a label to see current attributes, properties, and computed state
-- **Inline editing** — toggle boolean attributes with a switch, edit string/number values and press Enter to apply
-- **Console logging** — structured `console.group` output on every attribute change, lifecycle events at `console.debug` level
-
-Changes made through the debug panel are live but ephemeral — they modify the DOM directly and do not survive a page refresh.
-
-Debug mode is dev-only and is excluded from the production ESM build (`npm run build`).
-
----
-
-## bare-demo — starter template for ClojureScript web apps
-
-The `bare-demo/` folder is a ready-to-use ClojureScript application that consumes BareDOM components with **zero framework dependency and no Node.js**. It is designed as a starting point for developers building new web apps on top of BareDOM.
-
-The architecture is built on three ideas:
-
-- **Declarative hiccup views.** UI is described as nested ClojureScript vectors — the same syntax used by Reagent and Hiccup. Views are plain functions, easy to compose and reason about.
-- **A single state atom with reactive rendering.** All UI state lives in one `defonce` atom. `mount!` attaches `add-watch` so every `swap!` triggers a re-render automatically.
-- **DOM reconciliation, not rebuild.** On state changes the renderer patches the existing DOM in place — updating attributes, text, and children without destroying elements. Web Components keep their lifecycle, shadow DOM, focus state, and animations intact.
-
-This approach scales naturally: add more state, more views, more components — no manual wiring, no framework overhead, no impedance mismatch with the Web Component model.
-
-**Run it:**
-
-```bash
-cd bare-demo
-clj -M:dev
-```
-
-Then open `http://localhost:8001`.
-
-See [`bare-demo/README.md`](./bare-demo/README.md) for a full walkthrough of the renderer, component registration, view syntax, state management, and theming.
-
-> **Prefer NPM?** The `bare-node-demo/` folder contains the same demo consuming BareDOM via npm. Run it with `cd bare-node-demo && npm install && npm start` (opens on `http://localhost:8003`).
-
----
-
-## Building from Source
-
-BareDOM is authored in ClojureScript and compiled with [shadow-cljs](https://shadow-cljs.github.io/docs/UsersGuide.html).
+## Development
 
-```bash
-# Install dependencies
-npm install
-
-# Start development server with hot reload (http://localhost:8000)
-npx shadow-cljs watch app
-
-# Run browser-based tests (http://localhost:8021)
-npx shadow-cljs watch test
-
-# Build production ESM library to dist/
-npm run build
-```
+See the [development guide](./docs/development.md) for setting up the dev server, using [debug mode](./docs/development.md#debug-mode), and building from source.
 
 ---
 

package/custom-elements.json

@@ -2749,6 +2749,11 @@
         }
       } ],
       "events" : [ {
+        "name" : "x-slider-change-request",
+        "type" : {
+          "text" : "CustomEvent"
+        }
+      }, {
         "name" : "x-slider-input",
         "type" : {
           "text" : "CustomEvent"
@@ -2987,7 +2992,12 @@
         }
       } ],
       "events" : [ {
-        "name" : ":page-change",
+        "name" : "page-change-request",
+        "type" : {
+          "text" : "CustomEvent"
+        }
+      }, {
+        "name" : "page-change",
         "type" : {
           "text" : "CustomEvent"
         }
@@ -3112,6 +3122,11 @@
         }
       } ],
       "events" : [ {
+        "name" : "value-change-request",
+        "type" : {
+          "text" : "CustomEvent"
+        }
+      }, {
         "name" : "value-change",
         "type" : {
           "text" : "CustomEvent"
@@ -4630,6 +4645,11 @@
         }
       } ],
       "events" : [ {
+        "name" : "x-combobox-change-request",
+        "type" : {
+          "text" : "CustomEvent"
+        }
+      }, {
         "name" : "x-combobox-change",
         "type" : {
           "text" : "CustomEvent"
@@ -4728,6 +4748,11 @@
         }
       } ],
       "events" : [ {
+        "name" : "x-text-area-change-request",
+        "type" : {
+          "text" : "CustomEvent"
+        }
+      }, {
         "name" : "x-text-area-input",
         "type" : {
           "text" : "CustomEvent"
@@ -5902,6 +5927,11 @@
         }
       } ],
       "events" : [ {
+        "name" : "x-select-change-request",
+        "type" : {
+          "text" : "CustomEvent"
+        }
+      }, {
         "name" : "select-change",
         "type" : {
           "text" : "CustomEvent"
@@ -7126,6 +7156,11 @@
         }
       } ],
       "events" : [ {
+        "name" : "x-currency-field-change-request",
+        "type" : {
+          "text" : "CustomEvent"
+        }
+      }, {
         "name" : "x-currency-field-input",
         "type" : {
           "text" : "CustomEvent"