@spearwolf/shadow-objects 0.33.0 → 0.35.0

package/src/elements/ShaePropElement.js

@@ -1,63 +1,35 @@
-import { batch, createEffect, createSignal, link } from "@spearwolf/signalize";
+import { batch, createEffect, createSignal, Effect, hibernate, link } from "@spearwolf/signalize";
 import { readBooleanAttribute } from "../utils/attr-utils.js";
 import { ConsoleLogger } from "../utils/ConsoleLogger.js";
-import { TRUTHY_VALUES } from "../utils/constants.js";
-import { ATTR_NAME, ATTR_NO_TRIM, ATTR_TYPE, ATTR_VALUE } from "./constants.js";
-const findEntNode = (start) => {
-  let el = start.parentElement;
-  while (el) {
-    if (el.isShaeEntElement) {
-      return el;
-    }
-    el = el.parentElement;
+import { MicrotaskGate } from "../utils/MicrotaskGate.js";
+import { ATTR_NAME, ATTR_NO_TRIM, ATTR_TYPE, ATTR_VALUE, ReRequestEntHostEventName } from "./constants.js";
+import { propValueConverters } from "./propValueConverters.js";
+import { requestEntAncestor } from "./requestEntAncestor.js";
+import { ShaeLifecycleElement } from "./ShaeLifecycleElement.js";
+const declarantsPerComponent = /* @__PURE__ */ new WeakMap();
+const addDeclarant = (vc, name) => {
+  let names = declarantsPerComponent.get(vc);
+  if (names == null) {
+    names = /* @__PURE__ */ new Map();
+    declarantsPerComponent.set(vc, names);
+  }
+  names.set(name, (names.get(name) ?? 0) + 1);
+};
+const removeDeclarant = (vc, name) => {
+  const names = declarantsPerComponent.get(vc);
+  if (names == null) return true;
+  const remaining = (names.get(name) ?? 1) - 1;
+  if (remaining > 0) {
+    names.set(name, remaining);
+    return false;
+  }
+  names.delete(name);
+  if (names.size === 0) {
+    declarantsPerComponent.delete(vc);
   }
-  return void 0;
+  return true;
 };
-const TYPES = /* @__PURE__ */ new Set([
-  "string",
-  "text",
-  "number",
-  "bigint",
-  "float",
-  "int",
-  "integer",
-  "hex",
-  "hexadecimal",
-  "oct",
-  "octal",
-  "bin",
-  "binary",
-  "bool",
-  "boolean",
-  "[]",
-  "text[]",
-  "string[]",
-  "number[]",
-  "float[]",
-  "int[]",
-  "integer[]",
-  "hex[]",
-  "hexadecimal[]",
-  "oct[]",
-  "octal[]",
-  "bin[]",
-  "binary[]",
-  "bool[]",
-  "boolean[]",
-  "int8array",
-  "uint8array",
-  "uint8clampedarray",
-  "int16array",
-  "uint16array",
-  "int32array",
-  "uint32array",
-  "float32array",
-  "float64array",
-  "bigint64array",
-  "biguint64array",
-  "json"
-]);
-class ShaePropElement extends HTMLElement {
+class ShaePropElement extends ShaeLifecycleElement {
   constructor() {
     super();
     this.isShaePropElement = true;
@@ -68,9 +40,78 @@ class ShaePropElement extends HTMLElement {
     this.valueOut$ = createSignal();
     this.type$ = createSignal();
     this.shouldTrim$ = createSignal(true);
-    this.logger = new ConsoleLogger("ShaePropElement");
+    this.#logger = new ConsoleLogger("ShaePropElement");
+    /** Whether the missing-host warning has already gone out for this element. */
+    this.#reportedMissingHost = false;
+    // Two terms, and they answer two different questions. `isConnected` separates an element in
+    // the tree from one on its way out: a round booked before the departure has nothing left to
+    // say about a position the element no longer holds. `isDestroyed` separates one that is
+    // listening from one that was ended by hand and is still standing where it was — a lookup
+    // running there would write `entNode$` and register the re-request listener again that the
+    // teardown just took off, and the element would be listening after it let go of everything.
+    // The flag is up before `teardown()` runs, so a round that comes due afterwards reads the
+    // state the element is actually in.
+    //
+    // The test stands here and not in the gate: a `MicrotaskGate` has no way to call a booking
+    // off, and that is the whole of what tells it apart from `DeferredTeardown`.
+    this.#hostLookup = new MicrotaskGate(() => {
+      if (this.isConnected && !this.isDestroyed) {
+        this.#findEntNode();
+      }
+    });
+    // Determines the host from where the element stands right now. The request runs *without* a
+    // namespace: a property belongs to the closest entity above it, whatever namespace that entity
+    // is in.
+    //
+    // Nobody answering means there is no entity above this position, and the element says so. A
+    // binding without an answer belongs to a place that is no longer there — whether the element
+    // moved or the entity above it did. The cleanup on `entNode$` then takes the property off the
+    // entity that no longer holds it, instead of leaving the element writing into an entity it does
+    // not sit under any more.
     this.#findEntNode = () => {
-      this.entNode$.set(findEntNode(this));
+      let found;
+      requestEntAncestor(this, { answer: (entNode) => found = entNode });
+      this.entNode$.set(found);
+      if (found == null && this.isConnected && !this.#reportedMissingHost) {
+        this.#reportedMissingHost = true;
+        this.logger.warn(`[${this.name}] no entity above this element, the property is set nowhere`, {
+          shaeProp: this
+        });
+      }
+      this.#listenForHostChanges();
+    };
+    // Someone above started or stopped answering. Two things separate this from a lookup the
+    // element makes on arrival, and both belong here, to the trigger — what an unanswered
+    // request means is the same on either path.
+    //
+    // It waits a microtask: the message arrives while the tree is still moving. An entity that
+    // announces its departure has left, but everything below it can be back in place before the
+    // tick ends, and an ancestor answering *right now* can be one this element is about to
+    // leave behind. Asking after the dust settles is asking once, about the tree that is
+    // actually there.
+    //
+    // And it drops the question if this element has left in the meantime, for the same reason
+    // `#reRequestParent` does in `ShaeEntElement`: an element that is out of the tree answers
+    // nothing about its position any more. Whether its departure is a move or an end is
+    // `#disconnectFromEntNode`'s to answer, one microtask later, and it is answered in one place.
+    // Nothing observable turns on the test — a departing entity takes its properties with it
+    // either way — so it stands as a rule, not as a measurement.
+    //
+    // `#hostLookup` bounds the cost: a page filling up with entities sends many messages through the
+    // same ancestor chain, and the gate turns them into one lookup per microtask and per element.
+    this.#onReRequestHost = () => {
+      this.#hostLookup.schedule();
+    };
+    this.#listenForHostChanges = () => {
+      const target = this.entNode$.value ?? this.ownerDocument;
+      if (target === this.#reRequestHostTarget) return;
+      this.#stopListeningForHostChanges();
+      target.addEventListener(ReRequestEntHostEventName, this.#onReRequestHost);
+      this.#reRequestHostTarget = target;
+    };
+    this.#stopListeningForHostChanges = () => {
+      this.#reRequestHostTarget?.removeEventListener(ReRequestEntHostEventName, this.#onReRequestHost);
+      this.#reRequestHostTarget = void 0;
     };
     this.#disconnectFromEntNode = () => {
       queueMicrotask(() => {
@@ -83,16 +124,20 @@ class ShaePropElement extends HTMLElement {
       this.name$.set(this.getAttribute(ATTR_NAME)?.trim() ?? void 0);
     };
     this.#readValueAttribute = () => {
-      this.valueIn$.set(this.getAttribute(ATTR_VALUE));
+      const value = this.getAttribute(ATTR_VALUE);
+      this.valueIn$.set(value === null || value === "" ? void 0 : value);
+    };
+    /** Whether the `value` attribute says something — absent and empty are the same "nothing" here. */
+    this.#valueAttributeCarriesValue = () => {
+      const value = this.getAttribute(ATTR_VALUE);
+      return value !== null && value !== "";
     };
     this.#readTypeAttribute = () => {
       let type = this.getAttribute(ATTR_TYPE)?.trim().toLowerCase();
-      if (type && !TYPES.has(type)) {
-        if (this.logger.isWarn) {
-          this.logger.warn(`[${this.name}] unknown type "${type}"`, {
-            shaeProp: this
-          });
-        }
+      if (type && !propValueConverters.has(type)) {
+        this.logger.warn(`[${this.name}] unknown type "${type}"`, {
+          shaeProp: this
+        });
         type = void 0;
       }
       this.type$.set(type);
@@ -100,7 +145,77 @@ class ShaePropElement extends HTMLElement {
     this.#readNoTrimAttribute = () => {
       this.shouldTrim$.set(!readBooleanAttribute(this, ATTR_NO_TRIM));
     };
-    this.entNode$.onChange((entNode) => {
+    batch(() => {
+      this.#readNameAttribute();
+      this.#readValueAttribute();
+      this.#readTypeAttribute();
+      this.#readNoTrimAttribute();
+    });
+  }
+  static {
+    this.observedAttributes = [ATTR_NAME, ATTR_VALUE, ATTR_TYPE, ATTR_NO_TRIM];
+  }
+  #logger;
+  /** The logger this element reports through: a subclass reads it and does not replace it. */
+  get logger() {
+    return this.#logger;
+  }
+  /** Binds this element to the entity above it, and carries that entity's component through. */
+  #hostBinding;
+  /** Holds the property on the entity for as long as this element declares it. */
+  #declareProperty;
+  /** Writes the value through to the entity. */
+  #writePropertyValue;
+  /** Turns what the attribute spells into the value the property carries. */
+  #convertValue;
+  #reportedMissingHost;
+  /** The node this element listens on for a re-request of the host, so the listener can come off the same one. */
+  #reRequestHostTarget;
+  #hostLookup;
+  get name() {
+    return this.name$.value;
+  }
+  /**
+   * Writes the `name` attribute, and `attributeChangedCallback` takes it from there: the attribute
+   * is the one source the name is read from, so a write through the property and a write through
+   * `setAttribute` end up in the same place and are trimmed by the same rule. A framework renderer
+   * assigns every prop it finds `in` the element as a property — React 19 and Vue 3 both do — and
+   * a name it cannot assign is a property that never binds.
+   */
+  set name(name) {
+    const trimmed = name?.trim();
+    if (!trimmed) {
+      this.removeAttribute(ATTR_NAME);
+    } else if (this.getAttribute(ATTR_NAME) !== trimmed) {
+      this.setAttribute(ATTR_NAME, trimmed);
+    }
+  }
+  get value() {
+    return this.valueOut$.value;
+  }
+  set value(val) {
+    this.valueIn$.set(val);
+  }
+  get shouldTrim() {
+    return this.shouldTrim$.value;
+  }
+  get entNode() {
+    return this.entNode$.value;
+  }
+  set entNode(el) {
+    this.entNode$.set(el);
+  }
+  get viewComponent() {
+    return this.viewComponent$.value;
+  }
+  /**
+   * Take up everything this element listens to.
+   *
+   * Called from {@link ShaePropElement.restore} and from nowhere else — that is the one place where
+   * this element's subscriptions begin, at the first connect as well as after a teardown.
+   */
+  #subscribe() {
+    this.#hostBinding = this.entNode$.onChange((entNode) => {
       if (entNode) {
         const con = link(entNode.viewComponent$, this.viewComponent$);
         return () => {
@@ -110,18 +225,29 @@ class ShaePropElement extends HTMLElement {
         this.viewComponent$.set(void 0);
       }
     });
-    createEffect(() => {
+    this.#declareProperty = createEffect(() => {
+      const vc = this.viewComponent$.get();
+      const name = this.name$.get();
+      if (vc == null || !name) return;
+      const entNode = this.entNode$.value;
+      addDeclarant(vc, name);
+      return () => {
+        if (removeDeclarant(vc, name)) {
+          vc.removeProperty(name);
+          entNode?.syncShadowObjects();
+        }
+      };
+    });
+    this.#writePropertyValue = createEffect(() => {
       const vc = this.viewComponent$.get();
       if (vc) {
         const name = this.name$.get();
         if (name) {
           const value = this.valueOut$.get();
-          if (this.logger.isDebug) {
-            this.logger.debug(`[${this.name}] view-component set-property`, name, value, vc.uuid, {
-              viewComponent: vc,
-              shaeProp: this
-            });
-          }
+          this.logger.debug(`[${this.name}] view-component set-property`, name, value, vc.uuid, {
+            viewComponent: vc,
+            shaeProp: this
+          });
           vc.setProperty(name, value);
           if (this.isConnected) {
             this.entNode?.syncShadowObjects();
@@ -129,165 +255,59 @@ class ShaePropElement extends HTMLElement {
         }
       }
     });
-    createEffect(() => {
+    this.#convertValue = createEffect(() => {
       const type = this.type$.get();
       const shouldTrim = this.shouldTrim$.get();
       let value = this.valueIn$.get();
       if (shouldTrim && typeof value === "string") {
         value = value.trim();
       }
-      value = value || void 0;
-      if (value != null && typeof value === "string" && type) {
-        switch (type) {
-          case "string":
-          case "text":
-            break;
-          case "number":
-            value = Number(value);
-            break;
-          case "bigint":
-            value = BigInt(value);
-            break;
-          case "float":
-            value = parseFloat(value);
-            break;
-          case "int":
-          case "integer":
-            value = parseInt(value, 10);
-            break;
-          case "hex":
-          case "hexadecimal":
-            value = parseInt(value, 16);
-            break;
-          case "oct":
-          case "octal":
-            value = parseInt(value, 8);
-            break;
-          case "bin":
-          case "binary":
-            value = parseInt(value, 2);
-            break;
-          case "bool":
-          case "boolean":
-            value = TRUTHY_VALUES.has(value.toLowerCase());
-            break;
-          case "[]":
-          case "text[]":
-          case "string[]":
-            value = value.split(/\W+/);
-            break;
-          case "number[]":
-            value = value.split(/\s+/).map((v) => Number(v));
-            break;
-          case "float[]":
-            value = value.split(/\s+/).map((v) => parseFloat(v));
-            break;
-          case "int[]":
-          case "integer[]":
-            value = value.split(/\s+/).map((v) => parseInt(v, 10));
-            break;
-          case "hex[]":
-          case "hexadecimal[]":
-            value = value.split(/\W+/).map((v) => parseInt(v, 16));
-            break;
-          case "oct[]":
-          case "octal[]":
-            value = value.split(/\W+/).map((v) => parseInt(v, 8));
-            break;
-          case "bin[]":
-          case "binary[]":
-            value = value.split(/\W+/).map((v) => parseInt(v, 2));
-            break;
-          case "bool[]":
-          case "boolean[]":
-            value = value.split(/\W+/).map((v) => TRUTHY_VALUES.has(v.toLowerCase()));
-            break;
-          case "int8array":
-            value = new Int8Array(value.split(/\W+/).map((v) => Number(v)));
-            break;
-          case "uint8array":
-            value = new Uint8Array(value.split(/\W+/).map((v) => Number(v)));
-            break;
-          case "uint8clampedarray":
-            value = new Uint8ClampedArray(value.split(/\W+/).map((v) => Number(v)));
-            break;
-          case "int16array":
-            value = new Int16Array(value.split(/\W+/).map((v) => Number(v)));
-            break;
-          case "uint16array":
-            value = new Uint16Array(value.split(/\W+/).map((v) => Number(v)));
-            break;
-          case "int32array":
-            value = new Int32Array(value.split(/\W+/).map((v) => Number(v)));
-            break;
-          case "uint32array":
-            value = new Uint32Array(value.split(/\W+/).map((v) => Number(v)));
-            break;
-          case "float32array":
-            value = new Float32Array(value.split(/\s+/).map((v) => Number(v)));
-            break;
-          case "float64array":
-            value = new Float64Array(value.split(/\s+/).map((v) => Number(v)));
-            break;
-          case "bigint64array":
-            value = new BigInt64Array(value.split(/\W+/).map((v) => BigInt(v)));
-            break;
-          case "biguint64array":
-            value = new BigUint64Array(value.split(/\W+/).map((v) => BigInt(v)));
-            break;
-          case "json":
-            value = JSON.parse(value);
-            break;
-          default:
-            if (this.logger.isWarn) {
-              this.logger.warn(`[${this.name}] unknown type "${type}"`, {
-                value,
-                shaeProp: this
-              });
-            }
+      value = value ?? void 0;
+      if (typeof value === "string" && type) {
+        const convert = propValueConverters.get(type);
+        if (convert != null) {
+          try {
+            value = convert(value);
+          } catch (error) {
+            this.logger.error(`[${this.name}] could not convert the value into the type "${type}"`, {
+              value,
+              error,
+              shaeProp: this
+            });
+            value = void 0;
+          }
         }
       }
       this.valueOut$.set(value);
     });
-    batch(() => {
-      this.#readNameAttribute();
-      this.#readValueAttribute();
-      this.#readTypeAttribute();
-      this.#readNoTrimAttribute();
-    });
-    this.style.display = "contents";
-  }
-  static {
-    this.observedAttributes = [ATTR_NAME, ATTR_VALUE, ATTR_TYPE, ATTR_NO_TRIM];
-  }
-  get name() {
-    return this.name$.value;
   }
-  get value() {
-    return this.valueOut$.value;
-  }
-  set value(val) {
-    this.valueIn$.set(val);
-  }
-  get shouldTrim() {
-    return this.shouldTrim$.value;
-  }
-  get entNode() {
-    return this.entNode$.value;
-  }
-  set entNode(el) {
-    this.entNode$.set(el);
-  }
-  get viewComponent() {
-    return this.viewComponent$.value;
+  /**
+   * Take this element's own subscriptions up. Its half of {@link ShaeLifecycleElement.restore}.
+   *
+   * There is nothing to catch up on here, unlike `<shae-ent>`: `connectedCallback` reads `name`,
+   * `type` and `no-trim` off the attributes, `value` where the attribute carries one, and looks the
+   * host up again straight after this. So the attributes decide, and whatever was written to a
+   * released element through `prop.entNode` — or through `prop.value` against a `value` attribute
+   * that says something — is replaced by what the tree and the markup say. That is this element's
+   * rule in and out of a teardown alike — a `<shae-prop>` reads its position on every connect — and
+   * the documentation states it as the difference it is.
+   */
+  restore() {
+    super.restore();
+    this.#subscribe();
   }
   connectedCallback() {
-    batch(() => {
-      this.#findEntNode();
-      this.#readNameAttribute();
-      this.#readValueAttribute();
-      this.#readTypeAttribute();
-      this.#readNoTrimAttribute();
+    hibernate(() => {
+      super.connectedCallback();
+      batch(() => {
+        this.#findEntNode();
+        this.#readNameAttribute();
+        if (this.#valueAttributeCarriesValue()) {
+          this.#readValueAttribute();
+        }
+        this.#readTypeAttribute();
+        this.#readNoTrimAttribute();
+      });
     });
   }
   attributeChangedCallback(name) {
@@ -307,12 +327,37 @@ class ShaePropElement extends HTMLElement {
     }
   }
   disconnectedCallback() {
+    this.#stopListeningForHostChanges();
     this.#disconnectFromEntNode();
+    super.disconnectedCallback();
+  }
+  /**
+   * Release this element's own subscriptions. Its half of {@link ShaeLifecycleElement.teardown}.
+   *
+   * The `link()` between the host's `viewComponent$` and this element's own needs no line of its
+   * own: it is built in the cleanup path of the `entNode$` subscription, and taking that
+   * subscription off runs the cleanup that destroys it.
+   */
+  teardown() {
+    this.#stopListeningForHostChanges();
+    this.#hostBinding?.();
+    this.#hostBinding = void 0;
+    this.#declareProperty?.destroy();
+    this.#declareProperty = void 0;
+    this.#writePropertyValue?.destroy();
+    this.#writePropertyValue = void 0;
+    this.#convertValue?.destroy();
+    this.#convertValue = void 0;
+    super.teardown();
   }
   #findEntNode;
+  #onReRequestHost;
+  #listenForHostChanges;
+  #stopListeningForHostChanges;
   #disconnectFromEntNode;
   #readNameAttribute;
   #readValueAttribute;
+  #valueAttributeCarriesValue;
   #readTypeAttribute;
   #readNoTrimAttribute;
 }