jj 3.0.0-rc.4 → 3.0.0-rc.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jj",
-    "version": "3.0.0-rc.4",
+    "version": "3.0.0-rc.5",
     "description": "A minimal DOM manipulation library with web components",
     "keywords": [
         "javascript",
@@ -28,7 +28,7 @@
     },
     "files": [
         "lib",
-        "SKILL.md"
+        "skills"
     ],
     "scripts": {
         "fmt": "prettier --write .",

package/skills/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: jj
+description: Expert guide for the JJ DOM manipulation library. Load this skill whenever you need to write, debug, or review JJ code; create native web components using JJ's defineComponent, setShadow, fetchTemplate, or fetchStyle; translate React, Vue, Svelte, Angular, jQuery, or Lit patterns to JJ idioms; work with JJHE, JJD, JJSE, JJME, JJDF, JJSR, JJET, JJN, or JJT wrappers; or write JJ tests with jsdom. If any JJ class name or helper function appears in the conversation, always load this skill.
+---
+
+# JJ DOM Library
+
+JJ is a minimal, zero-dependency TypeScript library that wraps browser DOM interfaces in fluent, type-safe classes. It complements native browser APIs rather than replacing them.
+
+## Wrapper Hierarchy
+
+Each JJ wrapper exposes the native node via `.ref`.
+
+| Class | Wraps            | Key additions                                          |
+| ----- | ---------------- | ------------------------------------------------------ |
+| JJET  | EventTarget      | `.on()`, `.off()`, `.trigger()`, `.run()`              |
+| JJN   | Node             | `.getParent()`, `.getChildren()`, `.rm()`, `.clone()`  |
+| JJD   | Document         | `.find()`, `.findAll()`                                |
+| JJDF  | DocumentFragment | `.addTemplate()`, `.setTemplate()`, batch child ops    |
+| JJE   | Element          | Attributes, classes, ARIA, visibility, HTML write      |
+| JJHE  | HTMLElement      | `.setText()`, `.setStyle()`, `.setShadow()`, `.tree()` |
+| JJSE  | SVGElement       | SVG namespace factory                                  |
+| JJME  | MathMLElement    | MathML namespace factory                               |
+| JJSR  | ShadowRoot       | `.find()`, `.findAll()`, `.addStyle()`, `.init()`      |
+| JJDF  | DocumentFragment | Fragment operations                                    |
+| JJT   | Text             | `.getText()`, `.setText()`                             |
+
+## Type-Safe Creation — Always Use Factory Methods
+
+```typescript
+// ✅ CORRECT — factory methods infer the precise generic type
+const div = JJHE.create('div') // JJHE<HTMLDivElement>
+const input = JJHE.create('input') // JJHE<HTMLInputElement>
+const svg = JJSE.create('svg') // JJSE<SVGSVGElement>
+const math = JJME.create('math') // JJME<MathMLElement>
+const frag = JJDF.create() // JJDF
+const btn = JJHE.fromId('my-btn') // JJHE<HTMLButtonElement>
+
+// ❌ WRONG
+JJHE.create('svg') // throws — use JJSE.create('svg')
+new JJHE(element) // don't call constructors directly
+```
+
+## Chaining
+
+All mutating methods return `this`. Chain as much as possible; access `.ref` only when a wrapper method does not exist.
+
+```typescript
+const btn = JJHE.create('button')
+    .addClass('btn', 'primary')
+    .setText('Save')
+    .setAttr('type', 'submit')
+    .setAriaAttr('label', 'Save changes')
+    .on('click', handleSave)
+```
+
+## Document Queries
+
+Wrap `document` with `JJD.from(document)` before querying.
+
+```typescript
+const doc = JJD.from(document)
+const app = doc.find('#app', true) // throws when absent
+const card = doc.find('.card') // null when absent
+const items = doc.findAll('.item') // always an array
+
+// Inside a custom element's shadow root
+const btn = this.getShadow(true).find('#submit')
+```
+
+## Attributes, Classes, Styles
+
+```typescript
+// Attribute — singular
+el.setAttr('role', 'button')
+el.getAttr('role')
+el.rmAttr('hidden')
+el.swAttr('disabled', !isReady) // sets disabled="" or removes it
+
+// Attribute — batch (null/undefined skipped)
+el.setAttrs({ type: 'text', placeholder: 'Search…' })
+
+// Classes
+el.addClass('active')
+el.addClasses(['chip', 'selected'])
+el.rmClass('disabled')
+el.rmClasses(['pending', 'loading'])
+el.swClass('expanded', isExpanded) // explicit: adds when truthy, removes when falsy
+el.swClass('is-active') // auto: flips current state (adds if absent, removes if present)
+el.swAttr('disabled', !isReady) // explicit: sets disabled="" or removes it
+el.swAttr('readonly') // auto: flips current state
+el.setClasses({ active: isActive, disabled: !isReady })
+el.setClass('card card--featured') // replaces entire className
+
+// Dataset
+el.getDataAttr('userId')
+el.hasDataAttr('userId')
+el.setDataAttr('userId', '42')
+el.setDataAttrs({ role: 'admin', team: 'ui' })
+el.rmDataAttr('userId')
+el.rmDataAttrs(['role', 'team'])
+
+// ARIA
+el.getAriaAttr('hidden')
+el.hasAriaAttr('hidden')
+el.setAriaAttr('hidden', 'true')
+el.setAriaAttrs({ label: 'Dialog', modal: 'true' })
+el.rmAriaAttr('hidden')
+
+// ARIA is not presence-based like HTML boolean attributes
+// Use explicit string states instead of swAttr()
+el.setAriaAttr('disabled', 'true')
+
+// Inline styles
+el.setStyle('color', 'var(--color-brand)')
+el.setStyles({ color: 'red', padding: '8px', border: null })
+el.rmStyle('color', 'padding')
+```
+
+## Security — HTML Writes
+
+Prefer `.setText()` for any user-supplied content. `.setHTML()` requires an explicit `true` flag when the string is non-empty.
+
+```typescript
+el.setText(userInput) // ✅ always safe
+el.setHTML('<p>Trusted markup</p>', true) // ✅ explicit opt-in
+el.setHTML('') // ✅ clearing is allowed without flag
+el.setHTML('<p>content</p>') // ❌ THROWS — missing unsafe flag
+el.ref.innerHTML = '…' // ❌ bypasses guard — avoid
+```
+
+## Events
+
+```typescript
+// Native events
+el.on('click', handler)
+el.off('click', handler)
+el.trigger('click')
+
+// Explicit event objects (equivalent to JJ helpers below)
+el.trigger(new Event('click', { bubbles: true, composed: true }))
+el.trigger(new CustomEvent('todo-toggle', { detail: { id: 1, done: true }, bubbles: true, composed: true }))
+
+// Custom events — JJ defaults: bubbles: true, composed: true
+this.dispatchEvent(new CustomEvent('todo-toggle', { detail: { id: 1, done: true }, bubbles: true, composed: true }))
+
+// Fluent dispatch (same defaults)
+el.triggerEvent('click') // equivalent to trigger(new Event('click', { bubbles: true, composed: true }))
+JJHE.from(this).triggerCustomEvent('todo-toggle', { id: 1, done: true })
+// equivalent to trigger(new CustomEvent('todo-toggle', { detail: { id: 1, done: true }, bubbles: true, composed: true }))
+
+// Override defaults for internal-only events
+new CustomEvent('panel-ready', { bubbles: false, composed: false })
+```
+
+## Custom Elements — Complete Pattern
+
+Fetch template and style at **module scope** — loaded once, shared across all instances.
+
+```typescript
+import { attr2prop, defineComponent, fetchStyle, fetchTemplate, JJHE } from 'jj'
+
+const templatePromise = fetchTemplate(import.meta.resolve('./my-card.html'))
+const stylePromise = fetchStyle(import.meta.resolve('./my-card.css'))
+
+export class MyCard extends HTMLElement {
+    static observedAttributes = ['user-name', 'count']
+    static defined = defineComponent('my-card', MyCard)
+
+    #userName = ''
+    #count = 0
+    #root = null // JJSR wrapper; attached in constructor
+    #isInitialized = false
+
+    constructor() {
+        super()
+        this.#root = JJHE.from(this).setShadow('open').getShadow(true)
+    }
+
+    attributeChangedCallback(name, oldValue, newValue) {
+        // Converts kebab-case → camelCase, then calls the matching setter
+        attr2prop(this, name, oldValue, newValue)
+    }
+
+    get userName() {
+        return this.#userName
+    }
+    set userName(v) {
+        this.#userName = String(v ?? '')
+        this.#render()
+    }
+
+    get count() {
+        return this.#count
+    }
+    set count(v) {
+        this.#count = Number(v) || 0
+        this.#render()
+    }
+
+    async connectedCallback() {
+        if (!this.#isInitialized) {
+            this.#root.init(await templatePromise, await stylePromise)
+            this.#isInitialized = true
+        }
+        this.#render()
+    }
+
+    #render() {
+        if (!this.#root) return // guard for attribute changes before mount
+        this.#root.find('[data-role="name"]')?.setText(this.#userName)
+        this.#root.find('[data-role="count"]')?.setText(String(this.#count))
+    }
+}
+
+// Caller must await before using the custom element tag
+await MyCard.defined
+// Or multiple in parallel
+await Promise.all([MyCard.defined, OtherCard.defined])
+```
+
+`defineComponent()` returns `Promise<boolean>`:
+
+- `false` — newly defined by this call
+- `true` — already defined with the same constructor
+
+## Tree Builder
+
+`JJHE.tree` is a factory for declarative element trees. Alias as `h` for brevity.
+
+```typescript
+const h = JJHE.tree
+
+const card = h(
+    'article',
+    { class: 'card' },
+    h('h2', null, title),
+    h('p', { class: 'body' }, description),
+    h('footer', null, h('a', { href: url }, 'Read more')),
+)
+```
+
+## Children and Templates
+
+```typescript
+// Clear children — internally uses replaceChildren()
+el.empty()
+
+// Replace all children in one call (prefer over .empty().addChild())
+el.setChild(newChild)
+el.setChildren([childA, childB])
+el.setChildMap(items, (item) => JJHE.tree('li', null, item.label))
+el.setTemplate(templateElement)
+
+// Append
+el.addChild(child)
+el.addChildMap(items, (item) => JJHE.tree('li', null, item.label))
+el.addTemplate(await templatePromise) // clones before appending
+```
+
+`addChild` / `preChild` / `setChild` and map variants ignore `null`/`undefined`; all other non-node values are coerced to Text nodes.
+
+## Node Traversal
+
+```typescript
+const parent = el.getParent() // wrapped parent or null (detached)
+const children = el.getChildren() // wrapped child array (always an array)
+el.rm() // detach from parent (no-op if already detached)
+const ancestor = el.closest('[data-section]') // null if not found
+```
+
+## Resource Loaders
+
+```typescript
+import { JJHE, fetchStyle, fetchTemplate } from 'jj'
+
+const h = JJHE.tree
+
+// Hint browser to preload early with native <link>
+document.head.append(
+    h('link', {
+        href: import.meta.resolve('./bundle.js'),
+        rel: 'modulepreload',
+    }).ref,
+)
+document.head.append(
+    h('link', {
+        href: import.meta.resolve('./main.css'),
+        rel: 'preload',
+        as: 'style',
+    }).ref,
+)
+
+// Load a CSSStyleSheet for adoptedStyleSheets or setShadow
+const sheet = await fetchStyle(import.meta.resolve('./theme.css'))
+document.adoptedStyleSheets = [sheet]
+
+// Load a DocumentFragment for addTemplate / setShadow
+const fragment = await fetchTemplate(import.meta.resolve('./dialog.html'))
+```
+
+## String Casing
+
+String case-conversion helpers are internal implementation details.
+Use higher-level public APIs like `attr2prop` and `defineComponent` instead of importing low-level casing utilities.
+
+## Common mistakes
+
+1. **`.ts` extension in imports** — TypeScript source must use `.js` (`import { X } from './X.js'`).
+2. **`JJHE.create('svg')`** — throws; use `JJSE.create('svg')`.
+3. **`el.setHTML(html)` without `true`** — throws when html is non-empty.
+4. **Fetching template/style inside `connectedCallback`** — fetch at module scope so the network request is shared.
+5. **Not awaiting `Element.defined`** — markup may be parsed before the element is defined, causing flaky upgrades.
+6. **Breaking the chain with `.ref` unnecessarily** — use wrapper methods first; reach for `.ref` only when no wrapper method exists.
+
+## Pitfall Prevention Rules (Component Work)
+
+Apply these rules whenever building or refactoring JJ-based custom elements:
+
+1. **Template-first component UI** — if component markup is static, use `fetchTemplate` + `setTemplate` (or shadow `init`) rather than building the UI imperatively in JS.
+2. **Keep routing/URL state outside UI components** — query params and history updates belong in page/controller code, not in reusable visual components.
+3. **Query with wrappers, not native DOM first** — prefer `find` / `findAll` on JJ wrappers before dropping to `.ref`.
+4. **Do not unwrap and re-wrap** — avoid `find(...).ref` followed by `JJHE.from(...)`; keep the wrapper value.
+5. **Use specific selectors for required nodes** — prefer selectors like `button#save` and `progress#step-progress` so selector intent replaces manual `instanceof` checks.
+6. **Keep one canonical state-update path** — for state like `step`, centralize validation/clamping/render/event dispatch in one code path; avoid split setter/private-method duplication unless clearly justified.
+7. **Use one initialization invariant** — if `isInitialized` exists and guarantees bound refs are ready, guard on that flag instead of repeating null checks for every bound field.
+8. **Prefer fluent assignment when binding handlers** — in setup code, chain `.on(...)` directly on `find(...)` where readable (for example assigning a button wrapper and click handler in one line).
+
+## Reference Docs
+
+For framework migration or deep-dive patterns, load these on demand:
+
+- `references/react-to-jj-translation.md`
+- `references/vue-to-jj-translation.md`
+- `references/svelte-to-jj-translation.md`
+- `references/angular-to-jj-translation.md`
+- `references/jquery-to-jj-translation.md`
+- `references/lit-to-jj-translation.md`
+- `references/web-components-patterns.md`
+- `references/eventing-patterns.md`
+- `references/querying-patterns.md`
+- `references/css-improvements.md`
+- `references/testing-with-jsdom.md`
+- `references/security-and-html.md`
+- `references/error-handling-patterns.md`

package/skills/references/angular-to-jj-translation.md

@@ -0,0 +1,76 @@
+# Angular to JJ Translation
+
+Angular uses a DI-driven component architecture with templates and decorators. JJ is library-level, not framework-level.
+
+## Mental mapping
+
+| Angular concept              | JJ equivalent                                                   |
+| ---------------------------- | --------------------------------------------------------------- |
+| `@Component` template        | `JJHE.tree()` or external HTML with `fetchTemplate`             |
+| `@Input()`                   | `observedAttributes` + `attr2prop` + property setter            |
+| `@Output()` / `EventEmitter` | `triggerCustomEvent()` dispatching a `CustomEvent`              |
+| `ngOnInit`                   | `connectedCallback`                                             |
+| `ngOnDestroy`                | `disconnectedCallback`                                          |
+| `ChangeDetectionRef`         | Explicit render call in property setters                        |
+| `*ngFor`                     | `el.addChildMap(items, fn)`                                     |
+| `*ngIf`                      | `el.hide()` / `el.show()` or conditional class via `setClasses` |
+| DI services                  | Plain ES modules exporting shared state or event buses          |
+
+## Input binding example
+
+Angular:
+
+```typescript
+@Input() userName: string = ''
+```
+
+JJ:
+
+```js
+static observedAttributes = ['user-name']
+attributeChangedCallback(name, oldValue, newValue) {
+    attr2prop(this, name, oldValue, newValue)
+}
+get userName() { return this.#userName }
+set userName(v) { this.#userName = String(v ?? ''); this.#render() }
+```
+
+## Output binding example
+
+Angular:
+
+```typescript
+@Output() selected = new EventEmitter<string>()
+this.selected.emit(itemId)
+```
+
+JJ:
+
+```js
+JJHE.from(this).triggerCustomEvent('selected', itemId)
+// JJ default: bubbles: true, composed: true — parent receives through shadow boundary
+```
+
+## No DI — use ES modules instead
+
+Angular service:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+class AuthService { … }
+```
+
+JJ — just a module:
+
+```js
+// auth.js
+export const authState = { user: null }
+export function login(user) {
+    authState.user = user
+}
+```
+
+## Browser references
+
+- Custom element lifecycle: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
+- ES Modules: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules

package/skills/references/css-improvements.md

@@ -0,0 +1,91 @@
+# CSS Improvements
+
+Use JJ for DOM wiring and rely on CSS standards for the styling system.
+
+## JJ style helpers with examples
+
+```js
+// Single property
+el.setStyle('color', 'var(--color-brand)')
+el.setStyle('padding', '8px 16px')
+
+// Batch — null/false removes the property
+el.setStyles({
+    color: 'red',
+    padding: '8px',
+    border: null, // removes border
+    background: false, // removes background
+})
+
+// Remove properties
+el.rmStyle('color', 'padding')
+
+// Read a property
+const val = el.getStyle('color') // '' when not set
+```
+
+## Class-driven styling (preferred)
+
+Modify classes and keep visual logic in CSS:
+
+```js
+el.addClass('is-active')
+el.rmClass('is-loading')
+el.swClass('is-expanded', isExpanded) // explicit: condition drives add/remove
+el.swClass('is-expanded') // auto: flips current state
+el.setClasses({ 'is-active': isActive, 'is-error': hasError })
+el.setClass('card card--featured') // replaces entire className
+```
+
+## Text direction and advanced DOM state
+
+```js
+el.setAttr('dir', 'rtl')
+el.setAttr('lang', 'ar')
+```
+
+## CSS custom properties pierce Shadow DOM
+
+Custom properties cascade through shadow boundaries. Define variables on the host or `:root`:
+
+```css
+:root {
+    --btn-color: #0070f3;
+}
+```
+
+Inside shadow styles:
+
+```css
+button {
+    background: var(--btn-color);
+}
+```
+
+## Loading stylesheets
+
+```js
+import { JJHE, fetchStyle } from 'jj'
+
+const h = JJHE.tree
+
+// Hint browser to start loading early
+document.head.addChild(
+    h('link', {
+        href: import.meta.resolve('./theme.css'),
+        rel: 'preload',
+        as: 'style',
+    }).ref,
+)
+
+// Load as a CSSStyleSheet for adoptedStyleSheets
+const sheet = await fetchStyle(import.meta.resolve('./theme.css'))
+document.adoptedStyleSheets = [sheet]
+```
+
+## Browser references
+
+- CSSStyleDeclaration: https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration
+- CSS nesting: https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Nesting
+- CSS custom properties: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
+- adoptedStyleSheets: https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets

package/skills/references/error-handling-patterns.md

@@ -0,0 +1,79 @@
+# Error Handling Patterns
+
+JJ follows four principles for errors: specific, actionable, proximate, and runtime-verified.
+
+## Principles
+
+1. **Specific** — Use the most precise error type: `TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`.
+2. **Actionable** — Include a fix hint when the stack trace alone is insufficient.
+3. **Proximate** — Throw where the invalid value is _consumed_, not where it is received.
+4. **Runtime-verified** — Don't rely on TypeScript types alone; validate at library boundaries because callers may be plain JavaScript.
+
+## Internal helpers
+
+```typescript
+import { typeErr, errMsg } from './internal.js'
+
+// TypeError with standardized message
+throw typeErr('name', 'a string', name)
+//   → TypeError: Expected name to be a string, but got number
+
+// RangeError using errMsg for the message
+throw new RangeError(
+    errMsg('as', "'fetch', 'style', or 'script'", as, 'Use a valid value or omit it to auto-detect from the URL.'),
+)
+
+// With extra fix hint when context is ambiguous
+throw typeErr('ref', 'a Text node', ref, "Create a Text node with JJT.create() or document.createTextNode('text').")
+```
+
+`errMsg(varName, expected, received, extra?)` — generates the standard message string.  
+`typeErr(varName, expected, received, extra?)` — creates and returns a `TypeError` using that message.
+
+## When to add an `extra` hint
+
+Add it when:
+
+- The API has overloads and the caller might not know which to use.
+- The wrapper constructor / factory method accepts multiple input forms.
+- The correct alternative is not obvious from the stack trace.
+
+Skip it when:
+
+- The failure is a simple scalar type check and the stack trace already pinpoints the misuse.
+
+## Practical validation example
+
+```typescript
+if (!isStr(name)) {
+    throw typeErr('name', 'a string', name)
+}
+if (!isObj(attrs)) {
+    throw typeErr(
+        'attrs',
+        'a plain object or null/undefined',
+        attrs,
+        'Pass an object like { class: "btn" } or omit the argument.',
+    )
+}
+if (val < 0 || val > 100) {
+    throw new RangeError(errMsg('val', 'a number between 0 and 100', val))
+}
+```
+
+## Error types reference
+
+| Error type       | When to use                                       |
+| ---------------- | ------------------------------------------------- |
+| `TypeError`      | Wrong type or shape                               |
+| `RangeError`     | Value out of acceptable range                     |
+| `SyntaxError`    | Malformed string input (selector, expression)     |
+| `ReferenceError` | Reference to undefined name                       |
+| `AggregateError` | Multiple simultaneous failures (e.g., map-reduce) |
+
+## Browser references
+
+- TypeError: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError
+- RangeError: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError
+- SyntaxError: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError
+- AggregateError: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError

package/skills/references/eventing-patterns.md

@@ -0,0 +1,78 @@
+# Eventing Patterns
+
+## Native event listeners
+
+```js
+el.on('click', handler) // addEventListener
+el.off('click', handler) // removeEventListener (same function reference)
+el.trigger('click') // dispatchEvent(new Event('click'))
+```
+
+The handler `this` inside `.on()` is bound to the JJ wrapper instance. Use `this.ref` to access the native element:
+
+```js
+btn.on('click', function () {
+    // this → the JJHE wrapper
+    // this.ref → the HTMLButtonElement
+    console.log(this.ref.textContent)
+})
+```
+
+## Custom events with payloads
+
+`trigger()` accepts a full event object. JJ also provides two convenience constructors that keep dispatch fluent:
+
+- `triggerEvent(name, options?)` is equivalent to `trigger(new Event(name, { bubbles: true, composed: true, ...options }))`
+- `triggerCustomEvent(name, detail?, options?)` is equivalent to `trigger(new CustomEvent(name, { bubbles: true, composed: true, ...options, detail }))`
+
+Use the native `CustomEvent` constructor when dispatching directly:
+
+```js
+this.dispatchEvent(new CustomEvent('todo-toggle', { detail: { id: 1, done: true }, bubbles: true, composed: true }))
+```
+
+`triggerCustomEvent(name, detail?, options?)` — fluent wrapper dispatch:
+
+```js
+JJHE.from(this).triggerCustomEvent('todo-toggle', { id: 1, done: true })
+```
+
+## Shadow DOM event rules
+
+| Situation                               | propagates past shadow root?              |
+| --------------------------------------- | ----------------------------------------- |
+| Native UI events (click, input, change) | Yes — already `composed: true`            |
+| Native `CustomEvent` (no options)       | No — `composed` defaults to `false`       |
+| `triggerCustomEvent()`                  | Yes — JJ sets `composed: true` by default |
+
+Override defaults explicitly when the event is internal:
+
+```js
+new CustomEvent('internal-ready', { bubbles: false, composed: false })
+```
+
+## Event delegation
+
+```js
+const list = doc.find('#list', true)
+list.on('click', (e) => {
+    const item = e.target.closest('[data-id]')
+    if (item) handleClick(item.dataset.id)
+})
+```
+
+## One-time listener via AbortController
+
+```js
+const ctrl = new AbortController()
+el.ref.addEventListener('click', handler, { signal: ctrl.signal })
+// later:
+ctrl.abort() // removes listener
+```
+
+## Browser references
+
+- EventTarget.addEventListener: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
+- CustomEvent: https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent
+- Event.composed: https://developer.mozilla.org/en-US/docs/Web/API/Event/composed
+- Event bubbling: https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling