@supersoniks/concorde 4.6.0 → 4.7.0

package/src/docs/_misc/html-integration.md

@@ -0,0 +1,13 @@
+# HTML integration (no Lit)
+
+Some hosts (legacy PHP pages, static HTML) embed Concorde components **without** a Lit build step. They can use HTML attributes such as **`data-bind`**, **`dataProvider`**, and **`formDataProvider`** on tags directly in the page.
+
+That style is **not** what we demonstrate in this doc site: live examples are **Lit components** under `src/docs/example/`, registered once and reused from Markdown via tags like `<docs-joke-search-demo>`.
+
+| Goal | Use |
+|------|-----|
+| Learn modern patterns | [My first component](#docs/_getting-started/my-first-component.md/my-first-component), [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) |
+| Author doc examples | `<docs-lit-demo>` + `src/docs/example/*.ts` — see [My first component](#docs/_getting-started/my-first-component.md/my-first-component) |
+| Embed in plain HTML only | `data-bind` / Subscriber docs in **Legacy** — [Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber) |
+
+New application code in TypeScript should use **`@subscribe`**, **`formDataProvider` + `name`**, and Lit templates — not HTML `data-bind`.

package/src/docs/code.ts

@@ -27,7 +27,7 @@ export class DocsCode extends LitElement {
     css`
       :host(:not([inline])) {
         display: block;
-        margin: 1rem 0;
+        margin: 1.1rem 0;
       }
 
       :host([inline]) {
@@ -84,6 +84,11 @@ export class DocsCode extends LitElement {
   //States
   @state() codeEdited = false;
 
+  /** Aperçu live uniquement pour les blocs markup (évite d’injecter du HTML depuis des exemples JS). */
+  private get rendersLiveOutput(): boolean {
+    return this.language === "markup" && !this.noOutput;
+  }
+
   // createRenderRoot() {
   //   return this;
   // }
@@ -95,10 +100,7 @@ export class DocsCode extends LitElement {
     }
 
     this.templateEl = this.querySelector("template");
-    this.defaultCode = this.templateEl?.innerHTML
-      .toString()
-      .replace(/&lt;/g, "<")
-      .replace(/&gt;/g, ">");
+    this.defaultCode = this.readTemplateSourceCode();
 
     if (this.defaultCode) {
       Prism.plugins.NormalizeWhitespace.setDefaults({
@@ -120,11 +122,40 @@ export class DocsCode extends LitElement {
       this.currentCode = Prism.highlight(
         normalizedCode,
         Prism.languages[this.language],
-        this.language
+        this.language,
       );
     }
 
-    this.codeOutput = this.defaultCode;
+    if (this.rendersLiveOutput) {
+      this.codeOutput = this.defaultCode;
+    } else {
+      this.removeOutputSlot();
+    }
+  }
+
+  private decodeTemplateEntities(html: string): string {
+    return html
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&amp;/g, "&");
+  }
+
+  /**
+   * Markup demos: serialized HTML for the live preview.
+   * TS/JS with Lit `html\`…\``: browser parses tags in &lt;template&gt; — use innerHTML
+   * when the fragment has elements; otherwise textContent (imports, types, etc.).
+   */
+  private readTemplateSourceCode(): string {
+    const template = this.templateEl;
+    if (!template) return "";
+
+    if (this.language === "markup") {
+      return this.decodeTemplateEntities(template.innerHTML);
+    }
+
+    // TS/JS/bash/json: never use innerHTML — the browser parses tags in <template>
+    // (e.g. <sonic-button> in Lit examples) and the source would be truncated.
+    return template.content.textContent ?? "";
   }
 
   updateCodeRender() {
@@ -143,11 +174,13 @@ export class DocsCode extends LitElement {
         this.currentCode = Prism.highlight(
           this.defaultCode || "",
           Prism.languages[this.language],
-          this.language
+          this.language,
         );
       });
     }
-    this.codeOutput = this.defaultCode;
+    if (this.rendersLiveOutput) {
+      this.codeOutput = this.defaultCode;
+    }
   }
 
   handleToggleCode() {
@@ -155,8 +188,9 @@ export class DocsCode extends LitElement {
   }
 
   handleCopyCode(e: Event) {
-    if (this.codeOutput) {
-      navigator.clipboard.writeText(this.codeOutput);
+    const text = this.codeOutput ?? this.defaultCode;
+    if (text) {
+      navigator.clipboard.writeText(text);
       const button = e.currentTarget as HTMLButtonElement;
       button?.setAttribute("active", "");
       setTimeout(() => {
@@ -167,12 +201,24 @@ export class DocsCode extends LitElement {
 
   updated(changedProperties: PropertyValues) {
     super.updated(changedProperties);
-    if (changedProperties.has("codeOutput")) {
+    if (
+      changedProperties.has("codeOutput") ||
+      changedProperties.has("language") ||
+      changedProperties.has("noOutput")
+    ) {
       this.appendOutput();
     }
   }
 
+  removeOutputSlot() {
+    this.querySelector("[slot=output]")?.remove();
+  }
+
   appendOutput() {
+    if (!this.rendersLiveOutput) {
+      this.removeOutputSlot();
+      return;
+    }
     let output = this.querySelector("[slot=output]") as HTMLElement;
     if (!output) {
       output = document.createElement("div");

package/src/docs/components/docs-demo-sources.ts

@@ -0,0 +1,397 @@
+import { html, LitElement, nothing } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { docsSourceLinks, type DocsSource } from "./docs-source-link";
+
+export type { DocsSource };
+
+/** Live demo + TypeScript excerpt shown by `<docs-lit-demo>` (one file, no Markdown copy). */
+export type DocsLitDemoConfig = {
+  sources: DocsSource[];
+  /** Optional manual excerpt (1-based); default is auto from `@customElement(liveTag)` */
+  excerptStart?: number;
+  excerptEnd?: number;
+  /** Defaults to registry key */
+  liveTag?: string;
+};
+
+export const DOCS_LIT_DEMO_REGISTRY: Record<string, DocsLitDemoConfig> = {
+  "docs-toggle-if-demo": {
+    sources: [
+      {
+        path: "src/docs/example/docs-toggle-demos.ts",
+        line: 18,
+        label: "docs-toggle-if-demo",
+      },
+    ],
+  },
+  "docs-toggle-loader-demo": {
+    sources: [
+      {
+        path: "src/docs/example/docs-toggle-demos.ts",
+        line: 49,
+        label: "docs-toggle-loader-demo",
+      },
+    ],
+  },
+  "docs-joke-search-demo": {
+    sources: [
+      { path: "src/docs/example/docs-joke-demos.ts", line: 111, label: "search" },
+    ],
+  },
+  "docs-joke-lang-demo": {
+    sources: [
+      { path: "src/docs/example/docs-joke-demos.ts", line: 136, label: "lang" },
+    ],
+  },
+  "docs-joke-blacklist-demo": {
+    sources: [
+      { path: "src/docs/example/docs-joke-demos.ts", line: 181, label: "blacklist" },
+    ],
+  },
+  "docs-joke-blacklist-radio-demo": {
+    sources: [
+      { path: "src/docs/example/docs-joke-demos.ts", line: 212, label: "radio" },
+    ],
+  },
+  "docs-joke-blacklist-switch-demo": {
+    sources: [
+      { path: "src/docs/example/docs-joke-demos.ts", line: 256, label: "switch" },
+    ],
+  },
+  "docs-queue-users-demo": {
+    sources: [
+      { path: "src/docs/example/docs-queue-demos.ts", line: 66, label: "users" },
+    ],
+  },
+  "docs-queue-geo-demo": {
+    sources: [
+      { path: "src/docs/example/docs-queue-demos.ts", line: 38, label: "geo" },
+    ],
+  },
+  "docs-users-list": {
+    sources: [
+      { path: "src/docs/example/docs-users-list.ts", line: 15, label: "docs-users-list" },
+    ],
+  },
+  "docs-list-alternate-demo": {
+    sources: [
+      { path: "src/docs/example/docs-list-demos.ts", line: 51, label: "alternate" },
+    ],
+  },
+  "docs-list-template-key-demo": {
+    sources: [
+      { path: "src/docs/example/docs-list-demos.ts", line: 79, label: "templateKey" },
+    ],
+  },
+  "docs-list-separator-demo": {
+    sources: [
+      { path: "src/docs/example/docs-list-demos.ts", line: 118, label: "separator" },
+    ],
+  },
+  "docs-list-extract-values-demo": {
+    sources: [
+      { path: "src/docs/example/docs-list-demos.ts", line: 146, label: "extractValues" },
+    ],
+  },
+  "docs-router-basic-demo": {
+    sources: [
+      { path: "src/docs/example/docs-router-demos.ts", line: 33, label: "basic" },
+    ],
+  },
+  "docs-router-params-demo": {
+    sources: [
+      { path: "src/docs/example/docs-router-demos.ts", line: 61, label: "params" },
+    ],
+  },
+  "docs-submit-demo": {
+    sources: [
+      { path: "src/docs/example/docs-submit-demos.ts", line: 86, label: "submit" },
+    ],
+  },
+  "docs-submit-native-demo": {
+    sources: [
+      { path: "src/docs/example/docs-submit-demos.ts", line: 307, label: "native" },
+    ],
+  },
+  "docs-submit-formdata-demo": {
+    sources: [
+      { path: "src/docs/example/docs-submit-demos.ts", line: 231, label: "formdata" },
+    ],
+  },
+  "docs-submit-result-key-demo": {
+    sources: [
+      { path: "src/docs/example/docs-submit-demos.ts", line: 184, label: "result-key" },
+    ],
+  },
+  "docs-submit-clear-demo": {
+    sources: [
+      { path: "src/docs/example/docs-submit-demos.ts", line: 144, label: "clear" },
+    ],
+  },
+  "docs-submit-event-demo": {
+    sources: [
+      { path: "src/docs/example/docs-submit-demos.ts", line: 357, label: "event" },
+    ],
+  },
+  "docs-submit-endpoint-demo": {
+    sources: [
+      { path: "src/docs/example/docs-submit-demos.ts", line: 407, label: "endpoint" },
+    ],
+  },
+  "docs-submit-get-demo": {
+    sources: [
+      { path: "src/docs/example/docs-submit-demos.ts", line: 276, label: "get" },
+    ],
+  },
+  "docs-api-config-bearer-demo": {
+    sources: [
+      { path: "src/docs/example/docs-api-config-demos.ts", line: 63, label: "bearer" },
+    ],
+  },
+  "docs-api-config-token-provider-demo": {
+    sources: [
+      {
+        path: "src/docs/example/docs-api-config-demos.ts",
+        line: 83,
+        label: "tokenProvider",
+      },
+    ],
+  },
+  "docs-api-config-stale-token-demo": {
+    sources: [
+      { path: "src/docs/example/docs-api-config-demos.ts", line: 104, label: "498" },
+    ],
+  },
+  "docs-api-config-wording-demo": {
+    sources: [
+      { path: "src/docs/example/docs-api-config-demos.ts", line: 132, label: "wording" },
+    ],
+  },
+  "docs-api-config-scoped-attrs-demo": {
+    sources: [
+      { path: "src/docs/example/docs-api-config-demos.ts", line: 162, label: "scope" },
+    ],
+  },
+  "docs-api-config-events-token-demo": {
+    sources: [
+      {
+        path: "src/docs/example/docs-api-config-demos.ts",
+        line: 191,
+        label: "eventsApiToken",
+      },
+    ],
+  },
+};
+
+/** Live demo tag → useful source files (not inline sonic-code samples). */
+export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
+  "docs-user": [
+    { path: "src/docs/example/users.ts", label: "docs-user" },
+  ],
+  "docs-user-two-scopes": [
+    { path: "src/docs/example/docs-user-two-scopes.ts", label: "two scopes" },
+    { path: "src/docs/example/users.ts", label: "docs-user" },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "docs-joke-search-demo": [
+    { path: "src/docs/example/docs-joke-demos.ts", label: "joke demos" },
+  ],
+  "docs-joke-lang-demo": [
+    { path: "src/docs/example/docs-joke-demos.ts", label: "joke demos" },
+  ],
+  "docs-queue-geo-demo": [
+    { path: "src/docs/example/docs-queue-demos.ts", label: "queue demos" },
+  ],
+  "docs-queue-users-demo": [
+    { path: "src/docs/example/docs-queue-demos.ts", label: "queue demos" },
+  ],
+  "docs-toggle-if-demo": [
+    { path: "src/docs/example/docs-toggle-demos.ts", label: "toggle demos" },
+  ],
+  "docs-toggle-loader-demo": [
+    { path: "src/docs/example/docs-toggle-demos.ts", label: "toggle demos" },
+  ],
+  "demo-publish": [
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 29,
+      label: "demo-publish",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-subscribe-dynamic": [
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 313,
+      label: "demo-subscribe-dynamic",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-sub-template": [
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 282,
+      label: "demo-sub-template",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-api-get": [
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 83,
+      label: "demo-api-get",
+    },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+    { path: "src/docs/mock-api/router.ts", label: "mock router" },
+  ],
+  "demo-api-get-configuration-key": [
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 126,
+      label: "demo-api-get-configuration-key",
+    },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+  ],
+  "demo-api-get-publish-subscribe": [
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 227,
+      label: "demo-api-get-publish-subscribe",
+    },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+  ],
+  "demo-handle": [
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 360,
+      label: "demo-handle",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-handle-dynamic": [
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 396,
+      label: "demo-handle-dynamic",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-bind": [
+    { path: "src/docs/example/decorators-demo-bind-demos.ts", line: 14, label: "demo-bind" },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-bind-reflect": [
+    {
+      path: "src/docs/example/decorators-demo-bind-demos.ts",
+      line: 56,
+      label: "demo-bind-reflect",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-bind-dynamic": [
+    {
+      path: "src/docs/example/decorators-demo-bind-demos.ts",
+      line: 124,
+      label: "demo-bind-dynamic",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-ancestor-attribute": [
+    { path: "src/docs/example/decorators-demo.ts", line: 19, label: "demo-ancestor-attribute" },
+  ],
+  "demo-on-assign": [
+    { path: "src/docs/example/decorators-demo.ts", line: 43, label: "demo-on-assign" },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-on-assign-dynamic": [
+    {
+      path: "src/docs/example/decorators-demo.ts",
+      line: 94,
+      label: "demo-on-assign-dynamic",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-auto-subscribe": [
+    { path: "src/docs/example/decorators-demo.ts", line: 211, label: "demo-auto-subscribe" },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-wait-ancestors-section": [
+    {
+      path: "src/docs/example/decorators-demo.ts",
+      line: 278,
+      label: "demo-wait-ancestors-section",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-wait-ancestors-multi-section": [
+    {
+      path: "src/docs/example/decorators-demo.ts",
+      line: 355,
+      label: "demo-wait-ancestors-multi-section",
+    },
+    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+  ],
+  "demo-wait-ancestors-static-section": [
+    {
+      path: "src/docs/example/decorators-demo.ts",
+      line: 462,
+      label: "demo-wait-ancestors-static-section",
+    },
+  ],
+  "demo-wait-ancestors-ready-section": [
+    {
+      path: "src/docs/example/decorators-demo.ts",
+      line: 432,
+      label: "demo-wait-ancestors-ready-section",
+    },
+  ],
+  "sonic-queue-demo": [
+    { path: "src/core/components/functional/queue/queue.demo.ts", label: "sonic-queue-demo" },
+    { path: "src/docs/mock-api/router.ts", label: "mock router" },
+  ],
+  "sonic-list-demo": [
+    { path: "src/core/components/functional/list/list.demo.ts", label: "sonic-list-demo" },
+    { path: "src/docs/mock-api/router.ts", label: "mock router" },
+  ],
+  "queue-users-scroll": [
+    { path: "src/docs/example/docs-queue-demos.ts", label: "docs-queue-users-demo" },
+    { path: "src/docs/example/users.ts", label: "docs-user" },
+  ],
+  /** Inline list.md fetch demo — component + mock. */
+  "list-users-fetch": [
+    { path: "src/docs/example/docs-users-list.ts", label: "docs-users-list" },
+    { path: "src/docs/mock-api/router.ts", label: "mock API" },
+  ],
+  "docs-submit-demo": [
+    { path: "src/docs/example/docs-submit-demos.ts", label: "submit demo" },
+    { path: "src/docs/mock-api/router.ts", label: "mock API (POST register)" },
+  ],
+  "docs-api-config-bearer-demo": [
+    { path: "src/docs/example/docs-api-config-demos.ts", label: "API config demos" },
+    { path: "src/docs/mock-api/api-config-mock.ts", label: "mock routes" },
+  ],
+  "docs-api-config-token-provider-demo": [
+    { path: "src/docs/example/docs-api-config-demos.ts", label: "API config demos" },
+    { path: "src/docs/mock-api/api-config-mock.ts", label: "mock routes" },
+  ],
+  "docs-api-config-stale-token-demo": [
+    { path: "src/docs/example/docs-api-config-demos.ts", label: "API config demos" },
+    { path: "src/docs/mock-api/api-config-mock.ts", label: "mock routes" },
+  ],
+  "docs-api-config-wording-demo": [
+    { path: "src/docs/example/docs-api-config-demos.ts", label: "API config demos" },
+    { path: "src/docs/mock-api/api-config-mock.ts", label: "mock routes" },
+  ],
+};
+
+@customElement("docs-demo-sources")
+export class DocsDemoSources extends LitElement {
+  /** Registry key matching the live demo custom element tag. */
+  @property({ attribute: "for" }) forTag = "";
+
+  render() {
+    const sources = DOCS_DEMO_SOURCE_REGISTRY[this.forTag];
+    if (!sources?.length) return nothing;
+    return docsSourceLinks(sources);
+  }
+}

package/src/docs/components/docs-lit-demo-raw.ts

@@ -0,0 +1,28 @@
+/**
+ * Raw sources for `<docs-lit-demo>` — explicit imports only (no import.meta.glob).
+ * Included in the **docs** bundle (`src/docs.ts`), not in the **core** library build (`src/index.ts`).
+ * Add one import + map entry when registering a new file in `DOCS_LIT_DEMO_REGISTRY`.
+ */
+import docsJokeDemos from "../example/docs-joke-demos.ts?raw";
+import docsListDemos from "../example/docs-list-demos.ts?raw";
+import docsQueueDemos from "../example/docs-queue-demos.ts?raw";
+import docsToggleDemos from "../example/docs-toggle-demos.ts?raw";
+import docsUserTwoScopes from "../example/docs-user-two-scopes.ts?raw";
+import docsRouterDemos from "../example/docs-router-demos.ts?raw";
+import docsSubmitDemos from "../example/docs-submit-demos.ts?raw";
+import docsApiConfigDemos from "../example/docs-api-config-demos.ts?raw";
+import docsUsersList from "../example/docs-users-list.ts?raw";
+import users from "../example/users.ts?raw";
+
+export const DOCS_LIT_DEMO_RAW: Record<string, string> = {
+  "src/docs/example/docs-toggle-demos.ts": docsToggleDemos,
+  "src/docs/example/docs-joke-demos.ts": docsJokeDemos,
+  "src/docs/example/docs-queue-demos.ts": docsQueueDemos,
+  "src/docs/example/docs-list-demos.ts": docsListDemos,
+  "src/docs/example/docs-router-demos.ts": docsRouterDemos,
+  "src/docs/example/docs-submit-demos.ts": docsSubmitDemos,
+  "src/docs/example/docs-api-config-demos.ts": docsApiConfigDemos,
+  "src/docs/example/docs-users-list.ts": docsUsersList,
+  "src/docs/example/docs-user-two-scopes.ts": docsUserTwoScopes,
+  "src/docs/example/users.ts": users,
+};