@excom/kit-shims 0.1.0

package/.rush/temp/chunked-rush-logs/kit-shims.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/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": 32.23579199999995
+}

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

@@ -0,0 +1,3 @@
+{
+  "../../packages/kit-shims": "../../packages/kit-shims:DpFAJ6l9NZ7PxsGv74etlzI4VS4IyRu5jGEhInb3gEw=:"
+}

package/close-watcher-polyfill.ts

@@ -0,0 +1,131 @@
+const closeWatcherStack: CloseWatcher[] = [];
+class CloseWatcher extends EventTarget {
+  #isActive = true;
+  #firingCancelEvent = false;
+  #oncancelHandler = null;
+  #oncloseHandler = null;
+
+  constructor({ signal }: { signal?: AbortSignal } = {}) {
+    super();
+    // No user-activation check. Real CloseWatcher would sometimes group
+    // with previous watchers; this polyfill never does.
+
+    if (signal) {
+      if (signal.aborted) {
+        this.#isActive = false;
+        return;
+      }
+      signal.addEventListener("abort", () => this.#deactivate());
+    }
+
+    closeWatcherStack.push(this);
+  }
+
+  destroy() {
+    this.#deactivate();
+  }
+
+  close() {
+    if (!this.#isActive || !document.defaultView) {
+      return;
+    }
+
+    this.dispatchEvent(new Event("close"));
+
+    this.#deactivate();
+  }
+
+  requestClose() {
+    if (!this.#isActive) {
+      return;
+    }
+    if (this.#firingCancelEvent) {
+      return;
+    }
+
+    // No user-activation check. Real CloseWatcher would sometimes skip
+    // `cancel`; this polyfill always fires it.
+
+    this.#firingCancelEvent = true;
+    const shouldContinue = this.dispatchEvent(
+      new Event("cancel", { cancelable: true })
+    );
+    this.#firingCancelEvent = false;
+    if (!shouldContinue) {
+      return;
+    }
+
+    if (this.#isActive && document.defaultView) {
+      this.dispatchEvent(new Event("close"));
+    }
+    this.#deactivate();
+  }
+
+  #deactivate() {
+    this.#isActive = false;
+
+    // May not be top of stack if `destroy()` ran.
+    const index = closeWatcherStack.indexOf(this);
+    if (index !== -1) {
+      closeWatcherStack.splice(index, 1);
+    }
+  }
+
+  get oncancel() {
+    return this.#oncancelHandler;
+  }
+  set oncancel(handler) {
+    if (handler !== this.#oncancelHandler || handler === null) {
+      this.removeEventListener("cancel", this.#oncancelHandler);
+      this.#oncancelHandler = null;
+      return;
+    }
+
+    this.#oncancelHandler = handler;
+    this.addEventListener("cancel", this.#oncancelHandler);
+  }
+
+  get onclose() {
+    return this.#oncancelHandler;
+  }
+  set onclose(handler) {
+    if (handler !== this.#oncloseHandler || handler === null) {
+      this.removeEventListener("close", this.#oncloseHandler);
+      this.#oncloseHandler = null;
+      return;
+    }
+
+    this.#oncloseHandler = handler;
+    this.addEventListener("close", this.#oncloseHandler);
+  }
+}
+
+// Escape keydowns only. No Android back button (or other close signals).
+document.addEventListener("keydown", (e) => {
+  if (!e.isTrusted) {
+    // Not a user-triggered keydown.
+    return;
+  }
+
+  if (e.key !== "Escape") {
+    return;
+  }
+
+  const closeWatcher = closeWatcherStack.at(-1);
+  if (!closeWatcher) {
+    return;
+  }
+
+  /* Let other listeners run first. Queue a task; `queueMicrotask()`
+     empties between each listener for browser-triggered events. */
+  setTimeout(() => {
+    if (e.defaultPrevented) {
+      // Another listener canceled; don't deliver to CloseWatcher.
+      return;
+    }
+
+    closeWatcher.requestClose();
+  }, 0);
+});
+
+export { CloseWatcher };

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/idle-cb.ts

@@ -0,0 +1,30 @@
+export const requestIdleCb = (
+  cb: (arg?: { didTimeout: boolean; timeRemaining: () => number }) => void,
+  fallbackDelay: number = 1
+) => {
+  if (window.requestIdleCallback) {
+    /* Use the caller delay as a timeout so idle work can't race ahead of
+       "wait until after paint" (Safari fallback already uses
+       `fallbackDelay` as setTimeout ms). */
+    return window.requestIdleCallback(cb, { timeout: fallbackDelay });
+  } else {
+    const start = Date.now();
+    return setTimeout(() => {
+      cb({
+        didTimeout: false,
+        timeRemaining: () => Math.max(0, 50 - (Date.now() - start)),
+      });
+    }, fallbackDelay);
+  }
+};
+
+/*
+ * unused
+ * export const cancelIdleCb = (id: number) => {
+ *   if (window.cancelIdleCallback) {
+ *     window.cancelIdleCallback(id);
+ *   } else {
+ *     clearTimeout(id);
+ *   }
+ * };
+ */

package/index.ts

@@ -0,0 +1,2 @@
+export { CloseWatcher } from "./close-watcher-polyfill";
+export { requestIdleCb } from "./idle-cb";

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@excom/kit-shims",
+  "version": "0.1.0",
+  "description": "kit-shims library",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {},
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/kit-shims"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/kit-shims/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "kit-shims"
+  ],
+  "excom": {
+    "documented": false,
+    "packageType": "library"
+  },
+  "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"
+  }
+}

package/rush-logs/kit-shims.apply-exports.cache.log

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

package/rush-logs/kit-shims.apply-exports.log

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

package/support/tests/close-watcher.test.ts

@@ -0,0 +1,226 @@
+import { CloseWatcher, requestIdleCb } from "../../index";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/node_modules/vitest";
+
+/** Dispatch a keydown that the polyfill treats as user-triggered. */
+const pressKey = (key: string, { prevent = false } = {}) => {
+  const evt = new KeyboardEvent("keydown", { key, cancelable: true });
+  // happy-dom does not model `isTrusted`; the polyfill only honours trusted keydowns.
+  Object.defineProperty(evt, "isTrusted", { value: true });
+  if (prevent) {
+    document.addEventListener("keydown", (e) => e.preventDefault(), {
+      once: true,
+    });
+  }
+  document.dispatchEvent(evt);
+  return evt;
+};
+
+describe("index", () => {
+  it("re-exports the shims", () => {
+    expect(typeof CloseWatcher).toBe("function");
+    expect(typeof requestIdleCb).toBe("function");
+  });
+});
+
+describe("CloseWatcher", () => {
+  const live: CloseWatcher[] = [];
+  const make = (opts?: { signal?: AbortSignal }) => {
+    const w = new CloseWatcher(opts);
+    live.push(w);
+    return w;
+  };
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    // Empty the module-level stack so tests stay independent.
+    while (live.length) live.pop()!.destroy();
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("is an EventTarget", () => {
+    const w = make();
+    expect(w).toBeInstanceOf(EventTarget);
+  });
+
+  it("close() fires close once and then deactivates", () => {
+    const w = make();
+    const onClose = vi.fn();
+    w.addEventListener("close", onClose);
+    w.close();
+    w.close();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("requestClose() fires cancel then close", () => {
+    const w = make();
+    const order: string[] = [];
+    w.addEventListener("cancel", () => order.push("cancel"));
+    w.addEventListener("close", () => order.push("close"));
+    w.requestClose();
+    expect(order).toEqual(["cancel", "close"]);
+    // Deactivated: subsequent calls are no-ops.
+    w.requestClose();
+    w.close();
+    expect(order).toEqual(["cancel", "close"]);
+  });
+
+  it("cancel event is cancelable and preventDefault() stops close", () => {
+    const w = make();
+    const onClose = vi.fn();
+    let cancelable = false;
+    w.addEventListener("cancel", (e) => {
+      cancelable = e.cancelable;
+      e.preventDefault();
+    });
+    w.addEventListener("close", onClose);
+    w.requestClose();
+    expect(cancelable).toBe(true);
+    expect(onClose).not.toHaveBeenCalled();
+    // Still active: a later requestClose without preventDefault closes.
+    w.addEventListener("cancel", (e) => e.stopImmediatePropagation(), {
+      capture: true,
+    });
+    w.close();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-entrant requestClose() from inside cancel is ignored", () => {
+    const w = make();
+    const onCancel = vi.fn(() => w.requestClose());
+    const onClose = vi.fn();
+    w.addEventListener("cancel", onCancel);
+    w.addEventListener("close", onClose);
+    w.requestClose();
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("destroy() deactivates without firing events", () => {
+    const w = make();
+    const onCancel = vi.fn();
+    const onClose = vi.fn();
+    w.addEventListener("cancel", onCancel);
+    w.addEventListener("close", onClose);
+    w.destroy();
+    w.requestClose();
+    w.close();
+    expect(onCancel).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("an already-aborted signal creates an inactive watcher", () => {
+    const ac = new AbortController();
+    ac.abort();
+    const w = make({ signal: ac.signal });
+    const onClose = vi.fn();
+    w.addEventListener("close", onClose);
+    w.requestClose();
+    w.close();
+    expect(onClose).not.toHaveBeenCalled();
+    // Not on the stack: Escape reaches nobody.
+    pressKey("Escape");
+    vi.runAllTimers();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("aborting the signal later destroys the watcher", () => {
+    const ac = new AbortController();
+    const w = make({ signal: ac.signal });
+    const onClose = vi.fn();
+    w.addEventListener("close", onClose);
+    ac.abort();
+    w.close();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("Escape keydown requests close on the top-most watcher only", () => {
+    const first = make();
+    const second = make();
+    const firstClose = vi.fn();
+    const secondClose = vi.fn();
+    first.addEventListener("close", firstClose);
+    second.addEventListener("close", secondClose);
+
+    pressKey("Escape");
+    // Delivered on a queued task so other keydown listeners run first.
+    expect(secondClose).not.toHaveBeenCalled();
+    vi.runAllTimers();
+    expect(secondClose).toHaveBeenCalledTimes(1);
+    expect(firstClose).not.toHaveBeenCalled();
+
+    // The stack unwinds: next Escape hits the first watcher.
+    pressKey("Escape");
+    vi.runAllTimers();
+    expect(firstClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("destroying a watcher mid-stack removes it from the stack", () => {
+    const bottom = make();
+    const middle = make();
+    const top = make();
+    const closes = { bottom: vi.fn(), middle: vi.fn(), top: vi.fn() };
+    bottom.addEventListener("close", closes.bottom);
+    middle.addEventListener("close", closes.middle);
+    top.addEventListener("close", closes.top);
+
+    middle.destroy();
+    pressKey("Escape");
+    vi.runAllTimers();
+    pressKey("Escape");
+    vi.runAllTimers();
+    expect(closes.top).toHaveBeenCalledTimes(1);
+    expect(closes.bottom).toHaveBeenCalledTimes(1);
+    expect(closes.middle).not.toHaveBeenCalled();
+  });
+
+  it("ignores Escape when another listener prevented default", () => {
+    const w = make();
+    const onClose = vi.fn();
+    w.addEventListener("close", onClose);
+    pressKey("Escape", { prevent: true });
+    vi.runAllTimers();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("ignores non-Escape keys and untrusted keydowns", () => {
+    const w = make();
+    const onClose = vi.fn();
+    w.addEventListener("close", onClose);
+    pressKey("Enter");
+    document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    vi.runAllTimers();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("Escape with an empty stack is a no-op", () => {
+    expect(() => {
+      pressKey("Escape");
+      vi.runAllTimers();
+    }).not.toThrow();
+  });
+
+  it("oncancel / onclose accessors", () => {
+    const w = make();
+    const handler = () => {};
+    expect(w.oncancel).toBeNull();
+    expect(w.onclose).toBeNull();
+    w.oncancel = handler as any;
+    w.onclose = handler as any;
+    w.oncancel = null;
+    w.onclose = null;
+    expect(w.oncancel).toBeNull();
+    expect(w.onclose).toBeNull();
+  });
+});

package/support/tests/kit-shims.test.ts

@@ -0,0 +1,62 @@
+import { requestIdleCb } from "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/node_modules/vitest";
+
+describe("requestIdleCb", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("falls back to setTimeout when requestIdleCallback is missing", () => {
+    vi.useFakeTimers();
+    const cb = vi.fn();
+    const id = requestIdleCb(cb, 10);
+    expect(id).toBeTruthy();
+    vi.advanceTimersByTime(10);
+    expect(cb).toHaveBeenCalled();
+  });
+
+  it("provides didTimeout and timeRemaining in fallback", () => {
+    vi.useFakeTimers();
+    let received: any;
+    requestIdleCb((arg) => {
+      received = arg;
+    }, 5);
+    vi.advanceTimersByTime(5);
+    expect(received).toBeDefined();
+    expect(received.didTimeout).toBe(false);
+    expect(typeof received.timeRemaining).toBe("function");
+    expect(received.timeRemaining()).toBeGreaterThanOrEqual(0);
+    expect(received.timeRemaining()).toBeLessThanOrEqual(50);
+  });
+
+  it("uses default fallback delay of 1ms", () => {
+    vi.useFakeTimers();
+    const cb = vi.fn();
+    requestIdleCb(cb);
+    vi.advanceTimersByTime(0);
+    expect(cb).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(cb).toHaveBeenCalled();
+  });
+
+  it("uses native requestIdleCallback when available", () => {
+    const nativeCb = vi.fn((cb) => {
+      cb();
+      return 99;
+    });
+    vi.stubGlobal("requestIdleCallback", nativeCb);
+    const handler = vi.fn();
+    requestIdleCb(handler, 17);
+    expect(nativeCb).toHaveBeenCalledWith(handler, { timeout: 17 });
+    expect(handler).toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+});
+

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