@vanelsas/baredom 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to BareDOM will be documented in this file.
 
+## [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
+
+- **x-welcome-tour** — Fixed console error caused by `feGaussianBlur` `stdDeviation` attribute receiving a CSS `var()` value instead of a number. SVG filter attributes don't support CSS custom properties.
+
 ## [2.4.0] - 2026-04-27
 
 ### Added

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
@@ -116,13 +166,13 @@ BareDOM can be consumed three ways: as a **ClojureScript source dependency** (Cl
 Add BareDOM to your `deps.edn`:
 
 ```clojure
-{:deps {com.github.avanelsas/baredom {:mvn/version "2.4.0"}}}
+{:deps {com.github.avanelsas/baredom {:mvn/version "2.5.0"}}}
 ```
 
 Or in your `shadow-cljs.edn` dependencies:
 
 ```clojure
-:dependencies [[com.github.avanelsas/baredom "2.4.0"]]
+:dependencies [[com.github.avanelsas/baredom "2.5.0"]]
 ```
 
 Then require component namespaces directly and call their `init!` function once at startup:
@@ -179,7 +229,7 @@ Add the npm package to your `package.json`:
 ```json
 {
   "dependencies": {
-    "@vanelsas/baredom": "^2.4.0"
+    "@vanelsas/baredom": "^2.5.0"
   }
 }
 ```
@@ -453,7 +503,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.
 
 ---
 
@@ -482,6 +532,34 @@ 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