@supersoniks/concorde 4.9.0 → 4.9.2

package/src/docs/example/decorators-demo-subscribe-publish-get-demos.ts

@@ -1,32 +1,37 @@
 import { html, LitElement } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import { get, handle, publish, subscribe } from "@supersoniks/concorde/decorators";
-import type {
-  APIConfiguration,
-  ApiResult,
-} from "@supersoniks/concorde/core/utils/api";
+import type { ApiResult } from "@supersoniks/concorde/core/utils/api";
 import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
 import { sub } from "@supersoniks/concorde/directives";
 import {
+  dp,
   get as storeGet,
   set,
 } from "@supersoniks/concorde/core/utils/PublisherProxy";
 import { publishDemoKey } from "./docs-provider-keys";
-import {
-  docsDemoDynApiConfAKey,
-  docsDemoDynApiConfBKey,
-} from "./decorators-demo-geo";
 import { tailwind } from "../tailwind";
 import "./decorators-demo-init";
 import {
   docsDemoDynApiConfKeyTemplate,
   docsDemoGeoApiConfigurationKey,
+  docsDemoGeoCommunesRefreshKey,
   geoCommunesApiGetEndpoint,
   geoCommunesApiGetEndpointDynamic,
   geoCommunesApiGetPublishKey,
   type GeoCommuneRow,
 } from "./decorators-demo-geo";
 
+function formatFetchedAt(response: Response | null | undefined): string {
+  const raw = response?.headers.get("X-Fetched-At");
+  if (!raw) return "—";
+  try {
+    return new Date(raw).toLocaleTimeString();
+  } catch {
+    return raw;
+  }
+}
+
 type PublishDemoData = {
   email: string;
   message: string;
@@ -90,22 +95,35 @@ export class DemoPublish extends LitElement {
 export class DemoApiGet extends LitElement {
   static styles = [tailwind];
 
-  @get(geoCommunesApiGetEndpoint, docsDemoGeoApiConfigurationKey)
+  @get(geoCommunesApiGetEndpoint, docsDemoGeoApiConfigurationKey, {
+    triggerKey: docsDemoGeoCommunesRefreshKey,
+  })
   @state()
   geoApiPayload?: ApiResult<GeoCommuneRow[]>;
 
+  private refresh() {
+    dp(docsDemoGeoCommunesRefreshKey).invalidate();
+  }
+
   render() {
     const rows = this.geoApiPayload?.result;
     const status = this.geoApiPayload?.response?.status;
+    const fetchedAt = formatFetchedAt(this.geoApiPayload?.response ?? null);
     return html`
       <div class="space-y-2">
         <p class="text-sm text-neutral-600 dark:text-neutral-400">
           <code>@get</code> — même service que
           <code>sonic-queue</code> (<code>/docs-mock-api/geo/</code>).
           Propriété typée <code>ApiResult&lt;T&gt;</code>.
+          Refetch via <code>triggerKey</code> (<code
+            >docsDemoGeoCommunesRefresh</code
+          >).
         </p>
+        <sonic-button size="sm" @click=${this.refresh}>Rafraîchir</sonic-button>
         ${status != null
-          ? html`<p class="text-xs text-neutral-500">HTTP ${status}</p>`
+          ? html`<p class="text-xs text-neutral-500">
+              HTTP ${status} · fetch ${fetchedAt}
+            </p>`
           : ""}
         ${this.geoApiPayload === null
           ? html`<p class="text-neutral-500">Chargement…</p>`
@@ -139,29 +157,23 @@ export class DemoApiGetConfigurationKey extends LitElement {
   @property({ type: Number })
   communeLimit = 5;
 
-  @get(geoCommunesApiGetEndpointDynamic, docsDemoDynApiConfKeyTemplate)
+  @get(geoCommunesApiGetEndpointDynamic, docsDemoDynApiConfKeyTemplate, {
+    triggerKey: docsDemoGeoCommunesRefreshKey,
+  })
   @state()
   geoApiPayloadDyn?: ApiResult<GeoCommuneRow[]>;
 
-  private touchCurrentConfigPublisher() {
-    const key =
-      this.configSlot === "A" ? docsDemoDynApiConfAKey : docsDemoDynApiConfBKey;
-    const cur = storeGet(key) as APIConfiguration;
-    set(key, {
-      ...cur,
-      blockUntilDone: !cur.blockUntilDone,
-    });
-  }
-
   render() {
     const rows = this.geoApiPayloadDyn?.result;
     const status = this.geoApiPayloadDyn?.response?.status;
+    const fetchedAt = formatFetchedAt(this.geoApiPayloadDyn?.response ?? null);
     return html`
       <div class="space-y-3">
         <p class="text-sm text-neutral-600 dark:text-neutral-400">
           Config dynamique (<code>docsDemoDynApiConf\${configSlot}</code>) +
-          path d’endpoint avec <code>communeLimit</code>. « Toucher la config »
-          déclenche un nouveau GET.
+          path d’endpoint avec <code>communeLimit</code>. Le refetch manuel
+          passe par <code>triggerKey</code> — voir le bouton « ailleurs »
+          ci-dessous dans la doc.
         </p>
         <div class="flex flex-wrap gap-2 items-center">
           <span class="text-xs text-neutral-500">Limite API :</span>
@@ -196,16 +208,11 @@ export class DemoApiGetConfigurationKey extends LitElement {
             }}
             >docsDemoDynApiConfB</sonic-button
           >
-          <sonic-button
-            size="sm"
-            @click=${() => this.touchCurrentConfigPublisher()}
-            >Toucher la config</sonic-button
-          >
         </div>
         ${status != null
           ? html`<p class="text-xs text-neutral-500">
-              HTTP ${status} · limit=${this.communeLimit} · conf=
-              docsDemoDynApiConf${this.configSlot}
+              HTTP ${status} · fetch ${fetchedAt} · limit=${this.communeLimit} ·
+              conf=docsDemoDynApiConf${this.configSlot}
             </p>`
           : ""}
         ${this.geoApiPayloadDyn === null
@@ -230,6 +237,35 @@ export class DemoApiGetConfigurationKey extends LitElement {
   }
 }
 
+/** Déclenche le refetch d’un `@get` distant via `triggerKey` (sans toucher la config). */
+@customElement("demo-api-get-refresh-remote")
+export class DemoApiGetRefreshRemote extends LitElement {
+  static styles = [tailwind];
+
+  private refreshFromElsewhere() {
+    dp(docsDemoGeoCommunesRefreshKey).invalidate();
+  }
+
+  render() {
+    return html`
+      <div
+        class="rounded border border-dashed border-neutral-300 dark:border-neutral-600 p-3 space-y-2"
+      >
+        <p class="text-sm text-neutral-600 dark:text-neutral-400">
+          Composant séparé — même publisher
+          <code>docsDemoGeoCommunesRefresh</code> :
+        </p>
+        <pre
+          class="text-xs bg-neutral-100 dark:bg-neutral-800 p-2 rounded overflow-x-auto"
+        ><code>dp(docsDemoGeoCommunesRefreshKey).invalidate();</code></pre>
+        <sonic-button size="sm" variant="secondary" @click=${this.refreshFromElsewhere}>
+          Rafraîchir le GET (depuis ailleurs)
+        </sonic-button>
+      </div>
+    `;
+  }
+}
+
 @customElement("demo-api-get-publish-subscribe")
 export class DemoApiGetPublishSubscribe extends LitElement {
   static styles = [tailwind];
@@ -247,6 +283,9 @@ export class DemoApiGetPublishSubscribe extends LitElement {
     const rows =
       this.geoCommunesFromSubscribe ?? this.geoApiPayloadPublished?.result;
     const status = this.geoApiPayloadPublished?.response?.status;
+    const fetchedAt = formatFetchedAt(
+      this.geoApiPayloadPublished?.response ?? null,
+    );
     return html`
       <div class="space-y-2">
         <p class="text-sm text-neutral-600 dark:text-neutral-400">
@@ -255,7 +294,9 @@ export class DemoApiGetPublishSubscribe extends LitElement {
           rendu que <code>&lt;demo-api-get&gt;</code> (doc @get).
         </p>
         ${status != null
-          ? html`<p class="text-xs text-neutral-500">HTTP ${status}</p>`
+          ? html`<p class="text-xs text-neutral-500">
+              HTTP ${status} · fetch ${fetchedAt}
+            </p>`
           : ""}
         ${this.geoApiPayloadPublished === null
           ? html`<p class="text-neutral-500">Chargement…</p>`

package/src/docs/mock-api/router.ts

@@ -242,7 +242,9 @@ export async function handleDocsMockApiRequest(
   }
 
   if (subPath === "/geo/communes" || subPath.startsWith("/geo/communes")) {
-    return json(geoCommunes(url));
+    return json(geoCommunes(url), {
+      headers: { "X-Fetched-At": new Date().toISOString() },
+    });
   }
 
   const jokeMatch = subPath.match(/^\/jokes\/joke\/([^/]+)$/);

package/src/docs/search/docs-search.json

@@ -4030,7 +4030,22 @@
     }
   },
   {
-    "search": "Use { dynamic: true } when the decorated property must follow the DOM. The live demo below shows only the resolved attribute value — no store, no reparenting.\n",
+    "search": "Use { dynamic: true } when the decorated property must follow the DOM. With Lit, add @state() on the same property so template updates are visible when the observer assigns a new value.\n",
+    "files": {
+      "docs/_decorators/ancestor-attribute.md": {
+        "title": "@ancestorAttribute",
+        "hashes": {
+          "dynamic-mode": {
+            "count": 1,
+            "title": "Dynamic mode",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The live demo below shows only the resolved attribute value — no store, no reparenting.\n",
     "files": {
       "docs/_decorators/ancestor-attribute.md": {
         "title": "@ancestorAttribute",
@@ -4729,6 +4744,66 @@
       }
     }
   },
+  {
+    "search": "Pass as the second argument (scoped config) or third (with a configuration key). Same shape as send decorators where applicable:\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "options-getoptions": {
+            "count": 1,
+            "title": "Options (`GetOptions`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Same pattern as @post: a publisher acts as a signal, independent of the response payload.\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "manual-refetch-triggerkey": {
+            "count": 1,
+            "title": "Manual refetch (`triggerKey`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Prefer triggerKey over mutating the API configuration publisher when you only want to reload the same URL — no need to touch serviceURL, tokens, etc.\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "manual-refetch-triggerkey": {
+            "count": 1,
+            "title": "Manual refetch (`triggerKey`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The docs mock adds an X-Fetched-At response header on /docs-mock-api/geo/communes so live demos can show when the last fetch happened (response.headers.get("X-Fetched-At")).\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "manual-refetch-triggerkey": {
+            "count": 1,
+            "title": "Manual refetch (`triggerKey`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Same demo service as sonic-queue (/docs-mock-api/geo/). Publisher setup lives in decorators-demo-geo.ts and decorators-demo-subscribe-publish-get-demos.ts.\n",
     "files": {
@@ -4745,7 +4820,22 @@
     }
   },
   {
-    "search": "Dynamic config and endpoint path (demo-api-get-configuration-key in doc sources):\n",
+    "search": "@get with triggerKey — refresh button + X-Fetched-At timestamp in the UI:\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "live-demos": {
+            "count": 1,
+            "title": "Live demos",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Dynamic config and endpoint path. Manual refetch is triggered from a separate component (same triggerKey publisher):\n",
     "files": {
       "docs/_decorators/get.md": {
         "title": "@get",