@excom/dismiss-watcher 0.1.0

package/.rush/temp/chunked-rush-logs/dismiss-watcher.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/dismiss-watcher.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/dismiss-watcher.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.36495500000001
+}

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

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

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

@@ -0,0 +1,3 @@
+{
+  "../../packages/dismiss-watcher": "../../packages/dismiss-watcher:crnI8zrhGnIZQxhLw4BKNf1dqfZ8PVcoMDfa7J8QXek=:"
+}

package/config/rig.json

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

package/dismiss-watcher.ts

@@ -0,0 +1,209 @@
+import { CloseWatcher } from "@excom/kit-shims";
+import { selectOne } from "@excom/kit-utils";
+import {
+  ConstructorType,
+  Neutron,
+  TEvent,
+  TokenList,
+} from "@excom/neutron";
+
+export type DismissWatcherReason = "escape" | "outside-click";
+
+export type DismissWatcherDismissEvent = TEvent & {
+  type: "dismiss-watcher-dismiss";
+  detail: { reason: DismissWatcherReason };
+};
+
+const DISMISS_EVENT = "dismiss-watcher-dismiss";
+const OUTSIDE_EVENT = "mouseup";
+
+/**
+ * Dismissal-request Adapter for drawers, menus, dialogs and popovers. While
+ * `is-active` it watches for Escape / the platform back gesture (through a
+ * `CloseWatcher`) and for a `mouseup` outside its target, then fires
+ * `dismiss-watcher-dismiss`. The default action invokes each `command-name`
+ * (`--close`) and dispatches each `fire-event` name at the target;
+ * `preventDefault()` keeps the panel open. Renders nothing — drop it inside
+ * the element being dismissed, or point `target-ref` at it.
+ *
+ * @summary Escape / back-gesture and outside-click dismissal for any panel.
+ *
+ * @fires dismiss-watcher-dismiss - A dismissal was requested; `detail.reason`
+ *   is `"escape"` or `"outside-click"`. Default action: invoke each
+ *   `command-name` on the target and dispatch each `fire-event` name at it
+ *   as a bubbling `CustomEvent`. `preventDefault()` skips both.
+ * @type DismissWatcherDismissEvent
+ */
+export const DismissWatcher = Neutron({
+  tag: "dismiss-watcher",
+  props: {
+    /**
+     * @option
+     * @state
+     * Watchers are live while set. Gate it from Quark on the panel's open
+     * state, and write the inverse rule.
+     */
+    isActive: Boolean,
+    /**
+     * @option
+     * Watch Escape / the back gesture through a `CloseWatcher`. When neither
+     * `watch-*` attribute is present both watchers are on.
+     */
+    watchEscape: Boolean,
+    /**
+     * @option
+     * Watch for a `mouseup` on the document outside the target. When neither
+     * `watch-*` attribute is present both watchers are on.
+     */
+    watchOutsideClick: Boolean,
+    /**
+     * @option
+     * Selector for the element being dismissed, `:scope`-relative
+     * (`:scope ~ nav`). Unset = the parent element.
+     */
+    targetRef: String,
+    /**
+     * @option
+     * Commands invoked on the target as the default action of
+     * `dismiss-watcher-dismiss` — `--close` for a `<content-drawer>`, or any
+     * `--verb` the panel handles.
+     * @values <command>…
+     */
+    commandName: TokenList,
+    /**
+     * @option
+     * Event names dispatched at the target (bubbling `CustomEvent`s) as the
+     * default action of `dismiss-watcher-dismiss`, for panels driven by
+     * events rather than commands (`menu-close`).
+     */
+    fireEvent: TokenList,
+    // private state
+    _closeWatcher: Object as unknown as ConstructorType<CloseWatcher>,
+  },
+})
+  .defineMethods({
+    _handleOutsideMouseup: (element, e: MouseEvent) => {
+      const target = resolveTarget(element);
+      if (!target || !(e.target instanceof Node) || target.contains(e.target)) {
+        return;
+      }
+      return {
+        emit: [DISMISS_EVENT, { detail: { reason: "outside-click" } }],
+      };
+    },
+    _handleClose: () => [
+      /* CloseWatcher deactivates after `close`: drop it and re-arm before
+         emitting, so a cancelled dismissal (`preventDefault()`) keeps Escape. */
+      { _closeWatcher: null },
+      { _apply: [] },
+      { emit: [DISMISS_EVENT, { detail: { reason: "escape" } }] },
+    ],
+  })
+  // Second `defineMethods` so the handlers above are typed on the element
+  .defineMethods({
+    _apply: ({
+      watchEscape,
+      watchOutsideClick,
+      _closeWatcher,
+      _handleClose,
+      _handleOutsideMouseup,
+    }) => {
+      // Neither `watch-*` set → both
+      const wantsEscape = !!watchEscape || !watchOutsideClick;
+      const wantsOutsideClick = !!watchOutsideClick || !watchEscape;
+      return [
+        wantsOutsideClick
+          ? {
+              addListener: [
+                OUTSIDE_EVENT,
+                _handleOutsideMouseup,
+                { target: document },
+              ],
+            }
+          : {
+              removeListener: [
+                OUTSIDE_EVENT,
+                _handleOutsideMouseup,
+                { target: document },
+              ],
+            },
+        wantsEscape
+          ? !_closeWatcher && {
+              _closeWatcher: createCloseWatcher(_handleClose),
+            }
+          : !!_closeWatcher && {
+              _closeWatcher: destroyCloseWatcher(_closeWatcher, _handleClose),
+            },
+      ].filter(Boolean);
+    },
+    _teardown: ({ _closeWatcher, _handleClose, _handleOutsideMouseup }) =>
+      [
+        {
+          removeListener: [
+            OUTSIDE_EVENT,
+            _handleOutsideMouseup,
+            { target: document },
+          ],
+        },
+        !!_closeWatcher && {
+          _closeWatcher: destroyCloseWatcher(_closeWatcher, _handleClose),
+        },
+      ].filter(Boolean),
+  })
+  .onPropSet("isActive", () => ({ _apply: [] }))
+  .onPropUnset("isActive", () => ({ _teardown: [] }))
+  .onPropChanged(
+    ["watchEscape", "watchOutsideClick", "targetRef"],
+    ({ isActive }) => !!isActive && { _apply: [] }
+  )
+  .onConnected(
+    ({ wasMounted, isActive, isMoving }) =>
+      // Real reconnect rebuilds; first mount is the prop flush
+      wasMounted && !!isActive && !isMoving && { _apply: [] }
+  )
+  .onDisconnected(
+    ({ isMoving }) =>
+      // Neutron restores tracked listeners on a move; keep the watcher too
+      !isMoving && { _teardown: [] }
+  )
+  .onEventDefault(DISMISS_EVENT, (element) => {
+    const target = resolveTarget(element);
+    const commands = element.commandName || [];
+    const names = element.fireEvent || [];
+    return (
+      !!target && [
+        commands.length > 0 && {
+          commands: commands.map((name) => [name, { target }]),
+        },
+        names.length > 0 && {
+          emits: names.map((type) => [type, { target }]),
+        },
+      ]
+    );
+  });
+
+/** `target-ref`, `:scope`-relative to the watcher; default = parent. */
+function resolveTarget(
+  element: HTMLElement & { targetRef?: string | null }
+): HTMLElement | null {
+  return element.targetRef
+    ? selectOne(element.targetRef, { scope: element })
+    : element.parentElement;
+}
+
+function createCloseWatcher(onClose: EventListener) {
+  const watcher = new CloseWatcher();
+  watcher.addEventListener("close", onClose);
+  return watcher;
+}
+
+function destroyCloseWatcher(
+  watcher: CloseWatcher | null | undefined,
+  onClose: EventListener
+) {
+  if (watcher) {
+    watcher.removeEventListener("close", onClose);
+    watcher.destroy();
+  }
+  return null;
+}

package/index.ts

@@ -0,0 +1,21 @@
+import { DismissWatcher } from "./dismiss-watcher";
+
+DismissWatcher.define();
+
+export { DismissWatcher };
+export type {
+  DismissWatcherDismissEvent,
+  DismissWatcherReason,
+} from "./dismiss-watcher";
+
+type T_HTMLDismissWatcherElement = typeof DismissWatcher.CustomElement;
+declare global {
+  interface HTMLDismissWatcherElement extends T_HTMLDismissWatcherElement {}
+  interface Window {
+    HTMLDismissWatcherElement: HTMLDismissWatcherElement;
+  }
+  interface HTMLElementTagNameMap {
+    "dismiss-watcher": HTMLDismissWatcherElement;
+  }
+}
+export type { HTMLDismissWatcherElement };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@excom/dismiss-watcher",
+  "version": "0.1.0",
+  "description": "<dismiss-watcher> custom element",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/kit-utils": "^0.1.0",
+    "@excom/neutron": "^0.1.0",
+    "@excom/kit-shims": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/content-drawer": "^0.1.0",
+    "@excom/heft-rig": "^0.1.0",
+    "@excom/quark": "^0.1.0",
+    "@excom/event-handler": "^0.1.0",
+    "@excom/quark-sheet": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/dismiss-watcher"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/dismiss-watcher/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "dismiss-watcher",
+    "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/dismiss-watcher.apply-exports.cache.log

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

package/rush-logs/dismiss-watcher.apply-exports.log

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

package/rush-logs/dismiss-watcher.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/dismiss-watcher.build_docs.log

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

package/rush-logs/dismiss-watcher.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/dismiss-watcher.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,180 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "dismiss-watcher.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "DismissWatcher",
+          "customElement": true,
+          "tagName": "dismiss-watcher",
+          "summary": "Escape / back-gesture and outside-click dismissal for any panel.",
+          "description": "Dismissal-request Adapter for drawers, menus, dialogs and popovers. While `is-active` it watches for Escape / the platform back gesture (through a `CloseWatcher`) and for a `mouseup` outside its target, then fires `dismiss-watcher-dismiss`. The default action invokes each `command-name` (`--close`) and dispatches each `fire-event` name at the target; `preventDefault()` keeps the panel open. Renders nothing — drop it inside the element being dismissed, or point `target-ref` at it.",
+          "attributes": [
+            {
+              "name": "is-active",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Watchers are live while set. Gate it from Quark on the panel's open state, and write the inverse rule.",
+              "fieldName": "isActive"
+            },
+            {
+              "name": "watch-escape",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Watch Escape / the back gesture through a `CloseWatcher`. When neither `watch-*` attribute is present both watchers are on.",
+              "fieldName": "watchEscape"
+            },
+            {
+              "name": "watch-outside-click",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Watch for a `mouseup` on the document outside the target. When neither `watch-*` attribute is present both watchers are on.",
+              "fieldName": "watchOutsideClick"
+            },
+            {
+              "name": "target-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "Selector for the element being dismissed, `:scope`-relative (`:scope ~ nav`). Unset = the parent element.",
+              "fieldName": "targetRef"
+            },
+            {
+              "name": "command-name",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Commands invoked on the target as the default action of `dismiss-watcher-dismiss` — `--close` for a `<content-drawer>`, or any `--verb` the panel handles.",
+              "fieldName": "commandName",
+              "values": [
+                "<command>…"
+              ]
+            },
+            {
+              "name": "fire-event",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Event names dispatched at the target (bubbling `CustomEvent`s) as the default action of `dismiss-watcher-dismiss`, for panels driven by events rather than commands (`menu-close`).",
+              "fieldName": "fireEvent"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "isActive",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Watchers are live while set. Gate it from Quark on the panel's open state, and write the inverse rule.",
+              "_neutron": {
+                "surface": "hybrid"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "watchEscape",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Watch Escape / the back gesture through a `CloseWatcher`. When neither `watch-*` attribute is present both watchers are on.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "watchOutsideClick",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Watch for a `mouseup` on the document outside the target. When neither `watch-*` attribute is present both watchers are on.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "targetRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Selector for the element being dismissed, `:scope`-relative (`:scope ~ nav`). Unset = the parent element.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "commandName",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Commands invoked on the target as the default action of `dismiss-watcher-dismiss` — `--close` for a `<content-drawer>`, or any `--verb` the panel handles.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "fireEvent",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Event names dispatched at the target (bubbling `CustomEvent`s) as the default action of `dismiss-watcher-dismiss`, for panels driven by events rather than commands (`menu-close`).",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "dismiss-watcher-dismiss",
+              "description": "A dismissal was requested; `detail.reason` is `\"escape\"` or `\"outside-click\"`. Default action: invoke each `command-name` on the target and dispatch each `fire-event` name at it as a bubbling `CustomEvent`. `preventDefault()` skips both.",
+              "type": {
+                "text": "DismissWatcherDismissEvent",
+                "expanded": "CustomEvent & { type: \"dismiss-watcher-dismiss\"; detail: { reason: \"escape\" | \"outside-click\" }; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DismissWatcher",
+          "declaration": {
+            "name": "DismissWatcher",
+            "module": "dismiss-watcher.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "dismiss-watcher",
+          "declaration": {
+            "name": "DismissWatcher",
+            "module": "dismiss-watcher.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/drawer.html

@@ -0,0 +1,19 @@
+<section>
+  <quark-sheet>
+    :scope {
+      content-drawer[is-open] dismiss-watcher { is-active: ""; }
+      content-drawer:not([is-open]) dismiss-watcher { is-active: none; }
+    }
+  </quark-sheet>
+  <button type="button" command="--open" commandfor="demo-dismiss-drawer">
+    Open drawer
+  </button>
+  <content-drawer id="demo-dismiss-drawer">
+    <dismiss-watcher watch-escape watch-outside-click command-name="--close"></dismiss-watcher>
+    <header>
+      <h2>Drawer</h2>
+    </header>
+    <p>Press Escape or click outside to close.</p>
+  </content-drawer>
+  <event-handler class="tag-backdrop" role="presentation" target-ref="content-drawer:has(+ :scope)" command-name="--close"></event-handler>
+</section>

package/support/demos/simple.html

@@ -0,0 +1,24 @@
+<div>
+  <quark-sheet>
+    :scope {
+      @on menu-open { data-is-open: ""; }
+      @on dismiss-watcher-dismiss { data-is-open: none; }
+      &[data-is-open] dismiss-watcher { is-active: ""; }
+      &:not([data-is-open]) dismiss-watcher { is-active: none; }
+    }
+  </quark-sheet>
+  <style>
+    [data-demo-menu] { display: none; }
+    [data-is-open] > [data-demo-menu] { display: block; }
+  </style>
+  <event-handler role="button" fire-event="menu-open">Open menu</event-handler>
+  <nav data-demo-menu>
+    <dismiss-watcher></dismiss-watcher>
+    <ul>
+      <li><a href="#">Profile</a></li>
+      <li><a href="#">Settings</a></li>
+      <li><a href="#">Sign out</a></li>
+    </ul>
+    <p>Press Escape or click outside to close.</p>
+  </nav>
+</div>