@supersoniks/concorde 4.1.0 → 4.2.1

package/docs/src/docs/search/docs-search.json

@@ -4274,6 +4274,121 @@
       }
     }
   },
+  {
+    "search": "The @subscribe decorator is a simplified version of @bind without reflect. It accepts only Key<T> and enforces that the decorated property must be of type T:\n",
+    "files": {
+      "docs/_misc/bind.md": {
+        "title": "@bind",
+        "hashes": {
+          "subscribe-read-only-strictly-typed-with-key": {
+            "count": 1,
+            "title": "@subscribe (read-only, strictly typed with Key)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "const statsKey = new Key("idDonneesDeStats");\n",
+    "files": {
+      "docs/_misc/bind.md": {
+        "title": "@bind",
+        "hashes": {
+          "subscribe-read-only-strictly-typed-with-key": {
+            "count": 1,
+            "title": "@subscribe (read-only, strictly typed with Key)",
+            "type": "paragraph"
+          }
+        }
+      },
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "integration-with-subscribe": {
+            "count": 1,
+            "title": "Integration with @subscribe",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "@subscribe(statsKey.gauge)\n@state()\ngauge: number = 0;  // OK — matches Key\n",
+    "files": {
+      "docs/_misc/bind.md": {
+        "title": "@bind",
+        "hashes": {
+          "subscribe-read-only-strictly-typed-with-key": {
+            "count": 1,
+            "title": "@subscribe (read-only, strictly typed with Key)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "// @subscribe(statsKey.gauge)\n// gauge: string = "";  // Error — type 'string' is not assignable to type 'number'\n  \n\n",
+    "files": {
+      "docs/_misc/bind.md": {
+        "title": "@bind",
+        "hashes": {
+          "subscribe-read-only-strictly-typed-with-key": {
+            "count": 1,
+            "title": "@subscribe (read-only, strictly typed with Key)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The @publish decorator is the inverse of @subscribe: when you write to the property, the value is published to the publisher path. No subscription (no read from publisher).\n",
+    "files": {
+      "docs/_misc/bind.md": {
+        "title": "@bind",
+        "hashes": {
+          "publish-write-only-inverse-of-subscribe": {
+            "count": 1,
+            "title": "@publish (write-only, inverse of @subscribe)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "const formKey = new Key("formData");\n",
+    "files": {
+      "docs/_misc/bind.md": {
+        "title": "@bind",
+        "hashes": {
+          "publish-write-only-inverse-of-subscribe": {
+            "count": 1,
+            "title": "@publish (write-only, inverse of @subscribe)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "@publish(formKey.email)\n@state()\nemail = "";  // Writing to email publishes to formData.email\n  \n\n",
+    "files": {
+      "docs/_misc/bind.md": {
+        "title": "@bind",
+        "hashes": {
+          "publish-write-only-inverse-of-subscribe": {
+            "count": 1,
+            "title": "@publish (write-only, inverse of @subscribe)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Lorsque vous avez besoin que les modifications locales se propagent également vers le publisher, activez l'option reflect :\n",
     "files": {
@@ -4344,6 +4459,21 @@
       }
     }
   },
+  {
+    "search": "  }\n  //\n  render() {\n    return html      <div class="flex flex-col gap-2">         <sonic-select           .value=${this.dataProvider}           label="Users set"           @change=${this.updateDataProvider}         >           <option value="demoUsers">First set of users</option>           <option value="demoUsersAlt">Second set of users</option>         </sonic-select>         <sonic-input           type="number"           .value=${this.userIndex}           @input=${this.updateUserIndex}           min="0"           max="9"           label="Index"           class="block"         >         </sonic-input>         <sonic-button @click=${this.updateCurrentUserData}           >Update current user data</sonic-button         >         <div class="flex flex-col gap-2 border p-2">           <div>             <sonic-icon name="user" library="heroicons"></sonic-icon>             ${this.user?.firstName} ${this.user?.lastName}           </div>           <div>             <sonic-icon name="envelope" library="heroicons"></sonic-icon>             ${this.user?.email}           </div>         </div>       </div>    ;\n  }\n",
+    "files": {
+      "docs/_misc/bind.md": {
+        "title": "@bind",
+        "hashes": {
+          "dynamic-path-driven-by-class-properties": {
+            "count": 1,
+            "title": "Dynamic path driven by class properties",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "⚠️ Use a classic string literal: @bind("${dataProvider}.${profileId}.info.title"). Do not use a template literal (backticks), otherwise JavaScript would try to interpolate the value immediately.\n",
     "files": {
@@ -4371,6 +4501,211 @@
             "type": "paragraph"
           }
         }
+      },
+      "docs/_misc/on-assign.md": {
+        "title": "@onAssign",
+        "hashes": {
+          "dynamic-path-driven-by-class-properties": {
+            "count": 1,
+            "title": "Dynamic path driven by class properties",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Key",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "key": {
+            "count": 1,
+            "title": "",
+            "type": "page"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The Key<T> utility provides type-safe navigation through composite data structures. Each property or index access extends the path, and the final key can be retrieved via toString() or the path property.\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "key": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Key uses a Proxy to intercept property access and build a cumulative path string. TypeScript infers the nested type at each level, so myKey.checkedTickets[0] is correctly typed as Key<LegacyCheckedTicket> when checkedTickets is LegacyCheckedTicket[].\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "principle": {
+            "count": 1,
+            "title": "Principle",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "// Create a key and navigate through the structure\nconst myKey = new Key("idDonneesDeStats").checkedTickets[0];\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "basic-example": {
+            "count": 1,
+            "title": "Basic example",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "// Equivalent to: new Key("idDonneesDeStats.checkedTickets.0")\nmyKey.toString();  // "idDonneesDeStats.checkedTickets.0"\nmyKey.path;        // same value\n// myKey is typed as Key\n  \n\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "basic-example": {
+            "count": 1,
+            "title": "Basic example",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "const firstTicket = ticketsKey[0];\nfirstTicket.path;  // "data.checkedTickets.0"\n// firstTicket is Key\n  \n\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "array-index-access": {
+            "count": 1,
+            "title": "Array index access",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "const key = Key("root");\nkey.path;  // "root"\n  \n\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "usage-without-new": {
+            "count": 1,
+            "title": "Usage without `new`",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The final path is built by concatenating each accessed property with a dot:\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "path-retrieval": {
+            "count": 1,
+            "title": "Path retrieval",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Use toString() or path to get the full path string:\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "path-retrieval": {
+            "count": 1,
+            "title": "Path retrieval",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Use Key with the @subscribe decorator for strictly typed, read-only bindings (no reflect). The decorated property must match the Key type:\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "integration-with-subscribe": {
+            "count": 1,
+            "title": "Integration with @subscribe",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "@customElement("stats-gauge")\nexport class StatsGauge extends LitElement {\n  @subscribe(statsKey.gauge)\n  @state()\n  gauge: number = 0;  // Type enforced: must be number\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "integration-with-subscribe": {
+            "count": 1,
+            "title": "Integration with @subscribe",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "  render() {\n    return html<span>Gauge: ${this.gauge}</span>;\n  }\n}\n  \n\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "integration-with-subscribe": {
+            "count": 1,
+            "title": "Integration with @subscribe",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "If you declare gauge: string with @subscribe(statsKey.gauge) (Key), TypeScript will error.\n",
+    "files": {
+      "docs/_misc/key.md": {
+        "title": "Key",
+        "hashes": {
+          "integration-with-subscribe": {
+            "count": 1,
+            "title": "Integration with @subscribe",
+            "type": "paragraph"
+          }
+        }
       }
     }
   },
@@ -4434,6 +4769,51 @@
       }
     }
   },
+  {
+    "search": "You can now build the paths dynamically by referencing the host class properties inside the strings passed to @onAssign. Two placeholder syntaxes are supported:\n",
+    "files": {
+      "docs/_misc/on-assign.md": {
+        "title": "@onAssign",
+        "hashes": {
+          "dynamic-path-driven-by-class-properties": {
+            "count": 1,
+            "title": "Dynamic path driven by class properties",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Each placeholder is replaced at runtime with the current value of the corresponding property. @onAssign automatically watches those properties and:\n",
+    "files": {
+      "docs/_misc/on-assign.md": {
+        "title": "@onAssign",
+        "hashes": {
+          "dynamic-path-driven-by-class-properties": {
+            "count": 1,
+            "title": "Dynamic path driven by class properties",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "⚠️ Use classic string literals: @onAssign("${dataProvider}.${profileId}", "settings.${profileId}"). Do not use template literals (backticks), otherwise JavaScript would try to interpolate the value immediately.\n",
+    "files": {
+      "docs/_misc/on-assign.md": {
+        "title": "@onAssign",
+        "hashes": {
+          "dynamic-path-driven-by-class-properties": {
+            "count": 1,
+            "title": "Dynamic path driven by class properties",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Templates Demo",
     "files": {
@@ -4463,5 +4843,215 @@
         }
       }
     }
+  },
+  {
+    "search": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "awaitconnectedancestors-and-dispatchconnectedevent": {
+            "count": 1,
+            "title": "",
+            "type": "page"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The @awaitConnectedAncestors and @dispatchConnectedEvent decorators delay a web component's initialization until its matching ancestors have executed their connectedCallback. This is when contextual elements (publisher, dataProvider, etc.) are configured.\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "awaitconnectedancestors-and-dispatchconnectedevent": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "When a child component attaches to the DOM, its ancestors may not yet be initialized (especially if custom element definitions are loaded asynchronously). The @awaitConnectedAncestors decorator delays the component's connectedCallback until all ancestors matching the provided CSS selectors have executed their connectedCallback.\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "principle": {
+            "count": 1,
+            "title": "Principle",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The @dispatchConnectedEvent decorator allows ancestors to signal they are ready by dispatching the sonic-connected event at the end of their connectedCallback. The event bubbles, so it can be listened to from anywhere (e.g. document.addEventListener(CONNECTED, handler)).\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "principle": {
+            "count": 1,
+            "title": "Principle",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Ancestors that are not web components (no hyphen in tag name) are considered connected by default and do not need to emit the event.\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "principle": {
+            "count": 1,
+            "title": "Principle",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "An ancestor container decorated with @dispatchConnectedEvent() signals when it is ready. A child component decorated with @awaitConnectedAncestors("demo-wait-ancestor-container[dataProvider]") waits for this container to be initialized before initializing itself. Parameters are CSS selectors (element.matches()).\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "basic-example": {
+            "count": 1,
+            "title": "Basic example",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The parent is registered via customElements.define() (vanilla JS) rather than @customElement, so it can be defined later—e.g. when the user clicks a button. This demonstrates the child waiting until the parent exists.\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "basic-example": {
+            "count": 1,
+            "title": "Basic example",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The child waits for all specified ancestors. Register outer first, then inner — the child initializes only when both are ready.\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "multiple-ancestors": {
+            "count": 1,
+            "title": "Multiple ancestors",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "When the parent is defined at load and already in the DOM, the child initializes immediately (no delay).\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "ancestors-already-connected": {
+            "count": 1,
+            "title": "Ancestors already connected",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Static (both in DOM from start):\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "ancestors-already-connected": {
+            "count": 1,
+            "title": "Ancestors already connected",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Dynamic (child added on button click):\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "ancestors-already-connected": {
+            "count": 1,
+            "title": "Ancestors already connected",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Parameters are CSS selectors matched via element.matches() — e.g. "sonic-subscriber", "sonic-subscriber[dataProvider]", ".my-container", or multiple: "sonic-subscriber", "sonic-sdui".\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "css-selector-support": {
+            "count": 1,
+            "title": "CSS selector support",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "These decorators are particularly useful for:\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "use-cases": {
+            "count": 1,
+            "title": "Use cases",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The sonic-connected event bubbles, so you can listen to it from anywhere:\n",
+    "files": {
+      "docs/_misc/wait-for-ancestors.md": {
+        "title": "@awaitConnectedAncestors and @dispatchConnectedEvent",
+        "hashes": {
+          "listening-to-the-connected-event": {
+            "count": 1,
+            "title": "Listening to the connected event",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
   }
 ]

package/docs/src/tsconfig-model.json

@@ -1,5 +1,5 @@
 {
-  "exclude": ["node_modules/**/*", "dist/**/*", "vite.config.mts", "docs.ts", "docs/*", "router-test.html"],
+  "exclude": ["node_modules/**/*", "dist/**/*", "vite.config.mts", "docs.ts", "docs/*", "router-test.html", "**/*.type-test.ts"],
   "compilerOptions": {
     "target": "es2021",
     "experimentalDecorators": true,