@vanelsas/baredom 2.4.1 → 2.6.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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
+
+- **TypeScript support** — First-class `.d.ts` type declarations auto-generated from component model metadata. Per-component interfaces with typed properties, methods, and `addEventListener` overloads. Custom Elements Manifest (`custom-elements.json`) for IDE support.
+- **Debug mode** — Dev-only visual debugging overlay for all BareDOM components. Activate via `?baredom-debug` URL param or `window.BAREDOM_DEBUG = true`. Shows dashed outlines, tag labels on hover, and a floating inspection panel with live attribute/property editing and structured console logging. Excluded from the production `:lib` build.
+
+### Fixed
+
+- **TypeScript declarations** — Fixed invalid kebab-case identifiers in generated `.d.ts` files. Property names like `max-items` and event detail keys like `press-x` are now correctly output as camelCase (`maxItems`, `pressX`). Affected components: x-breadcrumbs, x-context-menu, x-pagination, x-particle-button.
+
 ## [2.4.1] - 2026-04-28
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="public/assets/baredom_darkmode.svg">
     <source media="(prefers-color-scheme: light)" srcset="public/assets/baredom_lightmode.svg">
-    <img alt="Project Logo" src="public/assets/baredom_lightmode.svg" width="200">
+    <img alt="Project Logo" src="public/assets/baredom_lightmode.svg" width="160">
   </picture>
 </p>
 
@@ -13,6 +13,7 @@
 [![npm version](https://img.shields.io/npm/v/%40vanelsas%2Fbaredom.svg)](https://www.npmjs.com/package/@vanelsas/baredom)
 [![license](https://img.shields.io/npm/l/%40vanelsas%2Fbaredom.svg)](./LICENSE)
 [![ESM](https://img.shields.io/badge/module-ESM-blue.svg)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
+[![TypeScript](https://img.shields.io/badge/types-included-blue.svg)](https://www.typescriptlang.org/)
 [![Custom Elements v1](https://img.shields.io/badge/Custom%20Elements-v1-green.svg)](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)
 
 ---
@@ -63,6 +64,55 @@ I first built the usual suspects for web components, a basis to create a UI. I t
 
 **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
+
+BareDOM includes TypeScript declarations for every component. Types are auto-generated from component metadata and ship alongside the ESM files — no additional setup required.
+
+### What you get
+
+- **Typed element interfaces** extending `HTMLElement` with all properties and methods
+- **Typed custom events** with full `detail` payload types
+- **`HTMLElementTagNameMap` augmentation** so `document.querySelector('x-button')` returns `XButton`
+- **[Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest)** (`custom-elements.json`) for IDE tooling and HTML intellisense
+
+### Usage
+
+```typescript
+import '@vanelsas/baredom/x-button';
+import '@vanelsas/baredom/x-alert';
+
+// querySelector returns typed XButton
+const btn = document.querySelector('x-button')!;
+btn.disabled = true;    // type-checked
+btn.loading = true;     // autocomplete works
+
+// Event listeners have typed detail payloads
+btn.addEventListener('press', (e) => {
+  console.log(e.detail.source);  // string — fully typed
+});
+
+// Custom events on other components
+const alert = document.querySelector('x-alert')!;
+alert.addEventListener('x-alert-dismiss', (e) => {
+  console.log(e.detail.reason);  // string
+  console.log(e.detail.type);    // string
+});
+
+// Components with methods
+import '@vanelsas/baredom/x-modal';
+const modal = document.querySelector('x-modal')!;
+modal.show();   // typed method
+modal.hide();   // typed method
+```
+
+### IDE support
+
+The `custom-elements.json` manifest enables HTML intellisense in editors that support it. For VS Code, install the [Lit Plugin](https://marketplace.visualstudio.com/items?itemName=nicktomlin.vscode-lit-html) or the [Custom Elements Language Server](https://marketplace.visualstudio.com/items?itemName=nicktomlin.vscode-lit-html) to get attribute autocomplete and validation in HTML templates.
+
 ---
 
 ## Theming
@@ -107,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.4.1"}}}
-```
-
-Or in your `shadow-cljs.edn` dependencies:
-
-```clojure
-:dependencies [[com.github.avanelsas/baredom "2.4.1"]]
-```
-
-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.4.1"
-  }
-}
+```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
+BareDOM components are native HTML elements. Import, register, and use them in any framework or vanilla HTML.
 
-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:
-
-```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)
 
 ---
 
@@ -453,7 +300,7 @@ BareDOM compiles to lightweight ES modules. Sizes below are gzipped:
 
 Each component loads `base.js` once plus its own module. A typical page using 5-10 components weighs **40-65 KB** gzipped total.
 
-> **ESM only.** BareDOM ships ES modules exclusively — there is no CommonJS or UMD build. This works natively in all modern browsers and with any bundler that supports ESM (webpack 5+, Vite, esbuild, Rollup, Parcel). If you need server-side rendering, pre-render the HTML and hydrate with component registration on the client.
+> **ESM only.** BareDOM ships ES modules exclusively — there is no CommonJS or UMD build. This works natively in all modern browsers and with any bundler that supports ESM (webpack 5+, Vite, esbuild, Rollup, Parcel). TypeScript declarations (`.d.ts`) are included for every component. If you need server-side rendering, pre-render the HTML and hydrate with component registration on the client.
 
 ---
 
@@ -471,63 +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.
-
----
-
-## 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`.
+## Development
 
-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).
-
-```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.
 
 ---