@supersoniks/concorde 4.8.0 → 4.9.1

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/example/decorators-demo.ts

@@ -1,4 +1,4 @@
-import { html, LitElement } from "lit";
+import { html, LitElement, nothing } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import {
   ancestorAttribute,
@@ -22,12 +22,16 @@ import {
   waitAncestorDemoKey,
 } from "./docs-provider-keys";
 import { tailwind } from "../tailwind";
+import "./decorators-demo-init";
+import "../../core/components/ui/button/button";
 import "./decorators-demo-bind-demos";
 import "./decorators-demo-subscribe-publish-get-demos";
 import "./decorators-demo-post";
 
 @customElement("demo-ancestor-attribute")
 export class DemoAncestorAttribute extends LitElement {
+  static styles = [tailwind];
+
   @ancestorAttribute("dataProvider")
   dataProvider: string | null = null;
 
@@ -36,16 +40,166 @@ export class DemoAncestorAttribute extends LitElement {
 
   render() {
     return html`
-      <section>
+      <div
+        class="space-y-2 rounded border border-neutral-200 dark:border-neutral-700 p-3"
+      >
+        <p class="text-sm text-neutral-600 dark:text-neutral-400">
+          <code>@ancestorAttribute</code> — lecture unique au connect (défaut)
+        </p>
         <p>
-          DataProvider property initialized from ancestor:
-          <strong>${this.dataProvider || "null"}</strong>
+          dataProvider:
+          <strong>${this.dataProvider ?? "null"}</strong>
         </p>
         <p>
-          TestAttribute property initialized from ancestor:
-          <strong>${this.testAttribute || "null"}</strong>
+          testAttribute:
+          <strong>${this.testAttribute ?? "null"}</strong>
+        </p>
+      </div>
+    `;
+  }
+}
+
+@customElement("demo-ancestor-attribute-dynamic")
+export class DemoAncestorAttributeDynamic extends LitElement {
+  static styles = [tailwind];
+
+  @ancestorAttribute("dataProvider", { dynamic: true })
+  @state()
+  dataProvider: string | null = null;
+
+  render() {
+    return html`
+      <div
+        class="rounded border border-neutral-200 dark:border-neutral-700 bg-white dark:bg-neutral-950 p-3"
+      >
+        <p class="text-sm text-neutral-500">
+          Nearest ancestor <code>dataProvider</code>
+        </p>
+        <p class="text-lg font-semibold">${this.dataProvider ?? "null"}</p>
+      </div>
+    `;
+  }
+}
+
+@customElement("demo-ancestor-attribute-dynamic-section")
+export class DemoAncestorAttributeDynamicSection extends LitElement {
+  static styles = [tailwind];
+
+  /** Direct parent of the child — closest ancestor when set. */
+  @state() parentValue: string | null = "from-parent";
+  /** Grandparent — used when the parent has no attribute. */
+  @state() outerValue: string | null = "from-outer";
+  /** Optional wrapper inserted between parent and child (wins over parent). */
+  @state() closerActive = false;
+
+  render() {
+    return html`
+      <div class="space-y-4">
+        <p class="text-sm text-neutral-600 dark:text-neutral-400">
+          The child always displays the <strong>nearest</strong> ancestor
+          <code>dataProvider</code>. Change a value, add a closer wrapper, or
+          remove an attribute — the property follows automatically.
         </p>
-      </section>
+
+        <div class="flex flex-wrap gap-2">
+          <span class="text-xs text-neutral-500 self-center w-full"
+            >Parent</span
+          >
+          <sonic-button
+            size="sm"
+            @click=${() => (this.parentValue = "from-parent")}
+          >
+            parent-a
+          </sonic-button>
+          <sonic-button
+            size="sm"
+            @click=${() => (this.parentValue = "from-parent-b")}
+          >
+            parent-b
+          </sonic-button>
+          <sonic-button
+            size="sm"
+            variant="outline"
+            @click=${() => (this.parentValue = null)}
+          >
+            Remove parent attr
+          </sonic-button>
+        </div>
+
+        <div class="flex flex-wrap gap-2">
+          <span class="text-xs text-neutral-500 self-center w-full"
+            >Closer wrapper (inserted between parent and child)</span
+          >
+          <sonic-button
+            size="sm"
+            ?disabled=${this.closerActive}
+            @click=${() => (this.closerActive = true)}
+          >
+            Add closer → from-closer
+          </sonic-button>
+          <sonic-button
+            size="sm"
+            variant="outline"
+            ?disabled=${!this.closerActive}
+            @click=${() => (this.closerActive = false)}
+          >
+            Remove closer
+          </sonic-button>
+        </div>
+
+        <div class="flex flex-wrap gap-2">
+          <span class="text-xs text-neutral-500 self-center w-full">Outer</span>
+          <sonic-button
+            size="sm"
+            @click=${() => (this.outerValue = "from-outer")}
+          >
+            outer-a
+          </sonic-button>
+          <sonic-button
+            size="sm"
+            @click=${() => (this.outerValue = "from-outer-b")}
+          >
+            outer-b
+          </sonic-button>
+          <sonic-button
+            size="sm"
+            variant="outline"
+            @click=${() => (this.outerValue = null)}
+          >
+            Remove outer attr
+          </sonic-button>
+        </div>
+
+        <div
+          class="rounded border border-neutral-200 dark:border-neutral-700 p-3 space-y-2"
+          dataProvider=${this.outerValue ?? nothing}
+        >
+          <p class="text-xs text-neutral-400">
+            outer ${this.outerValue ?? "— no dataProvider —"}
+          </p>
+          <div
+            class="rounded border border-dashed border-neutral-300 dark:border-neutral-600 p-3 space-y-2"
+            dataProvider=${this.parentValue ?? nothing}
+          >
+            <p class="text-xs text-neutral-400">
+              parent ${this.parentValue ?? "— no dataProvider —"}
+            </p>
+            ${this.closerActive
+              ? html`
+                  <div
+                    class="rounded border border-amber-300 dark:border-amber-700 bg-amber-50 dark:bg-amber-950/30 p-2 space-y-2"
+                    dataProvider="from-closer"
+                  >
+                    <p class="text-xs text-amber-800 dark:text-amber-200">
+                      closer from-closer
+                    </p>
+                    <demo-ancestor-attribute-dynamic></demo-ancestor-attribute-dynamic>
+                  </div>
+                `
+              : html`<demo-ancestor-attribute-dynamic></demo-ancestor-attribute-dynamic>`}
+          </div>
+        </div>
+      </div>
     `;
   }
 }
@@ -133,7 +287,9 @@ export class DemoOnAssignDynamic extends LitElement {
 
   updateCurrentUserData() {
     const usersKey =
-      this.dataProvider === demoUsersAltKey.path ? demoUsersAltKey : demoUsersKey;
+      this.dataProvider === demoUsersAltKey.path
+        ? demoUsersAltKey
+        : demoUsersKey;
     const settingsKey =
       this.dataProvider === demoUsersAltKey.path
         ? demoUsersAltSettingsKey

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

@@ -3935,7 +3935,7 @@
     }
   },
   {
-    "search": "The component reads dataProvider and testAttribute from its ancestor wrapper.\n",
+    "search": "The component reads dataProvider and testAttribute from its ancestor wrapper. By default (dynamic: false), values are read once at connect.\n",
     "files": {
       "docs/_decorators/ancestor-attribute.md": {
         "title": "@ancestorAttribute",
@@ -3980,7 +3980,7 @@
     }
   },
   {
-    "search": "  render() {\n    return html      <section>         <p>dataProvider: <strong>${this.dataProvider || "null"}</strong></p>         <p>testAttribute: <strong>${this.testAttribute || "null"}</strong></p>       </section>    ;\n  }\n}\n  \n\n",
+    "search": "  render() {\n    return html      <p>dataProvider: <strong>${this.dataProvider ?? "null"}</strong></p>       <p>testAttribute: <strong>${this.testAttribute ?? "null"}</strong></p>    ;\n  }\n}\n  \n\n",
     "files": {
       "docs/_decorators/ancestor-attribute.md": {
         "title": "@ancestorAttribute",
@@ -4029,6 +4029,81 @@
       }
     }
   },
+  {
+    "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",
+        "hashes": {
+          "dynamic-mode": {
+            "count": 1,
+            "title": "Dynamic mode",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "  render() {\n    return html      <p>Nearest ancestor: <strong>${this.dataProvider ?? "null"}</strong></p>    ;\n  }\n}\n  \n\n",
+    "files": {
+      "docs/_decorators/ancestor-attribute.md": {
+        "title": "@ancestorAttribute",
+        "hashes": {
+          "dynamic-mode": {
+            "count": 1,
+            "title": "Dynamic mode",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Try in the demo:\n",
+    "files": {
+      "docs/_decorators/ancestor-attribute.md": {
+        "title": "@ancestorAttribute",
+        "hashes": {
+          "dynamic-mode": {
+            "count": 1,
+            "title": "Dynamic mode",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Static mode (default) — read once at connect, no observer:\n",
+    "files": {
+      "docs/_decorators/ancestor-attribute.md": {
+        "title": "@ancestorAttribute",
+        "hashes": {
+          "dynamic-mode": {
+            "count": 1,
+            "title": "Dynamic mode",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "@autoSubscribe",
     "files": {
@@ -4669,6 +4744,21 @@
       }
     }
   },
+  {
+    "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 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": {

package/src/tsconfig.declarations.json

@@ -0,0 +1,22 @@
+{
+  "extends": "./tsconfig-model.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "../dist/types",
+    "rootDir": "."
+  },
+  "include": ["**/*.ts"],
+  "exclude": [
+    "node_modules/**/*",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.demo.ts",
+    "**/*.stories.ts",
+    "**/*.type-test.ts",
+    "docs.ts",
+    "docs/**/*"
+  ]
+}

package/src/tsconfig.emit.json

@@ -0,0 +1,23 @@
+{
+  "extends": "./tsconfig-model.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": false,
+    "declaration": false,
+    "sourceMap": true,
+    "outDir": "../dist/js",
+    "rootDir": ".",
+    "lib": ["ES2021", "DOM", "DOM.Iterable"]
+  },
+  "include": ["**/*.ts"],
+  "exclude": [
+    "node_modules/**/*",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.demo.ts",
+    "**/*.stories.ts",
+    "**/*.type-test.ts",
+    "docs.ts",
+    "docs/**/*"
+  ]
+}