@excom/abortable-element 0.1.0

package/.rush/temp/chunked-rush-logs/abortable-element.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/abortable-element.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/abortable-element.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": 34.980425000000196
+}

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

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

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

@@ -0,0 +1,3 @@
+{
+  "../../packages/abortable-element": "../../packages/abortable-element:YAC8G8l1nkKknuTXH370JI0/DynCPkP81MNQcvbO6fA=:"
+}

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/index.ts

@@ -0,0 +1,22 @@
+import { Neutron } from "@excom/neutron";
+
+/**
+ * Composition base that owns an `AbortController` for cancellable async work. Subclasses call `doAbort()` to cancel in-flight operations and rotate a fresh controller. Used by `RenderableElement` (and thus `<include-content>`, `<spa-route>`) when template fetches are superseded.
+ *
+ * @summary AbortController ownership for Neutron elements.
+ */
+export const AbortableElement = Neutron({
+  tag: "noop-tag",
+  props: {
+    // private state
+    abortController: {
+      type: AbortController,
+      defaultValue: () => new AbortController(),
+    },
+  },
+}).defineMethods({
+  doAbort: ({ abortController }, reason?: any) => {
+    abortController?.abort(reason);
+    return { abortController: new AbortController() };
+  },
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@excom/abortable-element",
+  "version": "0.1.0",
+  "description": "AbortableElement base for Neutron elements",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/neutron": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/abortable-element"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/abortable-element/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "AbortableElement",
+    "abortable-element",
+    "neutron",
+    "kit-element-base",
+    "custom-elements"
+  ],
+  "excom": {
+    "packageType": "element-base"
+  },
+  "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/abortable-element.apply-exports.cache.log

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

package/rush-logs/abortable-element.apply-exports.log

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

package/rush-logs/abortable-element.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/abortable-element.build_docs.log

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

package/rush-logs/abortable-element.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/abortable-element.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,27 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "index.ts",
+      "declarations": [
+        {
+          "kind": "mixin",
+          "name": "AbortableElement",
+          "summary": "AbortController ownership for Neutron elements.",
+          "description": "Composition base that owns an `AbortController` for cancellable async work. Subclasses call `doAbort()` to cancel in-flight operations and rotate a fresh controller. Used by `RenderableElement` (and thus `<include-content>`, `<spa-route>`) when template fetches are superseded."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "AbortableElement",
+          "declaration": {
+            "name": "AbortableElement",
+            "module": "index.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/dist-docs/abortable-element.md

@@ -0,0 +1,72 @@
+# abortable-element
+
+AbortController ownership for Neutron elements — cancel in-flight
+work cleanly when a newer request supersedes it.
+
+## Features
+
+- **Owned controller** Fresh `AbortController` per in-flight cycle
+- **doAbort()** Abort current work and rotate a new controller
+- **Fetch-ready** Pass `abortController.signal` into `fetch` /
+  template loads
+
+## Installation
+
+
+`@excom/abortable-element` v0.1.0
+
+```bash
+pnpm add @excom/abortable-element
+```
+
+```bash
+npm install @excom/abortable-element
+```
+
+```bash
+yarn add @excom/abortable-element
+```
+
+### Import
+
+```ts
+import { /* … */ } from "@excom/abortable-element";
+```
+
+
+
+## Usage
+
+Compose `AbortableElement` and pass `abortController.signal` into
+async work. Call `doAbort()` when that work should be cancelled (e.g.
+`template-ref` changed). `RenderableElement` already does this for
+template fetches.
+
+```ts
+import { Neutron } from "@excom/neutron";
+import { AbortableElement } from "@excom/abortable-element";
+
+export const FetchOnce = Neutron.compose([
+  AbortableElement,
+  Neutron({
+    tag: "fetch-once",
+    props: { src: String },
+  }),
+])
+  .onPropChanged("src", async (el) => {
+    el.doAbort();
+    if (!el.src) return;
+    const res = await fetch(el.src, {
+      signal: el.abortController.signal,
+    });
+    // …
+  });
+
+FetchOnce.define();
+```
+
+There are no public attributes — the controller is internal. See
+[renderable-element](/nucleus/packages/renderable-element) for the primary
+consumer.
+
+### API Reference

package/support/docs/README.md

@@ -0,0 +1,53 @@
+# abortable-element
+
+AbortController ownership for Neutron elements — cancel in-flight
+work cleanly when a newer request supersedes it.
+
+## Features
+
+- **Owned controller** Fresh `AbortController` per in-flight cycle
+- **doAbort()** Abort current work and rotate a new controller
+- **Fetch-ready** Pass `abortController.signal` into `fetch` /
+  template loads
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Compose `AbortableElement` and pass `abortController.signal` into
+async work. Call `doAbort()` when that work should be cancelled (e.g.
+`template-ref` changed). `RenderableElement` already does this for
+template fetches.
+
+```ts
+import { Neutron } from "@excom/neutron";
+import { AbortableElement } from "@excom/abortable-element";
+
+export const FetchOnce = Neutron.compose([
+  AbortableElement,
+  Neutron({
+    tag: "fetch-once",
+    props: { src: String },
+  }),
+])
+  .onPropChanged("src", async (el) => {
+    el.doAbort();
+    if (!el.src) return;
+    const res = await fetch(el.src, {
+      signal: el.abortController.signal,
+    });
+    // …
+  });
+
+FetchOnce.define();
+```
+
+There are no public attributes — the controller is internal. See
+[renderable-element](/nucleus/packages/renderable-element) for the primary
+consumer.
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>

package/support/package-meta.json

@@ -0,0 +1,49 @@
+{
+  "shortName": "abortable-element",
+  "package": {
+    "name": "@excom/abortable-element",
+    "version": "0.1.0",
+    "description": "AbortableElement base for Neutron elements",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "element-base"
+    }
+  },
+  "demos": {},
+  "readme": "<h1 id=\"md-abortable-element\">abortable-element</h1>\n<p>AbortController ownership for Neutron elements — cancel in-flight\nwork cleanly when a newer request supersedes it.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Owned controller</strong> Fresh <code>AbortController</code> per in-flight cycle</li>\n<li><strong>doAbort()</strong> Abort current work and rotate a new controller</li>\n<li><strong>Fetch-ready</strong> Pass <code>abortController.signal</code> into <code>fetch</code> /\ntemplate loads</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>Compose <code>AbortableElement</code> and pass <code>abortController.signal</code> into\nasync work. Call <code>doAbort()</code> when that work should be cancelled (e.g.\n<code>template-ref</code> changed). <code>RenderableElement</code> already does this for\ntemplate fetches.</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\nimport { AbortableElement } from \"@excom/abortable-element\";\n\nexport const FetchOnce = Neutron.compose([\n  AbortableElement,\n  Neutron({\n    tag: \"fetch-once\",\n    props: { src: String },\n  }),\n])\n  .onPropChanged(\"src\", async (el) =&gt; {\n    el.doAbort();\n    if (!el.src) return;\n    const res = await fetch(el.src, {\n      signal: el.abortController.signal,\n    });\n    // …\n  });\n\nFetchOnce.define();</template></include-content>\n<p>There are no public attributes — the controller is internal. See\n<spa-a route-href=\"/nucleus/packages/renderable-element\" role=\"link\">renderable-element</spa-a> for the primary\nconsumer.</p>\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",
+  "docs": {
+    "readme": "<h1 id=\"md-abortable-element\">abortable-element</h1>\n<p>AbortController ownership for Neutron elements — cancel in-flight\nwork cleanly when a newer request supersedes it.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Owned controller</strong> Fresh <code>AbortController</code> per in-flight cycle</li>\n<li><strong>doAbort()</strong> Abort current work and rotate a new controller</li>\n<li><strong>Fetch-ready</strong> Pass <code>abortController.signal</code> into <code>fetch</code> /\ntemplate loads</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>Compose <code>AbortableElement</code> and pass <code>abortController.signal</code> into\nasync work. Call <code>doAbort()</code> when that work should be cancelled (e.g.\n<code>template-ref</code> changed). <code>RenderableElement</code> already does this for\ntemplate fetches.</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\nimport { AbortableElement } from \"@excom/abortable-element\";\n\nexport const FetchOnce = Neutron.compose([\n  AbortableElement,\n  Neutron({\n    tag: \"fetch-once\",\n    props: { src: String },\n  }),\n])\n  .onPropChanged(\"src\", async (el) =&gt; {\n    el.doAbort();\n    if (!el.src) return;\n    const res = await fetch(el.src, {\n      signal: el.abortController.signal,\n    });\n    // …\n  });\n\nFetchOnce.define();</template></include-content>\n<p>There are no public attributes — the controller is internal. See\n<spa-a route-href=\"/nucleus/packages/renderable-element\" role=\"link\">renderable-element</spa-a> for the primary\nconsumer.</p>\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"
+  },
+  "installation": {
+    "name": "@excom/abortable-element",
+    "shortName": "abortable-element",
+    "version": "0.1.0",
+    "description": "AbortableElement base for Neutron elements",
+    "packageType": "element-base",
+    "install": {
+      "npm": "npm install @excom/abortable-element"
+    },
+    "imports": {
+      "js": "import { /* … */ } from \"@excom/abortable-element\";"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "summary": "AbortController ownership for Neutron elements.",
+      "kind": "mixin",
+      "attributes": [],
+      "events": [],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/abortable-element.test.ts

@@ -0,0 +1,58 @@
+import { AbortableElement } from "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+
+const TAG = "abortable-element-test";
+if (!customElements.get(TAG)) {
+  AbortableElement.define(TAG);
+}
+
+describe("AbortableElement", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("has a fresh AbortController by default", () => {
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    expect(el.abortController).toBeInstanceOf(AbortController);
+    expect(el.abortController.signal.aborted).toBe(false);
+  });
+
+  it("aborts and returns a fresh controller", () => {
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    const initial = el.abortController;
+    expect(initial).toBeInstanceOf(AbortController);
+    el.doAbort("test");
+    expect(initial.signal.aborted).toBe(true);
+    expect(el.abortController).toBeInstanceOf(AbortController);
+    expect(el.abortController).not.toBe(initial);
+    expect(el.abortController.signal.aborted).toBe(false);
+  });
+
+  it("passes abort reason to the signal", () => {
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    const controller = el.abortController;
+    el.doAbort("custom-reason");
+    expect(controller.signal.aborted).toBe(true);
+    expect(controller.signal.reason).toBe("custom-reason");
+  });
+
+  it("can abort multiple times, each producing a new controller", () => {
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    const first = el.abortController;
+    el.doAbort();
+    const second = el.abortController;
+    el.doAbort();
+    const third = el.abortController;
+    expect(first).not.toBe(second);
+    expect(second).not.toBe(third);
+    expect(first.signal.aborted).toBe(true);
+    expect(second.signal.aborted).toBe(true);
+    expect(third.signal.aborted).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"]
+}