@supersoniks/concorde 4.6.0 → 4.7.3

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

@@ -0,0 +1,166 @@
+import { css, html, LitElement, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
+import { tailwind } from "../tailwind";
+import { docsSourceLinks } from "./docs-source-link";
+import {
+  DOCS_LIT_DEMO_REGISTRY,
+  type DocsLitDemoConfig,
+} from "./docs-demo-sources";
+
+import "../prism/prism";
+import { prismCSS } from "../prism";
+import * as Prism from "prismjs";
+import "prismjs/components/prism-typescript";
+
+import { DOCS_LIT_DEMO_RAW } from "./docs-lit-demo-raw";
+
+/** Class body for `liveTag`: from `@customElement("…")` through the line before the next `@customElement`. */
+export function excerptForCustomElement(
+  source: string,
+  liveTag: string,
+): string | null {
+  const lines = source.split("\n");
+  const needle = `@customElement("${liveTag}")`;
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(needle)) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return null;
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].includes("@customElement(")) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+function excerptLines(
+  source: string,
+  start?: number,
+  end?: number,
+): string {
+  const lines = source.split("\n");
+  if (!start && !end) return source;
+  const from = Math.max(1, start ?? 1) - 1;
+  const to = end ?? lines.length;
+  return lines.slice(from, to).join("\n");
+}
+
+function resolveDemoExcerpt(
+  raw: string,
+  liveTag: string,
+  cfg: DocsLitDemoConfig,
+): string {
+  const auto = excerptForCustomElement(raw, liveTag);
+  if (auto) return auto;
+  if (cfg.excerptStart != null || cfg.excerptEnd != null) {
+    return excerptLines(raw, cfg.excerptStart, cfg.excerptEnd);
+  }
+  return raw;
+}
+
+function highlightTs(code: string): string {
+  return Prism.highlight(code, Prism.languages.typescript, "typescript");
+}
+
+const tagName = "docs-lit-demo";
+
+@customElement(tagName)
+export class DocsLitDemo extends LitElement {
+  static styles = [
+    tailwind,
+    prismCSS,
+    css`
+      :host {
+        display: block;
+        margin: 1.1rem 0;
+      }
+      pre {
+        font-size: 13px !important;
+      }
+      .preview {
+        border: 1px solid var(--sc-border, #e5e5e5);
+        border-radius: 0.375rem;
+        padding: 1rem;
+        margin-bottom: 0.75rem;
+      }
+    `,
+  ];
+
+  /** Registry key = live custom element tag name */
+  @property({ attribute: "for" }) forTag = "";
+
+  @property({ type: Boolean }) showCode = true;
+
+  @state() private highlighted = "";
+
+  private liveHost?: HTMLDivElement;
+
+  private get config(): DocsLitDemoConfig | undefined {
+    return DOCS_LIT_DEMO_REGISTRY[this.forTag];
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    const cfg = this.config;
+    if (!cfg?.sources[0]) return;
+
+    const raw = DOCS_LIT_DEMO_RAW[cfg.sources[0].path];
+    if (!raw) {
+      console.warn(`[docs-lit-demo] No raw source for ${cfg.sources[0].path}`);
+      return;
+    }
+
+    const liveTag = cfg.liveTag ?? this.forTag;
+    const excerpt = resolveDemoExcerpt(raw, liveTag, cfg);
+    this.highlighted = highlightTs(excerpt);
+  }
+
+  render() {
+    const cfg = this.config;
+    if (!cfg) return nothing;
+
+    const liveTag = cfg.liveTag ?? this.forTag;
+
+    return html`
+      ${docsSourceLinks(cfg.sources)}
+      <div class="preview" data-live-host></div>
+      ${this.showCode && this.highlighted
+        ? html`
+            <pre
+              class="rounded-md custom-scroll language-typescript overflow-auto"
+            ><code>${unsafeHTML(this.highlighted)}</code></pre>
+          `
+        : nothing}
+    `;
+  }
+
+  firstUpdated() {
+    super.firstUpdated();
+    this.mountLiveDemo();
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has("forTag")) this.mountLiveDemo();
+  }
+
+  private mountLiveDemo() {
+    const cfg = this.config;
+    const tag = cfg?.liveTag ?? this.forTag;
+    const host = this.renderRoot.querySelector(
+      "[data-live-host]",
+    ) as HTMLDivElement | null;
+    if (!host || !tag) return;
+    const existing = host.firstElementChild;
+    if (existing?.tagName.toLowerCase() === tag && existing.isConnected) return;
+    host.replaceChildren(document.createElement(tag));
+  }
+}

package/src/docs/components/docs-source-link.ts

@@ -0,0 +1,72 @@
+import { html, nothing } from "lit";
+import "../../core/components/ui/button/button";
+import "../../core/components/ui/icon/icon";
+
+declare const __DOCS_EDITOR_AVAILABLE__: boolean;
+
+export type DocsSource = {
+  path: string;
+  line?: number;
+  column?: number;
+  label?: string;
+};
+
+const editorAvailable =
+  import.meta.env.DEV &&
+  typeof __DOCS_EDITOR_AVAILABLE__ !== "undefined" &&
+  __DOCS_EDITOR_AVAILABLE__;
+
+function openDocsSource(source: DocsSource, event: Event) {
+  event.preventDefault();
+  if (!editorAvailable) return;
+
+  const params = new URLSearchParams({
+    path: source.path,
+    line: String(source.line ?? 1),
+    column: String(source.column ?? 1),
+  });
+
+  void fetch(`/__docs/open?${params}`).catch(() => {
+    console.warn("[docs] Could not open in editor:", source.path);
+  });
+}
+
+export function docsSourceLink(source: DocsSource) {
+  if (!editorAvailable) return nothing;
+  const label = source.label ?? source.path.split("/").pop() ?? "source";
+  return html`
+    <sonic-button
+      variant="link"
+      size="2xs"
+      type="neutral"
+      title=${source.path}
+      @click=${(e: Event) => openDocsSource(source, e)}
+    >
+      <sonic-icon
+        library="heroicons"
+        name="arrow-top-right-on-square"
+        class="w-3 h-3 opacity-70"
+      ></sonic-icon>
+      ${label}
+    </sonic-button>
+  `;
+}
+
+export function docsSourceLinks(sources: DocsSource[]) {
+  if (!editorAvailable || sources.length === 0) return nothing;
+  return html`
+    <div
+      class="flex flex-wrap items-center gap-x-1 gap-y-1 mb-4 pb-3 border-b border-neutral-200/80 dark:border-neutral-700/80"
+    >
+      <span class="text-xs uppercase tracking-wide text-neutral-400 mr-1"
+        >Source</span
+      >
+      ${sources.map((s, i) =>
+        i === 0
+          ? docsSourceLink(s)
+          : html`<span class="text-neutral-300 dark:text-neutral-600">·</span
+              >${docsSourceLink(s)}`,
+      )}
+    </div>
+  `;
+}

package/src/docs/docs-location.ts

@@ -0,0 +1,54 @@
+/** Doc page hash for `router.md` (markdown anchor, before demo sub-routes). */
+export const DOC_ROUTER_PAGE_HASH =
+  "#core/components/functional/router/router.md/router";
+
+/**
+ * Doc site hash: `#<markdown-path>/<page-anchor>[#<in-page-demo-route>]`
+ * e.g. `#core/.../router.md/router#home` — second `#` is for sonic-router demos only.
+ */
+export function parseDocsLocation(location: string): {
+  /** Path for markdown fetch (no leading `#`). */
+  url: string;
+  /** Page anchor (last segment before demo sub-hash). */
+  anchor: string;
+  /** In-page route segment after a second `#` (router demos). */
+  demoSubHash: string;
+  /** Full doc page hash including anchor, without demo sub-hash. */
+  pageHash: string;
+} {
+  const sharpIdx = location.indexOf("#");
+  if (sharpIdx < 0) {
+    return { url: "", anchor: "", demoSubHash: "", pageHash: "" };
+  }
+
+  let hashBody = location.substring(sharpIdx + 1);
+  let demoSubHash = "";
+  const nested = hashBody.lastIndexOf("#");
+  if (nested > 0) {
+    demoSubHash = hashBody.substring(nested + 1);
+    hashBody = hashBody.substring(0, nested);
+  }
+
+  const parts = hashBody.split("/").filter(Boolean);
+  const anchor = decodeURIComponent(parts.pop() || "");
+  const url = parts.join("/");
+
+  return {
+    url,
+    anchor,
+    demoSubHash,
+    pageHash: hashBody ? `#${hashBody}` : "",
+  };
+}
+
+/** Navigate inside the current doc page without reloading markdown. */
+export function setDocsDemoSubHash(subRoute: string, pageHash?: string): void {
+  const loc = document.location;
+  const base =
+    pageHash ||
+    parseDocsLocation(loc.pathname + loc.search + loc.hash).pageHash ||
+    loc.hash;
+  const sub = subRoute.replace(/^#/, "");
+  const nextHash = sub ? `${base}#${sub}` : base;
+  history.replaceState(history.state, "", `${loc.pathname}${loc.search}${nextHash}`);
+}

package/src/docs/docs.ts

@@ -1,8 +1,20 @@
+import "./example/docs-provider-keys";
 import "./layout";
 import "./search/search";
 import "./search/page";
 import "./search/markdown-renderer";
 import "./code";
+import "./components/docs-demo-sources";
+import "./components/docs-lit-demo";
 import "./header/header";
 import "./navigation/navigation";
 import "./example/users";
+import "./example/docs-users-list";
+import "./example/docs-user-two-scopes";
+import "./example/docs-joke-demos";
+import "./example/docs-queue-demos";
+import "./example/docs-toggle-demos";
+import "./example/docs-list-demos";
+import "./example/docs-router-demos";
+import "./example/docs-submit-demos";
+import "./example/docs-api-config-demos";

package/src/docs/example/decorators-demo-bind-demos.ts

@@ -3,11 +3,13 @@ import { customElement, property, state } from "lit/decorators.js";
 import { bind } from "@supersoniks/concorde/decorators";
 import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
 import { sub } from "@supersoniks/concorde/directives";
+import { get, set } from "@supersoniks/concorde/core/utils/PublisherProxy";
 import {
-  PublisherManager,
-  PublisherProxy,
-} from "@supersoniks/concorde/core/utils/PublisherProxy";
-import { Objects } from "@supersoniks/concorde/utils";
+  bindReflectDemoKey,
+  demoDataKey,
+  demoUsersAltKey,
+  demoUsersKey,
+} from "./docs-provider-keys";
 import { tailwind } from "../tailwind";
 import "./decorators-demo-init";
 
@@ -41,14 +43,14 @@ export class DemoBind extends LitElement {
   }
 
   updateData() {
-    const demoData = PublisherManager.get("demoData");
-    const demoUsers = PublisherManager.get("demoUsers");
-    const randomIndex = Math.floor(Math.random() * demoUsers.get().length);
-    const randomUser = demoUsers.get()[randomIndex];
-    demoData.set({
-      firstName: randomUser.firstName,
-      lastName: randomUser.lastName,
-      count: (demoData.count.get() || 0) + 1,
+    const users = get(demoUsersKey);
+    const randomIndex = Math.floor(Math.random() * users.length);
+    const randomUser = users[randomIndex];
+    const data = get(demoDataKey);
+    set(demoDataKey, {
+      ...data,
+      count: data.count + 1,
+      user: { name: `${randomUser.firstName} ${randomUser.lastName}` },
     });
   }
 }
@@ -71,7 +73,7 @@ export class DemoBindReflect extends LitElement {
   }
 
   resetData() {
-    PublisherManager.get("bindReflectDemo").set({ count: 0 });
+    set(bindReflectDemoKey, { count: 0 });
   }
   render() {
     return html`
@@ -91,11 +93,6 @@ export class DemoBindReflect extends LitElement {
   }
 }
 
-type BindReflectDemoData = { count: number };
-const bindReflectDemoKey = new DataProviderKey<BindReflectDemoData>(
-  "bindReflectDemo",
-);
-
 @customElement("demo-bind-key")
 export class DemoBindKey extends LitElement {
   static styles = [tailwind];
@@ -106,7 +103,7 @@ export class DemoBindKey extends LitElement {
 
   connectedCallback() {
     super.connectedCallback();
-    PublisherManager.get("bindReflectDemo").set({ count: 0 });
+    set(bindReflectDemoKey, { count: 0 });
   }
 
   render() {
@@ -126,7 +123,8 @@ export class DemoBindDynamic extends LitElement {
   static styles = [tailwind];
 
   @property({ type: String })
-  dataProvider: "demoUsers" | "demoUsersAlt" = "demoUsers";
+  dataProvider: typeof demoUsersKey.path | typeof demoUsersAltKey.path =
+    demoUsersKey.path;
 
   @property({ type: Number })
   userIndex: number = 1;
@@ -141,36 +139,33 @@ export class DemoBindDynamic extends LitElement {
 
   updateDataProvider(e: Event) {
     this.dataProvider = (e.target as HTMLSelectElement).value as
-      | "demoUsers"
-      | "demoUsersAlt";
+      | typeof demoUsersKey.path
+      | typeof demoUsersAltKey.path;
   }
 
   updateCurrentUserData() {
-    const usersPublisher = PublisherManager.get(this.dataProvider);
-    const userPublisher = Objects.traverse(usersPublisher, [
-      String(this.userIndex),
-    ]) as PublisherProxy;
-
-    if (userPublisher) {
-      const randomNames = [
-        { firstName: "Alice", lastName: "Wonder" },
-        { firstName: "Bob", lastName: "Builder" },
-        { firstName: "Charlie", lastName: "Chaplin" },
-        { firstName: "Diana", lastName: "Prince" },
-        { firstName: "Eve", lastName: "Adams" },
-      ];
-
-      const randomName =
-        randomNames[Math.floor(Math.random() * randomNames.length)];
-      const randomEmail = `${randomName.firstName.toLowerCase()}.${randomName.lastName.toLowerCase()}@example.com`;
-
-      const currentUser = userPublisher.get() || {};
-      userPublisher.set({
-        ...currentUser,
+    const key =
+      this.dataProvider === demoUsersAltKey.path ? demoUsersAltKey : demoUsersKey;
+    const users = [...get(key)];
+    const randomNames = [
+      { firstName: "Alice", lastName: "Wonder" },
+      { firstName: "Bob", lastName: "Builder" },
+      { firstName: "Charlie", lastName: "Chaplin" },
+      { firstName: "Diana", lastName: "Prince" },
+      { firstName: "Eve", lastName: "Adams" },
+    ];
+    const randomName =
+      randomNames[Math.floor(Math.random() * randomNames.length)];
+    const randomEmail = `${randomName.firstName.toLowerCase()}.${randomName.lastName.toLowerCase()}@example.com`;
+    const idx = this.userIndex;
+    if (users[idx]) {
+      users[idx] = {
+        ...users[idx],
         firstName: randomName.firstName,
         lastName: randomName.lastName,
         email: randomEmail,
-      });
+      };
+      set(key, users);
     }
   }
 
@@ -182,8 +177,8 @@ export class DemoBindDynamic extends LitElement {
           label="Users set"
           @change=${this.updateDataProvider}
         >
-          <option value="demoUsers">First set of users</option>
-          <option value="demoUsersAlt">Second set of users</option>
+          <option value=${demoUsersKey.path}>First set of users</option>
+          <option value=${demoUsersAltKey.path}>Second set of users</option>
         </sonic-select>
         <sonic-input
           type="number"

package/src/docs/example/decorators-demo-geo.ts

@@ -2,13 +2,14 @@ import type { APIConfiguration } from "@supersoniks/concorde/core/utils/api";
 import type { ApiGetResult } from "@supersoniks/concorde/core/utils/api";
 import { Endpoint } from "@supersoniks/concorde/core/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
-import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
+import { get, set } from "@supersoniks/concorde/core/utils/PublisherProxy";
 import "./decorators-demo-init";
+import { DOCS_MOCK_GEO_SERVICE } from "../mock-api/urls";
 
 export type GeoCommuneRow = { nom: string; code: string };
 
 export const geoApiDemoConfiguration: APIConfiguration = {
-  serviceURL: "https://geo.api.gouv.fr/",
+  serviceURL: DOCS_MOCK_GEO_SERVICE,
   token: null,
   userName: null,
   password: null,
@@ -16,13 +17,10 @@ export const geoApiDemoConfiguration: APIConfiguration = {
   tokenProvider: null,
 };
 
-const docsDemoGeoApiConfigurationId = "docsDemoGeoApiConfiguration";
-PublisherManager.get(docsDemoGeoApiConfigurationId).set(
-  geoApiDemoConfiguration,
-);
-
 export const docsDemoGeoApiConfigurationKey =
-  new DataProviderKey<APIConfiguration>(docsDemoGeoApiConfigurationId);
+  new DataProviderKey<APIConfiguration>("docsDemoGeoApiConfiguration");
+
+set(docsDemoGeoApiConfigurationKey, geoApiDemoConfiguration);
 
 export const geoCommunesApiGetEndpoint = new Endpoint<GeoCommuneRow[]>(
   "communes?limit=5&fields=nom,code",
@@ -31,10 +29,17 @@ export const geoCommunesApiGetEndpoint = new Endpoint<GeoCommuneRow[]>(
 export const docsDemoDynApiConfKeyTemplate =
   new DataProviderKey<APIConfiguration>("docsDemoDynApiConf${configSlot}");
 
-PublisherManager.get("docsDemoDynApiConfA").set(geoApiDemoConfiguration);
-PublisherManager.get("docsDemoDynApiConfB").set({
+export const docsDemoDynApiConfAKey = new DataProviderKey<APIConfiguration>(
+  "docsDemoDynApiConfA",
+);
+export const docsDemoDynApiConfBKey = new DataProviderKey<APIConfiguration>(
+  "docsDemoDynApiConfB",
+);
+
+set(docsDemoDynApiConfAKey, geoApiDemoConfiguration);
+set(docsDemoDynApiConfBKey, {
   ...geoApiDemoConfiguration,
-  serviceURL: "https://geo.api.gouv.fr/",
+  serviceURL: DOCS_MOCK_GEO_SERVICE,
 });
 
 export const geoCommunesApiGetEndpointDynamic = new Endpoint<GeoCommuneRow[]>(