@supersoniks/concorde 4.9.0 → 4.9.2

package/src/core/decorators/api.spec.ts

@@ -22,6 +22,15 @@ async function flushGetMicrotasks() {
   await Promise.resolve();
 }
 
+async function flushGetFrames() {
+  await new Promise<void>((resolve) => {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => resolve());
+    });
+  });
+  await Promise.resolve();
+}
+
 function mockPayload<T>(result: T) {
   return {
     request: new Request("https://api.example.test/items/1"),
@@ -61,7 +70,7 @@ describe("get", () => {
     }
     const el = document.createElement(tag) as InstanceType<typeof C>;
     document.body.appendChild(el);
-    await flushGetMicrotasks();
+    await flushGetFrames();
     expect(el.payload?.result).toEqual({ id: "loaded" });
     expect(el.payload?.response?.ok).toBe(true);
     expect(el.payload?.request.url).toContain("api.example.test");
@@ -88,7 +97,7 @@ describe("get", () => {
 
     const el = document.createElement(tag) as InstanceType<typeof TestRow>;
     document.body.appendChild(el);
-    await flushGetMicrotasks();
+    await flushGetFrames();
 
     expect(API.prototype.getDetailed).toHaveBeenCalledWith("rows/42");
     expect(el.payload?.result).toEqual({ id: "loaded" });
@@ -136,15 +145,76 @@ describe("get", () => {
     }
     const el = document.createElement(tag) as InstanceType<typeof C>;
     document.body.appendChild(el);
-    await flushGetMicrotasks();
+    await flushGetFrames();
     expect(API.prototype.getDetailed).toHaveBeenCalledTimes(1);
 
     pub.set({
       ...staticConfig,
       serviceURL: "https://api.example.test/v2",
     });
-    await flushGetMicrotasks();
+    await flushGetFrames();
     expect(API.prototype.getDetailed).toHaveBeenCalledTimes(2);
     expect(el.payload?.result).toEqual({ id: "loaded" });
   });
+
+  it("relance le GET quand le publisher trigger est invalidé", async () => {
+    const triggerPubId = "getSpecTrigger1";
+    const triggerKey = new DataProviderKey<number>(triggerPubId);
+    const itemEp = new Endpoint<{ id: string }>("items/1");
+    const tag = "test-api-get-trigger";
+
+    class C extends HTMLElement {
+      @get(itemEp, { triggerKey })
+      payload: ApiResult<{ id: string }> | null = null;
+    }
+    if (!customElements.get(tag)) {
+      customElements.define(tag, C);
+    }
+
+    const wrap = document.createElement("div");
+    wrap.setAttribute("serviceURL", "https://api.example.test");
+    const el = document.createElement(tag) as InstanceType<typeof C>;
+    wrap.appendChild(el);
+    document.body.appendChild(wrap);
+
+    await flushGetMicrotasks();
+    const callsBeforeInvalidate = vi.mocked(API.prototype.getDetailed).mock
+      .calls.length;
+    expect(callsBeforeInvalidate).toBeGreaterThanOrEqual(1);
+
+    PublisherManager.get(triggerPubId).invalidate();
+    await flushGetFrames();
+    expect(
+      vi.mocked(API.prototype.getDetailed).mock.calls.length,
+    ).toBeGreaterThan(callsBeforeInvalidate);
+    expect(el.payload?.result).toEqual({ id: "loaded" });
+  });
+
+  it("refetch automatique avec refetchEveryMs", async () => {
+    vi.useFakeTimers();
+    const itemEp = new Endpoint<{ id: string }>("items/1");
+    const tag = "test-api-get-refetch";
+
+    class C extends HTMLElement {
+      @get(itemEp, { refetchEveryMs: 1000 })
+      payload: ApiResult<{ id: string }> | null = null;
+    }
+    if (!customElements.get(tag)) {
+      customElements.define(tag, C);
+    }
+
+    const wrap = document.createElement("div");
+    wrap.setAttribute("serviceURL", "https://api.example.test");
+    wrap.appendChild(document.createElement(tag));
+    document.body.appendChild(wrap);
+
+    await flushGetMicrotasks();
+    expect(API.prototype.getDetailed).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(1000);
+    await flushGetMicrotasks();
+    expect(API.prototype.getDetailed).toHaveBeenCalledTimes(2);
+
+    vi.useRealTimers();
+  });
 });

package/src/core/decorators/api.ts

@@ -162,14 +162,25 @@ function watchScopedConfiguration(
   };
 }
 
-type ApiGetState = {
-  cleanupWatchers: Array<() => void>;
-  requestGeneration: number;
-  configPublisher: DataProvider | null;
-  configMutationHandler: (() => void) | null;
-  scopeWatchCleanup: (() => void) | null;
+type TriggerPublisherBinding = {
+  triggerPublisher: DataProvider | null;
+  triggerInvalidateHandler: (() => void) | null;
+};
+
+type RefetchScheduleState = {
+  refetchTimeoutId: ReturnType<typeof setTimeout> | null;
+  refetchEveryMs: number;
 };
 
+type ApiGetState = TriggerPublisherBinding &
+  RefetchScheduleState & {
+    cleanupWatchers: Array<() => void>;
+    requestGeneration: number;
+    configPublisher: DataProvider | null;
+    configMutationHandler: (() => void) | null;
+    scopeWatchCleanup: (() => void) | null;
+  };
+
 function detachConfigPublisher(state: ApiGetState): void {
   if (state.configPublisher && state.configMutationHandler) {
     state.configPublisher.offInternalMutation(state.configMutationHandler);
@@ -191,6 +202,9 @@ function detachConfigPublisher(state: ApiGetState): void {
  * `PublisherManager` sur le chemin résolu (même syntaxe dynamique que `@subscribe`).
  * Toute mutation interne du publisher (`onInternalMutation`) relance le GET.
  *
+ * **Options** (`GetOptions`) : `triggerKey` — `PublisherManager.get(...).invalidate()` relance le GET ;
+ * `refetchEveryMs` — polling automatique.
+ *
  * @example
  * @get(new Endpoint<User, { userId: string }>("users/${userId}"))
  * payload?: ApiResult<User>;
@@ -200,6 +214,11 @@ function detachConfigPublisher(state: ApiGetState): void {
  * PublisherManager.get("myApiConf").set({ serviceURL: "...", token: null, ... });
  * @get(new Endpoint<Thing, { id: string }>("things/${id}"), apiConf)
  * payload?: ApiResult<Thing>;
+ *
+ * @example
+ * @get(usersEndpoint, { triggerKey: refreshUsersKey })
+ * payload?: ApiResult<User[]>;
+ * // PublisherManager.get("users.refresh").invalidate() → refetch
  */
 export function get<T, Ue = any>(
   endpoint: Endpoint<T, Ue>,
@@ -260,18 +279,24 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
     skipEmptyPlaceholder: options?.skipEmptyPlaceholder,
   };
   const configurationKeyPath = configurationKey?.path;
+  const triggerKeyPath = options?.triggerKey?.path;
   const endpointDynamicDependencies = extractDynamicDependencies(pathTemplate);
   const configKeyDynamicDependencies = configurationKeyPath
     ? extractDynamicDependencies(configurationKeyPath)
     : [];
+  const triggerKeyDynamicDependencies = triggerKeyPath
+    ? extractDynamicDependencies(triggerKeyPath)
+    : [];
   const mergedDynamicDependencies = [
     ...new Set([
       ...endpointDynamicDependencies,
       ...configKeyDynamicDependencies,
+      ...triggerKeyDynamicDependencies,
     ]),
   ];
   const isDynamicPath = endpointDynamicDependencies.length > 0;
   const usesPublisherConfig = Boolean(configurationKeyPath);
+  const refetchEveryMs = options?.refetchEveryMs ?? 0;
 
   return function (target: object, propertyKey: string) {
     if (!target) return;
@@ -288,6 +313,10 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
           configPublisher: null,
           configMutationHandler: null,
           scopeWatchCleanup: null,
+          triggerPublisher: null,
+          triggerInvalidateHandler: null,
+          refetchTimeoutId: null,
+          refetchEveryMs,
         };
         comp[stateKey] = state;
       }
@@ -295,6 +324,17 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
       state.cleanupWatchers.forEach((cleanup) => cleanup());
       state.cleanupWatchers = [];
       state.requestGeneration++;
+      state.refetchEveryMs = refetchEveryMs;
+      clearRefetch(state);
+
+      const scheduleRefetch = () => {
+        clearRefetch(state);
+        if (!state.refetchEveryMs || state.refetchEveryMs <= 0) return;
+        state.refetchTimeoutId = setTimeout(() => {
+          state.refetchTimeoutId = null;
+          runFetch();
+        }, state.refetchEveryMs);
+      };
 
       const runFetch = () => {
         const resolution = isDynamicPath
@@ -302,6 +342,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
           : { ready: true, path: pathTemplate };
         if (!resolution.ready || !resolution.path) {
           comp[propertyKey] = undefined;
+          scheduleRefetch();
           return;
         }
         let config: APIConfiguration | null = null;
@@ -313,6 +354,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
           );
           if (!configRes.ready || !configRes.path) {
             comp[propertyKey] = undefined;
+            scheduleRefetch();
             return;
           }
           const configPublisher = getPublisherFromPath(configRes.path);
@@ -329,6 +371,7 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
               state.scopeWatchCleanup = null;
             });
           }
+          scheduleRefetch();
           return;
         }
         const generation = ++state.requestGeneration;
@@ -338,9 +381,31 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
           .then((payload?: ApiResult<T>) => {
             if (generation !== state.requestGeneration) return;
             comp[propertyKey] = payload;
+            scheduleRefetch();
           });
       };
 
+      const scheduleFetch = createAnimationFrameCoalescedRunner(runFetch);
+
+      const rebindTriggerPublisher = () => {
+        detachTriggerPublisher(state);
+        if (!triggerKeyPath) return;
+        const triggerResolution = resolveDynamicPath(
+          component,
+          triggerKeyPath,
+          pathOptions,
+        );
+        if (!triggerResolution.ready || !triggerResolution.path) {
+          return;
+        }
+        const publisher = getPublisherFromPath(triggerResolution.path);
+        if (!publisher) return;
+        const invalidateHandler = () => scheduleFetch();
+        publisher.onInvalidate(invalidateHandler);
+        state.triggerPublisher = publisher;
+        state.triggerInvalidateHandler = invalidateHandler;
+      };
+
       const rebindPublisherConfig = () => {
         if (!usesPublisherConfig || !configurationKeyPath) return;
         detachConfigPublisher(state);
@@ -358,26 +423,32 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
           comp[propertyKey] = undefined;
           return;
         }
-        const mutationHandler = () => {
-          runFetch();
-        };
+        const mutationHandler = () => scheduleFetch();
         publisher.onInternalMutation(mutationHandler);
         state.configPublisher = publisher;
         state.configMutationHandler = mutationHandler;
       };
 
-      if (usesPublisherConfig) {
+      const rebindAll = () => {
+        rebindTriggerPublisher();
+        rebindPublisherConfig();
+        if (!usesPublisherConfig) {
+          scheduleFetch();
+        }
+      };
+
+      if (usesPublisherConfig || triggerKeyDynamicDependencies.length) {
         for (const dependency of mergedDynamicDependencies) {
           const unsubscribe = observeDynamicProperty(
             getDynamicWatchKeys.watcherStore,
             getDynamicWatchKeys.hooked,
             component,
             dependency,
-            () => rebindPublisherConfig(),
+            () => rebindAll(),
           );
           state.cleanupWatchers.push(unsubscribe);
         }
-        rebindPublisherConfig();
+        rebindAll();
       } else {
         const startScopedFetch = () => {
           if (isDynamicPath) {
@@ -387,11 +458,12 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
                 getDynamicWatchKeys.hooked,
                 component,
                 dependency,
-                () => runFetch(),
+                () => scheduleFetch(),
               );
               state.cleanupWatchers.push(unsubscribe);
             }
           }
+          rebindTriggerPublisher();
           runFetch();
         };
         state.cleanupWatchers.push(
@@ -405,6 +477,8 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
       const state = comp[stateKey] as ApiGetState | undefined;
       if (!state) return;
       detachConfigPublisher(state);
+      detachTriggerPublisher(state);
+      clearRefetch(state);
       state.cleanupWatchers.forEach((cleanup) => cleanup());
       state.cleanupWatchers = [];
       state.requestGeneration++;
@@ -413,7 +487,12 @@ export function get<T, Ue = any, Uk = any, _Ut = any>(
   };
 }
 
-export type GetOptions = DynamicPathOptions;
+export type GetOptions<Uk = any> = DynamicPathOptions & {
+  /** Intervalle de refetch automatique (ms). 0 ou absent = pas de polling. */
+  refetchEveryMs?: number;
+  /** Publisher dont `invalidate()` relance le GET. */
+  triggerKey?: DataProviderKey<unknown, Uk>;
+};
 
 export type ApiSendOptions<Uk = any> = DynamicPathOptions & {
   /** Intervalle de renvoi automatique (ms). 0 ou absent = pas de polling. */
@@ -436,7 +515,11 @@ export type PatchOptions<Uk = any> = ApiSendOptions<Uk>;
 
 function isGetOptions(value: unknown): value is GetOptions {
   if (!value || typeof value !== "object") return false;
-  return "skipEmptyPlaceholder" in value;
+  return (
+    "skipEmptyPlaceholder" in value ||
+    "refetchEveryMs" in value ||
+    "triggerKey" in value
+  );
 }
 
 function isApiSendOptions(value: unknown): value is ApiSendOptions {
@@ -469,7 +552,7 @@ function detachBodyPublisher(state: ApiSendState): void {
   state.bodyMutationHandler = null;
 }
 
-function detachTriggerPublisher(state: ApiSendState): void {
+function detachTriggerPublisher(state: TriggerPublisherBinding): void {
   if (state.triggerPublisher && state.triggerInvalidateHandler) {
     state.triggerPublisher.offInvalidate(state.triggerInvalidateHandler);
   }
@@ -477,7 +560,7 @@ function detachTriggerPublisher(state: ApiSendState): void {
   state.triggerInvalidateHandler = null;
 }
 
-function clearSendRefetch(state: ApiSendState): void {
+function clearRefetch(state: RefetchScheduleState): void {
   if (state.refetchTimeoutId) {
     clearTimeout(state.refetchTimeoutId);
     state.refetchTimeoutId = null;
@@ -582,10 +665,10 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
         state.refetchEveryMs = refetchEveryMs;
         state.skipIfBodyMissing = skipIfBodyMissing;
         state.autoPostOnBodyMutation = autoPostOnBodyMutation;
-        clearSendRefetch(state);
+        clearRefetch(state);
 
         const scheduleRefetch = () => {
-          clearSendRefetch(state);
+          clearRefetch(state);
           if (!state.refetchEveryMs || state.refetchEveryMs <= 0) return;
           state.refetchTimeoutId = setTimeout(() => {
             state.refetchTimeoutId = null;
@@ -789,7 +872,7 @@ function createApiSendDecorator<T, B, Ue = any, Uk = any, Ut = any>(
         detachConfigPublisher(state);
         detachBodyPublisher(state);
         detachTriggerPublisher(state);
-        clearSendRefetch(state);
+        clearRefetch(state);
         state.cleanupWatchers.forEach((cleanup) => cleanup());
         state.cleanupWatchers = [];
         state.requestGeneration++;

package/src/core/decorators/subscriber/ancestorAttribute.spec.ts

@@ -55,6 +55,25 @@ describe("ancestorAttribute", () => {
     expect(el.dataProvider).toBe("scope-a");
   });
 
+  it("assigne une chaine vide si l'attribut ancêtre est présent sans valeur (mode statique)", () => {
+    const tag = "test-ancestor-attr-static-empty";
+    class C extends HTMLElement {
+      @ancestorAttribute("is_guichet")
+      isGuichet: string | null = null;
+    }
+    if (!customElements.get(tag)) {
+      customElements.define(tag, C);
+    }
+
+    const wrap = document.createElement("div");
+    wrap.setAttribute("is_guichet", "");
+    const el = document.createElement(tag) as InstanceType<typeof C>;
+    wrap.appendChild(el);
+    document.body.appendChild(wrap);
+
+    expect(el.isGuichet).toBe("");
+  });
+
   it("met à jour la propriété quand un ancêtre change (mode dynamique)", async () => {
     const tag = "test-ancestor-attr-dynamic-mutation";
     class C extends HTMLElement {
@@ -101,6 +120,29 @@ describe("ancestorAttribute", () => {
     expect(el.dataProvider).toBeNull();
   });
 
+  it("met à jour avec une chaine vide si l'attribut ancêtre devient présent sans valeur (mode dynamique)", async () => {
+    const tag = "test-ancestor-attr-dynamic-empty";
+    class C extends HTMLElement {
+      @ancestorAttribute("is_guichet", { dynamic: true })
+      isGuichet: string | null = null;
+    }
+    if (!customElements.get(tag)) {
+      customElements.define(tag, C);
+    }
+
+    const wrap = document.createElement("div");
+    const el = document.createElement(tag) as InstanceType<typeof C>;
+    wrap.appendChild(el);
+    document.body.appendChild(wrap);
+
+    expect(el.isGuichet).toBeNull();
+
+    wrap.setAttribute("is_guichet", "");
+    await flushFrames();
+
+    expect(el.isGuichet).toBe("");
+  });
+
   it("retombe sur l'ancêtre suivant quand le plus proche perd l'attribut", async () => {
     const tag = "test-ancestor-attr-dynamic-fallback";
     class C extends HTMLElement {

package/src/core/utils/HTML.ts

@@ -71,10 +71,9 @@ class HTML {
   ): string | null {
     for (const attrName of HTML.scopeAttributeNames(attributeName)) {
       if (element.hasAttribute(attrName)) {
-        const attr = element.getAttribute(attrName);
-        if (attr != null && attr.length > 0) {
-          return attr;
-        }
+        // Un attribut HTML peut exister sans valeur (ex: <x is_guichet>),
+        // on retourne donc "" plutôt que null pour préserver ce cas.
+        return element.getAttribute(attrName) ?? "";
       }
     }
     return null;
@@ -94,7 +93,7 @@ class HTML {
     while (current) {
       if (current instanceof HTMLElement) {
         const value = HTML.readScopeAttributeOnElement(current, attributeName);
-        if (value != null && value.length > 0) {
+        if (value != null) {
           return value;
         }
       }

package/src/docs/_decorators/get.md

@@ -13,10 +13,53 @@ Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument.
 
 `${prop}` on the endpoint or config key is resolved on the host. While a placeholder is `null` or `undefined`, no GET runs. Optional `skipEmptyPlaceholder: true` also blocks `""` (empty string only). Details: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
 
+## Options (`GetOptions`)
+
+Pass as the **second** argument (scoped config) or **third** (with a configuration key). Same shape as send decorators where applicable:
+
+| Option | Description |
+|--------|-------------|
+| `skipEmptyPlaceholder` | Treat `""` as not ready (see [Dynamic path](#docs/_misc/dynamic-path.md/dynamic-path)). |
+| `refetchEveryMs` | Automatic polling interval (ms). `0` or omitted = no polling. |
+| `triggerKey` | `DataProviderKey` — `PublisherManager.get(...).invalidate()` on that publisher re-runs the GET. |
+
+### Manual refetch (`triggerKey`)
+
+Same pattern as [@post](#docs/_decorators/post.md/post): a publisher acts as a **signal**, independent of the response payload.
+
+```typescript
+import { get, type ApiResult } from "@supersoniks/concorde/decorators";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { dp } from "@supersoniks/concorde/core/utils/PublisherProxy";
+
+const geoCommunesEndpoint = new Endpoint<GeoCommuneRow[]>(
+  "communes?limit=5&fields=nom,code",
+);
+const geoCommunesRefreshKey = new DataProviderKey<void>(
+  "docsDemoGeoCommunesRefresh",
+);
+
+@get(geoCommunesEndpoint, apiConfigurationKey, {
+  triggerKey: geoCommunesRefreshKey,
+})
+@state()
+payload: ApiResult<GeoCommuneRow[]> | null = null;
+
+// Same component or anywhere else:
+dp(geoCommunesRefreshKey).invalidate();
+```
+
+Prefer `triggerKey` over mutating the API configuration publisher when you only want to **reload the same URL** — no need to touch `serviceURL`, tokens, etc.
+
+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")`).
+
 ## When the GET runs again
 
 - A referenced Lit property changes (endpoint path and/or config key contains `${...}`).
 - `set` on the active configuration publisher (`onInternalMutation`).
+- `triggerKey` publisher `invalidate()`.
+- `refetchEveryMs` polling (after each successful fetch).
 
 ## Import
 
@@ -42,6 +85,8 @@ payload: ApiResult<User> | null = null;
 
 ## Live demos
 
+`@get` with **`triggerKey`** — refresh button + `X-Fetched-At` timestamp in the UI:
+
 <sonic-code>
   <template>
     <docs-demo-sources for="demo-api-get"></docs-demo-sources>
@@ -49,12 +94,13 @@ payload: ApiResult<User> | null = null;
   </template>
 </sonic-code>
 
-Dynamic config and endpoint path (`demo-api-get-configuration-key` in doc sources):
+Dynamic config and endpoint path. Manual refetch is triggered **from a separate component** (same `triggerKey` publisher):
 
 <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>
+    <demo-api-get-refresh-remote></demo-api-get-refresh-remote>
   </template>
 </sonic-code>
 

package/src/docs/components/docs-demo-sources.ts

@@ -255,10 +255,15 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-api-get-configuration-key": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 126,
+      line: 147,
       label: "demo-api-get-configuration-key",
     },
-    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 239,
+      label: "demo-api-get-refresh-remote",
+    },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API + triggerKey" },
   ],
   "demo-api-get-publish-subscribe": [
     {

package/src/docs/example/decorators-demo-geo.ts

@@ -49,3 +49,8 @@ export const geoCommunesApiGetEndpointDynamic = new Endpoint<GeoCommuneRow[]>(
 export const geoCommunesApiGetPublishKey = new DataProviderKey<
   ApiResult<GeoCommuneRow[]>
 >(geoCommunesApiGetEndpoint.path);
+
+/** Signal de refetch manuel pour les démos `@get` (voir `triggerKey`). */
+export const docsDemoGeoCommunesRefreshKey = new DataProviderKey<void>(
+  "docsDemoGeoCommunesRefresh",
+);