@excom/fetchable-element 0.1.0

package/support/package-meta.json

@@ -0,0 +1,218 @@
+{
+  "shortName": "fetchable-element",
+  "package": {
+    "name": "@excom/fetchable-element",
+    "version": "0.1.0",
+    "description": "FetchableElement base for Neutron elements",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "element-base"
+    }
+  },
+  "demos": {},
+  "readme": "<h1 id=\"md-fetchable-element\">fetchable-element</h1>\n<p>Composition base that owns the <code>fetch()</code> lifecycle for Neutron elements —\nbuild the request from attributes, a <code>&lt;form&gt;</code>, or a custom override, then\ntrack loading / success / error state automatically.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><p><strong>Shared lifecycle</strong> States, <code>provision</code> and events come from <spa-a route-href=\"/nucleus/packages/loadable-element\" role=\"link\">loadable-element</spa-a></p>\n</li>\n<li><p><strong>Attribute-driven requests</strong> URL, method, headers, redirect, and\ncredentials all configurable declaratively</p>\n</li>\n<li><p><strong>Form-aware</strong> Point <code>form-ref</code> at a <code>&lt;form&gt;</code> to source action, method,\nenctype, and field values</p>\n</li>\n<li><p><strong>Merged payloads</strong> Attributes, form, and custom args deep-merge\n(lowest → highest priority)</p>\n</li>\n<li><p><strong>Lifecycle state</strong> <code>is-loading</code> / <code>is-success</code> / <code>is-error</code> managed\nfor you</p>\n</li>\n<li><p><strong>Provision</strong> <code>provision</code> is the parsed response (or error payload) for\nQuark <code>prop(&quot;provision&quot;)</code> — not a reflected attribute</p>\n</li>\n<li><p><strong>Cancel-safe</strong> Superseded or disconnected requests are aborted via\n<code>AbortableElement</code></p>\n</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>FetchableElement</code>, then call <code>doFetch(url, requestInit)</code> —\nusually built via <code>getFetchArgs(customFetchArgs?)</code> — whenever the\nsubclass decides a request should run. Concrete consumers include\n<code>&lt;provider-fetch&gt;</code> (fetch on attribute change), <code>&lt;super-form&gt;</code> (fetch on\nsubmit), and <code>&lt;web-authn&gt;</code> (WebAuthn ceremonies that still round-trip to\na server).</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\nimport { FetchableElement } from \"@excom/fetchable-element\";\n\nexport const RefreshOnClick = Neutron.compose([\n  FetchableElement,\n  Neutron({ tag: \"refresh-on-click\" }),\n])\n  .onEvent(\"click\", ({ getFetchArgs }) =&gt; ({\n    doFetch: getFetchArgs(),\n  }));\n\nRefreshOnClick.define();</template></include-content>\n<include-content data-language=\"html\"><template>&lt;refresh-on-click api-url=\"/api/status\"&gt;&lt;/refresh-on-click&gt;</template></include-content>\n<p>Every prop, state field, and event documented below is inherited\nverbatim by any element that composes <code>FetchableElement</code> — it flattens\ndirectly into that element&#39;s own generated docs, so <code>&lt;provider-fetch&gt;</code>\nand friends don&#39;t redeclare it.</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<p>There are no demos for this package — see\n<spa-a route-href=\"/nucleus/packages/provider-fetch\" role=\"link\">provider-fetch</spa-a> for <code>FetchableElement</code> in\naction against a real endpoint.</p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-fetchable-element\">fetchable-element</h1>\n<p>Composition base that owns the <code>fetch()</code> lifecycle for Neutron elements —\nbuild the request from attributes, a <code>&lt;form&gt;</code>, or a custom override, then\ntrack loading / success / error state automatically.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><p><strong>Shared lifecycle</strong> States, <code>provision</code> and events come from <spa-a route-href=\"/nucleus/packages/loadable-element\" role=\"link\">loadable-element</spa-a></p>\n</li>\n<li><p><strong>Attribute-driven requests</strong> URL, method, headers, redirect, and\ncredentials all configurable declaratively</p>\n</li>\n<li><p><strong>Form-aware</strong> Point <code>form-ref</code> at a <code>&lt;form&gt;</code> to source action, method,\nenctype, and field values</p>\n</li>\n<li><p><strong>Merged payloads</strong> Attributes, form, and custom args deep-merge\n(lowest → highest priority)</p>\n</li>\n<li><p><strong>Lifecycle state</strong> <code>is-loading</code> / <code>is-success</code> / <code>is-error</code> managed\nfor you</p>\n</li>\n<li><p><strong>Provision</strong> <code>provision</code> is the parsed response (or error payload) for\nQuark <code>prop(&quot;provision&quot;)</code> — not a reflected attribute</p>\n</li>\n<li><p><strong>Cancel-safe</strong> Superseded or disconnected requests are aborted via\n<code>AbortableElement</code></p>\n</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>FetchableElement</code>, then call <code>doFetch(url, requestInit)</code> —\nusually built via <code>getFetchArgs(customFetchArgs?)</code> — whenever the\nsubclass decides a request should run. Concrete consumers include\n<code>&lt;provider-fetch&gt;</code> (fetch on attribute change), <code>&lt;super-form&gt;</code> (fetch on\nsubmit), and <code>&lt;web-authn&gt;</code> (WebAuthn ceremonies that still round-trip to\na server).</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\nimport { FetchableElement } from \"@excom/fetchable-element\";\n\nexport const RefreshOnClick = Neutron.compose([\n  FetchableElement,\n  Neutron({ tag: \"refresh-on-click\" }),\n])\n  .onEvent(\"click\", ({ getFetchArgs }) =&gt; ({\n    doFetch: getFetchArgs(),\n  }));\n\nRefreshOnClick.define();</template></include-content>\n<include-content data-language=\"html\"><template>&lt;refresh-on-click api-url=\"/api/status\"&gt;&lt;/refresh-on-click&gt;</template></include-content>\n<p>Every prop, state field, and event documented below is inherited\nverbatim by any element that composes <code>FetchableElement</code> — it flattens\ndirectly into that element&#39;s own generated docs, so <code>&lt;provider-fetch&gt;</code>\nand friends don&#39;t redeclare it.</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<p>There are no demos for this package — see\n<spa-a route-href=\"/nucleus/packages/provider-fetch\" role=\"link\">provider-fetch</spa-a> for <code>FetchableElement</code> in\naction against a real endpoint.</p>\n"
+  },
+  "installation": {
+    "name": "@excom/fetchable-element",
+    "shortName": "fetchable-element",
+    "version": "0.1.0",
+    "description": "FetchableElement base for Neutron elements",
+    "packageType": "element-base",
+    "install": {
+      "npm": "npm install @excom/fetchable-element"
+    },
+    "imports": {
+      "js": "import { /* … */ } from \"@excom/fetchable-element\";"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "kind": "mixin",
+      "attributes": [
+        {
+          "name": "api-method",
+          "type": "string",
+          "description": "HTTP method. Always uppercased before the request is sent.",
+          "fieldName": "apiMethod",
+          "surface": "option",
+          "default": "\"GET\""
+        },
+        {
+          "name": "api-url",
+          "type": "string",
+          "description": "Endpoint URL. When the request has no body, the JSON payload (from <code>form-ref</code> or custom <code>doFetch()</code> args) is merged in as query params instead.",
+          "fieldName": "apiUrl",
+          "surface": "option",
+          "default": "\"\""
+        },
+        {
+          "name": "fetch-credentials",
+          "type": "string",
+          "description": "<code>RequestInit.credentials</code> mode.",
+          "fieldName": "fetchCredentials",
+          "surface": "option",
+          "default": "\"include\"",
+          "values": "\"omit\" | \"same-origin\" | \"include\""
+        },
+        {
+          "name": "fetch-redirect",
+          "type": "string",
+          "description": "<code>RequestInit.redirect</code> mode. Unset defers to the browser default (<code>follow</code>).",
+          "fieldName": "fetchRedirect",
+          "surface": "option",
+          "values": "\"follow\" | \"error\" | \"manual\""
+        },
+        {
+          "name": "form-ref",
+          "type": "string",
+          "description": "CSS selector for a <code>&lt;form&gt;</code> to source the request from — its <code>action</code> (URL), <code>method</code>, <code>enctype</code> (Content-Type), and field values (as the JSON payload) all take priority over the matching attributes below. Omit to build the request entirely from attributes / custom <code>doFetch()</code> args.",
+          "fieldName": "formRef",
+          "surface": "option",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "has-body",
+          "type": "boolean",
+          "description": "Force a request body even for methods that don&#39;t imply one (<code>GET</code> / <code>HEAD</code>). Already implied for <code>POST</code> / <code>PUT</code> / <code>PATCH</code>.",
+          "fieldName": "hasBody",
+          "surface": "option"
+        },
+        {
+          "name": "header-accept",
+          "type": "string",
+          "description": "<code>Accept</code> request header.",
+          "fieldName": "headerAccept",
+          "surface": "option",
+          "default": "\"application/json\""
+        },
+        {
+          "name": "header-cache-control",
+          "type": "string",
+          "description": "<code>Cache-Control</code> request header. Unset by default (browser default caching applies).",
+          "fieldName": "headerCacheControl",
+          "surface": "option"
+        },
+        {
+          "name": "header-content-type",
+          "type": "string",
+          "description": "<code>Content-Type</code> request header. Dropped entirely when the request has no body.",
+          "fieldName": "headerContentType",
+          "surface": "option",
+          "default": "\"application/json\""
+        },
+        {
+          "name": "is-error",
+          "type": "boolean",
+          "description": "The most recent request failed (non-2xx status, network error, or a thrown error other than <code>AbortError</code>). Fires with the <code>error</code> event.",
+          "fieldName": "isError",
+          "surface": "state"
+        },
+        {
+          "name": "is-error",
+          "type": "boolean",
+          "description": "The most recent work failed. Mutually exclusive with <code>is-success</code>.",
+          "fieldName": "isError",
+          "surface": "state",
+          "inheritedFrom": "@excom/loadable-element"
+        },
+        {
+          "name": "is-loading",
+          "type": "boolean",
+          "description": "A request is currently in flight.",
+          "fieldName": "isLoading",
+          "surface": "state"
+        },
+        {
+          "name": "is-loading",
+          "type": "boolean",
+          "description": "Work is in flight.",
+          "fieldName": "isLoading",
+          "surface": "state",
+          "inheritedFrom": "@excom/loadable-element"
+        },
+        {
+          "name": "is-success",
+          "type": "boolean",
+          "description": "The most recent request resolved successfully. Mutually exclusive with <code>is-error</code>.",
+          "fieldName": "isSuccess",
+          "surface": "state"
+        },
+        {
+          "name": "is-success",
+          "type": "boolean",
+          "description": "The most recent work finished successfully. Mutually exclusive with <code>is-error</code>.",
+          "fieldName": "isSuccess",
+          "surface": "state",
+          "inheritedFrom": "@excom/loadable-element"
+        }
+      ],
+      "events": [
+        {
+          "name": "{tag}-error",
+          "description": "Dispatched when the request fails — non-2xx status, network error, or a thrown error. <code>event.detail</code> is the error payload (see <code>provision</code>). Not dispatched for aborted requests.",
+          "type": "FetchableErrorEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-error\"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; } | { message: string; stack?: string }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "{tag}-error",
+          "description": "After <code>is-error</code> is set. <code>event.detail</code> is the error payload (also stored as <code>provision</code>).",
+          "type": "LoadableErrorEvent",
+          "inheritedFrom": "@excom/loadable-element"
+        },
+        {
+          "name": "{tag}-loading",
+          "description": "Dispatched immediately before the request is sent.",
+          "type": "FetchableLoadingEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-loading\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "{tag}-loading",
+          "description": "After <code>is-loading</code> is set (work started).",
+          "type": "LoadableLoadingEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-loading\"; detail: void; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/loadable-element"
+        },
+        {
+          "name": "{tag}-success",
+          "description": "Dispatched when the request resolves successfully. <code>event.detail</code> is the parsed response (see <code>provision</code>).",
+          "type": "FetchableSuccessEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-success\"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "{tag}-success",
+          "description": "After <code>is-success</code> is set. <code>event.detail</code> is the new <code>provision</code>.",
+          "type": "LoadableSuccessEvent",
+          "inheritedFrom": "@excom/loadable-element"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "FetchResponse",
+          "typeExpanded": "{ bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }",
+          "description": "Response payload on success, or error payload on failure. Success shape: <code>{ status, statusText, ok, headers, url, redirected, bodyUsed, type, body }</code>. Failure shape is either that same response shape (server responded with an error status) or <code>{ message, stack }</code> (request never completed). Not reflected as an attribute.",
+          "fieldName": "provision"
+        },
+        {
+          "name": "provision",
+          "type": "unknown",
+          "description": "The result of the most recent work on success, or the error payload on failure. Shape is defined by the composing element. Not reflected as an attribute.",
+          "fieldName": "provision",
+          "inheritedFrom": "@excom/loadable-element"
+        }
+      ]
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/fetch-lifecycle.test.ts

@@ -0,0 +1,401 @@
+import { FetchableElement } from "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  spyFetch,
+  vi,
+  wait,
+  waitForEvent,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { KitLogger } from "@excom/kit-logger";
+
+const TAG = "fetchable-lifecycle-test";
+if (!customElements.get(TAG)) {
+  FetchableElement.define(TAG);
+}
+
+// Lifecycle events use the base's config tag (`noop-tag`), not the defined tag.
+const EVT = (name: string) => `noop-tag-${name}`;
+
+const abortError = () =>
+  new DOMException("The operation was aborted.", "AbortError");
+
+/** A fetch stub that only settles when its signal aborts (rejects `AbortError`). */
+const spyAbortableFetch = () =>
+  vi.spyOn(globalThis, "fetch").mockImplementation(
+    (_url, init) =>
+      new Promise((_resolve, reject) => {
+        init?.signal?.addEventListener("abort", () => reject(abortError()));
+      }),
+  );
+
+const jsonResponse = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+
+describe("FetchableElement fetch lifecycle", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+    KitLogger.unsuppress();
+  });
+
+  it("emits loading, then success with the parsed JSON provision", async () => {
+    spyFetch({ body: JSON.stringify({ ok: 1 }) });
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+
+    const loading = waitForEvent(el, EVT("loading"));
+    const provisioned = waitForEvent(el, "neutron-provision");
+    let successDetail: any;
+    el.addEventListener(EVT("success"), (e: CustomEvent) => {
+      successDetail = e.detail;
+    });
+
+    await waitForEvent(el, EVT("success"), () => {
+      el.doFetch(["/api/json-ok", { method: "GET" }]);
+    });
+    await loading;
+    await provisioned;
+
+    expect(el).dom.to.equalTag(`<${TAG} is-success></${TAG}>`);
+    expect(el.isLoading).toBe(false);
+    expect(el.fetchPromise).toBeNull();
+    expect(el.provision.status).toBe(200);
+    expect(el.provision.ok).toBe(true);
+    expect(el.provision.body).toEqual({ ok: 1 });
+    expect(el.provision.headers).toEqual(
+      expect.arrayContaining([["content-type", "application/json"]]),
+    );
+    expect(successDetail).toBe(el.provision);
+  });
+
+  it("reads the body as text when the response is not JSON", async () => {
+    spyFetch({
+      body: "plain text",
+      headers: new Headers({ "content-type": "text/plain" }),
+    });
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+
+    await waitForEvent(el, EVT("success"), () => {
+      el.doFetch(["/api/text", {}]);
+    });
+
+    expect(el.provision.body).toBe("plain text");
+  });
+
+  it("reads the body as text when the response has no content-type", async () => {
+    spyFetch({ body: "untyped", headers: new Headers() });
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+
+    await waitForEvent(el, EVT("success"), () => {
+      el.doFetch(["/api/untyped", {}]);
+    });
+
+    expect(el.provision.body).toBe("untyped");
+  });
+
+  it("sets is-loading while the request is in flight", () => {
+    spyAbortableFetch();
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    el.doFetch(["/api/slow", {}]);
+    expect(el).dom.to.equalTag(`<${TAG} is-loading></${TAG}>`);
+    expect(el.fetchPromise).toBeInstanceOf(Promise);
+  });
+
+  it("emits error with the response payload on a non-2xx status", async () => {
+    KitLogger.suppress();
+    spyFetch({ status: 500, body: JSON.stringify({ reason: "boom" }) });
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+
+    let errorDetail: any;
+    el.addEventListener(EVT("error"), (e: CustomEvent) => {
+      errorDetail = e.detail;
+    });
+
+    await waitForEvent(el, EVT("error"), () => {
+      el.doFetch(["/api/server-error", {}]);
+    });
+
+    expect(el).dom.to.equalTag(`<${TAG} is-error></${TAG}>`);
+    expect(el.isLoading).toBe(false);
+    expect(el.fetchPromise).toBeNull();
+    expect(el.provision.status).toBe(500);
+    expect(el.provision.ok).toBe(false);
+    expect(el.provision.body).toEqual({ reason: "boom" });
+    expect(errorDetail).toBe(el.provision);
+  });
+
+  it("emits error with { message, stack } when fetch itself throws", async () => {
+    KitLogger.suppress();
+    vi.spyOn(globalThis, "fetch").mockImplementation(() =>
+      Promise.reject(new TypeError("Failed to fetch")),
+    );
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+
+    await waitForEvent(el, EVT("error"), () => {
+      el.doFetch(["/api/network-down", {}]);
+    });
+
+    expect(el).dom.to.equalTag(`<${TAG} is-error></${TAG}>`);
+    expect(el.provision.message).toBe("Failed to fetch");
+    expect(el.provision.stack).toBeDefined();
+  });
+
+  it("cancelling an in-flight request clears state without an error event", async () => {
+    spyAbortableFetch();
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    const onError = vi.fn();
+    const onSuccess = vi.fn();
+    el.addEventListener(EVT("error"), onError);
+    el.addEventListener(EVT("success"), onSuccess);
+
+    el.doFetch(["/api/cancel-me", {}]);
+    const { signal } = el.abortController;
+    expect(el.isLoading).toBe(true);
+
+    el.setCanceledState();
+    await wait(10);
+
+    expect(signal.aborted).toBe(true);
+    expect(el).dom.to.equalTag(`<${TAG}></${TAG}>`);
+    expect(el.fetchPromise).toBeNull();
+    expect(el.provision).toBeFalsy();
+    expect(onError).not.toHaveBeenCalled();
+    expect(onSuccess).not.toHaveBeenCalled();
+  });
+
+  it("a replacing request aborts the first and resolves with the second response", async () => {
+    let nthCall = 0;
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockImplementation((_url, init) => {
+        nthCall++;
+        if (nthCall === 1) {
+          return new Promise((_resolve, reject) => {
+            init?.signal?.addEventListener("abort", () =>
+              reject(abortError()),
+            );
+          });
+        }
+        return Promise.resolve(jsonResponse({ call: nthCall }));
+      });
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+
+    el.doFetch(["/api/first", {}]);
+    const firstSignal = el.abortController.signal;
+
+    await waitForEvent(el, EVT("success"), () => {
+      el.doFetch(["/api/second", {}]);
+    });
+
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(firstSignal.aborted).toBe(true);
+    expect(el.provision.body).toEqual({ call: 2 });
+    expect(el).dom.to.equalTag(`<${TAG} is-success></${TAG}>`);
+  });
+
+  it("aborts the in-flight request when disconnected", async () => {
+    spyAbortableFetch();
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    const onError = vi.fn();
+    el.addEventListener(EVT("error"), onError);
+
+    el.doFetch(["/api/disconnect", {}]);
+    const { signal } = el.abortController;
+    expect(el.isLoading).toBe(true);
+
+    el.remove();
+    await wait(10);
+
+    expect(signal.aborted).toBe(true);
+    expect(el.fetchPromise).toBeNull();
+    expect(el.isLoading).toBe(false);
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("serialises the body and forwards method, headers and signal to fetch", async () => {
+    const fetchSpy = spyFetch({ body: JSON.stringify({ saved: true }) });
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+
+    await waitForEvent(el, EVT("success"), () => {
+      el.doFetch([
+        "/api/items",
+        {
+          method: "POST",
+          body: { name: "widget" } as unknown as BodyInit,
+          headers: { "X-Test": "1" },
+        },
+      ]);
+    });
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("/api/items");
+    expect(init.method).toBe("POST");
+    expect(init.body).toBe(JSON.stringify({ name: "widget" }));
+    expect(init.headers).toEqual({ "X-Test": "1" });
+    expect(init.signal).toBeDefined();
+    expect(init.signal!.aborted).toBe(false);
+  });
+
+  it("sends no body when the request init has none", async () => {
+    const fetchSpy = spyFetch({ body: "{}" });
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+
+    await waitForEvent(el, EVT("success"), () => {
+      el.doFetch(["/api/no-body", { method: "GET" }]);
+    });
+
+    const [, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(init.body).toBeUndefined();
+  });
+});
+
+describe("FetchableElement getFetchArgs", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("defaults api-url to an empty string resolved against the origin", () => {
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    expect(el.apiUrl).toBe("");
+    const [url] = el.getFetchArgs();
+    expect(url).toBe(new URL("", window.location.origin).toString());
+  });
+
+  it("custom fetch args take priority over attributes", () => {
+    const el = fixture<any>(
+      `<${TAG} api-url="/api/base" api-method="get"></${TAG}>`,
+    );
+    const [url, init] = el.getFetchArgs([
+      "/api/custom",
+      { method: "post", headers: { "X-Custom": "1" } },
+    ]);
+    expect(url).toContain("/api/custom");
+    expect(url).not.toContain("/api/base");
+    expect(init.method).toBe("POST");
+    expect(init.headers["X-Custom"]).toBe("1");
+    expect(init.headers.Accept).toBe("application/json");
+    expect(init.body).toBeDefined();
+  });
+
+  it("custom init without a url keeps the attribute url", () => {
+    const el = fixture<any>(`<${TAG} api-url="/api/base"></${TAG}>`);
+    const [url, init] = el.getFetchArgs([undefined, { redirect: "error" }]);
+    expect(url).toContain("/api/base");
+    expect(init.redirect).toBe("error");
+  });
+
+  it("keeps a body supplied through custom fetch args", () => {
+    const el = fixture<any>(
+      `<${TAG} api-url="/api/items" form-ref=":scope form">
+        <form><input name="ignored" value="1" /></form>
+      </${TAG}>`,
+    );
+    const [, init] = el.getFetchArgs([
+      undefined,
+      { method: "post", body: "raw-body" },
+    ]);
+    expect(init.method).toBe("POST");
+    expect(init.body).toBe("raw-body");
+  });
+
+  it("an empty api-method sends no body", () => {
+    const el = fixture<any>(`<${TAG} api-url="/api/items"></${TAG}>`);
+    el.apiMethod = "";
+    const [, init] = el.getFetchArgs();
+    expect(init.method).toBe("");
+    expect(init.body).toBeUndefined();
+    expect(init.headers["Content-Type"]).toBeUndefined();
+  });
+
+  it("has-body forces a body (and Content-Type) on a GET request", () => {
+    const el = fixture<any>(
+      `<${TAG} api-url="/api/items" has-body form-ref=":scope form">
+        <form><input name="q" value="1" /></form>
+      </${TAG}>`,
+    );
+    const [url, init] = el.getFetchArgs();
+    expect(init.method).toBe("GET");
+    expect(init.body).toEqual({ q: "1" });
+    expect(init.headers["Content-Type"]).toBe("application/json");
+    expect(url).not.toContain("q=1");
+  });
+
+  it("merges the payload into query params when there is no body", () => {
+    const el = fixture<any>(
+      `<${TAG} api-url="/api/items" form-ref=":scope form">
+        <form><input name="q" value="1" /><input name="page" value="2" /></form>
+      </${TAG}>`,
+    );
+    const [url, init] = el.getFetchArgs();
+    expect(url).toContain("q=1");
+    expect(url).toContain("page=2");
+    expect(init.body).toBeUndefined();
+    expect(init.headers["Content-Type"]).toBeUndefined();
+  });
+
+  it("drops headers and credentials that are cleared to empty strings", () => {
+    const el = fixture<any>(
+      `<${TAG} api-url="/api/items" api-method="post"></${TAG}>`,
+    );
+    el.headerAccept = "";
+    el.headerContentType = "";
+    el.fetchCredentials = "";
+    const [, init] = el.getFetchArgs();
+    expect(init.method).toBe("POST");
+    expect(init.headers.Accept).toBeUndefined();
+    expect(init.headers["Content-Type"]).toBeUndefined();
+    expect(init.credentials).toBeUndefined();
+  });
+
+  it("passes fetch-redirect and a custom Content-Type through", () => {
+    const el = fixture<any>(
+      `<${TAG} api-url="/api/items" api-method="put" fetch-redirect="manual" header-content-type="text/plain"></${TAG}>`,
+    );
+    const [, init] = el.getFetchArgs();
+    expect(init.redirect).toBe("manual");
+    expect(init.headers["Content-Type"]).toBe("text/plain");
+  });
+
+  it("sources action, method, enctype and fields from an external form-ref", () => {
+    document.body.innerHTML = `
+      <form id="ext-form" action="/api/from-form" method="post" enctype="multipart/form-data">
+        <input name="title" value="hello" />
+      </form>
+      <${TAG} api-url="/api/ignored" form-ref="#ext-form"></${TAG}>
+    `;
+    const el = document.querySelector(TAG) as any;
+    expect(el.getFormElement()).toBe(document.getElementById("ext-form"));
+
+    const [url, init] = el.getFetchArgs();
+    expect(url).toContain("/api/from-form");
+    expect(url).not.toContain("/api/ignored");
+    expect(init.method).toBe("POST");
+    expect(init.headers["Content-Type"]).toBe("multipart/form-data");
+    expect(init.body).toEqual({ title: "hello" });
+  });
+
+  it("falls back to attribute url and method when the form has neither", () => {
+    const el = fixture<any>(
+      `<${TAG} api-url="/api/attr" api-method="patch" form-ref=":scope form">
+        <form><input name="a" value="b" /></form>
+      </${TAG}>`,
+    );
+    const [url, init] = el.getFetchArgs();
+    expect(url).toContain("/api/attr");
+    expect(init.method).toBe("PATCH");
+    expect(init.headers["Content-Type"]).toBe("application/json");
+    expect(init.body).toEqual({ a: "b" });
+  });
+
+  it("getFormElement returns null when the form-ref selector matches nothing", () => {
+    const el = fixture<any>(`<${TAG} form-ref="#no-such-form"></${TAG}>`);
+    expect(el.getFormElement()).toBeNull();
+  });
+});