npm - @supersoniks/concorde - Versions diffs - 4.9.0 → 4.9.2 - Mend

@supersoniks/concorde 4.9.0 → 4.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (123) hide show

package/build-infos.json +1 -1
package/concorde-core.bundle.js +195 -195
package/concorde-core.es.js +3390 -3370
package/dist/concorde-core.bundle.js +195 -195
package/dist/concorde-core.es.js +3390 -3370
package/dist/docs-mock-api-sw.js +3 -1
package/dist/docs-mock-api-sw.js.map +2 -2
package/dist/js/core/decorators/api.js +64 -12
package/dist/js/core/decorators/api.js.map +1 -1
package/dist/js/core/utils/HTML.js +4 -5
package/dist/js/core/utils/HTML.js.map +1 -1
package/dist/robots.txt +15 -1
package/dist/types/core/decorators/api.d.ts +14 -1
package/dist/types/core/decorators/api.d.ts.map +1 -1
package/dist/types/core/utils/HTML.d.ts.map +1 -1
package/docs/assets/{index-t0-i22oI.css → index-Bnp7gVaA.css} +1 -1
package/docs/assets/{index-BEgZEIbv.js → index-hElUgV9_.js} +894 -552
package/docs/crawl/core/components/functional/date/date.html +190 -0
package/docs/crawl/core/components/functional/fetch/fetch.html +109 -0
package/docs/crawl/core/components/functional/if/if.html +27 -0
package/docs/crawl/core/components/functional/list/list.html +70 -0
package/docs/crawl/core/components/functional/mix/mix.html +45 -0
package/docs/crawl/core/components/functional/queue/queue.html +96 -0
package/docs/crawl/core/components/functional/router/router.html +106 -0
package/docs/crawl/core/components/functional/sdui/sdui.html +269 -0
package/docs/crawl/core/components/functional/states/states.html +66 -0
package/docs/crawl/core/components/functional/submit/submit.html +160 -0
package/docs/crawl/core/components/functional/subscriber/subscriber.html +67 -0
package/docs/crawl/core/components/functional/value/value.html +51 -0
package/docs/crawl/core/components/ui/alert/alert.html +110 -0
package/docs/crawl/core/components/ui/alert-messages/alert-messages.html +23 -0
package/docs/crawl/core/components/ui/badge/badge.html +119 -0
package/docs/crawl/core/components/ui/button/button.html +149 -0
package/docs/crawl/core/components/ui/captcha/captcha.html +30 -0
package/docs/crawl/core/components/ui/card/card.html +99 -0
package/docs/crawl/core/components/ui/divider/divider.html +58 -0
package/docs/crawl/core/components/ui/form/checkbox/checkbox.html +73 -0
package/docs/crawl/core/components/ui/form/fieldset/fieldset.html +135 -0
package/docs/crawl/core/components/ui/form/form-actions/form-actions.html +79 -0
package/docs/crawl/core/components/ui/form/form-layout/form-layout.html +62 -0
package/docs/crawl/core/components/ui/form/input/input.html +109 -0
package/docs/crawl/core/components/ui/form/input-autocomplete/input-autocomplete.html +106 -0
package/docs/crawl/core/components/ui/form/radio/radio.html +56 -0
package/docs/crawl/core/components/ui/form/select/select.html +73 -0
package/docs/crawl/core/components/ui/form/switch/switch.html +56 -0
package/docs/crawl/core/components/ui/form/textarea/textarea.html +59 -0
package/docs/crawl/core/components/ui/group/group.html +82 -0
package/docs/crawl/core/components/ui/icon/icon.html +133 -0
package/docs/crawl/core/components/ui/image/image.html +110 -0
package/docs/crawl/core/components/ui/link/link.html +42 -0
package/docs/crawl/core/components/ui/loader/loader.html +50 -0
package/docs/crawl/core/components/ui/menu/menu.html +322 -0
package/docs/crawl/core/components/ui/modal/modal.html +117 -0
package/docs/crawl/core/components/ui/pop/pop.html +102 -0
package/docs/crawl/core/components/ui/progress/progress.html +58 -0
package/docs/crawl/core/components/ui/table/table.html +413 -0
package/docs/crawl/core/components/ui/toast/toast.html +122 -0
package/docs/crawl/core/components/ui/tooltip/tooltip.html +79 -0
package/docs/crawl/docs/_core-concept/dataFlow.html +166 -0
package/docs/crawl/docs/_core-concept/overview.html +66 -0
package/docs/crawl/docs/_core-concept/subscriber.html +75 -0
package/docs/crawl/docs/_decorators/ancestor-attribute.html +116 -0
package/docs/crawl/docs/_decorators/auto-subscribe.html +202 -0
package/docs/crawl/docs/_decorators/bind.html +141 -0
package/docs/crawl/docs/_decorators/get.html +120 -0
package/docs/crawl/docs/_decorators/handle.html +165 -0
package/docs/crawl/docs/_decorators/on-assign.html +355 -0
package/docs/crawl/docs/_decorators/patch.html +52 -0
package/docs/crawl/docs/_decorators/post.html +102 -0
package/docs/crawl/docs/_decorators/publish.html +61 -0
package/docs/crawl/docs/_decorators/put.html +49 -0
package/docs/crawl/docs/_decorators/subscribe.html +109 -0
package/docs/crawl/docs/_decorators/wait-for-ancestors.html +137 -0
package/docs/crawl/docs/_directives/sub.html +93 -0
package/docs/crawl/docs/_getting-started/ai-agents.html +134 -0
package/docs/crawl/docs/_getting-started/concorde-manual-install.html +100 -0
package/docs/crawl/docs/_getting-started/concorde-outside.html +58 -0
package/docs/crawl/docs/_getting-started/create-a-component.html +111 -0
package/docs/crawl/docs/_getting-started/my-first-component.html +189 -0
package/docs/crawl/docs/_getting-started/my-first-subscriber.html +110 -0
package/docs/crawl/docs/_getting-started/pubsub.html +62 -0
package/docs/crawl/docs/_getting-started/start.html +76 -0
package/docs/crawl/docs/_getting-started/theming.html +85 -0
package/docs/crawl/docs/_misc/api-configuration.html +149 -0
package/docs/crawl/docs/_misc/dataProviderKey.html +135 -0
package/docs/crawl/docs/_misc/docs-mock-api.html +146 -0
package/docs/crawl/docs/_misc/dynamic-path.html +180 -0
package/docs/crawl/docs/_misc/endpoint.html +50 -0
package/docs/crawl/docs/_misc/html-integration.html +47 -0
package/docs/crawl/hubs/decorators.html +467 -0
package/docs/crawl/hubs/form-components.html +357 -0
package/docs/crawl/hubs/remote-data.html +374 -0
package/docs/crawl/index.html +99 -0
package/docs/docs-mock-api-sw.js +3 -1
package/docs/docs-mock-api-sw.js.map +2 -2
package/docs/index.html +3 -3
package/docs/llms-full.txt +5423 -0
package/docs/llms.txt +102 -0
package/docs/robots.txt +15 -1
package/docs/sitemap.xml +231 -0
package/docs/src/docs/_decorators/ancestor-attribute.md +56 -8
package/docs/src/docs/_decorators/get.md +47 -1
package/docs/src/docs/search/docs-search.json +92 -2
package/docs/src/tsconfig.declarations.json +22 -0
package/docs/src/tsconfig.emit.json +23 -0
package/docs/src/tsconfig.json +3 -285
package/index.html +1 -0
package/package.json +1 -1
package/public/docs-mock-api-sw.js +3 -1
package/public/docs-mock-api-sw.js.map +2 -2
package/public/robots.txt +15 -1
package/scripts/generate-crawl-docs.mjs +569 -0
package/scripts/post-build-docs.js +18 -14
package/src/core/decorators/api.spec.ts +74 -4
package/src/core/decorators/api.ts +103 -20
package/src/core/decorators/subscriber/ancestorAttribute.spec.ts +42 -0
package/src/core/utils/HTML.ts +4 -5
package/src/docs/_decorators/get.md +47 -1
package/src/docs/components/docs-demo-sources.ts +7 -2
package/src/docs/example/decorators-demo-geo.ts +5 -0
package/src/docs/example/decorators-demo-subscribe-publish-get-demos.ts +72 -31
package/src/docs/mock-api/router.ts +3 -1
package/src/docs/search/docs-search.json +92 -2

package/docs/crawl/docs/_decorators/subscribe.html ADDED Viewed

@@ -0,0 +1,109 @@
+<!DOCTYPE html>
+<html lang="fr" data-crawl-url="https://concorde.supersoniks.org/crawl/docs/_decorators/subscribe.html" data-doc-id="docs/_decorators/subscribe">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>@subscribe — Concorde</title>
+  <meta name="description" content="Keeps a Lit property in sync with a read-only slice of the DataProvider store. You pass a DataProviderKey; when that path changes, the property updates and the component re-renders.">
+  <meta name="keywords" content="Concorde, supersoniks, docs/_decorators/subscribe, subscribe, @subscribe, decorator, DataProviderKey,  | Shape of the object at that path (, , , , …) |
+| **Key** | ,  — static path (, ) or dynamic (,  (e.g. , ) — often filled via [">
+  <meta name="concorde-doc-id" content="docs/_decorators/subscribe">
+  <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_decorators/subscribe.html">
+</head>
+<body>
+  <header>
+    <p><a href="../../index.html">Concorde documentation (crawl)</a> · <a href="https://concorde.supersoniks.org/#docs/_decorators/subscribe.md/subscribe" rel="nofollow">interactive version</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @subscribe</strong>. Keeps a Lit property in sync with a read-only slice of the DataProvider store. You pass a DataProviderKey; when that path changes, the property updates and the component re-renders. <span>Doc ID: <code>docs/_decorators/subscribe</code>. Keywords: Concorde, supersoniks, docs/_decorators/subscribe, subscribe, @subscribe, decorator, DataProviderKey,  | Shape of the object at that path (, , , , …) |
+| **Key** | ,  — static path (, ) or dynamic (,  (e.g. , ) — often filled via [. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/subscribe.html">https://concorde.supersoniks.org/crawl/docs/_decorators/subscribe.html</a>.</span></p>
+      <h1 id="subscribe">@subscribe</h1>
+<p>Keeps a <strong>Lit property</strong> in sync with a <strong>read-only</strong> slice of the DataProvider store. You pass a <a href="../_misc/dataProviderKey.html#dataProviderKey"><code>DataProviderKey</code></a>; when that path changes, the property updates and the component re-renders.</p>
+<p>Typical setup (same idea as <a href="../_getting-started/my-first-component.html#my-first-component">My first component</a>):</p>
+<table>
+<thead>
+<tr>
+<th>Piece</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><strong>Type</strong> <code>T</code></td>
+<td>Shape of the object at that path (<code>DocsUserData</code>, <code>{ count: number }</code>, …)</td>
+</tr>
+<tr>
+<td><strong>Key</strong></td>
+<td><code>DataProviderKey&lt;T, U&gt;</code> — static path (<code>&quot;cart&quot;</code>) or dynamic (<code>&quot;users.${userIndex}&quot;</code>, <code>&quot;${dataProvider}&quot;</code>)</td>
+</tr>
+<tr>
+<td><strong>Scope on the host</strong></td>
+<td>Properties listed in <code>U</code> (e.g. <code>dataProvider</code>, <code>userIndex</code>) — often filled via <a href="./ancestor-attribute.html#ancestor-attribute"><code>@ancestorAttribute</code></a></td>
+</tr>
+<tr>
+<td><strong><code>@subscribe(key)</code></strong></td>
+<td>Mirrors the store into <code>@state()</code> (or another property); read-only from the component side</td>
+</tr>
+</tbody></table>
+<p>For <strong>writing</strong> back to the store from component state, use <a href="./publish.html#publish">@publish</a>. In templates, the same paths work with <a href="../_directives/sub.html#sub">sub()</a>.</p>
+<h2 id="import">Import</h2>
+<pre><code class="language-typescript">import { subscribe } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+type Data = { count: number };
+const dataKey = new DataProviderKey&amp;lt;Data&amp;gt;(&quot;data&quot;);
+@subscribe(dataKey.count)
+@state()
+count = 0;
+</code></pre>
+<h2 id="static-path">Static path</h2>
+<p>The key path is fixed. The property type must match <code>T</code> at that segment.</p>
+<pre><code class="language-typescript">const cartKey = new DataProviderKey&amp;lt;{ items: string[] }&amp;gt;(&quot;cart&quot;);
+@subscribe(cartKey)
+@state()
+cart: { items: string[] } | null = null;
+</code></pre>
+<h2 id="dynamic-path-and-scope">Dynamic path and scope</h2>
+<p>Placeholders <code>${prop}</code> in the key string are resolved from <strong>properties on the same component</strong>. While a value is <code>null</code>/<code>undefined</code>, the subscription is inactive; optional <code>{ skipEmptyPlaceholder: true }</code> also waits on <code>&quot;&quot;</code>. Full rules: <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a>.</p>
+<p>Declare dynamic props in the key’s second generic so TypeScript expects them on the host:</p>
+<pre><code class="language-typescript">type User = { firstName: string; lastName: string; email: string };
+@subscribe(new DataProviderKey&amp;lt;User, { userIndex: number }&amp;gt;(&quot;demoUsers.${userIndex}&quot;))
+@state()
+user: User | null = null;
+@property({ type: Number }) userIndex = 0;
+</code></pre>
+<p>When <code>userIndex</code> changes, <code>@subscribe</code> re-resolves the path and refreshes <code>user</code>.</p>
+<h2 id="row--ancestor-scope">Row / ancestor scope</h2>
+<p>List items (and wrappers like <code>&lt;div dataProvider=&quot;…&quot;&gt;</code>) set which branch the child reads. Pattern from the tutorial:</p>
+<pre><code class="language-typescript">export const rowKey = new DataProviderKey&amp;lt;
+  User,
+  { dataProvider: string | null }
+&amp;gt;(&quot;${dataProvider}&quot;);
+@ancestorAttribute(&quot;dataProvider&quot;)
+dataProvider: string | null = null;
+@subscribe(rowKey)
+@state()
+user: User | null = null;
+</code></pre>
+<h2 id="demo">Demo</h2>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-subscribe-dynamic&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-subscribe-dynamic&gt;&lt;/demo-subscribe-dynamic&gt;
+</code></pre>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="../_core-concept/dataFlow.html#dataFlow">Data flow</a> — overview</li>
+<li><a href="../_misc/dataProviderKey.html#dataProviderKey">DataProviderKey</a> — paths and host generics</li>
+<li><a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a> — <code>${prop}</code> resolution and <code>skipEmptyPlaceholder</code></li>
+<li><a href="../_directives/sub.html#sub">sub()</a> — same paths inside <code>html</code> templates</li>
+</ul>
+    </article>
+  </main>
+</body>
+</html>

package/docs/crawl/docs/_decorators/wait-for-ancestors.html ADDED Viewed

@@ -0,0 +1,137 @@
+<!DOCTYPE html>
+<html lang="fr" data-crawl-url="https://concorde.supersoniks.org/crawl/docs/_decorators/wait-for-ancestors.html" data-doc-id="docs/_decorators/wait-for-ancestors">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>@awaitConnectedAncestors and @dispatchConnectedEvent — Concorde</title>
+  <meta name="description" content="The @awaitConnectedAncestors and @dispatchConnectedEvent decorators delay a web component's initialization until its matching ancestors have executed their connectedCallback. This is when contextual e">
+  <meta name="keywords" content="Concorde, supersoniks, docs/_decorators/wait-for-ancestors, wait-for-ancestors, @awaitConnectedAncestors and @dispatchConnectedEvent, decorator, awaitConnectedAncestors and @dispatchConnectedEvent, @awaitConnectedAncestors, @dispatchConnectedEvent, connectedCallback, sonic-connected, @dispatchConnectedEvent()">
+  <meta name="concorde-doc-id" content="docs/_decorators/wait-for-ancestors">
+  <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_decorators/wait-for-ancestors.html">
+</head>
+<body>
+  <header>
+    <p><a href="../../index.html">Concorde documentation (crawl)</a> · <a href="https://concorde.supersoniks.org/#docs/_decorators/wait-for-ancestors.md/wait-for-ancestors" rel="nofollow">interactive version</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @awaitConnectedAncestors and @dispatchConnectedEvent</strong>. The @awaitConnectedAncestors and @dispatchConnectedEvent decorators delay a web component's initialization until its matching ancestors have executed their connectedCallback. This is when contextual e <span>Doc ID: <code>docs/_decorators/wait-for-ancestors</code>. Keywords: Concorde, supersoniks, docs/_decorators/wait-for-ancestors, wait-for-ancestors, @awaitConnectedAncestors and @dispatchConnectedEvent, decorator, awaitConnectedAncestors and @dispatchConnectedEvent, @awaitConnectedAncestors, @dispatchConnectedEvent, connectedCallback, sonic-connected, @dispatchConnectedEvent(). URL: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/wait-for-ancestors.html">https://concorde.supersoniks.org/crawl/docs/_decorators/wait-for-ancestors.html</a>.</span></p>
+      <h1 id="awaitconnectedancestors-and-dispatchconnectedevent">@awaitConnectedAncestors and @dispatchConnectedEvent</h1>
+<p>The <code>@awaitConnectedAncestors</code> and <code>@dispatchConnectedEvent</code> decorators delay a web component&#39;s initialization until its matching ancestors have executed their <code>connectedCallback</code>. This is when contextual elements (publisher, dataProvider, etc.) are configured.</p>
+<h2 id="principle">Principle</h2>
+<p>When a child component attaches to the DOM, its ancestors may not yet be initialized (especially if custom element definitions are loaded asynchronously). The <code>@awaitConnectedAncestors</code> decorator delays the component&#39;s <code>connectedCallback</code> until all ancestors matching the provided CSS selectors have executed their <code>connectedCallback</code>.</p>
+<p>The <code>@dispatchConnectedEvent</code> decorator allows ancestors to signal they are ready by dispatching the <code>sonic-connected</code> event at the end of their <code>connectedCallback</code>. The event bubbles, so it can be listened to from anywhere (e.g. <code>document.addEventListener(CONNECTED, handler)</code>).</p>
+<p>Ancestors that are not web components (no hyphen in tag name) are considered connected by default and do not need to emit the event.</p>
+<h2 id="usage">Usage</h2>
+<h3 id="import">Import</h3>
+<pre><code class="language-typescript">import { awaitConnectedAncestors, dispatchConnectedEvent, ancestorAttribute } from &quot;@supersoniks/concorde/decorators&quot;;
+</code></pre>
+<h3 id="basic-example">Basic example</h3>
+<p>An ancestor container decorated with <code>@dispatchConnectedEvent()</code> signals when it is ready. A child component decorated with <code>@awaitConnectedAncestors(&quot;demo-wait-ancestor-container[dataProvider]&quot;)</code> waits for this container to be initialized before initializing itself. Parameters are CSS selectors (<code>element.matches()</code>).</p>
+<p>The parent is registered via <code>customElements.define()</code> (vanilla JS) rather than <code>@customElement</code>, so it can be defined later—e.g. when the user clicks a button. This demonstrates the child waiting until the parent exists.</p>
+<pre><code class="language-typescript">import { html, LitElement } from &quot;lit&quot;;
+import { customElement, state } from &quot;lit/decorators.js&quot;;
+// Parent: registered later via customElements.define(), not @customElement
+@dispatchConnectedEvent()
+export class DemoWaitAncestorContainer extends LitElement {
+  render() {
+    return html`&lt;slot&gt;&lt;/slot&gt;`;
+  }
+}
+// Child: waits for parent before initializing
+@customElement(&quot;demo-wait-ancestor-value&quot;)
+@awaitConnectedAncestors(&quot;demo-wait-ancestor-container[dataProvider]&quot;)
+export class DemoWaitAncestorValue extends LitElement {
+  @ancestorAttribute(&quot;dataProvider&quot;)
+  dataProvider: string | null = null;
+  @state() initializedAt: string = &quot;&quot;;
+  connectedCallback() {
+    super.connectedCallback();
+    this.initializedAt = new Date().toISOString();
+  }
+  render() {
+    return html`
+      &lt;p&gt;DataProvider from ancestor: &lt;strong&gt;${this.dataProvider || &quot;—&quot;}&lt;/strong&gt;&lt;/p&gt;
+      &lt;p&gt;Initialized at: ${this.initializedAt || &quot;(waiting for parent…)&quot;}&lt;/p&gt;
+    `;
+  }
+}
+// Demo section: register parent via customElements.define() when user clicks
+@customElement(&quot;demo-wait-ancestors-section&quot;)
+export class DemoWaitAncestorsSection extends LitElement {
+  registerParent() {
+    if (!customElements.get(&quot;demo-wait-ancestor-container&quot;)) {
+      customElements.define(&quot;demo-wait-ancestor-container&quot;, DemoWaitAncestorContainer);
+    }
+  }
+  render() {
+    return html`
+      &lt;sonic-button @click=${this.registerParent}&gt;Register parent component&lt;/sonic-button&gt;
+      &lt;demo-wait-ancestor-container dataProvider=&quot;waitAncestorDemo&quot;&gt;
+        &lt;demo-wait-ancestor-value&gt;&lt;/demo-wait-ancestor-value&gt;
+      &lt;/demo-wait-ancestor-container&gt;
+    `;
+  }
+}
+</code></pre>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-wait-ancestors-section&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-wait-ancestors-section&gt;&lt;/demo-wait-ancestors-section&gt;
+</code></pre>
+<h3 id="multiple-ancestors">Multiple ancestors</h3>
+<p>The child waits for all specified ancestors. Register outer first, then inner — the child initializes only when both are ready.</p>
+<pre><code>&lt;demo-wait-ancestors-multi-section&gt;&lt;/demo-wait-ancestors-multi-section&gt;
+</code></pre>
+<h3 id="ancestors-already-connected">Ancestors already connected</h3>
+<p>When the parent is defined at load and already in the DOM, the child initializes immediately (no delay).</p>
+<p><strong>Static (both in DOM from start):</strong></p>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-wait-ancestors-static-section&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-wait-ancestors-static-section&gt;&lt;/demo-wait-ancestors-static-section&gt;
+</code></pre>
+<p><strong>Dynamic (child added on button click):</strong></p>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-wait-ancestors-ready-section&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-wait-ancestors-ready-section&gt;&lt;/demo-wait-ancestors-ready-section&gt;
+</code></pre>
+<h2 id="css-selector-support">CSS selector support</h2>
+<p>Parameters are CSS selectors matched via <code>element.matches()</code> — e.g. <code>&quot;sonic-subscriber&quot;</code>, <code>&quot;sonic-subscriber[dataProvider]&quot;</code>, <code>&quot;.my-container&quot;</code>, or multiple: <code>&quot;sonic-subscriber&quot;, &quot;sonic-sdui&quot;</code>.</p>
+<h2 id="behavior">Behavior</h2>
+<ul>
+<li>Ancestor search uses CSS selectors (<code>element.matches(selector)</code>) — supports tag names, classes, attributes, combinators, etc.</li>
+<li>Traversal includes shadow roots (parentNode / host)</li>
+<li>Non-web components (no hyphen in tag name) are considered connected by default</li>
+<li>For web component ancestors, it waits for <code>customElements.whenDefined(tagName)</code> and the <code>sonic-connected</code> event (or a timeout as fallback)</li>
+<li>If no matching ancestor is found, the original <code>connectedCallback</code> is called immediately</li>
+<li>Ancestors that do not emit <code>sonic-connected</code> trigger the fallback after the timeout (compatibility with existing components)</li>
+</ul>
+<h2 id="use-cases">Use cases</h2>
+<p>These decorators are particularly useful for:</p>
+<ul>
+<li><strong>sonic-value</strong> inside a <strong>sonic-subscriber</strong>: the value waits for the subscriber to configure its publisher</li>
+<li><strong>Components inside sonic-sdui</strong>: wait for the SDUI to load and configure its context</li>
+<li><strong>Any component</strong> depending on context provided by an ancestor custom element</li>
+</ul>
+<h2 id="listening-to-the-connected-event">Listening to the connected event</h2>
+<p>The <code>sonic-connected</code> event bubbles, so you can listen to it from anywhere:</p>
+<pre><code class="language-typescript">import { CONNECTED } from &quot;@supersoniks/concorde/decorators&quot;;
+someConnectable.addEventListener(CONNECTED, (e) =&gt; {
+  console.log(&quot;Component connected:&quot;, e.target);
+});
+</code></pre>
+<h2 id="notes">Notes</h2>
+<ul>
+<li>These decorators apply only to web components (classes extending <code>HTMLElement</code>)</li>
+<li>The fallback timeout ensures compatibility with components that do not yet use <code>@dispatchConnectedEvent</code></li>
+<li>Traversal includes shadow roots</li>
+<li>For a guarantee without relying on the timeout, decorate ancestors (Subscriber, Fetcher, etc.) with <code>@dispatchConnectedEvent</code></li>
+</ul>
+    </article>
+  </main>
+</body>
+</html>

package/docs/crawl/docs/_directives/sub.html ADDED Viewed

@@ -0,0 +1,93 @@
+<!DOCTYPE html>
+<html lang="fr" data-crawl-url="https://concorde.supersoniks.org/crawl/docs/_directives/sub.html" data-doc-id="docs/_directives/sub">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>sub() — Concorde</title>
+  <meta name="description" content="Read-only Lit directive: displays the current DataProvider value and updates whenever it is assigned.">
+  <meta name="keywords" content="Concorde, supersoniks, docs/_directives/sub, sub, sub(), directive, ${prop}, @subscribe, null, &quot;&quot;, skipEmptyPlaceholder, ${…}, get, set">
+  <meta name="concorde-doc-id" content="docs/_directives/sub">
+  <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_directives/sub.html">
+</head>
+<body>
+  <header>
+    <p><a href="../../index.html">Concorde documentation (crawl)</a> · <a href="https://concorde.supersoniks.org/#docs/_directives/sub.md/sub" rel="nofollow">interactive version</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde directive — sub()</strong>. Read-only Lit directive: displays the current DataProvider value and updates whenever it is assigned. <span>Doc ID: <code>docs/_directives/sub</code>. Keywords: Concorde, supersoniks, docs/_directives/sub, sub, sub(), directive, ${prop}, @subscribe, null, &quot;&quot;, skipEmptyPlaceholder, ${…}, get, set. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_directives/sub.html">https://concorde.supersoniks.org/crawl/docs/_directives/sub.html</a>.</span></p>
+      <h1 id="sub">sub()</h1>
+<p>Read-only Lit directive: displays the current <strong>DataProvider</strong> value and updates whenever it is assigned.</p>
+<h2 id="import">Import</h2>
+<pre><code class="language-typescript">import { sub } from &quot;@supersoniks/concorde/directives&quot;;
+</code></pre>
+<h2 id="string-path">String path</h2>
+<pre><code class="language-typescript">render() {
+  return html`&amp;lt;p&amp;gt;Count: ${sub(&quot;myCounter.count&quot;)}&amp;lt;/p&amp;gt;`;
+}
+</code></pre>
+<h2 id="dataproviderkey-static">DataProviderKey (static)</h2>
+<pre><code class="language-typescript">import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { sub } from &quot;@supersoniks/concorde/directives&quot;;
+const counterKey = new DataProviderKey&amp;lt;{ count: number }&amp;gt;(&quot;myCounter&quot;);
+render() {
+  return html`&amp;lt;p&amp;gt;${sub(counterKey.count)}&amp;lt;/p&amp;gt;`;
+}
+</code></pre>
+<h2 id="dynamic-dataproviderkey-prop">Dynamic DataProviderKey (<code>${prop}</code>)</h2>
+<p>Like <code>@subscribe</code>: the path is resolved on the template <strong>host component</strong>; the directive re-subscribes when observed props change. Placeholder values (<code>null</code>, <code>&quot;&quot;</code>, <code>0</code>, …): <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a> (<code>skipEmptyPlaceholder</code> not available on <code>sub()</code> yet).</p>
+<pre><code class="language-typescript">import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { sub } from &quot;@supersoniks/concorde/directives&quot;;
+type User = { firstName: string; lastName: string; email: string };
+const userKey = new DataProviderKey&amp;lt;User, { userIndex: number }&amp;gt;(
+  &quot;demoUsers.${userIndex}&quot;,
+);
+@customElement(&quot;demo-sub-dynamic&quot;)
+export class DemoSubDynamic extends LitElement {
+  @property({ type: Number }) userIndex = 0;
+  render() {
+    return html`
+      &amp;lt;p&amp;gt;${sub(userKey.email)}&amp;lt;/p&amp;gt;
+    `;
+  }
+}
+</code></pre>
+<h2 id="demo">Demo</h2>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-sub-template&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-sub-template&gt;&lt;/demo-sub-template&gt;
+</code></pre>
+<h2 id="concatenation-forms">Concatenation (forms)</h2>
+<pre><code class="language-typescript">html`&amp;lt;span&amp;gt;${sub(this.formDataProvider + &quot;.email&quot;)}&amp;lt;/span&amp;gt;`
+</code></pre>
+<h2 id="sub-vs-get--set--dp">sub() vs get() / set() / dp()</h2>
+<table>
+<thead>
+<tr>
+<th>API</th>
+<th>Context</th>
+<th>Dynamic <code>${…}</code></th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>sub()</code></td>
+<td>Lit template, reactive</td>
+<td>Yes</td>
+</tr>
+<tr>
+<td><code>get</code> / <code>set</code> / <code>dp</code></td>
+<td>Imperative code</td>
+<td>No</td>
+</tr>
+</tbody></table>
+<p>Do not replace <code>sub(path)</code> with <code>get(path)</code> in a template: <code>get</code> returns a one-time snapshot.</p>
+<p>See <a href="../_misc/dataProviderKey.html#dataProviderKey">DataProviderKey</a>, <a href="../_decorators/subscribe.html#subscribe">@subscribe</a>, and the <code>concorde-get-set-dp</code> migration skill.</p>
+    </article>
+  </main>
+</body>
+</html>

package/docs/crawl/docs/_getting-started/ai-agents.html ADDED Viewed

@@ -0,0 +1,134 @@
+<!DOCTYPE html>
+<html lang="fr" data-crawl-url="https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html" data-doc-id="docs/_getting-started/ai-agents">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>AI agents (skills &amp; AGENTS.md) — Concorde</title>
+  <meta name="description" content="Concorde ships skills, rules, and a root AGENTS.md so Cursor, JetBrains AI Assistant, and other coding agents follow framework patterns (DataProvider, decorators, short imports, scope, theme, migratio">
+  <meta name="keywords" content="Concorde, supersoniks, docs/_getting-started/ai-agents, ai-agents, AI agents (skills &amp; AGENTS.md), guide, AGENTS.md, yarn ai:sync, ai-init, yarn add @supersoniks/concorde,  |
+| Concorde repo (contributors) | , --merge-agents, --overlay , --cursor-only">
+  <meta name="concorde-doc-id" content="docs/_getting-started/ai-agents">
+  <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html">
+</head>
+<body>
+  <header>
+    <p><a href="../../index.html">Concorde documentation (crawl)</a> · <a href="https://concorde.supersoniks.org/#docs/_getting-started/ai-agents.md/ai-agents" rel="nofollow">interactive version</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — AI agents (skills &amp; AGENTS.md)</strong>. Concorde ships skills, rules, and a root AGENTS.md so Cursor, JetBrains AI Assistant, and other coding agents follow framework patterns (DataProvider, decorators, short imports, scope, theme, migratio <span>Doc ID: <code>docs/_getting-started/ai-agents</code>. Keywords: Concorde, supersoniks, docs/_getting-started/ai-agents, ai-agents, AI agents (skills &amp; AGENTS.md), guide, AGENTS.md, yarn ai:sync, ai-init, yarn add @supersoniks/concorde,  |
+| Concorde repo (contributors) | , --merge-agents, --overlay , --cursor-only. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html">https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html</a>.</span></p>
+      <h1 id="ai-agents-skills--agentsmd">AI agents (skills &amp; AGENTS.md)</h1>
+<p>Concorde ships <strong>skills</strong>, <strong>rules</strong>, and a root <strong><code>AGENTS.md</code></strong> so Cursor, JetBrains AI Assistant, and other coding agents follow framework patterns (DataProvider, decorators, short imports, scope, theme, migrations).</p>
+<p>On a <a href="./concorde-outside.html#concorde-outside">starter</a> project, run <code>yarn ai:sync</code> after install. On a <a href="./concorde-manual-install.html#concorde-manual-install">manual / brownfield</a> project, install Concorde first, then use <code>ai-init</code> below.</p>
+<h2 id="dedicated-commands">Dedicated commands</h2>
+<table>
+<thead>
+<tr>
+<th>Context</th>
+<th>Command</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><a href="https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter">create-concorde-ts-starter</a> project</td>
+<td><code>yarn ai:sync</code></td>
+</tr>
+<tr>
+<td>Any consumer app (after <code>yarn add @supersoniks/concorde</code>)</td>
+<td><code>node node_modules/@supersoniks/concorde/scripts/ai-init.mjs</code></td>
+</tr>
+<tr>
+<td>Concorde repo (contributors)</td>
+<td><code>yarn ai-init</code></td>
+</tr>
+</tbody></table>
+<pre><code class="language-shell"># Starter (from project root)
+yarn ai:sync
+# Manual / existing project
+node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
+</code></pre>
+<h2 id="useful-flags">Useful flags</h2>
+<table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Effect</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>--merge-agents</code></td>
+<td>Append to an existing <code>AGENTS.md</code> instead of replacing it</td>
+</tr>
+<tr>
+<td><code>--overlay &lt;dir&gt;</code></td>
+<td>Copy extra rules/skills from another layer (e.g. starter kit)</td>
+</tr>
+<tr>
+<td><code>--cursor-only</code></td>
+<td>Install only <code>.cursor/skills</code> and <code>.cursor/rules</code></td>
+</tr>
+<tr>
+<td><code>--jetbrains-only</code></td>
+<td>Install only <code>.aiassistant/rules/</code></td>
+</tr>
+</tbody></table>
+<h2 id="what-gets-installed">What gets installed</h2>
+<table>
+<thead>
+<tr>
+<th>Path</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>AGENTS.md</code></td>
+<td>Project-level guide for agents (Concorde conventions)</td>
+</tr>
+<tr>
+<td><code>.cursor/skills/concorde/</code></td>
+<td>Core Lit + DataProvider patterns</td>
+</tr>
+<tr>
+<td><code>.cursor/skills/concorde-imports/</code></td>
+<td>Short <code>@supersoniks/concorde/…</code> import paths</td>
+</tr>
+<tr>
+<td><code>.cursor/skills/concorde-scope/</code></td>
+<td><code>serviceURL</code>, <code>formDataProvider</code>, API configuration</td>
+</tr>
+<tr>
+<td><code>.cursor/skills/concorde-theme/</code></td>
+<td><code>sonic-theme</code> and <code>--sc-*</code> tokens</td>
+</tr>
+<tr>
+<td><code>.cursor/skills/concorde-menu/</code></td>
+<td><code>sonic-menu</code> navigation</td>
+</tr>
+<tr>
+<td><code>.cursor/skills/concorde-get-set-dp/</code></td>
+<td><code>get</code> / <code>set</code> / <code>dp</code> and <code>DataProviderKey</code> migration</td>
+</tr>
+<tr>
+<td><code>.cursor/rules/concorde.mdc</code></td>
+<td>Cursor rules (always-on patterns)</td>
+</tr>
+<tr>
+<td><code>.aiassistant/rules/concorde.md</code></td>
+<td>JetBrains AI Assistant rules</td>
+</tr>
+</tbody></table>
+<h2 id="workflow">Workflow</h2>
+<ol>
+<li><strong>Starter project:</strong> <a href="./concorde-outside.html#concorde-outside">Installation</a> — <code>yarn ai:sync</code> is wired in the kit.</li>
+<li><strong>Existing / manual Vite project:</strong> <a href="./concorde-manual-install.html#concorde-manual-install">Manual installation</a>, then <strong><code>ai-init</code></strong> after <code>yarn add @supersoniks/concorde</code>.</li>
+<li>Commit <code>AGENTS.md</code>, <code>.cursor/</code>, and <code>.aiassistant/</code> if your team shares agent settings.</li>
+<li>Re-run the same command when you bump <code>@supersoniks/concorde</code> to refresh skills from <code>node_modules/@supersoniks/concorde/ai/</code>.</li>
+<li>In Cursor, skills under <code>.cursor/skills/</code> are picked up automatically; mention a skill in chat for focused tasks (e.g. migration → <code>concorde-get-set-dp</code>).</li>
+</ol>
+<p>Source files in the npm package: <code>node_modules/@supersoniks/concorde/ai/</code> (see also <code>ai/README.md</code> in the <a href="https://github.com/supersoniks/concorde">Concorde repository</a>).</p>
+    </article>
+  </main>
+</body>
+</html>

package/docs/crawl/docs/_getting-started/concorde-manual-install.html ADDED Viewed

@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html lang="fr" data-crawl-url="https://concorde.supersoniks.org/crawl/docs/_getting-started/concorde-manual-install.html" data-doc-id="docs/_getting-started/concorde-manual-install">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Manual installation (Vite) — Concorde</title>
+  <meta name="description" content="&gt; Legacy — for brownfield apps or custom stacks. New projects should use the starter.">
+  <meta name="keywords" content="Concorde, supersoniks, docs/_getting-started/concorde-manual-install, concorde-manual-install, Manual installation (Vite), guide, tsconfig.json, AGENTS.md, --host,  becomes ,
+* , main.ts, my-element.ts">
+  <meta name="concorde-doc-id" content="docs/_getting-started/concorde-manual-install">
+  <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_getting-started/concorde-manual-install.html">
+</head>
+<body>
+  <header>
+    <p><a href="../../index.html">Concorde documentation (crawl)</a> · <a href="https://concorde.supersoniks.org/#docs/_getting-started/concorde-manual-install.md/concorde-manual-install" rel="nofollow">interactive version</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — Manual installation (Vite)</strong>. &gt; Legacy — for brownfield apps or custom stacks. New projects should use the starter. <span>Doc ID: <code>docs/_getting-started/concorde-manual-install</code>. Keywords: Concorde, supersoniks, docs/_getting-started/concorde-manual-install, concorde-manual-install, Manual installation (Vite), guide, tsconfig.json, AGENTS.md, --host,  becomes ,
+* , main.ts, my-element.ts. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_getting-started/concorde-manual-install.html">https://concorde.supersoniks.org/crawl/docs/_getting-started/concorde-manual-install.html</a>.</span></p>
+      <h1 id="manual-installation-vite">Manual installation (Vite)</h1>
+<blockquote>
+<p><strong>Legacy</strong> — for brownfield apps or custom stacks. New projects should use the <a href="./concorde-outside.html#concorde-outside">starter</a>.</p>
+</blockquote>
+<h2 id="brand-new-vite-project">Brand New Vite Project</h2>
+<p>Tailwind configuration is not covered here yet.</p>
+<h3 id="creating-the-project">Creating the Project</h3>
+<pre><code class="language-shell"># Pure JavaScript project
+yarn create vite --template vanilla-js
+# TypeScript project
+# (it is recommended to use this approach, which installs Lit separately if needed, via &quot;yarn add lit&quot;)
+yarn create vite --template vanilla-ts
+# TypeScript + Lit project
+# (creating new web components, for example, to extend the fetch or subscriber mixins)
+yarn create vite --template lit-ts
+</code></pre>
+<p>Using Lit with TypeScript requires the following configuration in the &quot;compilerOptions&quot; section of the <code>tsconfig.json</code> file:</p>
+<pre><code class="language-json">&quot;experimentalDecorators&quot;: true,
+&quot;useDefineForClassFields&quot;: false
+</code></pre>
+<h3 id="installing-concorde">Installing Concorde</h3>
+<p>Navigate to the project folder created and perform the installation:</p>
+<pre><code class="language-shell">yarn add @supersoniks/concorde
+</code></pre>
+<p>Agent skills (<code>AGENTS.md</code>, Cursor / JetBrains): see <a href="./ai-agents.html#ai-agents">AI agents</a> — run <code>node node_modules/@supersoniks/concorde/scripts/ai-init.mjs</code> after install.</p>
+<h3 id="development--build">Development / Build</h3>
+<pre><code class="language-shell"># Development (you can add `--host` after the command chain in package.json&#39;s dev script instead of typing it each time as shown below)
+yarn dev --host
+# Build
+yarn build
+</code></pre>
+<h2 id="shortcut-imports">Shortcut Imports</h2>
+<p>Shortcut imports work by default in JavaScript, but in TypeScript, they are activated by choice as they inject data into <em>tsconfig.json</em>. Here is the command:</p>
+<pre><code class="language-shell">npx concorde enable-short-paths
+</code></pre>
+<p>Shortcut imports replace the actual paths with aliases as follows:</p>
+<ul>
+<li><code>@supersoniks/concorde/core/components/functional_or_ui/component/component</code> becomes <code>@supersoniks/concorde/functional_or_ui/component</code></li>
+<li><code>@supersoniks/concorde/core/mixins_or_utils/class_name</code> becomes <code>@supersoniks/concorde/mixins_or_utils/class_name</code></li>
+</ul>
+<p>The original paths remain accessible. Shortcut imports are used for the examples later in this documentation.</p>
+<h2 id="usage">Usage</h2>
+<h3 id="simple-integration-in-html">Simple Integration in HTML</h3>
+<p>Import needed component in <code>main.ts</code> or wherever you want to use it:</p>
+<pre><code class="language-typescript">import &quot;@supersoniks/concorde/ui/button&quot;;
+</code></pre>
+<p>Then in the render function ofyour component or in the HTML of the web page that includes the compiled JS, use the component as follows:</p>
+<pre><code>&lt;sonic-button variant=&quot;outline&quot;&gt;My button&lt;/sonic-button&gt;
+</code></pre>
+<h3 id="using-a-mixin-to-create-a-new-lit-component">Using a Mixin to Create a New Lit Component</h3>
+<p>For example, create a file <code>my-element.ts</code> at the root:</p>
+<pre><code class="language-typescript">import { html, LitElement } from &quot;lit&quot;;
+import { customElement, property } from &quot;lit/decorators.js&quot;;
+import Fetcher from &quot;@supersoniks/concorde/mixins/Fetcher&quot;;
+import Subscriber from &quot;@supersoniks/concorde/mixins/Subscriber&quot;;
+@customElement(&quot;my-element&quot;)
+export class SonicComponent extends Fetcher(Subscriber(LitElement)) {
+  @property() email = &quot;&quot;;
+  @property() first_name = &quot;&quot;;
+  @property() last_name = &quot;&quot;;
+  render() {
+    return html`&lt;div&gt;
+      ${this.first_name} ${this.last_name} : ${this.email}
+    &lt;/div&gt;`;
+  }
+}
+</code></pre>
+<p>Import component <code>main.ts</code> or <code>main.js</code> or any other component that uses it to be compiled</p>
+<pre><code class="language-typescript">import &quot;./my-element&quot;;
+</code></pre>
+<p>In the HTML of a JS or TS component or in the HTML of the web page containing the compiled JS:</p>
+<pre><code class="language-html">&lt;my-element serviceURL=&quot;/docs-mock-api&quot; dataProvider=&quot;api/users/2&quot; key=&quot;data&quot;&gt;&lt;/my-element&gt;
+</code></pre>
+    </article>
+  </main>
+</body>
+</html>