@supersoniks/concorde 4.5.2 → 4.7.0

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/Subscriber.ts

@@ -2,6 +2,8 @@ export { bind } from "./subscriber/bind";
 export { publish } from "./subscriber/publish";
 export { subscribe } from "./subscriber/subscribe";
 export { onAssign } from "./subscriber/onAssign";
+export { handle, Skip } from "./subscriber/handle";
+export type { HandleOptions } from "./subscriber/handle";
 export { autoSubscribe } from "./subscriber/autoSubscribe";
 export { autoFill } from "./subscriber/autoFill";
 export { ancestorAttribute } from "./subscriber/ancestorAttribute";

package/src/core/decorators/subscriber/handle.disambig.spec.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { DataProviderKey } from "../../utils/dataProviderKey";
+
+function isDataProviderKey(value: unknown): boolean {
+  return Object.prototype.toString.call(value) === "[object DataProviderKey]";
+}
+
+describe("handle: désambiguïsation clé vs options", () => {
+  it("reconnaît une DataProviderKey (y compris après navigation)", () => {
+    const key = new DataProviderKey<{ total: number }>("cart");
+    expect(isDataProviderKey(key)).toBe(true);
+    expect(isDataProviderKey(key.total)).toBe(true);
+  });
+
+  it("ne confond pas un objet d'options avec une clé", () => {
+    expect(isDataProviderKey({ skip: ["emptyObject"] })).toBe(false);
+    expect(isDataProviderKey({ waitForAllDefined: true })).toBe(false);
+    expect(isDataProviderKey(undefined)).toBe(false);
+  });
+});

package/src/core/decorators/subscriber/handle.skip.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { Skip, isSkipped } from "./onAssign";
+
+describe("isSkipped (catégories Skip de @handle)", () => {
+  it("Nullish : null et undefined uniquement", () => {
+    expect(isSkipped(null, [Skip.Nullish])).toBe(true);
+    expect(isSkipped(undefined, [Skip.Nullish])).toBe(true);
+    expect(isSkipped(0, [Skip.Nullish])).toBe(false);
+    expect(isSkipped("", [Skip.Nullish])).toBe(false);
+  });
+
+  it("EmptyString : pas de coercition", () => {
+    expect(isSkipped("", [Skip.EmptyString])).toBe(true);
+    expect(isSkipped("a", [Skip.EmptyString])).toBe(false);
+    expect(isSkipped(0, [Skip.EmptyString])).toBe(false);
+  });
+
+  it("EmptyObject : objet sans clé, tableau exclu", () => {
+    expect(isSkipped({}, [Skip.EmptyObject])).toBe(true);
+    expect(isSkipped({ a: 1 }, [Skip.EmptyObject])).toBe(false);
+    expect(isSkipped([], [Skip.EmptyObject])).toBe(false);
+    expect(isSkipped(null, [Skip.EmptyObject])).toBe(false);
+  });
+
+  it("EmptyArray : tableau vide, objet exclu", () => {
+    expect(isSkipped([], [Skip.EmptyArray])).toBe(true);
+    expect(isSkipped([1], [Skip.EmptyArray])).toBe(false);
+    expect(isSkipped({}, [Skip.EmptyArray])).toBe(false);
+  });
+
+  it("combinaison de catégories", () => {
+    const kinds = [Skip.Nullish, Skip.EmptyObject];
+    expect(isSkipped(null, kinds)).toBe(true);
+    expect(isSkipped({}, kinds)).toBe(true);
+    expect(isSkipped({ a: 1 }, kinds)).toBe(false);
+  });
+});

package/src/core/decorators/subscriber/handle.ts

@@ -0,0 +1,128 @@
+import type {
+  DataProviderKey,
+  DataProviderKeyHost,
+} from "../../utils/dataProviderKey";
+import { createOnAssign, Skip } from "./onAssign";
+
+export { Skip } from "./onAssign";
+
+/**
+ * Options de `@handle`, nommées d'après les cas d'usage réels rencontrés dans
+ * les projets (panier, file d'attente, formulaires multi-publishers, etc.).
+ *
+ * Par défaut (aucune option), `@handle` appelle la méthode **à chaque
+ * assignation**, même quand la valeur reçue est `null`/`undefined` (c'est la
+ * différence de comportement voulue par rapport à `@onAssign`).
+ */
+export type HandleOptions = {
+  /**
+   * Attendre que **toutes** les clés surveillées soient définies (non
+   * `null`/`undefined`) avant d'appeler la méthode. Reproduit la sémantique
+   * historique de `@onAssign`.
+   *
+   * À utiliser quand la logique combine plusieurs sources et n'a de sens que
+   * lorsque toutes sont prêtes (ex. calcul de date à partir de
+   * `date` + `timeZone` + `direction`).
+   */
+  waitForAllDefined?: boolean;
+  /**
+   * Ne pas appeler la méthode si la valeur reçue appartient à l'une de ces
+   * catégories. Chaque entrée est une catégorie nommée (pas une valeur), donc
+   * aucune ambiguïté valeur/motif.
+   *
+   * - `Skip.Nullish` ignore `null`/`undefined` ;
+   * - `Skip.EmptyObject` / `Skip.EmptyArray` ignorent `{}` / `[]` ;
+   * - `Skip.EmptyString` ignore `""`.
+   *
+   * Pratique quand un publisher non initialisé émet `{}` comme état « pas encore
+   * chargé » : `skip: [Skip.EmptyObject]`. Pour une validation arbitraire sur une
+   * valeur précise, faire le test directement dans la méthode.
+   */
+  skip?: Skip[];
+};
+
+type HandleDecorator<Host, Fn> = (
+  target: Host,
+  propertyKey: string,
+  descriptor: TypedPropertyDescriptor<Fn>,
+) => void;
+
+/**
+ * Détecte une `DataProviderKey` (Proxy marqué `Symbol.toStringTag`) afin de la
+ * distinguer d'un objet d'options passé en dernier argument.
+ */
+function isDataProviderKey(value: unknown): value is DataProviderKey<unknown> {
+  return Object.prototype.toString.call(value) === "[object DataProviderKey]";
+}
+
+/**
+ * Callback typé déclenché lorsqu'un (ou plusieurs) chemin(s) publisher sont
+ * assignés via `DataProviderKey<T>`. Invoque la méthode décorée avec la/les
+ * valeur(s) assignée(s) (calculs, effets de bord, mise à jour d'autres `@state`…).
+ *
+ * Supporte les chemins dynamiques : placeholders type `"users.${userIndex}"`.
+ *
+ * Contrairement à `@onAssign`, la méthode est appelée à chaque assignation,
+ * même quand la valeur reçue est `null`/`undefined` — sauf si une option
+ * (`waitForAllDefined`, `skip`) restreint le déclenchement.
+ *
+ * @example
+ * // Mono-clé
+ * const cart = new DataProviderKey<Cart>("cart");
+ * @handle(cart.total)
+ * updateSummary(total: number) {
+ *   this.summary = total * this.taxRate;
+ * }
+ *
+ * @example
+ * // Multi-clés (coordination de plusieurs publishers)
+ * @handle(config.show, idle.isIdle, { waitForAllDefined: true })
+ * onModal(show: boolean, isIdle: boolean) {
+ *   if (show && isIdle) this.open(); else this.close();
+ * }
+ *
+ * @example
+ * // Ignorer un objet vide émis par un publisher non initialisé
+ * @handle(user.profile, { skip: [Skip.EmptyObject] })
+ * onProfile(profile: Profile) { this.name = profile.name; }
+ */
+export function handle<A, U = any>(
+  key: DataProviderKey<A, U>,
+  options?: HandleOptions,
+): HandleDecorator<DataProviderKeyHost<U>, (a: A) => void>;
+export function handle<A, B, UA = any, UB = any>(
+  keyA: DataProviderKey<A, UA>,
+  keyB: DataProviderKey<B, UB>,
+  options?: HandleOptions,
+): HandleDecorator<
+  DataProviderKeyHost<UA> & DataProviderKeyHost<UB>,
+  (a: A, b: B) => void
+>;
+export function handle<A, B, C, UA = any, UB = any, UC = any>(
+  keyA: DataProviderKey<A, UA>,
+  keyB: DataProviderKey<B, UB>,
+  keyC: DataProviderKey<C, UC>,
+  options?: HandleOptions,
+): HandleDecorator<
+  DataProviderKeyHost<UA> & DataProviderKeyHost<UB> & DataProviderKeyHost<UC>,
+  (a: A, b: B, c: C) => void
+>;
+export function handle(
+  ...args: Array<DataProviderKey<unknown> | HandleOptions | undefined>
+) {
+  const last = args[args.length - 1];
+  const hasOptions = last !== undefined && !isDataProviderKey(last);
+  const options = (hasOptions ? last : {}) as HandleOptions;
+  const keys = (hasOptions ? args.slice(0, -1) : args) as Array<
+    DataProviderKey<unknown>
+  >;
+  const paths = keys.map((key) => key.path);
+
+  return createOnAssign(
+    {
+      dispatchWhenUndefined: !options.waitForAllDefined,
+      skip: options.skip,
+    },
+    paths,
+  );
+}

package/src/core/decorators/subscriber/onAssign.ts

@@ -23,7 +23,100 @@ type Configuration = {
   index: number;
 };
 
+/**
+ * Catégories de valeurs « ignorables » par le garde `skip`. Chaque catégorie est
+ * un prédicat nommé (et non une égalité de valeur), ce qui lève toute ambiguïté
+ * entre « valeur » et « motif » (notamment pour l'objet vide).
+ */
+export enum Skip {
+  /**
+   * `null` ou `undefined`. En pratique un publisher renvoie toujours `null`
+   * (jamais `undefined`) car `get()` coerce `undefined → null`.
+   */
+  Nullish = "nullish",
+  /** Chaîne vide `""`. */
+  EmptyString = "emptyString",
+  /** Objet sans clé (`{}`), tableau exclu. */
+  EmptyObject = "emptyObject",
+  /** Tableau vide (`[]`). */
+  EmptyArray = "emptyArray",
+}
+
+const SKIP_PREDICATES: Record<Skip, (value: unknown) => boolean> = {
+  [Skip.Nullish]: (v) => v === null || v === undefined,
+  [Skip.EmptyString]: (v) => v === "",
+  [Skip.EmptyObject]: (v) =>
+    typeof v === "object" &&
+    v !== null &&
+    !Array.isArray(v) &&
+    Object.keys(v).length === 0,
+  [Skip.EmptyArray]: (v) => Array.isArray(v) && v.length === 0,
+};
+
+/**
+ * `true` si `value` appartient à au moins une des catégories `kinds`.
+ */
+export function isSkipped(value: unknown, kinds: Skip[]): boolean {
+  return kinds.some((kind) => SKIP_PREDICATES[kind](value));
+}
+
+export type OnAssignOptions = {
+  /**
+   * Quand `true`, le callback est invoqué à chaque assignation, même si la
+   * valeur reçue est `null`/`undefined`.
+   * Quand `false` (défaut), le callback n'est invoqué que lorsque toutes les
+   * valeurs surveillées sont définies (non `null` et non `undefined`).
+   */
+  dispatchWhenUndefined?: boolean;
+  /**
+   * Ne pas invoquer le callback si une valeur reçue appartient à l'une de ces
+   * catégories (ex. `[Skip.Nullish, Skip.EmptyObject]`).
+   */
+  skip?: Skip[];
+};
+
+function shouldDispatch(
+  currentValues: unknown[],
+  expectedCount: number,
+  options: OnAssignOptions,
+): boolean {
+  // Garde structurelle : toutes les valeurs doivent être définies.
+  if (!options.dispatchWhenUndefined) {
+    const definedCount = currentValues
+      .slice(0, expectedCount)
+      .filter((v) => v !== null && v !== undefined).length;
+    if (definedCount !== expectedCount) return false;
+  }
+  // Garde de contenu : catégories skip.
+  if (options.skip && options.skip.length > 0) {
+    for (let i = 0; i < expectedCount; i++) {
+      if (isSkipped(currentValues[i], options.skip)) return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * @deprecated Utiliser `@handle` à la place.
+ *
+ * `@onAssign` prend des chemins sous forme de **chaînes** non typées et n'appelle
+ * la méthode que lorsque **toutes** les valeurs sont définies. `@handle` offre la
+ * même chose en **typé** (via `DataProviderKey`), avec des options explicites :
+ *
+ * - équivalent direct : `@onAssign("a", "b")` → `@handle(keyA, keyB, { waitForAllDefined: true })`
+ * - comportement par défaut de `@handle` : appel à chaque assignation (même `null`/`undefined`)
+ * - `skip` pour ignorer des catégories de valeurs (ex. `[Skip.Nullish, Skip.EmptyObject]`)
+ *
+ * `@onAssign` reste fonctionnel et inchangé le temps de la migration.
+ */
 export function onAssign(...values: Array<string>) {
+  return createOnAssign({}, values);
+}
+
+export function createOnAssign(
+  options: OnAssignOptions,
+  values: Array<string>,
+) {
   const pathConfigs: PathConfiguration[] = values.map((path) => {
     const dynamicDependencies = extractDynamicDependencies(path);
     return {
@@ -69,10 +162,7 @@ export function onAssign(...values: Array<string>) {
         const callbacks: Set<Callback> = new Set();
         const onAssign = (assignedValue: unknown) => {
           onAssignValues[i] = assignedValue;
-          if (
-            onAssignValues.filter((v) => v !== null && v !== undefined)
-              .length === values.length
-          ) {
+          if (shouldDispatch(onAssignValues, values.length, options)) {
             callbacks.forEach((callback) => callback(...onAssignValues));
           }
         };

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));
+}