@excom/dialog-anchor 0.1.0

package/.rush/temp/chunked-rush-logs/dialog-anchor.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/dialog-anchor.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/dialog-anchor.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": 37.54774099999986
+}

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": 53.83026099999984
+}

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.41211699999985
+}

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

@@ -0,0 +1,3 @@
+{
+  "../../packages/dialog-anchor": "../../packages/dialog-anchor:iu+Gwd294io6cbeYmVbBu6c2aWWWMg9YuILC/ZbWLyY=:"
+}

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/dialog-anchor.css

@@ -0,0 +1 @@
+@import "./index.css";

package/dialog-anchor.ts

@@ -0,0 +1,73 @@
+import { selectOne } from "@excom/kit-utils";
+import { ListenableElement } from "@excom/listenable-element";
+import { Neutron } from "@excom/neutron";
+
+/**
+ * Click target that opens or closes a `<dialog>` without any JavaScript.
+ * Wrap a button (or any clickable content) in `<dialog-anchor>` and point
+ * it at a `<dialog>` via `target-ref`, or let it find the nearest ancestor
+ * `<dialog>` automatically — the common case for a close button living
+ * inside the dialog it closes.
+ *
+ * By default it listens for `click`; set `listen-for` (from
+ * `ListenableElement`) to toggle on another event instead — e.g. auto-close
+ * a dialog when a nested `<super-form>` succeeds.
+ *
+ * @summary Open/close a `<dialog>` — by selector or nearest ancestor.
+ *
+ * @example
+ * <dialog-anchor target-ref="#confirm" is-modal>
+ *   <button>Delete</button>
+ * </dialog-anchor>
+ * <dialog id="confirm">...</dialog>
+ */
+export const DialogAnchor = Neutron.compose([
+  ListenableElement,
+  Neutron({
+    tag: "dialog-anchor",
+    props: {
+      /**
+       * @option
+       * CSS selector for the `<dialog>` to toggle. If omitted, the
+       * element toggles the nearest ancestor `<dialog>`.
+       * @values <CSS Selector>
+       */
+      targetRef: String,
+      /**
+       * @option
+       * Open the dialog as a modal (blocks the rest of the page) instead
+       * of a non-modal popover.
+       */
+      isModal: Boolean,
+    },
+  }),
+])
+  .defineMethods({
+    actionHandler: (element) => {
+      let dialog =
+        element.targetRef &&
+        selectOne(element.targetRef, {
+          scope: element,
+        });
+      if (!(dialog instanceof HTMLDialogElement)) {
+        dialog = element.closest("dialog");
+      }
+      if (dialog instanceof HTMLDialogElement) {
+        const isOpen = dialog.open;
+        const isModal = element.isModal;
+        if (isOpen) {
+          dialog.close();
+        } else {
+          dialog[isModal ? "showModal" : "show"]();
+        }
+      }
+    },
+  })
+  .onConnected(
+    ({ listenFor, listenForLifecycle, handleEvent, isMoving }) =>
+      !isMoving &&
+      !listenFor?.length &&
+      !listenForLifecycle?.length && {
+        addListener: ["click", handleEvent],
+      }
+  );

package/index.css

@@ -0,0 +1 @@
+@import "./src/dialog-anchor.css";

package/index.ts

@@ -0,0 +1,17 @@
+import { DialogAnchor } from "./dialog-anchor";
+
+DialogAnchor.define();
+
+export { DialogAnchor };
+
+type T_HTMLDialogAnchorElement = typeof DialogAnchor.CustomElement;
+declare global {
+  interface HTMLDialogAnchorElement extends T_HTMLDialogAnchorElement {}
+  interface Window {
+    HTMLDialogAnchorElement: HTMLDialogAnchorElement;
+  }
+  interface HTMLElementTagNameMap {
+    "dialog-anchor": HTMLDialogAnchorElement;
+  }
+}
+export type { HTMLDialogAnchorElement };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@excom/dialog-anchor",
+  "version": "0.1.0",
+  "description": "<dialog-anchor> custom element",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/listenable-element": "^0.1.0",
+    "@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/dialog-anchor"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/dialog-anchor/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "dialog-anchor",
+    "neutron",
+    "custom-elements"
+  ],
+  "excom": {
+    "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/dialog-anchor.apply-exports.cache.log

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

package/rush-logs/dialog-anchor.apply-exports.log

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

package/rush-logs/dialog-anchor.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/dialog-anchor.build_docs.log

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

package/rush-logs/dialog-anchor.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/dialog-anchor.build_package-metas.log

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

package/src/dialog-anchor.css

@@ -0,0 +1,19 @@
+@import "@excom/listenable-element/src/index.css";
+
+/**
+ * Styles for `<dialog-anchor>`.
+ * @element dialog-anchor
+ */
+
+/* Aliases */
+@custom-selector :--dialog-anchor dialog-anchor, .tag-dialog-anchor;
+
+/**
+ * Skip the pointer cursor from the listenable mixin.
+ * @cssclass unstyled
+ */
+@layer {
+  :--dialog-anchor:not(.unstyled) {
+    @mixin listenable-element;
+  }
+}

package/support/custom-elements.json

@@ -0,0 +1,110 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "dialog-anchor.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "DialogAnchor",
+          "customElement": true,
+          "tagName": "dialog-anchor",
+          "mixins": [
+            {
+              "name": "ListenableElement",
+              "package": "@excom/listenable-element"
+            }
+          ],
+          "summary": "Open/close a `<dialog>` — by selector or nearest ancestor.",
+          "description": "Click target that opens or closes a `<dialog>` without any JavaScript. Wrap a button (or any clickable content) in `<dialog-anchor>` and point it at a `<dialog>` via `target-ref`, or let it find the nearest ancestor `<dialog>` automatically — the common case for a close button living inside the dialog it closes. By default it listens for `click`; set `listen-for` (from `ListenableElement`) to toggle on another event instead — e.g. auto-close a dialog when a nested `<super-form>` succeeds.",
+          "attributes": [
+            {
+              "name": "target-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "CSS selector for the `<dialog>` to toggle. If omitted, the element toggles the nearest ancestor `<dialog>`.",
+              "fieldName": "targetRef",
+              "values": [
+                "<CSS Selector>"
+              ]
+            },
+            {
+              "name": "is-modal",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Open the dialog as a modal (blocks the rest of the page) instead of a non-modal popover.",
+              "fieldName": "isModal"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "targetRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "CSS selector for the `<dialog>` to toggle. If omitted, the element toggles the nearest ancestor `<dialog>`.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isModal",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Open the dialog as a modal (blocks the rest of the page) instead of a non-modal popover.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "_neutron": {
+            "cssClasses": [
+              {
+                "name": "unstyled",
+                "description": "Skip the pointer cursor from the listenable mixin."
+              }
+            ],
+            "cssAliases": [
+              {
+                "name": ":--dialog-anchor",
+                "selectors": [
+                  "dialog-anchor",
+                  ".tag-dialog-anchor"
+                ],
+                "kind": "element"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DialogAnchor",
+          "declaration": {
+            "name": "DialogAnchor",
+            "module": "dialog-anchor.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "dialog-anchor",
+          "declaration": {
+            "name": "DialogAnchor",
+            "module": "dialog-anchor.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/auto-close.html

@@ -0,0 +1,11 @@
+<div>
+  <dialog-anchor role="button" target-ref="#da-auto" is-modal>Open form</dialog-anchor>
+  <dialog id="da-auto">
+    <dialog-anchor listen-for="super-form-success">
+      <p>Simulating a form submit…</p>
+      <event-handler role="button" fire-event="super-form-success">
+        Submit
+      </event-handler>
+    </dialog-anchor>
+  </dialog>
+</div>

package/support/demos/is-modal.html

@@ -0,0 +1,21 @@
+<div>
+  <dialog-anchor role="button" target-ref="#da-modal" is-modal>
+    Open as modal
+  </dialog-anchor>
+  <dialog-anchor role="button" target-ref="#da-modal">
+    Open as non-modal
+  </dialog-anchor>
+  <dialog id="da-modal">
+    <article>
+      <header>
+        <dialog-anchor role="button" rel="prev"></dialog-anchor>
+        <h4>Modal dialogs block interaction with the rest of the page.</h4>
+        <p>This dialog is shown with Valence.css styling</p>
+      </header>
+      <p>Dialog content</p>
+      <footer>
+        Footer content
+      </footer>
+    </article>
+  </dialog>
+</div>

package/support/demos/simple.html

@@ -0,0 +1,7 @@
+<div>
+  <dialog-anchor role="button" target-ref="#da-simple" is-modal>Open dialog</dialog-anchor>
+  <dialog id="da-simple">
+    <p>A native, modal dialog.</p>
+    <dialog-anchor role="button">Close</dialog-anchor>
+  </dialog>
+</div>

package/support/dist-docs/dialog-anchor.md

@@ -0,0 +1,163 @@
+# dialog-anchor
+
+Open and close a native `<dialog>` — no JavaScript required.
+
+
+```html
+<div>
+  <dialog-anchor role="button" target-ref="#da-simple" is-modal>Open dialog</dialog-anchor>
+  <dialog id="da-simple">
+    <p>A native, modal dialog.</p>
+    <dialog-anchor role="button">Close</dialog-anchor>
+  </dialog>
+</div>
+```
+
+
+## Features
+
+- **Click to toggle** Opens / closes a `<dialog>` on click
+- **Target or fallback** Point at any `<dialog>` via `target-ref`, or let
+  it find the nearest ancestor automatically (great for close buttons)
+- **Modal or non-modal** `is-modal` blocks the rest of the page; omit it
+  for a lightweight, dismissible popover
+- **Any trigger event** Inherits `listen-for` to open/close on custom
+  events instead of `click`
+
+## Installation
+
+
+`@excom/dialog-anchor` v0.1.0
+
+```bash
+pnpm add @excom/dialog-anchor
+```
+
+```bash
+npm install @excom/dialog-anchor
+```
+
+```bash
+yarn add @excom/dialog-anchor
+```
+
+### Import
+
+```ts
+import "@excom/dialog-anchor";
+```
+
+```css
+@import "@excom/dialog-anchor/dialog-anchor.css";
+```
+
+
+
+## Usage
+
+Wrap a trigger in `<dialog-anchor>` and point it at a `<dialog>`. A
+`<dialog-anchor>` with no `target-ref`, placed inside the `<dialog>` it
+should close, needs no configuration at all.
+
+```html
+<dialog-anchor target-ref="#confirm" role="button">Delete</dialog-anchor>
+<dialog id="confirm">
+  <p>Are you sure?</p>
+  <dialog-anchor role="button">Cancel</dialog-anchor>
+</dialog>
+```
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description | Inherited from |
+| --- | --- | --- | --- | --- | --- | --- |
+| `target-ref` | option | `string` |  | `<CSS Selector>` | CSS selector for the `<dialog>` to toggle. If omitted, the element toggles the nearest ancestor `<dialog>`. |  |
+| `is-modal` | option | `boolean` |  |  | Open the dialog as a modal (blocks the rest of the page) instead of a non-modal popover. |  |
+| `host-ref` | option | `string` |  | `<CSS Selector>` \| `"window"` \| `"document"` \| `"html"` \| `"body"` \| `"head"` | Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear. | `@excom/listenable-element` |
+| `listen-for` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set). | `@excom/listenable-element` |
+| `listen-for-lifecycle` | option | `tokenlist` |  | `"connected"` \| `"disconnected"` \| `"adopted"` | Space-separated element lifecycles to handle. | `@excom/listenable-element` |
+| `listen-once` | option | `boolean` |  |  | Handle each distinct event name / lifecycle at most once. | `@excom/listenable-element` |
+| `selector-filter` | option | `string` |  | `<CSS Selector>` | Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector. | `@excom/listenable-element` |
+| `keycode-filter` | option | `tokenlist` |  | `<key` \| `mod+key>…` | Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`. Case-insensitive. | `@excom/listenable-element` |
+| `pathname-filter` | option | `tokenlist` |  | `<pathname>…` | Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element. | `@excom/listenable-element` |
+| `prevent-default` | option | `boolean` |  |  | Call `preventDefault()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
+| `stop-propagation` | option | `boolean` |  |  | Call `stopPropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
+| `stop-immediate-propagation` | option | `boolean` |  |  | Call `stopImmediatePropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
+| `vibrate-ms` | option | `number` | `"20 (when attribute is present with no value)"` |  | Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse. | `@excom/listenable-element` |
+| `delay-ms` | option | `number` |  |  | Delay handling by this many milliseconds. | `@excom/listenable-element` |
+| `is-debounced` | option | `boolean` |  |  | With `delay-ms`, coalesce bursts into one trailing call (debounce). | `@excom/listenable-element` |
+
+#### CSS Classes
+
+| Name | Description |
+| --- | --- |
+| `.unstyled` | Skip the pointer cursor from the listenable mixin. |
+
+#### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--dialog-anchor` | element | `dialog-anchor`, `.tag-dialog-anchor` |  |
+
+
+
+### Examples
+
+#### Modal dialog
+
+`is-modal` opens the dialog as a modal, blocking interaction with the rest
+of the page until it's closed (using native `::backdrop`). Without that attribute,
+the dialog is opened without a backdrop.
+
+If using Valence.css, setting `.absolute` on the `dialog` element will display it `absolute`
+in the surrounding content (as opposed to fixed).
+
+
+```html
+<div>
+  <dialog-anchor role="button" target-ref="#da-modal" is-modal>
+    Open as modal
+  </dialog-anchor>
+  <dialog-anchor role="button" target-ref="#da-modal">
+    Open as non-modal
+  </dialog-anchor>
+  <dialog id="da-modal">
+    <article>
+      <header>
+        <dialog-anchor role="button" rel="prev"></dialog-anchor>
+        <h4>Modal dialogs block interaction with the rest of the page.</h4>
+        <p>This dialog is shown with Valence.css styling</p>
+      </header>
+      <p>Dialog content</p>
+      <footer>
+        Footer content
+      </footer>
+    </article>
+  </dialog>
+</div>
+```
+
+
+#### Close on a custom event
+
+`listen-for` swaps the default `click` for any event. Pair it with a real
+`<super-form>`'s `super-form-success` event to auto-close a dialog
+once a form inside it succeeds — simulated here with `<event-handler>`.
+
+
+```html
+<div>
+  <dialog-anchor role="button" target-ref="#da-auto" is-modal>Open form</dialog-anchor>
+  <dialog id="da-auto">
+    <dialog-anchor listen-for="super-form-success">
+      <p>Simulating a form submit…</p>
+      <event-handler role="button" fire-event="super-form-success">
+        Submit
+      </event-handler>
+    </dialog-anchor>
+  </dialog>
+</div>
+```

package/support/docs/INTERNAL.md

@@ -0,0 +1 @@
+Will probably deprecate this element now that `<button command commandfor>` and `event-handler[command-name]` cover invoking dialogs and popovers.

package/support/docs/README.md

@@ -0,0 +1,58 @@
+# dialog-anchor
+
+Open and close a native `<dialog>` — no JavaScript required.
+
+<include-content data-demo="simple"></include-content>
+
+## Features
+
+- **Click to toggle** Opens / closes a `<dialog>` on click
+- **Target or fallback** Point at any `<dialog>` via `target-ref`, or let
+  it find the nearest ancestor automatically (great for close buttons)
+- **Modal or non-modal** `is-modal` blocks the rest of the page; omit it
+  for a lightweight, dismissible popover
+- **Any trigger event** Inherits `listen-for` to open/close on custom
+  events instead of `click`
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Wrap a trigger in `<dialog-anchor>` and point it at a `<dialog>`. A
+`<dialog-anchor>` with no `target-ref`, placed inside the `<dialog>` it
+should close, needs no configuration at all.
+
+```html
+<dialog-anchor target-ref="#confirm" role="button">Delete</dialog-anchor>
+<dialog id="confirm">
+  <p>Are you sure?</p>
+  <dialog-anchor role="button">Cancel</dialog-anchor>
+</dialog>
+```
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Modal dialog
+
+`is-modal` opens the dialog as a modal, blocking interaction with the rest
+of the page until it's closed (using native `::backdrop`). Without that attribute,
+the dialog is opened without a backdrop.
+
+If using Valence.css, setting `.absolute` on the `dialog` element will display it `absolute`
+in the surrounding content (as opposed to fixed).
+
+<include-content data-demo="is-modal"></include-content>
+
+#### Close on a custom event
+
+`listen-for` swaps the default `click` for any event. Pair it with a real
+`<super-form>`'s `super-form-success` event to auto-close a dialog
+once a form inside it succeeds — simulated here with `<event-handler>`.
+
+<include-content data-demo="auto-close"></include-content>

package/support/package-meta.json

@@ -0,0 +1,199 @@
+{
+  "shortName": "dialog-anchor",
+  "package": {
+    "name": "@excom/dialog-anchor",
+    "version": "0.1.0",
+    "description": "<dialog-anchor> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "auto-close": "<div>\n  <dialog-anchor role=\"button\" target-ref=\"#da-auto\" is-modal>Open form</dialog-anchor>\n  <dialog id=\"da-auto\">\n    <dialog-anchor listen-for=\"super-form-success\">\n      <p>Simulating a form submit…</p>\n      <event-handler role=\"button\" fire-event=\"super-form-success\">\n        Submit\n      </event-handler>\n    </dialog-anchor>\n  </dialog>\n</div>\n",
+    "is-modal": "<div>\n  <dialog-anchor role=\"button\" target-ref=\"#da-modal\" is-modal>\n    Open as modal\n  </dialog-anchor>\n  <dialog-anchor role=\"button\" target-ref=\"#da-modal\">\n    Open as non-modal\n  </dialog-anchor>\n  <dialog id=\"da-modal\">\n    <article>\n      <header>\n        <dialog-anchor role=\"button\" rel=\"prev\"></dialog-anchor>\n        <h4>Modal dialogs block interaction with the rest of the page.</h4>\n        <p>This dialog is shown with Valence.css styling</p>\n      </header>\n      <p>Dialog content</p>\n      <footer>\n        Footer content\n      </footer>\n    </article>\n  </dialog>\n</div>",
+    "simple": "<div>\n  <dialog-anchor role=\"button\" target-ref=\"#da-simple\" is-modal>Open dialog</dialog-anchor>\n  <dialog id=\"da-simple\">\n    <p>A native, modal dialog.</p>\n    <dialog-anchor role=\"button\">Close</dialog-anchor>\n  </dialog>\n</div>\n"
+  },
+  "readme": "<h1 id=\"md-dialog-anchor\">dialog-anchor</h1>\n<p>Open and close a native <code>&lt;dialog&gt;</code> — no JavaScript required.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Click to toggle</strong> Opens / closes a <code>&lt;dialog&gt;</code> on click</li>\n<li><strong>Target or fallback</strong> Point at any <code>&lt;dialog&gt;</code> via <code>target-ref</code>, or let\nit find the nearest ancestor automatically (great for close buttons)</li>\n<li><strong>Modal or non-modal</strong> <code>is-modal</code> blocks the rest of the page; omit it\nfor a lightweight, dismissible popover</li>\n<li><strong>Any trigger event</strong> Inherits <code>listen-for</code> to open/close on custom\nevents instead of <code>click</code></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>Wrap a trigger in <code>&lt;dialog-anchor&gt;</code> and point it at a <code>&lt;dialog&gt;</code>. A\n<code>&lt;dialog-anchor&gt;</code> with no <code>target-ref</code>, placed inside the <code>&lt;dialog&gt;</code> it\nshould close, needs no configuration at all.</p>\n<include-content data-language=\"html\"><template>&lt;dialog-anchor target-ref=\"#confirm\" role=\"button\"&gt;Delete&lt;/dialog-anchor&gt;\n&lt;dialog id=\"confirm\"&gt;\n  &lt;p&gt;Are you sure?&lt;/p&gt;\n  &lt;dialog-anchor role=\"button\"&gt;Cancel&lt;/dialog-anchor&gt;\n&lt;/dialog&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-modal-dialog\">Modal dialog</h4>\n<p><code>is-modal</code> opens the dialog as a modal, blocking interaction with the rest\nof the page until it&#39;s closed (using native <code>::backdrop</code>). Without that attribute,\nthe dialog is opened without a backdrop.</p>\n<p>If using Valence.css, setting <code>.absolute</code> on the <code>dialog</code> element will display it <code>absolute</code>\nin the surrounding content (as opposed to fixed).</p>\n<p><include-content data-demo=\"is-modal\"></include-content></p>\n<h4 id=\"md-close-on-a-custom-event\">Close on a custom event</h4>\n<p><code>listen-for</code> swaps the default <code>click</code> for any event. Pair it with a real\n<code>&lt;super-form&gt;</code>&#39;s <code>super-form-success</code> event to auto-close a dialog\nonce a form inside it succeeds — simulated here with <code>&lt;event-handler&gt;</code>.</p>\n<p><include-content data-demo=\"auto-close\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-dialog-anchor\">dialog-anchor</h1>\n<p>Open and close a native <code>&lt;dialog&gt;</code> — no JavaScript required.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Click to toggle</strong> Opens / closes a <code>&lt;dialog&gt;</code> on click</li>\n<li><strong>Target or fallback</strong> Point at any <code>&lt;dialog&gt;</code> via <code>target-ref</code>, or let\nit find the nearest ancestor automatically (great for close buttons)</li>\n<li><strong>Modal or non-modal</strong> <code>is-modal</code> blocks the rest of the page; omit it\nfor a lightweight, dismissible popover</li>\n<li><strong>Any trigger event</strong> Inherits <code>listen-for</code> to open/close on custom\nevents instead of <code>click</code></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>Wrap a trigger in <code>&lt;dialog-anchor&gt;</code> and point it at a <code>&lt;dialog&gt;</code>. A\n<code>&lt;dialog-anchor&gt;</code> with no <code>target-ref</code>, placed inside the <code>&lt;dialog&gt;</code> it\nshould close, needs no configuration at all.</p>\n<include-content data-language=\"html\"><template>&lt;dialog-anchor target-ref=\"#confirm\" role=\"button\"&gt;Delete&lt;/dialog-anchor&gt;\n&lt;dialog id=\"confirm\"&gt;\n  &lt;p&gt;Are you sure?&lt;/p&gt;\n  &lt;dialog-anchor role=\"button\"&gt;Cancel&lt;/dialog-anchor&gt;\n&lt;/dialog&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-modal-dialog\">Modal dialog</h4>\n<p><code>is-modal</code> opens the dialog as a modal, blocking interaction with the rest\nof the page until it&#39;s closed (using native <code>::backdrop</code>). Without that attribute,\nthe dialog is opened without a backdrop.</p>\n<p>If using Valence.css, setting <code>.absolute</code> on the <code>dialog</code> element will display it <code>absolute</code>\nin the surrounding content (as opposed to fixed).</p>\n<p><include-content data-demo=\"is-modal\"></include-content></p>\n<h4 id=\"md-close-on-a-custom-event\">Close on a custom event</h4>\n<p><code>listen-for</code> swaps the default <code>click</code> for any event. Pair it with a real\n<code>&lt;super-form&gt;</code>&#39;s <code>super-form-success</code> event to auto-close a dialog\nonce a form inside it succeeds — simulated here with <code>&lt;event-handler&gt;</code>.</p>\n<p><include-content data-demo=\"auto-close\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/dialog-anchor",
+    "shortName": "dialog-anchor",
+    "version": "0.1.0",
+    "description": "<dialog-anchor> custom element",
+    "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/dialog-anchor@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/dialog-anchor@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/dialog-anchor"
+    },
+    "imports": {
+      "js": "import \"@excom/dialog-anchor\";",
+      "css": "@import \"@excom/dialog-anchor\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/dialog-anchor\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/dialog-anchor\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "dialog-anchor",
+      "summary": "Open/close a <code>&lt;dialog&gt;</code> — by selector or nearest ancestor.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "delay-ms",
+          "type": "number",
+          "description": "Delay handling by this many milliseconds.",
+          "fieldName": "delayMs",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "host-ref",
+          "type": "string",
+          "description": "Listen on another element / <code>window</code> / <code>document</code> — e.g. Escape to dismiss a dialog from a global <code>keydown</code>. Defaults to <code>:scope</code>. Used with <code>listen-for</code>. Not compatible with <code>listen-for-lifecycle</code>. The selector MUST resolve when <code>host-ref</code> is set — it will not wait for a match to appear.",
+          "fieldName": "hostRef",
+          "surface": "option",
+          "values": "<CSS Selector> | \"window\" | \"document\" | \"html\" | \"body\" | \"head\"",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "is-debounced",
+          "type": "boolean",
+          "description": "With <code>delay-ms</code>, coalesce bursts into one trailing call (debounce).",
+          "fieldName": "isDebounced",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "is-modal",
+          "type": "boolean",
+          "description": "Open the dialog as a modal (blocks the rest of the page) instead of a non-modal popover.",
+          "fieldName": "isModal",
+          "surface": "option"
+        },
+        {
+          "name": "keycode-filter",
+          "type": "tokenlist",
+          "description": "Space-separated key filters (OR). Join modifiers with <code>+</code> (AND, any order): <code>shift+k tab</code> → Shift+K or Tab. Modifiers: <code>shift</code>, <code>alt</code>, <code>ctrl</code>/<code>control</code>, <code>meta</code>. Case-insensitive.",
+          "fieldName": "keycodeFilter",
+          "surface": "option",
+          "values": "<key | mod+key>…",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "listen-for",
+          "type": "tokenlist",
+          "description": "Space-separated event names to listen for. Defaults to <code>click</code> when unset (and no lifecycle list is set).",
+          "fieldName": "listenFor",
+          "surface": "option",
+          "values": "<EventName>…",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "listen-for-lifecycle",
+          "type": "tokenlist",
+          "description": "Space-separated element lifecycles to handle.",
+          "fieldName": "listenForLifecycle",
+          "surface": "option",
+          "values": "\"connected\" | \"disconnected\" | \"adopted\"",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "listen-once",
+          "type": "boolean",
+          "description": "Handle each distinct event name / lifecycle at most once.",
+          "fieldName": "listenOnce",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "pathname-filter",
+          "type": "tokenlist",
+          "description": "Only handle when <code>location.pathname</code> is one of these values — route-aware behaviors without a separate router element.",
+          "fieldName": "pathnameFilter",
+          "surface": "option",
+          "values": "<pathname>…",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "prevent-default",
+          "type": "boolean",
+          "description": "Call <code>preventDefault()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "preventDefault",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "selector-filter",
+          "type": "string",
+          "description": "Only handle events whose <code>event.target</code> matches this CSS selector. Does not support <code>:scope</code> in the selector.",
+          "fieldName": "selectorFilter",
+          "surface": "option",
+          "values": "<CSS Selector>",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "stop-immediate-propagation",
+          "type": "boolean",
+          "description": "Call <code>stopImmediatePropagation()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "stopImmediatePropagation",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "stop-propagation",
+          "type": "boolean",
+          "description": "Call <code>stopPropagation()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "stopPropagation",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "target-ref",
+          "type": "string",
+          "description": "CSS selector for the <code>&lt;dialog&gt;</code> to toggle. If omitted, the element toggles the nearest ancestor <code>&lt;dialog&gt;</code>.",
+          "fieldName": "targetRef",
+          "surface": "option",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "vibrate-ms",
+          "type": "number",
+          "description": "Vibrate on handle (<code>navigator.vibrate</code>). Empty / <code>0</code> uses a 20ms pulse.",
+          "fieldName": "vibrateMs",
+          "surface": "option",
+          "default": "\"20 (when attribute is present with no value)\"",
+          "inheritedFrom": "@excom/listenable-element"
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [
+        {
+          "name": "unstyled",
+          "description": "Skip the pointer cursor from the listenable mixin."
+        }
+      ],
+      "cssAliases": [
+        {
+          "name": ":--dialog-anchor",
+          "selectors": [
+            "dialog-anchor",
+            ".tag-dialog-anchor"
+          ],
+          "kind": "element",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/auto-close.view.test.ts

@@ -0,0 +1,31 @@
+import "@excom/event-handler";
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  click,
+  flush,
+  mountView,
+  readDemo,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("auto-close view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("closes the dialog on simulated submit success", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "auto-close"));
+    const dialog = root.querySelector("dialog")!;
+    click(root.querySelector("[target-ref]"));
+    await flush();
+    expect(dialog.open).toBe(true);
+    click(dialog.querySelector("[role='button']"));
+    await flush();
+    expect(dialog.open).toBe(false);
+  });
+});

package/support/tests/dialog-anchor.test.ts

@@ -0,0 +1,102 @@
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import "../../index";
+
+describe("dialog-anchor", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("opens and closes dialog properly", async () => {
+    fixture<HTMLDivElement>(
+      `<div>
+        <dialog-anchor target-ref="dialog" id="c"></dialog-anchor>
+      </div>
+      <dialog>
+        <dialog-anchor id="b"></dialog-anchor>
+      </dialog>
+      <dialog-anchor is-modal target-ref="dialog:has(+:scope)" id="a"></dialog-anchor>`,
+    );
+    const dialogAnchor1 = document.querySelector(
+      "#a",
+    ) as HTMLDialogAnchorElement;
+    const dialogAnchor2 = document.querySelector(
+      "#b",
+    ) as HTMLDialogAnchorElement;
+    const dialogAnchor3 = document.querySelector(
+      "#c",
+    ) as HTMLDialogAnchorElement;
+    const dialog = document.querySelector("dialog")!;
+    const showSpy = vi.spyOn(dialog, "show");
+    const showModalSpy = vi.spyOn(dialog, "showModal");
+    const closeSpy = vi.spyOn(dialog, "close");
+
+    expect(dialog.open).toBe(false);
+
+    // modal, previous sibling
+    dialogAnchor1.dispatchEvent(new Event("click"));
+    expect(showModalSpy).toHaveBeenCalled();
+    expect(showSpy).not.toHaveBeenCalled();
+    expect(closeSpy).not.toHaveBeenCalled();
+
+    // close, child
+    dialogAnchor2.dispatchEvent(new Event("click"));
+    expect(closeSpy).toHaveBeenCalled();
+
+    // non-modal, target-ref
+    dialogAnchor3.dispatchEvent(new Event("click"));
+    expect(showSpy).toHaveBeenCalled();
+    expect(dialog.open).toBe(true);
+
+    // toggle
+    dialogAnchor3.dispatchEvent(new Event("click"));
+    expect(closeSpy).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("dialog-anchor (no dialog)", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("does nothing when neither target-ref nor an ancestor resolves to a dialog", () => {
+    const wrapper = fixture<HTMLDivElement>(
+      `<div>
+        <p id="not-a-dialog"></p>
+        <dialog-anchor target-ref="#not-a-dialog" id="x"></dialog-anchor>
+        <dialog-anchor target-ref="#missing" id="y"></dialog-anchor>
+        <dialog-anchor id="z"></dialog-anchor>
+      </div>`,
+    );
+    const showSpy = vi.spyOn(HTMLDialogElement.prototype, "show");
+    const showModalSpy = vi.spyOn(HTMLDialogElement.prototype, "showModal");
+    const closeSpy = vi.spyOn(HTMLDialogElement.prototype, "close");
+    wrapper.querySelectorAll("dialog-anchor").forEach((anchor) => {
+      expect(() => anchor.dispatchEvent(new Event("click"))).not.toThrow();
+    });
+    expect(showSpy).not.toHaveBeenCalled();
+    expect(showModalSpy).not.toHaveBeenCalled();
+    expect(closeSpy).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the closest dialog when target-ref is not a dialog", () => {
+    fixture<HTMLDialogElement>(
+      `<dialog>
+        <p id="inner-p"></p>
+        <dialog-anchor target-ref="#inner-p" is-modal></dialog-anchor>
+      </dialog>`,
+    );
+    const dialog = document.querySelector("dialog")!;
+    const showModalSpy = vi.spyOn(dialog, "showModal");
+    document.querySelector("dialog-anchor")!.dispatchEvent(new Event("click"));
+    expect(showModalSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/support/tests/is-modal.view.test.ts

@@ -0,0 +1,34 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  click,
+  flush,
+  mountView,
+  readDemo,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("is-modal view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("opens modal and non-modal", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "is-modal"));
+    const dialog = root.querySelector("dialog")!;
+    const [modalBtn, modelessBtn] = root.querySelectorAll(
+      "dialog-anchor[target-ref]",
+    );
+    click(modalBtn);
+    await flush();
+    expect(dialog.open).toBe(true);
+    dialog.close();
+    click(modelessBtn);
+    await flush();
+    expect(dialog.open).toBe(true);
+  });
+});

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

@@ -0,0 +1,31 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  click,
+  flush,
+  mountView,
+  readDemo,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("simple view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("opens and closes the dialog", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "simple"));
+    const dialog = root.querySelector("dialog")!;
+    expect(dialog.open).toBe(false);
+    click(root.querySelector("[target-ref]"));
+    await flush();
+    expect(dialog.open).toBe(true);
+    click(dialog.querySelector("dialog-anchor"));
+    await flush();
+    expect(dialog.open).toBe(false);
+  });
+});

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"]
+}