@supersoniks/concorde 5.1.0 → 5.1.2

package/src/docs/components/docs-source-link.ts

@@ -1,88 +1,6 @@
-import { html, nothing } from "lit";
-import "../../core/components/ui/button/button";
-import "../../core/components/ui/icon/icon";
-
-declare const __DOCS_EDITOR_AVAILABLE__: boolean;
-
 export type DocsSource = {
   path: string;
   line?: number;
   column?: number;
   label?: string;
 };
-
-const editorAvailable =
-  import.meta.env.DEV &&
-  typeof __DOCS_EDITOR_AVAILABLE__ !== "undefined" &&
-  __DOCS_EDITOR_AVAILABLE__;
-
-function openDocsSource(source: DocsSource, event: Event) {
-  event.preventDefault();
-  if (!editorAvailable) return;
-
-  const params = new URLSearchParams({
-    path: source.path,
-    line: String(source.line ?? 1),
-    column: String(source.column ?? 1),
-  });
-
-  void fetch(`/__docs/open?${params}`).catch(() => {
-    console.warn("[docs] Could not open in editor:", source.path);
-  });
-}
-
-export function docsSourceLink(source: DocsSource) {
-  if (!editorAvailable) return nothing;
-  const label = source.label ?? source.path.split("/").pop() ?? "source";
-  return html`
-    <sonic-button
-      variant="link"
-      size="2xs"
-      type="neutral"
-      title=${source.path}
-      @click=${(e: Event) => openDocsSource(source, e)}
-    >
-      <sonic-icon
-        library="heroicons"
-        name="arrow-top-right-on-square"
-        class="w-3 h-3 opacity-70"
-      ></sonic-icon>
-      ${label}
-    </sonic-button>
-  `;
-}
-
-export function docsSourceLinks(sources: DocsSource[]) {
-  if (sources.length === 0) return nothing;
-  return html`
-    <div
-      class="flex flex-wrap items-center gap-x-1 gap-y-1 mb-3 pb-3 border-b border-neutral-200/80 dark:border-neutral-700/80"
-    >
-      <span class="text-xs uppercase tracking-wide text-neutral-400 mr-1"
-        >Source</span
-      >
-      ${editorAvailable
-        ? sources.map((s, i) =>
-            i === 0
-              ? docsSourceLink(s)
-              : html`<span class="text-neutral-300 dark:text-neutral-600"
-                    >·</span
-                  >${docsSourceLink(s)}`,
-          )
-        : sources.map(
-            (s, i) => html`
-              ${i > 0
-                ? html`<span class="text-neutral-300 dark:text-neutral-600"
-                    >·</span
-                  >`
-                : nothing}
-              <span
-                class="text-xs font-mono text-neutral-500 dark:text-neutral-400"
-                title=${s.path}
-                >${s.label ?? s.path.split("/").pop()}</span
-              >
-            `,
-          )}
-    </div>
-  `;
-}

package/src/docs/decorators/ancestor-attribute.md

@@ -0,0 +1,59 @@
+# @ancestorAttribute
+
+Copies the value of an attribute from the nearest element that carries it (the host itself, then its ancestors, across shadow roots) into a class property. Use it to pick up a scope such as `dataProvider` without passing it down by hand, typically to feed a dynamic key of [@subscribe](/docs/decorators/subscribe).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { ancestorAttribute } from "@supersoniks/concorde/decorators";
+
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+## Read once at connect
+
+By default the value is read once, just before the component's `connectedCallback`, and never updated. The closest element with the attribute wins. If no ancestor has it, the property keeps its initial value.
+
+<sonic-code>
+  <template>
+<div dataProvider="flights.CN001" gate="B12">
+  <docs-demo-sources for="demo-ancestor-attribute"></docs-demo-sources>
+  <demo-ancestor-attribute></demo-ancestor-attribute>
+</div>
+  </template>
+</sonic-code>
+
+An attribute present without a value (`<div gate>`) resolves to `""`. A camelCase name also matches its lowercase form (`dataProvider` and `dataprovider`).
+
+## Follow DOM changes
+
+With `{ dynamic: true }`, the property stays in sync while the component is connected: when an ancestor changes the attribute, when a closer ancestor gains or loses it, and when the component is moved. When no ancestor has the attribute, the property becomes `null`. Add `@state()` so Lit re-renders on each assignment.
+
+<sonic-code language="typescript">
+  <template>
+@ancestorAttribute("dataProvider", { dynamic: true })
+@state()
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+Change the parent or outer value, insert a closer wrapper, or remove an attribute: the child always shows the nearest one.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-ancestor-attribute-dynamic-section"></docs-demo-sources>
+    <demo-ancestor-attribute-dynamic-section></demo-ancestor-attribute-dynamic-section>
+  </template>
+</sonic-code>
+
+Keys of [@subscribe](/docs/decorators/subscribe) and [@bind](/docs/decorators/bind) that use the property as a placeholder (`"${dataProvider}"`) are re-resolved on each change.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `attributeName` | `string` | Attribute to look up on the host, then on its ancestors |
+| `options.dynamic` | `boolean` (default `false`) | Keep the property in sync with attribute changes and reparenting until disconnect; assigns `null` when no ancestor has the attribute |

package/src/docs/decorators/auto-subscribe.md

@@ -0,0 +1,40 @@
+# @autoSubscribe
+
+Legacy decorator that re-runs a method whenever one of the store values it reads is assigned. For new code, prefer [@subscribe](/docs/decorators/subscribe) with a [`DataProviderKey`](/docs/misc/dataProviderKey): dependencies are explicit and typed.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { autoSubscribe } from "@supersoniks/concorde/decorators";
+import { get } from "@supersoniks/concorde/utils";
+
+@autoSubscribe()
+updateDisplay() {
+  this.total = get(passengersKey) + get(crewKey);
+}
+  </template>
+</sonic-code>
+
+## Tracked reads
+
+The method runs once after `connectedCallback`. Every store value read during that run becomes a dependency; assigning any of them runs the method again. Write the result to a `@state()` property (or call `requestUpdate()`) so the component re-renders.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-auto-subscribe"></docs-demo-sources>
+    <demo-auto-subscribe></demo-auto-subscribe>
+  </template>
+</sonic-code>
+
+## Notes
+
+- Several assignments in the same task trigger a single re-run (batched with `queueMicrotask`).
+- Keep reads unconditional: a value read only behind a condition becomes a dependency the first time that branch runs.
+- Subscriptions are removed in `disconnectedCallback`.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| none | | `@autoSubscribe()` takes no argument; apply it to a method of a custom element |

package/src/docs/decorators/bind.md

@@ -0,0 +1,77 @@
+# @bind
+
+Keeps a class property in sync with a path of the DataProvider store, in both directions when needed. Pass a dot-notation string or a [DataProviderKey](/docs/misc/dataProviderKey); add `{ reflect: true }` to push local writes back to the store. For read-only sync prefer [@subscribe](/docs/decorators/subscribe), and see [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { bind } from "@supersoniks/concorde/decorators";
+
+@bind("flight.gate")
+@state()
+gate = "";
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The first path segment is the data provider id, the rest is dot notation (array items use a numeric index: `passengers.0`). The property updates each time the store value changes. Add `@state()` so Lit re-renders.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-bind"></docs-demo-sources>
+    <demo-bind></demo-bind>
+  </template>
+</sonic-code>
+
+## Typed key
+
+With a `DataProviderKey<T>`, TypeScript checks that the property type matches `T` at that path.
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+type Flight = { flight: string; gate: string; boarded: number };
+const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
+
+@bind(flightKey.boarded, { reflect: true })
+@state()
+boarded = 0;
+  </template>
+</sonic-code>
+
+## Reflect
+
+By default (`reflect: false`) the binding is one-way: assigning the property does not touch the store. With `reflect: true`, each assignment calls `set()` on the publisher, so every other subscriber sees the new value. An internal guard prevents update loops.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-bind-reflect"></docs-demo-sources>
+    <demo-bind-reflect></demo-bind-reflect>
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+Placeholders such as `${index}` are resolved from properties of the same component, and `@bind` re-subscribes when they change. Write them in a plain string, not a backtick template literal. While a placeholder is `null` or `undefined` the binding is inactive; `{ skipEmptyPlaceholder: true }` also waits on `""`. Full rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-bind-dynamic"></docs-demo-sources>
+    <demo-bind-dynamic></demo-bind-dynamic>
+  </template>
+</sonic-code>
+
+## Lifecycle
+
+The decorator subscribes in `connectedCallback` and unsubscribes in `disconnectedCallback`. It works on any element with that lifecycle (`LitElement`, the `Subscriber` mixin).
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `path` | `string` or `DataProviderKey<T>` | Store path to bind. Supports `${prop}` placeholders |
+| `options.reflect` | `boolean` (default `false`) | Write local assignments back to the store |
+| `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |

package/src/docs/decorators/get.md

@@ -0,0 +1,160 @@
+# @get
+
+`@get(endpoint)` runs an HTTP GET on an [Endpoint](/docs/misc/endpoint) and stores the full `ApiResult<T>` in a property, or passes it to a method. It runs again when the endpoint's placeholders or the API configuration change, and on demand through `refetch`. For writes, see [@post](/docs/decorators/post), [@put](/docs/decorators/put) and [@patch](/docs/decorators/patch).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { get, Endpoint, type ApiResult } from "@supersoniks/concorde/decorators";
+
+type FlightBoard = { flights: Flight[] };
+const departuresEndpoint = new Endpoint&lt;FlightBoard&gt;("flights?direction=departures");
+
+@get(departuresEndpoint)
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+  </template>
+</sonic-code>
+
+## Property
+
+The property is `undefined` until the first response, then holds `result` (typed `T`), `response` (the HTTP response) and `request`. It is reset to `undefined` when the component disconnects.
+
+Without a configuration key, `serviceURL` and the token are read from the HTML scope: place the component under an element that sets them (see [API configuration](/docs/misc/api-configuration)). The GET waits until `serviceURL` is available.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get"></docs-demo-sources>
+    <demo-api-get></demo-api-get>
+  </template>
+</sonic-code>
+
+## Method
+
+Decorate a method to receive the `ApiResult<T>` after each GET instead of storing it.
+
+<sonic-code language="typescript">
+  <template>
+@get(departuresEndpoint)
+onDepartures(payload?: ApiResult&lt;FlightBoard&gt;) {
+  this.boarding = payload?.result?.flights.filter((f) =&gt; f.status === "boarding") ?? [];
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get-method"></docs-demo-sources>
+    <demo-api-get-method></demo-api-get-method>
+  </template>
+</sonic-code>
+
+## Configuration key
+
+Pass a `DataProviderKey<APIConfiguration>` as the second argument to read the configuration from the store instead of the HTML scope. Any change to that publisher runs the GET again.
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import type { APIConfiguration } from "@supersoniks/concorde/utils/api";
+
+const flightsApi = new DataProviderKey&lt;APIConfiguration&gt;("flightsApi");
+
+@get(departuresEndpoint, flightsApi)
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+  </template>
+</sonic-code>
+
+## Dynamic endpoint
+
+`${prop}` placeholders in the endpoint resolve from properties of the same component; each change runs a new GET. While a placeholder is `null` or `undefined`, no request is sent and the property is `undefined`. Rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+const boardEndpoint = new Endpoint&lt;FlightBoard, { direction: string }&gt;(
+  "flights?direction=${direction}",
+);
+
+@property() direction = "departures";
+
+@get(boardEndpoint, flightsApi)
+@state()
+board?: ApiResult&lt;FlightBoard&gt;;
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
+    <demo-api-get-configuration-key></demo-api-get-configuration-key>
+  </template>
+</sonic-code>
+
+## Refetch
+
+Keep the decorator in a constant to reuse it. `refetch(component)` runs the GET for that instance only and resolves with the new `ApiResult<T>` (or `undefined`).
+
+<sonic-code language="typescript">
+  <template>
+const departuresGet = get(departuresEndpoint);
+
+@departuresGet
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+
+async refresh() {
+  await departuresGet.refetch(this);
+}
+  </template>
+</sonic-code>
+
+`@refetch(handle)` does the same around a method. By default the GET runs **after** the method (and after its Promise, if it returns one); use `{ when: "before" }` to run it first. The method call resolves once the GET is done.
+
+<sonic-code language="typescript">
+  <template>
+import { refetch } from "@supersoniks/concorde/decorators";
+
+@refetch(departuresGet)
+async showArrivals() {
+  this.direction = "arrivals";
+}
+  </template>
+</sonic-code>
+
+## Polling and triggers
+
+`refetchEveryMs` runs the GET again that many milliseconds after each response (default `0`: off). `triggerKey` runs it whenever another component calls `invalidate()` on that publisher.
+
+<sonic-code language="typescript">
+  <template>
+import { dp } from "@supersoniks/concorde/utils";
+
+const boardRefresh = new DataProviderKey&lt;number&gt;("boardRefresh");
+
+@get(departuresEndpoint, { refetchEveryMs: 30000, triggerKey: boardRefresh })
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+
+// anywhere else
+dp(boardRefresh).invalidate();
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `Endpoint<T, U>` | Path relative to `serviceURL`. `U` lists the host properties used by `${…}` placeholders |
+| `configurationKey` | `DataProviderKey<APIConfiguration>` (optional) | Read the configuration from the store instead of the HTML scope |
+| `options.refetchEveryMs` | `number` (default `0`) | Polling interval after each response; `0` disables it |
+| `options.triggerKey` | `DataProviderKey<unknown>` | Publisher whose `invalidate()` runs the GET again |
+| `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |
+
+`options` is the second argument, or the third when a `configurationKey` is passed. The returned decorator exposes `refetch(component): Promise<ApiResult<T> | undefined>`.
+
+| `@refetch` argument | Type | Description |
+|---------------------|------|-------------|
+| `handle` | value returned by `get(…)` | GET to run |
+| `options.when` | `"before"` or `"after"` (default `"after"`) | Run the GET before or after the method |

package/src/docs/decorators/handle.md

@@ -0,0 +1,119 @@
+# @handle
+
+`@handle(...keys)` calls the decorated method each time a publisher assigns one of up to three store paths, with one typed argument per key. Nothing is stored on the component: use it for derived values and side effects, and [@subscribe](/docs/decorators/subscribe) when you only need the value. See [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { handle, Skip } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+const cockpitKey = new DataProviderKey&lt;{ altitude: number }&gt;("cockpit");
+
+@handle(cockpitKey.altitude)
+onAltitude(feet: number) {
+  this.meters = Math.round(feet * 0.3048);
+}
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The method runs once with the current value when the component connects, then on **every** assignment, including `null` and `undefined`. Below, each climb assigns a new altitude and the method derives meters and flight level.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-handle"></docs-demo-sources>
+    <demo-handle></demo-handle>
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+`${prop}` placeholders resolve from properties of the same component; when one changes, the method is called with the value at the new path. Rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
+  "demoOnBoard.${seatIndex}",
+);
+
+@property({ type: Number }) seatIndex = 0;
+
+@handle(personKey)
+onPerson(person: OnBoard | null) {
+  this.announcement = person ? `${person.name}, please proceed to gate B12.` : "";
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-handle-dynamic"></docs-demo-sources>
+    <demo-handle-dynamic></demo-handle-dynamic>
+  </template>
+</sonic-code>
+
+## Multiple keys
+
+Pass up to three [DataProviderKey](/docs/misc/dataProviderKey) values; the method receives one argument per key, in the same order. Any assignment to any key calls it, so other arguments may still be `null`.
+
+<sonic-code language="typescript">
+  <template>
+const flightKey = new DataProviderKey&lt;{ status: string; gate: string }&gt;("flight");
+const weatherKey = new DataProviderKey&lt;{ turbulence: boolean }&gt;("weather");
+
+@handle(flightKey.status, weatherKey.turbulence)
+onConditions(status: string, turbulence: boolean) {
+  this.seatbeltSign = status === "boarding" || turbulence === true;
+}
+  </template>
+</sonic-code>
+
+## Wait for all values
+
+With `waitForAllDefined: true`, the method runs only once every key holds a value other than `null` or `undefined`.
+
+<sonic-code language="typescript">
+  <template>
+@handle(flightKey.gate, passengerKey.name, { waitForAllDefined: true })
+announce(gate: string, name: string) {
+  this.message = `${name}, please proceed to gate ${gate}.`;
+}
+  </template>
+</sonic-code>
+
+## Skip values
+
+`skip` lists categories of values that must not call the method. A category is a named test, not a value to compare.
+
+| Category | Matches |
+|----------|---------|
+| `Skip.Nullish` | `null` or `undefined` |
+| `Skip.EmptyString` | `""` |
+| `Skip.EmptyObject` | `{}` (arrays excluded) |
+| `Skip.EmptyArray` | `[]` |
+
+<sonic-code language="typescript">
+  <template>
+@handle(passengerKey, { skip: [Skip.Nullish, Skip.EmptyObject] })
+onPassenger(passenger: Passenger) {
+  // not called while the publisher still holds {} (not loaded yet)
+  this.displayName = passenger.name;
+}
+  </template>
+</sonic-code>
+
+To reject a specific value, return early inside the method.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `key` (1 to 3) | `DataProviderKey<T, U>` | Paths to watch; the method receives one value per key, in order |
+| `options.waitForAllDefined` | `boolean` (default `false`) | Call the method only when no value is `null` or `undefined` |
+| `options.skip` | `Skip[]` (default none) | Do not call the method when any value matches one of these categories |
+| `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |
+
+`options`, if present, is the last argument. `@handle` replaces the deprecated [@onAssign](/docs/decorators/on-assign): `@onAssign("a", "b")` is `@handle(keyA, keyB, { waitForAllDefined: true })`.

package/src/docs/decorators/on-assign.md

@@ -0,0 +1,63 @@
+# @onAssign
+
+Legacy decorator that calls a method with the values at one or more string paths of the store, once all of them are defined. For new code, use [@handle](/docs/decorators/handle) with `{ waitForAllDefined: true }`: same behaviour, with typed `DataProviderKey` paths.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { onAssign } from "@supersoniks/concorde/decorators";
+
+@onAssign("passenger", "passengerSettings")
+onReady(passenger: Passenger, settings: Settings) {}
+  </template>
+</sonic-code>
+
+## Wait for every path
+
+The method is called only when every path holds a value other than `null` or `undefined`, with the values in the order of the paths. After that, each assignment calls it again with the latest values. Subscriptions start after `connectedCallback` and stop in `disconnectedCallback`.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-on-assign"></docs-demo-sources>
+    <demo-on-assign></demo-on-assign>
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+Paths accept `${prop}` placeholders resolved on the host. While a placeholder is `null` or `undefined`, that path is unsubscribed. Write the paths as plain strings, not template literals. Rules: [Dynamic path placeholders](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+@property({ type: Number }) seat = 0;
+
+@onAssign("passengers.${seat}", "passengerSettings.${seat}")
+onSeat(passenger: Passenger, settings: Settings) {}
+  </template>
+</sonic-code>
+
+## Migrate to @handle
+
+<sonic-code language="typescript">
+  <template>
+// Before
+@onAssign("passenger", "passengerSettings")
+onReady(passenger: any, settings: any) {}
+
+// After
+const passengerKey = new DataProviderKey&lt;Passenger&gt;("passenger");
+const settingsKey = new DataProviderKey&lt;Settings&gt;("passengerSettings");
+
+@handle(passengerKey, settingsKey, { waitForAllDefined: true })
+onReady(passenger: Passenger, settings: Settings) {}
+  </template>
+</sonic-code>
+
+`@handle` accepts up to three keys. For more paths, keep `@onAssign` or split the logic into several `@handle` methods.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `...paths` | `string[]` | Dot paths in the store (`"flights.0.status"`), optionally with `${prop}` placeholders; the method receives one argument per path, in order |

package/src/docs/decorators/patch.md

@@ -0,0 +1,44 @@
+# @patch
+
+Sends the value of a publisher as the body of a `PATCH` request, to update part of a resource, and stores the response in an `ApiResult<T>` property. It takes the same arguments, options and `send(component)` handle as [@post](/docs/decorators/post); only the HTTP method differs.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { patch, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The body holds only the fields to change, here a gate change for flight CN 001.
+
+<sonic-code language="typescript">
+  <template>
+type Flight = { flight: string; route: string; gate: string };
+
+const gateChangeKey = new DataProviderKey&lt;Partial&lt;Flight&gt;&gt;("gateChange");
+
+@patch(new Endpoint&lt;Flight&gt;("flights/CN001"), gateChangeKey)
+@state()
+payload?: ApiResult&lt;Flight&gt;;
+
+moveToB12() {
+  set(gateChangeKey, { gate: "B12" }); // sends the PATCH
+}
+  </template>
+</sonic-code>
+
+Triggers, the `send` method decorator and every option are described on [@post](/docs/decorators/post).
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `Endpoint<T>` | Resource path and response type |
+| `bodyKey` | `DataProviderKey<B>` | Publisher read as the partial body |
+| `configurationKey` | `DataProviderKey<APIConfiguration>` (optional) | API configuration publisher. Default: HTML scope |
+| `options` | `PatchOptions` | Same as [@post options](/docs/decorators/post) |