@excom/fetchable-element 0.1.0

package/support/custom-elements.json

@@ -0,0 +1,368 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "index.ts",
+      "declarations": [
+        {
+          "kind": "mixin",
+          "name": "FetchableElement",
+          "mixins": [
+            {
+              "name": "AbortableElement",
+              "package": "@excom/abortable-element"
+            },
+            {
+              "name": "LoadableElement",
+              "package": "@excom/loadable-element"
+            }
+          ],
+          "description": "Composition base that owns the request lifecycle for `fetch()`-backed elements — building request args (attributes, a referenced `<form>`, or a custom override), tracking loading / success / error state (through `LoadableElement`), and canceling in-flight requests (via `AbortableElement`) when superseded or disconnected. Not a registered element on its own (tag is intentionally `noop-tag`) — compose it via `Neutron.compose([FetchableElement, ...])` and the consumer element inherits every attribute, state, and event declared below. Concrete consumers include `<provider-fetch>` (fetch-on-attribute-change), `<super-form>` (fetch-on-submit), and `<web-authn>` (WebAuthn ceremonies that still round-trip to a server). Subclasses call `doFetch(url, requestInit)` — typically built via `getFetchArgs(customFetchArgs?)`, which deep-merges (lowest → highest priority) the element's own attributes, the `<form>` referenced by `form-ref` (action/method/enctype/fields), and any custom args passed in — to run the request and drive `is-loading` / `is-success` / `is-error` / `provision` automatically. A prior in-flight request is canceled before a new one starts.",
+          "attributes": [
+            {
+              "name": "form-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "CSS selector for a `<form>` to source the request from — its `action` (URL), `method`, `enctype` (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 `doFetch()` args.",
+              "fieldName": "formRef",
+              "values": [
+                "<CSS Selector>"
+              ]
+            },
+            {
+              "name": "has-body",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Force a request body even for methods that don't imply one (`GET` / `HEAD`). Already implied for `POST` / `PUT` / `PATCH`.",
+              "fieldName": "hasBody"
+            },
+            {
+              "name": "api-url",
+              "type": {
+                "text": "string"
+              },
+              "description": "Endpoint URL. When the request has no body, the JSON payload (from `form-ref` or custom `doFetch()` args) is merged in as query params instead.",
+              "fieldName": "apiUrl",
+              "default": ""
+            },
+            {
+              "name": "api-method",
+              "type": {
+                "text": "string"
+              },
+              "description": "HTTP method. Always uppercased before the request is sent.",
+              "fieldName": "apiMethod",
+              "default": "GET"
+            },
+            {
+              "name": "header-accept",
+              "type": {
+                "text": "string"
+              },
+              "description": "`Accept` request header.",
+              "fieldName": "headerAccept",
+              "default": "application/json"
+            },
+            {
+              "name": "header-content-type",
+              "type": {
+                "text": "string"
+              },
+              "description": "`Content-Type` request header. Dropped entirely when the request has no body.",
+              "fieldName": "headerContentType",
+              "default": "application/json"
+            },
+            {
+              "name": "header-cache-control",
+              "type": {
+                "text": "string"
+              },
+              "description": "`Cache-Control` request header. Unset by default (browser default caching applies).",
+              "fieldName": "headerCacheControl"
+            },
+            {
+              "name": "fetch-redirect",
+              "type": {
+                "text": "string"
+              },
+              "description": "`RequestInit.redirect` mode. Unset defers to the browser default (`follow`).",
+              "fieldName": "fetchRedirect",
+              "values": [
+                "follow",
+                "error",
+                "manual"
+              ]
+            },
+            {
+              "name": "fetch-credentials",
+              "type": {
+                "text": "string"
+              },
+              "description": "`RequestInit.credentials` mode.",
+              "fieldName": "fetchCredentials",
+              "default": "include",
+              "values": [
+                "omit",
+                "same-origin",
+                "include"
+              ]
+            },
+            {
+              "name": "is-loading",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "A request is currently in flight.",
+              "fieldName": "isLoading"
+            },
+            {
+              "name": "is-success",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "The most recent request resolved successfully. Mutually exclusive with `is-error`.",
+              "fieldName": "isSuccess"
+            },
+            {
+              "name": "is-error",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "The most recent request failed (non-2xx status, network error, or a thrown error other than `AbortError`). Fires with the `error` event.",
+              "fieldName": "isError"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "formRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "CSS selector for a `<form>` to source the request from — its `action` (URL), `method`, `enctype` (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 `doFetch()` args.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "hasBody",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Force a request body even for methods that don't imply one (`GET` / `HEAD`). Already implied for `POST` / `PUT` / `PATCH`.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "apiUrl",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Endpoint URL. When the request has no body, the JSON payload (from `form-ref` or custom `doFetch()` args) is merged in as query params instead.",
+              "default": "",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "apiMethod",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "HTTP method. Always uppercased before the request is sent.",
+              "default": "GET",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "headerAccept",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "`Accept` request header.",
+              "default": "application/json",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "headerContentType",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "`Content-Type` request header. Dropped entirely when the request has no body.",
+              "default": "application/json",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "headerCacheControl",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "`Cache-Control` request header. Unset by default (browser default caching applies).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "fetchRedirect",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "`RequestInit.redirect` mode. Unset defers to the browser default (`follow`).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "fetchCredentials",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "`RequestInit.credentials` mode.",
+              "default": "include",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isLoading",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "A request is currently in flight.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isSuccess",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "The most recent request resolved successfully. Mutually exclusive with `is-error`.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isError",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "The most recent request failed (non-2xx status, network error, or a thrown error other than `AbortError`). Fires with the `error` event.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "provision",
+              "type": {
+                "text": "FetchResponse",
+                "expanded": "{ bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Response payload on success, or error payload on failure. Success shape: `{ status, statusText, ok, headers, url, redirected, bodyUsed, type, body }`. Failure shape is either that same response shape (server responded with an error status) or `{ message, stack }` (request never completed). Not reflected as an attribute.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "{tag}-loading",
+              "description": "Dispatched immediately before the request is sent.",
+              "type": {
+                "text": "FetchableLoadingEvent",
+                "expanded": "CustomEvent & { type: \"{tag}-loading\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "{tag}-success",
+              "description": "Dispatched when the request resolves successfully. `event.detail` is the parsed response (see `provision`).",
+              "type": {
+                "text": "FetchableSuccessEvent",
+                "expanded": "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}-error",
+              "description": "Dispatched when the request fails — non-2xx status, network error, or a thrown error. `event.detail` is the error payload (see `provision`). Not dispatched for aborted requests.",
+              "type": {
+                "text": "FetchableErrorEvent",
+                "expanded": "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 }"
+              }
+            }
+          ],
+          "_neutron": {
+            "provisions": [
+              {
+                "name": "provision",
+                "type": {
+                  "text": "FetchResponse",
+                  "expanded": "{ 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: `{ status, statusText, ok, headers, url, redirected, bodyUsed, type, body }`. Failure shape is either that same response shape (server responded with an error status) or `{ message, stack }` (request never completed). Not reflected as an attribute.",
+                "fieldName": "provision"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "FetchableElement",
+          "declaration": {
+            "name": "FetchableElement",
+            "module": "index.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,120 @@
+# fetchable-element
+
+Composition base that owns the `fetch()` lifecycle for Neutron elements —
+build the request from attributes, a `<form>`, or a custom override, then
+track loading / success / error state automatically.
+
+## Features
+
+- **Shared lifecycle** States, `provision` and events come from [loadable-element](/nucleus/packages/loadable-element)
+
+- **Attribute-driven requests** URL, method, headers, redirect, and
+  credentials all configurable declaratively
+- **Form-aware** Point `form-ref` at a `<form>` to source action, method,
+  enctype, and field values
+- **Merged payloads** Attributes, form, and custom args deep-merge
+  (lowest → highest priority)
+- **Lifecycle state** `is-loading` / `is-success` / `is-error` managed
+  for you
+- **Provision** `provision` is the parsed response (or error payload) for
+  Quark `prop("provision")` — not a reflected attribute
+- **Cancel-safe** Superseded or disconnected requests are aborted via
+  `AbortableElement`
+
+## Installation
+
+
+`@excom/fetchable-element` v0.1.0
+
+```bash
+pnpm add @excom/fetchable-element
+```
+
+```bash
+npm install @excom/fetchable-element
+```
+
+```bash
+yarn add @excom/fetchable-element
+```
+
+### Import
+
+```ts
+import { /* … */ } from "@excom/fetchable-element";
+```
+
+
+
+## Usage
+
+Compose `FetchableElement`, then call `doFetch(url, requestInit)` —
+usually built via `getFetchArgs(customFetchArgs?)` — whenever the
+subclass decides a request should run. Concrete consumers include
+`<provider-fetch>` (fetch on attribute change), `<super-form>` (fetch on
+submit), and `<web-authn>` (WebAuthn ceremonies that still round-trip to
+a server).
+
+```ts
+import { Neutron } from "@excom/neutron";
+import { FetchableElement } from "@excom/fetchable-element";
+
+export const RefreshOnClick = Neutron.compose([
+  FetchableElement,
+  Neutron({ tag: "refresh-on-click" }),
+])
+  .onEvent("click", ({ getFetchArgs }) => ({
+    doFetch: getFetchArgs(),
+  }));
+
+RefreshOnClick.define();
+```
+
+```html
+<refresh-on-click api-url="/api/status"></refresh-on-click>
+```
+
+Every prop, state field, and event documented below is inherited
+verbatim by any element that composes `FetchableElement` — it flattens
+directly into that element's own generated docs, so `<provider-fetch>`
+and friends don't redeclare it.
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `form-ref` | option | `string` |  | `<CSS Selector>` | CSS selector for a `<form>` to source the request from — its `action` (URL), `method`, `enctype` (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 `doFetch()` args. |
+| `has-body` | option | `boolean` |  |  | Force a request body even for methods that don't imply one (`GET` / `HEAD`). Already implied for `POST` / `PUT` / `PATCH`. |
+| `api-url` | option | `string` | `""` |  | Endpoint URL. When the request has no body, the JSON payload (from `form-ref` or custom `doFetch()` args) is merged in as query params instead. |
+| `api-method` | option | `string` | `"GET"` |  | HTTP method. Always uppercased before the request is sent. |
+| `header-accept` | option | `string` | `"application/json"` |  | `Accept` request header. |
+| `header-content-type` | option | `string` | `"application/json"` |  | `Content-Type` request header. Dropped entirely when the request has no body. |
+| `header-cache-control` | option | `string` |  |  | `Cache-Control` request header. Unset by default (browser default caching applies). |
+| `fetch-redirect` | option | `string` |  | `"follow"` \| `"error"` \| `"manual"` | `RequestInit.redirect` mode. Unset defers to the browser default (`follow`). |
+| `fetch-credentials` | option | `string` | `"include"` | `"omit"` \| `"same-origin"` \| `"include"` | `RequestInit.credentials` mode. |
+| `is-loading` | state | `boolean` |  |  | A request is currently in flight. |
+| `is-success` | state | `boolean` |  |  | The most recent request resolved successfully. Mutually exclusive with `is-error`. |
+| `is-error` | state | `boolean` |  |  | The most recent request failed (non-2xx status, network error, or a thrown error other than `AbortError`). Fires with the `error` event. |
+
+#### Provision
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provision` | `FetchResponse` (`{ bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }`) | Response payload on success, or error payload on failure. Success shape: `{ status, statusText, ok, headers, url, redirected, bodyUsed, type, body }`. Failure shape is either that same response shape (server responded with an error status) or `{ message, stack }` (request never completed). Not reflected as an attribute. |
+
+#### Fires
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `{tag}-loading` | `FetchableLoadingEvent` (`CustomEvent & { type: "{tag}-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched immediately before the request is sent. |
+| `{tag}-success` | `FetchableSuccessEvent` (`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 }`) | Dispatched when the request resolves successfully. `event.detail` is the parsed response (see `provision`). |
+| `{tag}-error` | `FetchableErrorEvent` (`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 }`) | Dispatched when the request fails — non-2xx status, network error, or a thrown error. `event.detail` is the error payload (see `provision`). Not dispatched for aborted requests. |
+
+
+
+There are no demos for this package — see
+[provider-fetch](/nucleus/packages/provider-fetch) for `FetchableElement` in
+action against a real endpoint.

package/support/docs/README.md

@@ -0,0 +1,67 @@
+# fetchable-element
+
+Composition base that owns the `fetch()` lifecycle for Neutron elements —
+build the request from attributes, a `<form>`, or a custom override, then
+track loading / success / error state automatically.
+
+## Features
+
+- **Shared lifecycle** States, `provision` and events come from [loadable-element](/nucleus/packages/loadable-element)
+
+- **Attribute-driven requests** URL, method, headers, redirect, and
+  credentials all configurable declaratively
+- **Form-aware** Point `form-ref` at a `<form>` to source action, method,
+  enctype, and field values
+- **Merged payloads** Attributes, form, and custom args deep-merge
+  (lowest → highest priority)
+- **Lifecycle state** `is-loading` / `is-success` / `is-error` managed
+  for you
+- **Provision** `provision` is the parsed response (or error payload) for
+  Quark `prop("provision")` — not a reflected attribute
+- **Cancel-safe** Superseded or disconnected requests are aborted via
+  `AbortableElement`
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Compose `FetchableElement`, then call `doFetch(url, requestInit)` —
+usually built via `getFetchArgs(customFetchArgs?)` — whenever the
+subclass decides a request should run. Concrete consumers include
+`<provider-fetch>` (fetch on attribute change), `<super-form>` (fetch on
+submit), and `<web-authn>` (WebAuthn ceremonies that still round-trip to
+a server).
+
+```ts
+import { Neutron } from "@excom/neutron";
+import { FetchableElement } from "@excom/fetchable-element";
+
+export const RefreshOnClick = Neutron.compose([
+  FetchableElement,
+  Neutron({ tag: "refresh-on-click" }),
+])
+  .onEvent("click", ({ getFetchArgs }) => ({
+    doFetch: getFetchArgs(),
+  }));
+
+RefreshOnClick.define();
+```
+
+```html
+<refresh-on-click api-url="/api/status"></refresh-on-click>
+```
+
+Every prop, state field, and event documented below is inherited
+verbatim by any element that composes `FetchableElement` — it flattens
+directly into that element's own generated docs, so `<provider-fetch>`
+and friends don't redeclare it.
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+There are no demos for this package — see
+[provider-fetch](/nucleus/packages/provider-fetch) for `FetchableElement` in
+action against a real endpoint.