@supersoniks/concorde 3.2.8 → 3.3.2

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

@@ -0,0 +1,318 @@
+import { Objects } from "@supersoniks/concorde/utils";
+
+import { PublisherProxy, PublisherManager } from "../../utils/PublisherProxy";
+import { ConnectedComponent, setSubscribable } from "./common";
+
+const dynamicWatcherStore = Symbol("__onAssignDynamicWatcherStore__");
+const dynamicWillUpdateHookedStore = Symbol(
+  "__onAssignDynamicWillUpdateHooked__"
+);
+
+function registerDynamicWatcher(
+  instance: any,
+  propertyName: string,
+  onChange: () => void
+) {
+  const key = String(propertyName);
+  ensureWillUpdateHook(instance);
+  if (!instance[dynamicWatcherStore]) {
+    Object.defineProperty(instance, dynamicWatcherStore, {
+      value: new Map<string, Set<() => void>>(),
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+  const watcherMap = instance[dynamicWatcherStore] as Map<
+    string,
+    Set<() => void>
+  >;
+  if (!watcherMap.has(key)) {
+    watcherMap.set(key, new Set());
+  }
+  const watchers = watcherMap.get(key)!;
+  watchers.add(onChange);
+  return () => {
+    watchers.delete(onChange);
+    if (watchers.size === 0) {
+      watcherMap.delete(key);
+    }
+  };
+}
+
+function ensureWillUpdateHook(instance: any) {
+  const proto = Object.getPrototypeOf(instance);
+  if (!proto || proto[dynamicWillUpdateHookedStore]) return;
+  const originalWillUpdate = Object.prototype.hasOwnProperty.call(
+    proto,
+    "willUpdate"
+  )
+    ? proto.willUpdate
+    : Object.getPrototypeOf(proto)?.willUpdate;
+  proto.willUpdate = function (changedProperties?: Map<unknown, unknown>) {
+    const handlers = this[dynamicWatcherStore] as
+      | Map<string, Set<() => void>>
+      | undefined;
+    if (handlers && handlers.size > 0) {
+      if (changedProperties && changedProperties.size > 0) {
+        changedProperties.forEach((_value, dependency) => {
+          const callbacks = handlers.get(String(dependency));
+          if (callbacks) {
+            callbacks.forEach((cb) => cb());
+          }
+        });
+      } else {
+        handlers.forEach((callbacks) => callbacks.forEach((cb) => cb()));
+      }
+    }
+    originalWillUpdate?.call(this, changedProperties);
+  };
+  proto[dynamicWillUpdateHookedStore] = true;
+}
+
+function extractDynamicDependencies(path: string) {
+  const patterns = [/\$\{([^}]+)\}/g, /\{\$([^}]+)\}/g];
+  const deps = new Set<string>();
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(path)) !== null) {
+      const cleaned = cleanPlaceholder(match[1]);
+      if (!cleaned) continue;
+      const [root] = cleaned.split(".");
+      if (root) deps.add(root);
+    }
+  }
+  return Array.from(deps);
+}
+
+function cleanPlaceholder(value: string) {
+  return value.trim().replace(/^this\./, "");
+}
+
+function resolveDynamicPath(component: any, template: string) {
+  let missing = false;
+  const replaceValue = (_match: string, expression: string) => {
+    const cleaned = cleanPlaceholder(expression);
+    const resolved = getValueFromExpression(component, cleaned);
+    if (resolved === undefined || resolved === null) {
+      missing = true;
+      return "";
+    }
+    return `${resolved}`;
+  };
+  const resolvedPath = template
+    .replace(/\$\{([^}]+)\}/g, replaceValue)
+    .replace(/\{\$([^}]+)\}/g, replaceValue)
+    .trim();
+  if (missing || !resolvedPath.length) {
+    return { ready: false, path: null };
+  }
+  const segments = resolvedPath.split(".").filter(Boolean);
+  if (segments.length === 0 || !segments[0]) {
+    return { ready: false, path: null };
+  }
+  return { ready: true, path: resolvedPath };
+}
+
+function getValueFromExpression(component: any, expression: string) {
+  if (!expression) return undefined;
+  const segments = expression.split(".").filter(Boolean);
+  if (segments.length === 0) return undefined;
+  let current: unknown = component;
+  for (const segment of segments) {
+    if (
+      current === undefined ||
+      current === null ||
+      typeof current !== "object"
+    ) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function getPublisherFromPath(path: string) {
+  const segments = path.split(".").filter((segment) => segment.length > 0);
+  if (segments.length === 0) return null;
+  const dataProvider = segments.shift() || "";
+  if (!dataProvider) return null;
+  let publisher = PublisherManager.get(dataProvider);
+  if (!publisher) return null;
+  publisher = Objects.traverse(publisher, segments);
+  return publisher as PublisherProxy | null;
+}
+
+type Callback = (...values: unknown[]) => void;
+type PathConfiguration = {
+  originalPath: string;
+  dynamicDependencies: string[];
+  isDynamic: boolean;
+};
+
+type Configuration = {
+  callbacks: Set<Callback>;
+  publisher: PublisherProxy | null;
+  onAssign: (value: unknown) => void;
+  unsubscribePublisher: (() => void) | null;
+  pathConfig: PathConfiguration;
+  index: number;
+};
+
+export function onAssign(...values: Array<string>) {
+  const pathConfigs: PathConfiguration[] = values.map((path) => {
+    const dynamicDependencies = extractDynamicDependencies(path);
+    return {
+      originalPath: path,
+      dynamicDependencies,
+      isDynamic: dynamicDependencies.length > 0,
+    };
+  });
+
+  return function (
+    target: unknown,
+    _propertyKey: string,
+    descriptor: PropertyDescriptor
+  ) {
+    setSubscribable(target);
+    const stateKey = `__onAssign_state__`;
+    let callback: Callback;
+
+    (target as ConnectedComponent).__onConnected__((component) => {
+      const state =
+        (component as any)[stateKey] ||
+        ((component as any)[stateKey] = {
+          cleanupWatchers: [] as Array<() => void>,
+          configurations: [] as Configuration[],
+        });
+
+      // Nettoyage des watchers et configurations précédentes
+      state.cleanupWatchers.forEach((cleanup: () => void) => cleanup());
+      state.cleanupWatchers = [];
+      state.configurations.forEach((conf: Configuration) => {
+        if (conf.unsubscribePublisher) {
+          conf.unsubscribePublisher();
+        }
+      });
+      state.configurations = [];
+
+      const onAssignValues: unknown[] = [];
+      const confs: Configuration[] = [];
+
+      // Initialisation des configurations
+      for (let i = 0; i < values.length; i++) {
+        const pathConfig = pathConfigs[i];
+        const callbacks: Set<Callback> = new Set();
+        const onAssign = (assignedValue: unknown) => {
+          onAssignValues[i] = assignedValue;
+          if (
+            onAssignValues.filter((v) => v !== null && v !== undefined)
+              .length === values.length
+          ) {
+            callbacks.forEach((callback) => callback(...onAssignValues));
+          }
+        };
+        confs.push({
+          publisher: null,
+          onAssign,
+          callbacks,
+          unsubscribePublisher: null,
+          pathConfig,
+          index: i,
+        });
+      }
+
+      const subscribeToPath = (
+        conf: Configuration,
+        resolvedPath: string | null
+      ) => {
+        // Désabonnement de l'ancien publisher
+        if (conf.unsubscribePublisher) {
+          conf.unsubscribePublisher();
+          conf.unsubscribePublisher = null;
+        }
+
+        // Réinitialiser la valeur pour ce chemin lors du changement
+        onAssignValues[conf.index] = null;
+        conf.publisher = null;
+
+        if (!resolvedPath) {
+          return;
+        }
+
+        const publisher = getPublisherFromPath(resolvedPath);
+        if (!publisher) {
+          return;
+        }
+
+        publisher.onAssign(conf.onAssign);
+        conf.unsubscribePublisher = () => {
+          publisher.offAssign(conf.onAssign);
+          if (conf.publisher === publisher) {
+            conf.publisher = null;
+          }
+        };
+        conf.publisher = publisher;
+      };
+
+      const refreshSubscriptions = () => {
+        for (const conf of confs) {
+          if (conf.pathConfig.isDynamic) {
+            const resolution = resolveDynamicPath(
+              component,
+              conf.pathConfig.originalPath
+            );
+            if (!resolution.ready) {
+              subscribeToPath(conf, null);
+              continue;
+            }
+            subscribeToPath(conf, resolution.path);
+          } else {
+            subscribeToPath(conf, conf.pathConfig.originalPath);
+          }
+        }
+      };
+
+      // Enregistrement des watchers pour les chemins dynamiques
+      for (const conf of confs) {
+        if (conf.pathConfig.isDynamic) {
+          for (const dependency of conf.pathConfig.dynamicDependencies) {
+            const unsubscribe = registerDynamicWatcher(
+              component as Record<string, unknown>,
+              dependency,
+              () => refreshSubscriptions()
+            );
+            state.cleanupWatchers.push(unsubscribe);
+          }
+        }
+      }
+
+      // Initialisation du callback
+      callback = descriptor.value.bind(component);
+      for (const conf of confs) {
+        conf.callbacks.add(callback);
+      }
+
+      // Initialisation des abonnements
+      refreshSubscriptions();
+
+      state.configurations = confs;
+    });
+
+    (target as ConnectedComponent).__onDisconnected__((component) => {
+      const state = (component as any)[stateKey];
+      if (!state) return;
+
+      state.cleanupWatchers.forEach((cleanup: () => void) => cleanup());
+      state.cleanupWatchers = [];
+
+      state.configurations.forEach((conf: Configuration) => {
+        if (conf.unsubscribePublisher) {
+          conf.unsubscribePublisher();
+        }
+        conf.callbacks.delete(callback);
+      });
+      state.configurations = [];
+    });
+  };
+}

package/src/core/utils/PublisherProxy.ts

@@ -455,9 +455,9 @@ export class PublisherProxy<T = any> {
    */
   _cachedGet_?: T;
   get(): T {
-    if (this._cachedGet_ !== undefined) return this._cachedGet_;
     if (PublisherManager.modifiedCollectore.length > 0)
       PublisherManager.modifiedCollectore[0].add(this);
+    if (this._cachedGet_ !== undefined) return this._cachedGet_;
     if (Object.prototype.hasOwnProperty.call(this._value_, "__value")) {
       const v = (this._value_ as any).__value;
       return (this._cachedGet_ = (v != undefined ? v : null) as T);

package/src/decorators.ts

@@ -1,12 +1,19 @@
 import * as mySubscriber from "@supersoniks/concorde/core/decorators/Subscriber";
 export const bind = mySubscriber.bind;
 export const onAssign = mySubscriber.onAssign;
+export const ancestorAttribute = mySubscriber.ancestorAttribute;
+export const autoSubscribe = mySubscriber.autoSubscribe;
+export const autoFill = mySubscriber.autoFill;
 
-import {ConcordeWindow} from "./core/_types/types";
+import { ConcordeWindow } from "./core/_types/types";
 declare const window: ConcordeWindow;
 
-window["concorde-decorator-subscriber"] = window["concorde-decorator-subscriber"] || {};
+window["concorde-decorator-subscriber"] =
+  window["concorde-decorator-subscriber"] || {};
 window["concorde-decorator-subscriber"] = {
   bind: mySubscriber.bind,
   onAssing: mySubscriber.onAssign,
+  ancestorAttribute: mySubscriber.ancestorAttribute,
+  autoSubscribe: mySubscriber.autoSubscribe,
+  autoFill: mySubscriber.autoFill,
 };

package/src/docs/_misc/ancestor-attribute.md

@@ -0,0 +1,94 @@
+# @ancestorAttribute
+
+The `@ancestorAttribute` decorator automatically injects the value of an ancestor's attribute into a class property at the time of `connectedCallback`.
+
+## Principle
+
+This decorator uses `HTML.getAncestorAttributeValue` to traverse up the DOM tree from the current element and find the first ancestor that has the specified attribute. The value of this attribute is then assigned to the decorated property.
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { ancestorAttribute } from "@supersoniks/concorde/decorators";
+  </template>
+</sonic-code>
+
+### Basic example
+Le composant lit les attributs `dataProvider` et `testAttribute` exposés par son conteneur ancêtre.
+
+<sonic-code language="typescript">
+  <template>
+//...
+@customElement("demo-bind-reflect")
+export class DemoBindReflect extends LitElement {
+  static styles = [tailwind];
+//
+  @bind("bindReflectDemo.count", { reflect: true })
+  @state()
+  withReflect: number = 0;
+//
+  @bind("bindReflectDemo.count")
+  @state()
+  withoutReflect: number = 0;
+  // initialize the publisher data
+  connectedCallback() {
+    super.connectedCallback();
+    this.resetData();
+  }
+//
+  resetData() {
+    PublisherManager.get("bindReflectDemo").set({ count: 0 });
+  }
+  render() {
+    return html`
+      <div class="mb-3">
+        from publisher : ${sub("bindReflectDemo.count")} <br />
+        from component with reflect : ${this.withReflect} <br />
+        from component without reflect : ${this.withoutReflect}
+      </div>
+      <sonic-button @click=${() => this.withReflect++}
+        >Increment with reflect</sonic-button
+      >
+      <sonic-button @click=${() => this.withoutReflect++}
+        >Increment without reflect</sonic-button
+      >
+      <sonic-button @click=${this.resetData}>Reset publisher data</sonic-button>
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+<div dataProvider="demoDataProvider" testAttribute="test-value-123">
+  <demo-ancestor-attribute></demo-ancestor-attribute>
+</div>
+  </template>
+</sonic-code>
+
+
+## Use cases
+
+This decorator is particularly useful for:
+
+- **Retrieving the `dataProvider`** from an ancestor without having to pass it explicitly
+- **Retrieving the `formDataProvider`** in form components
+- **Retrieving the `wordingProvider`** for translation
+- **Retrieving any other attribute** defined on an ancestor
+
+## Behavior
+
+- The search starts from the current element and traverses up the DOM tree
+- If the attribute is not found, the property will be assigned `null`
+- The injection happens automatically at the time of `connectedCallback`
+- The value is not reactive: it is only updated once when the element is connected to the DOM
+
+## Notes
+
+- This decorator works with any component that has a `connectedCallback` method (such as `LitElement` or components extending `Subscriber`)
+- The search also traverses Shadow DOM if necessary
+- If multiple ancestors have the attribute, the closest one will be used

package/src/docs/_misc/auto-subscribe.md

@@ -0,0 +1,199 @@
+# @autoSubscribe
+
+The `@autoSubscribe` decorator automatically detects which publishers are accessed within a method and subscribes to them. When any of these publishers change, the method is automatically re-executed.
+
+## Principle
+
+This decorator wraps a method to track which publishers are accessed during its execution. It then subscribes to all accessed publishers, and when any of them change, the method is re-executed. This provides automatic reactivity without manually managing subscriptions.
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { autoSubscribe } from "@supersoniks/concorde/decorators";
+  </template>
+</sonic-code>
+
+### Basic example
+
+
+<sonic-code language="typescript">
+<template>
+@customElement("demo-auto-subscribe")
+export class DemoAutoSubscribe extends LitElement {
+  static styles = [tailwind];
+  //
+  @state() displayText: string = "";
+  @state() computedValue: number = 0;
+  //
+  @autoSubscribe()
+  updateDisplay() {
+    const value1 = PublisherManager.get("autoValue1").get() || 0;
+    const value2 = PublisherManager.get("autoValue2").get() || 0;
+    this.computedValue = value1 + value2;
+    this.displayText = `${value1} + ${value2} = ${this.computedValue}`;
+  }
+  //
+  render() {
+    return html`
+      <p><strong>${this.displayText}</strong></p>
+      <div>
+        <sonic-button @click=${() => this.randomizeValue("autoValue1")}>
+          Randomize Value 1
+        </sonic-button>
+        <sonic-button @click=${() => this.randomizeValue("autoValue2")}>
+          Randomize Value 2
+        </sonic-button>
+      </div>
+    `;
+  }
+  //
+  randomizeValue(publisherId: string) {
+    const value = PublisherManager.get(publisherId);
+    value.set(Math.floor(Math.random() * 100));
+  }
+}
+</template>
+</sonic-code>
+
+
+<sonic-code >
+  <template>
+    <demo-auto-subscribe></demo-auto-subscribe>
+  </template>
+</sonic-code>
+
+### Example with render method
+
+<sonic-code language="typescript">
+  <template>
+@customElement("reactive-view")
+export class ReactiveView extends LitElement {
+  @autoSubscribe()
+  render() {
+    const data = PublisherManager.get("myData");
+    const config = PublisherManager.get("config");
+    //
+    // This render method will be automatically re-executed
+    // when myData or config change
+    const value = data.get()?.value || 0;
+    const multiplier = config.get()?.multiplier || 1;
+    //
+    return html`
+      <div>
+        <h1>Result: ${value * multiplier}</h1>
+        <p>Value: ${value}</p>
+        <p>Multiplier: ${multiplier}</p>
+      </div>
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+## How it works
+
+1. **First execution**: When the method is called, `PublisherManager.collectModifiedPublisher()` is used to track which publishers are accessed
+2. **Subscription**: After execution, the decorator subscribes to all detected publishers
+3. **Re-execution**: When any subscribed publisher changes, the method is automatically called again
+4. **Cleanup**: On `disconnectedCallback`, all subscriptions are automatically removed
+
+## Behavior
+
+- The method is automatically called on `connectedCallback`
+- The method is re-executed whenever any accessed publisher changes
+- Subscriptions are managed automatically (no manual cleanup needed)
+- Only publishers accessed during method execution are subscribed to
+- The decorator uses `queueMicrotask` to batch multiple updates and avoid unnecessary re-renders
+
+## Use cases
+
+This decorator is particularly useful for:
+
+- **Reactive rendering** where the render method depends on multiple publishers
+- **Data transformation** that needs to update when source data changes
+- **Computed properties** that depend on multiple data sources
+- **Automatic synchronization** between publishers and component state
+
+## Complete example
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import { autoSubscribe } from "@supersoniks/concorde/decorators";
+import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
+//
+@customElement("shopping-cart")
+export class ShoppingCart extends LitElement {
+  items: any[] = [];
+  total: number = 0;
+  discount: number = 0;
+  //
+  @autoSubscribe()
+  calculateTotal() {
+    const cart = PublisherManager.get("cart");
+    const promo = PublisherManager.get("promo");
+    //
+    // Access cart items
+    this.items = cart.items.get() || [];
+    //
+    // Access promo code
+    const promoCode = promo.code.get() || "";
+    const discountPercent = promoCode === "SAVE10" ? 0.1 : 0;
+    //
+    // Calculate totals
+    const subtotal = this.items.reduce((sum, item) => 
+      sum + (item.price * item.quantity), 0
+    );
+    this.discount = subtotal * discountPercent;
+    this.total = subtotal - this.discount;
+    //
+    this.requestUpdate();
+  }
+  //
+  connectedCallback() {
+    super.connectedCallback();
+    this.calculateTotal();
+  }
+  //
+  render() {
+    return html`
+      <div class="cart">
+        <h2>Shopping Cart</h2>
+        ${this.items.map(item => html`
+          <div>${item.name} x${item.quantity} - ${item.price}€</div>
+        `)}
+        <div class="total">
+          <p>Subtotal: ${this.total + this.discount}€</p>
+          <p>Discount: -${this.discount}€</p>
+          <p><strong>Total: ${this.total}€</strong></p>
+        </div>
+      </div>
+    `;
+  }
+}
+//
+// When you update the publishers, calculateTotal is automatically called:
+const cart = PublisherManager.get("cart");
+cart.items.set([
+  { name: "Product 1", price: 10, quantity: 2 },
+  { name: "Product 2", price: 15, quantity: 1 }
+]);
+//
+const promo = PublisherManager.get("promo");
+promo.code.set("SAVE10");
+// calculateTotal will be automatically called and the UI will update
+  </template>
+</sonic-code>
+
+## Notes
+
+- This decorator works with any component that has `connectedCallback` and `disconnectedCallback` methods (such as `LitElement` or components extending `Subscriber`)
+- The method is called automatically on `connectedCallback`
+- Remember to call `this.requestUpdate()` if you're updating component properties
+- The decorator uses debouncing via `queueMicrotask` to prevent excessive re-executions
+- For more information about publishers, see the documentation on [Sharing data](#docs/_getting-started/pubsub.md/pubsub)
+