@excom/dom-observer 0.1.0

package/.rush/temp/chunked-rush-logs/dom-observer.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/chunked-rush-logs/dom-observer.build_docs.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/chunked-rush-logs/dom-observer.build_package-metas.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 36.671489000000065
+}

package/.rush/temp/operation/build_docs/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/.rush/temp/operation/build_docs/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/operation/build_docs/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 46.228836
+}

package/.rush/temp/operation/build_package-metas/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/.rush/temp/operation/build_package-metas/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/build_package-metas/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 98.21526899999981
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/dom-observer": "../../packages/dom-observer:n8+/7TfT7BWuKysR6wAgrprpaS+oWYsVdAAvlNgBNcM=:"
+}

package/config/rig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}

package/dom-observer.ts

@@ -0,0 +1,186 @@
+import { LoopGuard, selectOne } from "@excom/kit-utils";
+import { Neutron, TEvent } from "@excom/neutron";
+
+export type DomObserverChangeDetail = {
+  target: Element;
+  mutations: MutationRecord[];
+};
+
+export type DomObserverChangeEvent = TEvent & {
+  type: "dom-observer-change";
+  detail: DomObserverChangeDetail;
+};
+
+/**
+ * Resolves a target element via a CSS selector and fires a
+ * `dom-observer-change` event whenever that element mutates. Renders
+ * nothing of its own — pair it with `<event-handler>` (or Quark) to
+ * react to the changes.
+ *
+ * If `target-ref` does not match anything when the element connects,
+ * a document-level `MutationObserver` waits for a matching element to
+ * appear and then switches over to observing it.
+ *
+ * When the target is an `HTMLTemplateElement`, the `<template>` itself
+ * is observed (attribute/child mutations on the element), AND so is the
+ * template's `.content` `DocumentFragment` — otherwise mutations to the
+ * authored template children would be invisible (they don't live as
+ * descendants of the `<template>` element in the DOM tree).
+ *
+ * @fires dom-observer-change - Fires whenever the resolved target mutates,
+ *   and once immediately (with `mutations: []`) as soon as the target is
+ *   resolved so listeners can seed from current state. `mutations` is
+ *   the `MutationRecord[]` from the underlying `MutationObserver`
+ *   callback (empty on that first fire).
+ * @type DomObserverChangeEvent
+ *
+ * @example Log every mutation on a specific element
+ * <event-handler listen-for="dom-observer-change" target-ref="window">
+ *   <dom-observer target-ref="#watched"></dom-observer>
+ * </event-handler>
+ */
+export const DomObserver = Neutron({
+  tag: "dom-observer",
+  events: {
+    change: { prefixWithTag: true },
+  },
+  props: {
+    /**
+     * @option
+     * CSS selector used to resolve the element to observe. Resolved
+     * against `document`. If no element matches at connect time, the
+     * element waits for one to appear.
+     */
+    targetRef: String,
+    /**
+     * @state
+     * The currently observed target element (if any).
+     */
+    targetElement: HTMLElement,
+    /**
+     * @state
+     * Document-level observer used to wait for a target matching
+     * `target-ref` to appear. Disconnected as soon as the target is
+     * found.
+     */
+    targetFindingObserver: MutationObserver,
+    /**
+     * @state
+     * Observer attached to the resolved `targetElement` (and to its
+     * `.content` fragment when the target is a `<template>`).
+     */
+    targetChangeObserver: MutationObserver,
+  },
+})
+  .defineMethods({
+    findTargetElement: (element) => {
+      // @ts-ignore TODO defineMethods
+      const { targetRef, setTargetElement } = element;
+      if (!targetRef) return;
+      const targetElement = selectOne(targetRef, {
+        scope: element,
+      });
+      if (targetElement) {
+        return { targetElement };
+      }
+      /* Wait for a match. `MutationRecord.target` on a childList mutation
+         is the *parent*, not the inserted child, so scan the added nodes
+         (and their descendants). */
+      const targetFindingObserver = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          for (const node of mutation.addedNodes) {
+            if (!(node instanceof Element)) continue;
+            const match = node.matches(targetRef)
+              ? node
+              : node.querySelector(targetRef);
+            if (match) {
+              setTargetElement(match);
+              return;
+            }
+          }
+        }
+      });
+      targetFindingObserver.observe(document.body, {
+        childList: true,
+        subtree: true,
+      });
+      return { targetFindingObserver };
+    },
+    setTargetElement: ({ targetFindingObserver }, targetElement) => {
+      targetFindingObserver?.disconnect();
+      return {
+        targetElement,
+        targetFindingObserver: null,
+      };
+    },
+    notifyChange: ({ targetElement }, mutations: MutationRecord[] = []) => ({
+      emit: ["change", { detail: { target: targetElement, mutations } }],
+    }),
+  })
+  .onPropChanged(
+    "targetRef",
+    ({ targetRef, targetFindingObserver }, previous) => {
+      const shouldDisconnect = previous.targetRef && targetFindingObserver;
+      if (shouldDisconnect) {
+        targetFindingObserver.disconnect();
+      }
+      return [
+        shouldDisconnect && { targetFindingObserver: null },
+        targetRef && { findTargetElement: [] },
+      ];
+    }
+  )
+  .onPropChanged(
+    "targetElement",
+    ({ targetElement, targetChangeObserver, notifyChange }, previous) => {
+      if (previous.targetElement && targetChangeObserver) {
+        targetChangeObserver.disconnect();
+        if (!targetElement) return { targetChangeObserver: null };
+      }
+      if (targetElement) {
+        /* The change event continues the chain that made the mutation
+           (a Quark rule writing an attribute, an effect inserting
+           children): inherit the loop-guard depth on those addresses. */
+        const observer = new MutationObserver((mutations) =>
+          LoopGuard.run(
+            Math.max(
+              0,
+              ...mutations.map((m) =>
+                LoopGuard.depthOf(m.target, m.attributeName ?? "content")
+              )
+            ),
+            () => notifyChange(mutations)
+          )
+        );
+        const init: MutationObserverInit = {
+          attributes: true,
+          childList: true,
+          characterData: true,
+          subtree: true,
+        };
+        observer.observe(targetElement, init);
+        /* A `<template>`'s authored content lives on `.content`, not as
+           DOM descendants. Observe both so either mutation is one stream. */
+        if (targetElement instanceof HTMLTemplateElement) {
+          observer.observe(targetElement.content, init);
+        }
+        return [{ targetChangeObserver: observer }, { notifyChange: [] }];
+      }
+    }
+  )
+  .onDisconnected(
+    ({ isMoving, targetChangeObserver, targetFindingObserver }) => {
+      if (isMoving) return;
+      targetChangeObserver?.disconnect();
+      targetFindingObserver?.disconnect();
+      return {
+        targetElement: null,
+        targetChangeObserver: null,
+        targetFindingObserver: null,
+      };
+    }
+  )
+  .onConnected(({ isMoving, wasMounted, findTargetElement }) => {
+    if (isMoving || !wasMounted) return;
+    findTargetElement();
+  });

package/index.ts

@@ -0,0 +1,17 @@
+import { DomObserver } from "./dom-observer";
+
+DomObserver.define();
+
+export { DomObserver };
+
+type T_HTMLDomObserverElement = typeof DomObserver.CustomElement;
+declare global {
+  interface HTMLDomObserverElement extends T_HTMLDomObserverElement {}
+  interface Window {
+    HTMLDomObserverElement: HTMLDomObserverElement;
+  }
+  interface HTMLElementTagNameMap {
+    "dom-observer": HTMLDomObserverElement;
+  }
+}
+export type { HTMLDomObserverElement };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@excom/dom-observer",
+  "version": "0.1.0",
+  "description": "<dom-observer> custom element that resolves a target via a CSS selector and fires events on its mutations.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/neutron": "^0.1.0",
+    "@excom/kit-utils": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/dom-observer"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/dom-observer/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "dom-observer",
+    "neutron",
+    "custom-elements",
+    "mutation-observer"
+  ],
+  "excom": {
+    "documented": true,
+    "packageType": "kit-element"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs",
+    "build:package-metas": "node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs",
+    "build:docs": "node node_modules/@excom/heft-rig/scripts/build-docs.mjs"
+  }
+}

package/rush-logs/dom-observer.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/dom-observer.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/rush-logs/dom-observer.build_docs.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:docs" command, so caching has been disabled.

package/rush-logs/dom-observer.build_docs.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/rush-logs/dom-observer.build_package-metas.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:package-metas" command, so caching has been disabled.

package/rush-logs/dom-observer.build_package-metas.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/support/custom-elements.json

@@ -0,0 +1,134 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "dom-observer.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "DomObserver",
+          "customElement": true,
+          "tagName": "dom-observer",
+          "description": "Resolves a target element via a CSS selector and fires a `dom-observer-change` event whenever that element mutates. Renders nothing of its own — pair it with `<event-handler>` (or Quark) to react to the changes. If `target-ref` does not match anything when the element connects, a document-level `MutationObserver` waits for a matching element to appear and then switches over to observing it. When the target is an `HTMLTemplateElement`, the `<template>` itself is observed (attribute/child mutations on the element), AND so is the template's `.content` `DocumentFragment` — otherwise mutations to the authored template children would be invisible (they don't live as descendants of the `<template>` element in the DOM tree).",
+          "attributes": [
+            {
+              "name": "target-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "CSS selector used to resolve the element to observe. Resolved against `document`. If no element matches at connect time, the element waits for one to appear.",
+              "fieldName": "targetRef"
+            },
+            {
+              "name": "target-element",
+              "type": {
+                "text": "HTMLElement"
+              },
+              "description": "The currently observed target element (if any).",
+              "fieldName": "targetElement"
+            },
+            {
+              "name": "target-finding-observer",
+              "type": {
+                "text": "MutationObserver"
+              },
+              "description": "Document-level observer used to wait for a target matching `target-ref` to appear. Disconnected as soon as the target is found.",
+              "fieldName": "targetFindingObserver"
+            },
+            {
+              "name": "target-change-observer",
+              "type": {
+                "text": "MutationObserver"
+              },
+              "description": "Observer attached to the resolved `targetElement` (and to its `.content` fragment when the target is a `<template>`).",
+              "fieldName": "targetChangeObserver"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "targetRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "CSS selector used to resolve the element to observe. Resolved against `document`. If no element matches at connect time, the element waits for one to appear.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "targetElement",
+              "type": {
+                "text": "HTMLElement"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "The currently observed target element (if any).",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "targetFindingObserver",
+              "type": {
+                "text": "MutationObserver"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Document-level observer used to wait for a target matching `target-ref` to appear. Disconnected as soon as the target is found.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "targetChangeObserver",
+              "type": {
+                "text": "MutationObserver"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Observer attached to the resolved `targetElement` (and to its `.content` fragment when the target is a `<template>`).",
+              "_neutron": {
+                "surface": "state"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "dom-observer-change",
+              "description": "Fires whenever the resolved target mutates, and once immediately (with `mutations: []`) as soon as the target is resolved so listeners can seed from current state. `mutations` is the `MutationRecord[]` from the underlying `MutationObserver` callback (empty on that first fire).",
+              "type": {
+                "text": "DomObserverChangeEvent",
+                "expanded": "CustomEvent & { type: \"dom-observer-change\"; detail: { target: Element; mutations: MutationRecord[]; }; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DomObserver",
+          "declaration": {
+            "name": "DomObserver",
+            "module": "dom-observer.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "dom-observer",
+          "declaration": {
+            "name": "DomObserver",
+            "module": "dom-observer.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/simple.html

@@ -0,0 +1,18 @@
+<div>
+  <section>
+    <dom-observer target-ref=":scope + details"></dom-observer>
+    <details id="do-watched">
+      <summary>Toggle me — mutates the "open" attribute</summary>
+      <p>Toggling this
+        fired <code>dom-observer-change</code>.</p>
+    </details>
+    <output class="tag-pre" style="white-space: pre;"></output>
+  </section>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    section {
+      @on dom-observer-change (handle: appendOutputFromDetail);
+    }
+  </quark-sheet>
+</div>

package/support/dist-docs/dom-observer.md

@@ -0,0 +1,117 @@
+# dom-observer
+
+Fire an event whenever a configured element mutates.
+
+
+```html
+<div>
+  <section>
+    <dom-observer target-ref=":scope + details"></dom-observer>
+    <details id="do-watched">
+      <summary>Toggle me — mutates the "open" attribute</summary>
+      <p>Toggling this
+        fired <code>dom-observer-change</code>.</p>
+    </details>
+    <output class="tag-pre" style="white-space: pre;"></output>
+  </section>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    section {
+      @on dom-observer-change (handle: appendOutputFromDetail);
+    }
+  </quark-sheet>
+</div>
+```
+
+
+## Features
+
+- **Mutation events** Fires `dom-observer-change` on target changes
+- **Selector-based** `target-ref` resolves any element, anywhere
+- **Waits for its target** No matching element yet? It watches for one
+- **Fires once immediately** An empty-`mutations` fire on resolve lets
+  listeners seed from current state
+- **`<template>`-aware** Also observes a template's `.content` fragment
+
+## Installation
+
+
+`@excom/dom-observer` v0.1.0
+
+```bash
+pnpm add @excom/dom-observer
+```
+
+```bash
+npm install @excom/dom-observer
+```
+
+```bash
+yarn add @excom/dom-observer
+```
+
+### Import
+
+```ts
+import "@excom/dom-observer";
+```
+
+
+
+## Usage
+
+Point `target-ref` at any selector, then react to `dom-observer-change`
+with `<event-handler>` (or Quark).
+
+```html
+<dom-observer target-ref="#watched"></dom-observer>
+<event-handler listen-for="dom-observer-change" target-ref="#log">
+  <!-- runs on every #watched mutation, and once on attach -->
+</event-handler>
+```
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `target-ref` | option | `string` |  |  | CSS selector used to resolve the element to observe. Resolved against `document`. If no element matches at connect time, the element waits for one to appear. |
+| `target-element` | state | `HTMLElement` |  |  | The currently observed target element (if any). |
+| `target-finding-observer` | state | `MutationObserver` |  |  | Document-level observer used to wait for a target matching `target-ref` to appear. Disconnected as soon as the target is found. |
+| `target-change-observer` | state | `MutationObserver` |  |  | Observer attached to the resolved `targetElement` (and to its `.content` fragment when the target is a `<template>`). |
+
+#### Fires
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `dom-observer-change` | `DomObserverChangeEvent` (`CustomEvent & { type: "dom-observer-change"; detail: { target: Element; mutations: MutationRecord[]; }; bubbles: true; cancelable: true; composed: true }`) | Fires whenever the resolved target mutates, and once immediately (with `mutations: []`) as soon as the target is resolved so listeners can seed from current state. `mutations` is the `MutationRecord[]` from the underlying `MutationObserver` callback (empty on that first fire). |
+
+
+
+### Examples
+
+#### Waiting for the target to exist
+
+If nothing matches `target-ref` at connect time, `<dom-observer>` watches
+the document for a match and switches over automatically — no glue code:
+
+```html
+<dom-observer target-ref="article#late"></dom-observer>
+```
+
+#### Observing a `<template>`
+
+A `<template>`'s authored content lives on its `.content`
+`DocumentFragment`, not as DOM descendants of the `<template>` itself.
+`<dom-observer>` observes both, so mutations to either surface through the
+same event stream:
+
+```html
+<template id="rows">
+  <li>seed</li>
+</template>
+<dom-observer target-ref="#rows"></dom-observer>
+```

package/support/docs/INTERNAL.md

@@ -0,0 +1 @@
+- Consider moving `findTargetElement` and related logic to its own Base element or common util. Could be useful for other elements that use `x-ref`s to watch for the desired element if it's not in the document yet.

package/support/docs/README.md

@@ -0,0 +1,59 @@
+# dom-observer
+
+Fire an event whenever a configured element mutates.
+
+<include-content data-demo="simple"></include-content>
+
+## Features
+
+- **Mutation events** Fires `dom-observer-change` on target changes
+- **Selector-based** `target-ref` resolves any element, anywhere
+- **Waits for its target** No matching element yet? It watches for one
+- **Fires once immediately** An empty-`mutations` fire on resolve lets
+  listeners seed from current state
+- **`<template>`-aware** Also observes a template's `.content` fragment
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Point `target-ref` at any selector, then react to `dom-observer-change`
+with `<event-handler>` (or Quark).
+
+```html
+<dom-observer target-ref="#watched"></dom-observer>
+<event-handler listen-for="dom-observer-change" target-ref="#log">
+  <!-- runs on every #watched mutation, and once on attach -->
+</event-handler>
+```
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Waiting for the target to exist
+
+If nothing matches `target-ref` at connect time, `<dom-observer>` watches
+the document for a match and switches over automatically — no glue code:
+
+```html
+<dom-observer target-ref="article#late"></dom-observer>
+```
+
+#### Observing a `<template>`
+
+A `<template>`'s authored content lives on its `.content`
+`DocumentFragment`, not as DOM descendants of the `<template>` itself.
+`<dom-observer>` observes both, so mutations to either surface through the
+same event stream:
+
+```html
+<template id="rows">
+  <li>seed</li>
+</template>
+<dom-observer target-ref="#rows"></dom-observer>
+```

package/support/package-meta.json

@@ -0,0 +1,90 @@
+{
+  "shortName": "dom-observer",
+  "package": {
+    "name": "@excom/dom-observer",
+    "version": "0.1.0",
+    "description": "<dom-observer> custom element that resolves a target via a CSS selector and fires events on its mutations.",
+    "peerDependencies": {},
+    "excom": {
+      "documented": true,
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "simple": "<div>\n  <section>\n    <dom-observer target-ref=\":scope + details\"></dom-observer>\n    <details id=\"do-watched\">\n      <summary>Toggle me — mutates the \"open\" attribute</summary>\n      <p>Toggling this\n        fired <code>dom-observer-change</code>.</p>\n    </details>\n    <output class=\"tag-pre\" style=\"white-space: pre;\"></output>\n  </section>\n  <quark-sheet>\n    @use \"/demo-utils\" as *;\n\n    section {\n      @on dom-observer-change (handle: appendOutputFromDetail);\n    }\n  </quark-sheet>\n</div>"
+  },
+  "readme": "<h1 id=\"md-dom-observer\">dom-observer</h1>\n<p>Fire an event whenever a configured element mutates.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Mutation events</strong> Fires <code>dom-observer-change</code> on target changes</li>\n<li><strong>Selector-based</strong> <code>target-ref</code> resolves any element, anywhere</li>\n<li><strong>Waits for its target</strong> No matching element yet? It watches for one</li>\n<li><strong>Fires once immediately</strong> An empty-<code>mutations</code> fire on resolve lets\nlisteners seed from current state</li>\n<li><strong><code>&lt;template&gt;</code>-aware</strong> Also observes a template&#39;s <code>.content</code> fragment</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Point <code>target-ref</code> at any selector, then react to <code>dom-observer-change</code>\nwith <code>&lt;event-handler&gt;</code> (or Quark).</p>\n<include-content data-language=\"html\"><template>&lt;dom-observer target-ref=\"#watched\"&gt;&lt;/dom-observer&gt;\n&lt;event-handler listen-for=\"dom-observer-change\" target-ref=\"#log\"&gt;\n  &lt;!-- runs on every #watched mutation, and once on attach --&gt;\n&lt;/event-handler&gt;</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-waiting-for-the-target-to-exist\">Waiting for the target to exist</h4>\n<p>If nothing matches <code>target-ref</code> at connect time, <code>&lt;dom-observer&gt;</code> watches\nthe document for a match and switches over automatically — no glue code:</p>\n<include-content data-language=\"html\"><template>&lt;dom-observer target-ref=\"article#late\"&gt;&lt;/dom-observer&gt;</template></include-content>\n<h4 id=\"md-observing-a-lt-template-gt\">Observing a <code>&lt;template&gt;</code></h4>\n<p>A <code>&lt;template&gt;</code>&#39;s authored content lives on its <code>.content</code>\n<code>DocumentFragment</code>, not as DOM descendants of the <code>&lt;template&gt;</code> itself.\n<code>&lt;dom-observer&gt;</code> observes both, so mutations to either surface through the\nsame event stream:</p>\n<include-content data-language=\"html\"><template>&lt;template id=\"rows\"&gt;\n  &lt;li&gt;seed&lt;/li&gt;\n&lt;/template&gt;\n&lt;dom-observer target-ref=\"#rows\"&gt;&lt;/dom-observer&gt;</template></include-content>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-dom-observer\">dom-observer</h1>\n<p>Fire an event whenever a configured element mutates.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Mutation events</strong> Fires <code>dom-observer-change</code> on target changes</li>\n<li><strong>Selector-based</strong> <code>target-ref</code> resolves any element, anywhere</li>\n<li><strong>Waits for its target</strong> No matching element yet? It watches for one</li>\n<li><strong>Fires once immediately</strong> An empty-<code>mutations</code> fire on resolve lets\nlisteners seed from current state</li>\n<li><strong><code>&lt;template&gt;</code>-aware</strong> Also observes a template&#39;s <code>.content</code> fragment</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Point <code>target-ref</code> at any selector, then react to <code>dom-observer-change</code>\nwith <code>&lt;event-handler&gt;</code> (or Quark).</p>\n<include-content data-language=\"html\"><template>&lt;dom-observer target-ref=\"#watched\"&gt;&lt;/dom-observer&gt;\n&lt;event-handler listen-for=\"dom-observer-change\" target-ref=\"#log\"&gt;\n  &lt;!-- runs on every #watched mutation, and once on attach --&gt;\n&lt;/event-handler&gt;</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-waiting-for-the-target-to-exist\">Waiting for the target to exist</h4>\n<p>If nothing matches <code>target-ref</code> at connect time, <code>&lt;dom-observer&gt;</code> watches\nthe document for a match and switches over automatically — no glue code:</p>\n<include-content data-language=\"html\"><template>&lt;dom-observer target-ref=\"article#late\"&gt;&lt;/dom-observer&gt;</template></include-content>\n<h4 id=\"md-observing-a-lt-template-gt\">Observing a <code>&lt;template&gt;</code></h4>\n<p>A <code>&lt;template&gt;</code>&#39;s authored content lives on its <code>.content</code>\n<code>DocumentFragment</code>, not as DOM descendants of the <code>&lt;template&gt;</code> itself.\n<code>&lt;dom-observer&gt;</code> observes both, so mutations to either surface through the\nsame event stream:</p>\n<include-content data-language=\"html\"><template>&lt;template id=\"rows\"&gt;\n  &lt;li&gt;seed&lt;/li&gt;\n&lt;/template&gt;\n&lt;dom-observer target-ref=\"#rows\"&gt;&lt;/dom-observer&gt;</template></include-content>\n"
+  },
+  "installation": {
+    "name": "@excom/dom-observer",
+    "shortName": "dom-observer",
+    "version": "0.1.0",
+    "description": "<dom-observer> custom element that resolves a target via a CSS selector and fires events on its mutations.",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/dom-observer@0.1.0/dist/index.umd.min.js\"></script>",
+    "install": {
+      "npm": "npm install @excom/dom-observer"
+    },
+    "imports": {
+      "js": "import \"@excom/dom-observer\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/dom-observer\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/dom-observer\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "dom-observer",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "target-ref",
+          "type": "string",
+          "description": "CSS selector used to resolve the element to observe. Resolved against <code>document</code>. If no element matches at connect time, the element waits for one to appear.",
+          "fieldName": "targetRef",
+          "surface": "option"
+        },
+        {
+          "name": "target-change-observer",
+          "type": "MutationObserver",
+          "description": "Observer attached to the resolved <code>targetElement</code> (and to its <code>.content</code> fragment when the target is a <code>&lt;template&gt;</code>).",
+          "fieldName": "targetChangeObserver",
+          "surface": "state"
+        },
+        {
+          "name": "target-element",
+          "type": "HTMLElement",
+          "description": "The currently observed target element (if any).",
+          "fieldName": "targetElement",
+          "surface": "state"
+        },
+        {
+          "name": "target-finding-observer",
+          "type": "MutationObserver",
+          "description": "Document-level observer used to wait for a target matching <code>target-ref</code> to appear. Disconnected as soon as the target is found.",
+          "fieldName": "targetFindingObserver",
+          "surface": "state"
+        }
+      ],
+      "events": [
+        {
+          "name": "dom-observer-change",
+          "description": "Fires whenever the resolved target mutates, and once immediately (with <code>mutations: []</code>) as soon as the target is resolved so listeners can seed from current state. <code>mutations</code> is the <code>MutationRecord[]</code> from the underlying <code>MutationObserver</code> callback (empty on that first fire).",
+          "type": "DomObserverChangeEvent",
+          "typeExpanded": "CustomEvent & { type: \"dom-observer-change\"; detail: { target: Element; mutations: MutationRecord[]; }; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/__snapshots__/simple.view.test.ts.snap

@@ -0,0 +1,23 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`simple view > logs attribute mutations on the details element > complexity 1`] = `
+{
+  "attributeRuns": 0,
+  "closest": 0,
+  "getVar": 0,
+  "importNode": 0,
+  "listenerRuns": 0,
+  "matches": 0,
+  "parentElement": 0,
+  "quarkRuns": 0,
+  "queryScopeCost": 0,
+  "querySelectorAll": 0,
+  "removeAttribute": 0,
+  "ruleRuns": 0,
+  "schedulePaint": 0,
+  "setAttribute": 1,
+  "setVar": 0,
+  "textContent": 1,
+  "variableRuns": 0,
+}
+`;

package/support/tests/dom-observer.test.ts

@@ -0,0 +1,326 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import "../../index";
+
+describe("dom-observer", () => {
+  /*
+   * Listen at document before any fixture, so the sync
+   * `dom-observer-change` on connect is captured.
+   */
+  let events: CustomEvent[];
+  const listener = (e: Event) => events.push(e as CustomEvent);
+
+  beforeEach(() => {
+    events = [];
+    document.addEventListener("dom-observer-change", listener);
+  });
+
+  afterEach(() => {
+    document.removeEventListener("dom-observer-change", listener);
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("emits dom-observer-change once the target is resolved", async () => {
+    const target = document.createElement("div");
+    target.id = "watched";
+    document.body.appendChild(target);
+
+    const el = fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#watched"></dom-observer>`,
+    );
+
+    await wait(0);
+    expect(events.length).toBe(1);
+    expect(events[0].detail.mutations).toEqual([]);
+    expect(el.targetElement).toBe(target);
+  });
+
+  it("emits dom-observer-change on attribute mutations of the target", async () => {
+    const target = document.createElement("div");
+    target.id = "watched";
+    document.body.appendChild(target);
+
+    fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#watched"></dom-observer>`,
+    );
+    await wait(0);
+    events.length = 0;
+
+    target.setAttribute("data-state", "active");
+    await wait(0);
+
+    expect(events.length).toBeGreaterThanOrEqual(1);
+    const last = events[events.length - 1];
+    expect(last.detail.mutations[0].type).toBe("attributes");
+    expect(last.detail.mutations[0].attributeName).toBe("data-state");
+  });
+
+  it("emits dom-observer-change on childList mutations of the target", async () => {
+    const target = document.createElement("ul");
+    target.id = "watched";
+    document.body.appendChild(target);
+
+    fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#watched"></dom-observer>`,
+    );
+    await wait(0);
+    events.length = 0;
+
+    target.appendChild(document.createElement("li"));
+    await wait(0);
+
+    const types = events.flatMap((e) =>
+      (e.detail.mutations as MutationRecord[]).map((m) => m.type),
+    );
+    expect(types).toContain("childList");
+  });
+
+  it("waits for the target to appear before observing", async () => {
+    const el = fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#late"></dom-observer>`,
+    );
+    await wait(0);
+    expect(events.length).toBe(0);
+    expect(el.targetElement).toBeFalsy();
+
+    const target = document.createElement("section");
+    target.id = "late";
+    document.body.appendChild(target);
+    await wait(0);
+
+    expect(el.targetElement).toBe(target);
+    expect(events.length).toBe(1);
+    expect(events[0].detail.mutations).toEqual([]);
+  });
+
+  it("observes a <template>'s .content fragment", async () => {
+    const tpl = document.createElement("template");
+    tpl.id = "rows";
+    tpl.innerHTML = "<li>seed</li>";
+    document.body.appendChild(tpl);
+
+    fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#rows"></dom-observer>`,
+    );
+    await wait(0);
+    events.length = 0;
+
+    // Mutating `template.content` must surface; `.content` is a
+    // DocumentFragment outside the `<template>` descendant tree.
+    const li = document.createElement("li");
+    li.textContent = "added";
+    tpl.content.appendChild(li);
+    await wait(0);
+
+    const types = events.flatMap((e) =>
+      (e.detail.mutations as MutationRecord[]).map((m) => m.type),
+    );
+    expect(types).toContain("childList");
+  });
+
+  it("emits dom-observer-change on characterData mutations of the target", async () => {
+    const target = document.createElement("p");
+    target.id = "watched";
+    target.textContent = "before";
+    document.body.appendChild(target);
+
+    fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#watched"></dom-observer>`,
+    );
+    await wait(0);
+    events.length = 0;
+
+    (target.firstChild as Text).data = "after";
+    await wait(0);
+
+    const types = events.flatMap((e) =>
+      (e.detail.mutations as MutationRecord[]).map((m) => m.type),
+    );
+    expect(types).toContain("characterData");
+  });
+
+  it("finds a late target nested inside an inserted subtree", async () => {
+    const el = fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#late-nested"></dom-observer>`,
+    );
+    await wait(0);
+    expect(el.targetElement).toBeFalsy();
+
+    const wrapper = document.createElement("div");
+    wrapper.innerHTML = `<section><p id="late-nested"></p></section>`;
+    document.body.appendChild(wrapper);
+    await wait(0);
+
+    expect(el.targetElement).toBe(wrapper.querySelector("#late-nested"));
+    expect(events.length).toBe(1);
+  });
+
+  it("re-targets while still waiting for the first target", async () => {
+    const target = document.createElement("div");
+    target.id = "watched";
+    document.body.appendChild(target);
+
+    const el = fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#never-appears"></dom-observer>`,
+    );
+    await wait(0);
+    expect(el.targetFindingObserver).toBeTruthy();
+    expect(events.length).toBe(0);
+
+    el.targetRef = "#watched";
+    await wait(0);
+    expect(el.targetElement).toBe(target);
+    expect(el.targetFindingObserver).toBeNull();
+    expect(events.length).toBe(1);
+
+    // the abandoned finder no longer switches targets
+    const late = document.createElement("div");
+    late.id = "never-appears";
+    document.body.appendChild(late);
+    await wait(0);
+    expect(el.targetElement).toBe(target);
+  });
+
+  it("re-observes when target-ref moves to another resolved element", async () => {
+    const first = document.createElement("div");
+    first.id = "first";
+    const second = document.createElement("div");
+    second.id = "second";
+    document.body.append(first, second);
+
+    const el = fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#first"></dom-observer>`,
+    );
+    await wait(0);
+    expect(el.targetElement).toBe(first);
+    events.length = 0;
+
+    el.targetRef = "#second";
+    await wait(0);
+    expect(el.targetElement).toBe(second);
+    // seeds listeners from the new target
+    expect(events.length).toBe(1);
+    expect(events[0].detail.target).toBe(second);
+    events.length = 0;
+
+    first.setAttribute("data-state", "ignored");
+    await wait(0);
+    expect(events.length).toBe(0);
+
+    second.setAttribute("data-state", "seen");
+    await wait(0);
+    expect(events.length).toBe(1);
+    expect(events[0].detail.target).toBe(second);
+    expect(events[0].detail.mutations[0].attributeName).toBe("data-state");
+  });
+
+  it("stops observing when the target is cleared", async () => {
+    const target = document.createElement("div");
+    target.id = "watched";
+    document.body.appendChild(target);
+
+    const el = fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#watched"></dom-observer>`,
+    );
+    await wait(0);
+    expect(el.targetChangeObserver).toBeTruthy();
+    events.length = 0;
+
+    el.targetElement = null;
+    await wait(0);
+    expect(el.targetChangeObserver).toBeNull();
+
+    target.setAttribute("data-state", "cleared");
+    await wait(0);
+    expect(events.length).toBe(0);
+  });
+
+  it("keeps observing across a synchronous move", async () => {
+    const target = document.createElement("div");
+    target.id = "watched";
+    document.body.appendChild(target);
+
+    const el = fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#watched"></dom-observer>`,
+    );
+    await wait(0);
+    events.length = 0;
+
+    const other = document.createElement("div");
+    document.body.appendChild(other);
+    other.appendChild(el);
+    await wait(0);
+    expect(el.targetElement).toBe(target);
+    expect(events.length).toBe(0);
+
+    target.setAttribute("data-state", "moved");
+    await wait(0);
+    expect(events.length).toBe(1);
+  });
+
+  it("re-resolves the target after a real disconnect and reconnect", async () => {
+    const target = document.createElement("div");
+    target.id = "watched";
+    document.body.appendChild(target);
+
+    const el = fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#watched"></dom-observer>`,
+    );
+    await wait(0);
+    el.remove();
+    await wait(0);
+    expect(el.targetElement).toBeNull();
+    events.length = 0;
+
+    document.body.appendChild(el);
+    await wait(0);
+    expect(el.targetElement).toBe(target);
+    expect(events.length).toBe(1);
+    expect(events[0].detail.mutations).toEqual([]);
+
+    target.setAttribute("data-state", "reconnected");
+    await wait(0);
+    expect(events.length).toBe(2);
+  });
+
+  it("reconnects without a target-ref as a no-op", async () => {
+    const el = fixture<HTMLDomObserverElement>(`<dom-observer></dom-observer>`);
+    await wait(0);
+    el.remove();
+    await wait(0);
+    expect(() => document.body.appendChild(el)).not.toThrow();
+    await wait(0);
+    expect(el.targetElement).toBeFalsy();
+    expect(el.targetFindingObserver).toBeFalsy();
+    expect(events.length).toBe(0);
+  });
+
+  it("disconnects observers when disconnected", async () => {
+    const target = document.createElement("div");
+    target.id = "watched";
+    document.body.appendChild(target);
+
+    const el = fixture<HTMLDomObserverElement>(
+      `<dom-observer target-ref="#watched"></dom-observer>`,
+    );
+    await wait(0);
+    events.length = 0;
+
+    el.remove();
+    await wait(0);
+
+    target.setAttribute("data-state", "after-disconnect");
+    await wait(0);
+    expect(events.length).toBe(0);
+    expect(el.targetElement).toBeNull();
+  });
+});

package/support/tests/simple.view.test.ts

@@ -0,0 +1,40 @@
+import "@excom/quark-sheet";
+import "../../index";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  expectComplexity,
+  flush,
+  installDemoModules,
+  measureComplexity,
+  mountView,
+  readDemo,
+  restoreDemoModules,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("simple view", () => {
+  beforeEach(() => installDemoModules());
+  afterEach(() => {
+    document.body.innerHTML = "";
+    restoreDemoModules();
+  });
+
+  it("logs attribute mutations on the details element", async () => {
+    const { root, quark } = await mountView(readDemo(import.meta.url, "simple"));
+    const details = root.querySelector("details")!;
+    const meter = measureComplexity(quark!);
+    details.setAttribute("open", "");
+    await flush();
+    const budget = meter.take();
+    meter.stop();
+    expect(root.querySelector("output")?.textContent).toMatch(
+      /HTMLDetailsElement|MutationRecord/,
+    );
+    expectComplexity(budget);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@excom/heft-rig/profiles/default/config/tsconfig.json",
+  "include": ["./*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}