@supersoniks/concorde 4.6.0 → 4.7.3

package/src/core/components/ui/form/select/select.md

@@ -64,34 +64,8 @@
   </template>
 </sonic-code>
 
-## Example of use
-<sonic-code>
-  <template>
-    <sonic-select
-      formDataProvider="select-filter"
-      name="lang"
-      value="fr"
-    >
-    <option value="fr">fr<option>
-    <optionn value="en">en<option>
-    </sonic-select>
-    <sonic-subscriber dataProvider="select-filter" class="text-xl my-4 block font-bold">
-      Blagues trouvées pour le code de langue"<span data-bind ::inner-html="$lang"></span>" :
-    </sonic-subscriber>
-    <sonic-queue
-      lazyload
-      dataProviderExpression="joke/Any?amount=10"
-      dataFilterProvider="select-filter"
-      serviceURL="https://v2.jokeapi.dev"
-      key="jokes"
-    >
-      <template>
-        <div class="border-0 border-b-[1px] border-b-neutral-300 border-dotted py-3">
-          <div data-bind ::inner-html="$joke"></div>
-          <div data-bind ::inner-html="$setup"></div>
-          <div data-bind ::inner-html="$delivery"></div>
-        </div>
-      </template>
-    </sonic-queue>
-  </template>
-</sonic-code>
+## Example of use — language filter + queue
+
+**`name="lang"`** is sent as `?lang=fr|en` to the [doc mock API](#docs/_misc/docs-mock-api.md/docs-mock-api) (`filterDocsJokes`). Same pattern as [Input](#core/components/ui/form/input/input.md/input) (`contains`):
+
+<docs-lit-demo for="docs-joke-lang-demo"></docs-lit-demo>

package/src/core/components/ui/form/switch/switch.md

@@ -50,35 +50,8 @@
 </sonic-code>
 
 
-## Example of use
-<sonic-code>
-  <template>
-      <sonic-subscriber dataProvider="jokeFilterswitch" class="text-xl my-4 block font-bold">
-        Remove following jokes :
-        <sonic-value key="blacklistFlags" class="block text-sm"></sonic-value>
-      </sonic-subscriber>
-      <div formDataProvider="jokeFilterswitch"  class="grid grid-cols-2 lg:grid-cols-3 gap-x-6 gap-y-2 mt-2 mb-3">
-        <sonic-switch name="blacklistFlags"  value="nsfw">nsfw</sonic-switch>
-        <sonic-switch name="blacklistFlags"  value="religious">religious</sonic-switch>
-        <sonic-switch name="blacklistFlags"  value="political">political</sonic-switch>
-        <sonic-switch name="blacklistFlags"  value="racist" checked >racist</sonic-switch>
-        <sonic-switch name="blacklistFlags"  value="sexist"  >sexist</sonic-switch>
-        <sonic-switch name="blacklistFlags"   value="explicit">explicit</sonic-switch>
-      </div>
-      <sonic-queue
-        lazyload
-        dataProviderExpression="joke/Any?amount=10&lang=en"
-        dataFilterProvider="jokeFilterswitch"
-        serviceURL="https://v2.jokeapi.dev"
-        key="jokes"
-      >
-        <template>
-          <div class="border-0 border-b-[1px] border-b-neutral-300  py-3 leading-tight">
-            <sonic-value key="joke"></sonic-value>
-            <sonic-value key="setup" class="font-bold"></sonic-value><br>
-            <sonic-value key="delivery"></sonic-value>
-          </div>
-        </template>
-      </sonic-queue>
-  </template>
-</sonic-code>
+## Example of use — blacklist + queue
+
+Same mock filter as [Checkbox](#core/components/ui/form/checkbox/checkbox.md/checkbox); switches can enable several flags (comma-separated in the query).
+
+<docs-lit-demo for="docs-joke-blacklist-switch-demo"></docs-lit-demo>

package/src/core/components/ui/loader/loader.md

@@ -29,19 +29,7 @@
 
 ## Fixed mode
 
-<sonic-code >
-  <template>
-    <div dataProvider="toggleLoaderForm" formDataProvider="toggleLoaderForm">
-      <sonic-checkbox label="Show fixed loader" 
-          name="toggleLoader"
-          unique  value="true">
-      </sonic-checkbox>
-      <sonic-if  data-bind ::condition="$toggleLoader" >
-        <sonic-loader></sonic-loader>
-      </sonic-if>
-    </div>
-  </template>
-</sonic-code>
+<docs-lit-demo for="docs-toggle-loader-demo"></docs-lit-demo>
 
 
 ## Loading button

package/src/core/components/ui/table/table.md

@@ -42,7 +42,7 @@
         </sonic-tr> 
       </sonic-thead>
       <sonic-tbody>
-        <sonic-list debug fetch serviceURL="https://reqres.in" dataProvider="api/users" key="data" displayContents>
+        <sonic-list debug fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
           <template>
             <sonic-tr>
               <sonic-td data-bind ::inner-html="$id"></sonic-td>
@@ -135,7 +135,7 @@
         </sonic-tr> 
       </sonic-thead>
       <sonic-tbody>
-        <sonic-list  fetch serviceURL="https://reqres.in" dataProvider="api/users" key="data" displayContents>
+        <sonic-list  fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
           <template>
             <sonic-tr>
               <sonic-td data-bind ::inner-html="$id"></sonic-td>
@@ -256,7 +256,7 @@ Every table is responsive by default
         </sonic-tr> 
       </sonic-thead>
       <sonic-tbody>
-        <sonic-list fetch serviceURL="https://reqres.in" dataProvider="api/users" key="data" displayContents>
+        <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="api/users" key="data" displayContents>
           <template>
             <sonic-tr>
               <sonic-td data-bind ::inner-html="$id"></sonic-td>

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

@@ -22,6 +22,13 @@ async function flushGetMicrotasks() {
   await Promise.resolve();
 }
 
+/** @get scoped : scheduleAfterHostReady diffère le fetch (rAF ou updateComplete Lit). */
+async function flushScopedGet() {
+  await flushGetMicrotasks();
+  await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+  await flushGetMicrotasks();
+}
+
 function mockPayload<T>(result: T) {
   return {
     request: new Request("https://api.example.test/items/1"),
@@ -113,7 +120,7 @@ describe("get", () => {
     wrap.appendChild(el);
     document.body.appendChild(wrap);
 
-    await flushGetMicrotasks();
+    await flushScopedGet();
 
     expect(API.prototype.getDetailed).toHaveBeenCalledWith("scoped-endpoint");
     expect(el.payload?.result).toEqual({ id: "loaded" });

package/src/core/decorators/api.ts

@@ -47,11 +47,108 @@ function resolveScopedConfiguration(
   return HTML.getApiConfiguration(host);
 }
 
+function isScopedConfigurationReady(
+  config: APIConfiguration | null,
+): config is APIConfiguration {
+  return typeof config?.serviceURL === "string" && config.serviceURL.length > 0;
+}
+
+/** Attributs scope dont la présence peut déclencher un GET différé (Lit → minuscules). */
+const SCOPE_WATCH_ATTRIBUTES = [
+  "serviceURL",
+  "serviceurl",
+  "token",
+  "credentials",
+  "tokenProvider",
+  "tokenprovider",
+  "userName",
+  "username",
+  "password",
+  "eventsApiToken",
+  "eventsapitoken",
+] as const;
+
+type LitHost = HTMLElement & { updateComplete?: Promise<unknown> };
+
+function isLitHost(component: unknown): component is LitHost {
+  return (
+    component instanceof HTMLElement &&
+    typeof (component as LitHost).updateComplete !== "undefined"
+  );
+}
+
+function scheduleAfterHostReady(
+  component: unknown,
+  callback: () => void,
+): () => void {
+  if (isLitHost(component)) {
+    let cancelled = false;
+    void component.updateComplete!.then(() => {
+      if (!cancelled) callback();
+    });
+    return () => {
+      cancelled = true;
+    };
+  }
+  const rafId = requestAnimationFrame(() => callback());
+  return () => cancelAnimationFrame(rafId);
+}
+
+/**
+ * Attend que la config scope soit lisible (attributs DOM ou propriétés Lit reflect).
+ */
+function watchScopedConfiguration(
+  component: unknown,
+  onReady: () => void,
+): () => void {
+  const host = asSearchableHost(component);
+  if (!host) return () => {};
+
+  let settled = false;
+  const tryNotify = () => {
+    if (settled) return;
+    if (!isScopedConfigurationReady(resolveScopedConfiguration(component))) {
+      return;
+    }
+    settled = true;
+    onReady();
+  };
+
+  tryNotify();
+  if (settled) return () => {};
+
+  const cleanups: Array<() => void> = [];
+
+  const rafId = requestAnimationFrame(() => tryNotify());
+  cleanups.push(() => cancelAnimationFrame(rafId));
+
+  queueMicrotask(() => tryNotify());
+
+  const observer = new MutationObserver(() => tryNotify());
+  let node: SearchableDomElement | null = host;
+  while (node) {
+    if (node instanceof Element) {
+      observer.observe(node, {
+        attributes: true,
+        attributeFilter: [...SCOPE_WATCH_ATTRIBUTES],
+      });
+    }
+    node = (node.parentNode || (node as ShadowRoot).host) as SearchableDomElement;
+  }
+  cleanups.push(() => observer.disconnect());
+
+  return () => {
+    settled = true;
+    cleanups.forEach((cleanup) => cleanup());
+  };
+}
+
 type ApiGetState = {
   cleanupWatchers: Array<() => void>;
   requestGeneration: number;
   configPublisher: DataProvider | null;
   configMutationHandler: (() => void) | null;
+  scopeWatchCleanup: (() => void) | null;
 };
 
 function detachConfigPublisher(state: ApiGetState): void {
@@ -68,7 +165,8 @@ function detachConfigPublisher(state: ApiGetState): void {
  * Le path est un `Endpoint<T, Ue>` ; les placeholders `${nomPropriété}` sont résolus sur l'instance (`Ue` contraint l’hôte).
  *
  * **Scoped (défaut)** : `HTML.getApiConfiguration(host)` avec `host` = l’élément connecté
- * (`HTMLElement` / `ShadowRoot`). Sans hôte DOM valide, la propriété reste inchangée jusqu’à connexion.
+ * (`HTMLElement` / `ShadowRoot`). Si `serviceURL` n’est pas encore disponible (reflect Lit, scope
+ * ancêtre), le GET est différé jusqu’à ce que la config soit prête.
  *
  * **Deuxième paramètre** : `DataProviderKey<APIConfiguration>` — la config est lue via
  * `PublisherManager` sur le chemin résolu (même syntaxe dynamique que `@subscribe`).
@@ -138,6 +236,7 @@ export function get<T, Ue = any, Uk = any>(
           requestGeneration: 0,
           configPublisher: null,
           configMutationHandler: null,
+          scopeWatchCleanup: null,
         };
         comp[stateKey] = state;
       }
@@ -166,8 +265,15 @@ export function get<T, Ue = any, Uk = any>(
         } else {
           config = resolveScopedConfiguration(component);
         }
-        if (!config) {
-          comp[propertyKey] = undefined;
+        if (!isScopedConfigurationReady(config)) {
+          if (!usesPublisherConfig && !state.scopeWatchCleanup) {
+            const scopeWatch = watchScopedConfiguration(component, runFetch);
+            state.scopeWatchCleanup = scopeWatch;
+            state.cleanupWatchers.push(() => {
+              scopeWatch();
+              state.scopeWatchCleanup = null;
+            });
+          }
           return;
         }
         const generation = ++state.requestGeneration;
@@ -214,19 +320,24 @@ export function get<T, Ue = any, Uk = any>(
         }
         rebindPublisherConfig();
       } else {
-        if (isDynamicPath) {
-          for (const dependency of endpointDynamicDependencies) {
-            const unsubscribe = observeDynamicProperty(
-              getDynamicWatchKeys.watcherStore,
-              getDynamicWatchKeys.hooked,
-              component,
-              dependency,
-              () => runFetch(),
-            );
-            state.cleanupWatchers.push(unsubscribe);
+        const startScopedFetch = () => {
+          if (isDynamicPath) {
+            for (const dependency of endpointDynamicDependencies) {
+              const unsubscribe = observeDynamicProperty(
+                getDynamicWatchKeys.watcherStore,
+                getDynamicWatchKeys.hooked,
+                component,
+                dependency,
+                () => runFetch(),
+              );
+              state.cleanupWatchers.push(unsubscribe);
+            }
           }
-        }
-        runFetch();
+          runFetch();
+        };
+        state.cleanupWatchers.push(
+          scheduleAfterHostReady(component, startScopedFetch),
+        );
       }
     });
 

package/src/core/directives/DataProvider.sub.spec.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { DataProviderKey } from "../utils/dataProviderKey";
+import { dp, set } from "../utils/PublisherProxy";
+import { sub } from "./DataProvider";
+
+type User = { name: string };
+
+const dynamicUserKey = new DataProviderKey<User, { userIndex: number }>(
+  "subSpec.users.${userIndex}",
+);
+
+const staticCountKey = new DataProviderKey<{ count: number }>(
+  "subSpec.counter",
+).count;
+
+@customElement("sub-spec-host")
+class SubSpecHost extends LitElement {
+  @property({ type: Number }) userIndex = 0;
+
+  render() {
+    return html`
+      <span id="dynamic">${sub(dynamicUserKey.name)}</span>
+      <span id="static">${sub(staticCountKey)}</span>
+      <span id="string">${sub("subSpec.label")}</span>
+    `;
+  }
+}
+
+describe("sub() with DataProviderKey", () => {
+  let host: SubSpecHost;
+
+  beforeEach(async () => {
+    set("subSpec.users.0", { name: "Alice" });
+    set("subSpec.users.1", { name: "Bob" });
+    set("subSpec.counter", { count: 0 });
+    dpSetCount(7);
+    set("subSpec.label", "hello");
+
+    host = document.createElement("sub-spec-host") as SubSpecHost;
+    document.body.appendChild(host);
+    await host.updateComplete;
+    await flushMicrotasks();
+  });
+
+  afterEach(() => {
+    document.body.replaceChildren();
+  });
+
+  it("suit une clé dynamique quand userIndex change", async () => {
+    expect(text(host, "#dynamic")).toBe("Alice");
+
+    host.userIndex = 1;
+    await host.updateComplete;
+    await flushFrames();
+
+    expect(text(host, "#dynamic")).toBe("Bob");
+  });
+
+  it("suit une sous-clé statique", async () => {
+    expect(text(host, "#static")).toBe("7");
+
+    dpSetCount(42);
+    await host.updateComplete;
+
+    expect(text(host, "#static")).toBe("42");
+  });
+
+  it("accepte encore un chemin string", async () => {
+    expect(text(host, "#string")).toBe("hello");
+    set("subSpec.label", "world");
+    await host.updateComplete;
+    expect(text(host, "#string")).toBe("world");
+  });
+});
+
+function dpSetCount(count: number) {
+  dp(staticCountKey).set(count);
+}
+
+function text(el: SubSpecHost, selector: string): string {
+  return el.shadowRoot?.querySelector(selector)?.textContent ?? "";
+}
+
+async function flushMicrotasks() {
+  await Promise.resolve();
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+async function flushFrames() {
+  await flushMicrotasks();
+  await new Promise((r) => requestAnimationFrame(r));
+  await new Promise((r) => requestAnimationFrame(r));
+}

package/src/core/directives/DataProvider.ts

@@ -2,21 +2,32 @@ import { AsyncDirective, PartInfo } from "lit/async-directive.js";
 import { directive } from "lit/directive.js";
 import { noChange } from "lit";
 import { SearchableDomElement } from "../utils/HTML";
-import { 
+import {
+  extractDynamicDependencies,
+  hasPath,
+  resolveDynamicPath,
+} from "../decorators/subscriber/dynamicPath";
+import {
+  bindDynamicWatchKeys,
+  observeDynamicProperty,
+} from "../decorators/subscriber/dynamicPropertyWatch";
+import {
   getObservables,
-  get as pubGet, set as pubSet, dataProvider as pubDataProvider ,
-  dp as pubDp, DataProvider
+  get as pubGet,
+  set as pubSet,
+  dataProvider as pubDataProvider,
+  dp as pubDp,
+  DataProvider,
 } from "../utils/PublisherProxy";
 
+export type SubPathInput = string | {path: string};
 
 class ObserveDirective extends AsyncDirective {
   observables: Set<DataProvider<any>> = new Set();
-  unsubscribe(): void {
-    this.observables.forEach((publisher: DataProvider<any>) =>
-      publisher.offAssign(this.onAssign)
-    );
-  }
-  observable?: string;
+  pathTemplate?: string;
+  /** Chemin résolu actuellement abonné */
+  resolvedPath?: string;
+  cleanupWatchers: Array<() => void> = [];
   node?: SearchableDomElement;
 
   /* eslint-disable @typescript-eslint/no-explicit-any*/
@@ -26,21 +37,87 @@ class ObserveDirective extends AsyncDirective {
   }
   /* eslint-enable @typescript-eslint/no-explicit-any*/
 
-  render(observable: string) {
-    if (this.observable !== observable) {
-      this.observable = observable;
-      if (this.isConnected) {
-        this.subscribe(observable);
-      }
+  private teardownWatchers() {
+    this.cleanupWatchers.forEach((cleanup) => cleanup());
+    this.cleanupWatchers = [];
+  }
+
+  private normalizeInput(input: SubPathInput): string {
+    return hasPath(input) ? input.path : input;
+  }
+
+  render(input: SubPathInput) {
+    const path = this.normalizeInput(input);
+    const pathChanged = this.pathTemplate !== path;
+    if (pathChanged) {
+      this.pathTemplate = path;
+      this.teardownWatchers();
+    }
+    if (pathChanged || !this.resolvedPath) {
+      queueMicrotask(() => {
+        if (!this.isConnected || !this.pathTemplate) return;
+        this.setupSubscription();
+      });
     }
     return noChange;
   }
 
+  private setupSubscription() {
+    const host = this.node;
+    const path = this.pathTemplate;
+    if (!host || !path) return;
+
+    this.teardownWatchers();
+    const dependencies = extractDynamicDependencies(path);
+    if (dependencies.length > 0) {
+      for (const dependency of dependencies) {
+        this.cleanupWatchers.push(
+          observeDynamicProperty(
+            bindDynamicWatchKeys.watcherStore,
+            bindDynamicWatchKeys.hooked,
+            host,
+            dependency,
+            () => this.refreshSubscription(),
+          ),
+        );
+      }
+    }
+    this.refreshSubscription();
+  }
+
+  private refreshSubscription() {
+    const host = this.node;
+    const path = this.pathTemplate;
+    if (!path) return;
+
+    const isDynamic = extractDynamicDependencies(path).length > 0;
+    let resolved: string | null = path;
+    if (isDynamic) {
+      if (!host) {
+        resolved = null;
+      } else {
+        const resolution = resolveDynamicPath(host, path);
+        resolved = resolution.ready ? resolution.path : null;
+      }
+    }
+
+    if (resolved === this.resolvedPath) return;
+
+    if (!resolved) {
+      this.unsubscribe();
+      this.resolvedPath = undefined;
+      this.setValue(undefined);
+      return;
+    }
+
+    this.resolvedPath = resolved;
+    this.subscribe(resolved);
+  }
+
   onAssign = (v: unknown) => {
     this.setValue(v);
   };
-  // Subscribes to the observable, calling the directive's asynchronous
-  // setValue API each time the value changes
+
   subscribe<T>(observable: string) {
     this.unsubscribe();
     this.onAssign = (v: unknown) => {
@@ -52,55 +129,47 @@ class ObserveDirective extends AsyncDirective {
       publisher.onAssign(this.onAssign);
     });
   }
-  // When the directive is disconnected from the DOM, unsubscribe to ensure
-  // the directive instance can be garbage collected
+
+  unsubscribe(): void {
+    this.observables.forEach((publisher: DataProvider<any>) =>
+      publisher.offAssign(this.onAssign),
+    );
+    this.observables.clear();
+  }
+
   disconnected() {
+    this.teardownWatchers();
     this.unsubscribe();
+    this.resolvedPath = undefined;
   }
-  // If the subtree the directive is in was disconnected and subsequently
-  // re-connected, re-subscribe to make the directive operable again
+
   reconnected() {
-    if (!this.observable) return;
-    this.subscribe(this.observable);
+    if (!this.pathTemplate) return;
+    this.setupSubscription();
   }
 }
+
 const dir = directive(ObserveDirective);
-//
-//autoUpdate directive
+
 export const subscribe = dir;
 export const sub = dir;
 
-
 /**
  * @deprecated @see {@link "/src/core/utils/PublisherProxy.ts#get"}
- * @param id Observable
- * @returns value of the observable
- * 
  */
 export const get: <T = any>(id: string) => T = pubGet;
 
-
-
 /**
  * @deprecated @see {@link "/src/core/utils/PublisherProxy.ts#dataProvider"}
- * @param id Observable
- * @param defaultValue Optional default value
- * @returns Observable
  */
 export const dataProvider = pubDataProvider;
 
 /**
  * @deprecated @see {@link "/src/core/utils/PublisherProxy.ts#dp"}
- * @param id Observable
- * @param defaultValue Optional default value
- * @returns Observable
  */
 export const dp = pubDp;
 
 /**
  * @deprecated @see {@link "/src/core/utils/PublisherProxy.ts#set"}
- * @param id Observable
- * @param value value to set
- * @returns void
  */
 export const set: <T = any>(id: string, value: T) => void = pubSet;