@supersoniks/concorde 4.7.3 → 4.8.0

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

@@ -13,57 +13,24 @@ 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");
-}
+import { DOCS_SOURCE_RAW } from "./docs-source-raw";
+import {
+  excerptLines,
+  excerptForCustomElement,
+  resolveSourceExcerpt,
+} from "./docs-source-excerpt";
 
-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");
-}
+export { excerptForCustomElement } from "./docs-source-excerpt";
 
 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;
+  return resolveSourceExcerpt(raw, liveTag);
 }
 
 function highlightTs(code: string): string {
@@ -112,7 +79,7 @@ export class DocsLitDemo extends LitElement {
     const cfg = this.config;
     if (!cfg?.sources[0]) return;
 
-    const raw = DOCS_LIT_DEMO_RAW[cfg.sources[0].path];
+    const raw = DOCS_SOURCE_RAW[cfg.sources[0].path];
     if (!raw) {
       console.warn(`[docs-lit-demo] No raw source for ${cfg.sources[0].path}`);
       return;

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

@@ -0,0 +1,53 @@
+/** Extrait la classe Lit d'une démo à partir de `@customElement("liveTag")`. */
+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");
+}
+
+export 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");
+}
+
+export function resolveSourceExcerpt(
+  raw: string,
+  liveTag: string,
+  options?: { line?: number; excerptEnd?: number },
+): string {
+  const byTag = excerptForCustomElement(raw, liveTag);
+  if (byTag) return byTag;
+  if (options?.line != null) {
+    const end =
+      options.excerptEnd ??
+      Math.min(raw.split("\n").length, options.line + 72);
+    return excerptLines(raw, options.line, end);
+  }
+  return raw;
+}

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

@@ -53,20 +53,36 @@ export function docsSourceLink(source: DocsSource) {
 }
 
 export function docsSourceLinks(sources: DocsSource[]) {
-  if (!editorAvailable || sources.length === 0) return nothing;
+  if (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"
+      class="flex flex-wrap items-center gap-x-1 gap-y-1 mb-3 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)}`,
-      )}
+      ${editorAvailable
+        ? sources.map((s, i) =>
+            i === 0
+              ? docsSourceLink(s)
+              : html`<span class="text-neutral-300 dark:text-neutral-600"
+                    >·</span
+                  >${docsSourceLink(s)}`,
+          )
+        : sources.map(
+            (s, i) => html`
+              ${i > 0
+                ? html`<span class="text-neutral-300 dark:text-neutral-600"
+                    >·</span
+                  >`
+                : nothing}
+              <span
+                class="text-xs font-mono text-neutral-500 dark:text-neutral-400"
+                title=${s.path}
+                >${s.label ?? s.path.split("/").pop()}</span
+              >
+            `,
+          )}
     </div>
   `;
 }

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

@@ -0,0 +1,34 @@
+/**
+ * Sources brutes des démos doc (`?raw`) — `import.meta.glob` pour éviter les imports manuels.
+ * Clés alignées sur `DOCS_DEMO_SOURCE_REGISTRY` / `DOCS_LIT_DEMO_REGISTRY` (`src/docs/...`).
+ */
+const rawModules = import.meta.glob<string>(
+  [
+    "../example/**/*.ts",
+    "../mock-api/**/*.ts",
+    "../../core/components/functional/**/*.demo.ts",
+    "../../core/components/functional/queue/queue.ts",
+    "../../core/components/functional/list/list.ts",
+  ],
+  { query: "?raw", import: "default", eager: true },
+);
+
+function toRegistryPath(globKey: string): string {
+  if (globKey.startsWith("../example/")) {
+    return `src/docs/example/${globKey.slice("../example/".length)}`;
+  }
+  if (globKey.startsWith("../mock-api/")) {
+    return `src/docs/mock-api/${globKey.slice("../mock-api/".length)}`;
+  }
+  if (globKey.startsWith("../../core/components/functional/")) {
+    return `src/core/components/functional/${globKey.slice("../../core/components/functional/".length)}`;
+  }
+  return globKey;
+}
+
+export const DOCS_SOURCE_RAW: Record<string, string> = Object.fromEntries(
+  Object.entries(rawModules).map(([key, content]) => [toRegistryPath(key), content]),
+);
+
+/** @deprecated Alias — préférer `DOCS_SOURCE_RAW`. */
+export const DOCS_LIT_DEMO_RAW = DOCS_SOURCE_RAW;

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

@@ -1,5 +1,5 @@
 import type { APIConfiguration } from "@supersoniks/concorde/core/utils/api";
-import type { ApiGetResult } from "@supersoniks/concorde/core/utils/api";
+import type { ApiResult } from "@supersoniks/concorde/core/utils/api";
 import { Endpoint } from "@supersoniks/concorde/core/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
 import { get, set } from "@supersoniks/concorde/core/utils/PublisherProxy";
@@ -47,5 +47,5 @@ export const geoCommunesApiGetEndpointDynamic = new Endpoint<GeoCommuneRow[]>(
 );
 
 export const geoCommunesApiGetPublishKey = new DataProviderKey<
-  ApiGetResult<GeoCommuneRow[]>
+  ApiResult<GeoCommuneRow[]>
 >(geoCommunesApiGetEndpoint.path);

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

@@ -0,0 +1,249 @@
+import { html, LitElement, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import { post, publish, type ApiResult } from "@supersoniks/concorde/decorators";
+import type { APIConfiguration } from "@supersoniks/concorde/core/utils/api";
+import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/core/utils/endpoint";
+import {
+  dp,
+  set,
+} from "@supersoniks/concorde/core/utils/PublisherProxy";
+import { DOCS_MOCK_REQRES_SERVICE } from "../mock-api/urls";
+import { tailwind } from "../tailwind";
+import "./decorators-demo-init";
+
+type RegisterResult = {
+  id?: number;
+  token?: string;
+  email?: string;
+};
+
+type RegisterRequest = {
+  email: string;
+  password: string;
+};
+
+const registerPostEndpoint = new Endpoint<RegisterResult>("api/register");
+
+type SessionSyncResult = {
+  ok?: boolean;
+  sessionId?: string;
+  serverTime?: number;
+  echo?: { note?: string };
+};
+
+type SessionSyncRequest = {
+  note: string;
+};
+
+const sessionSyncPostEndpoint = new Endpoint<
+  SessionSyncResult,
+  { sessionId: string }
+>("api/sessions/${sessionId}/sync");
+
+const reqresApiConfiguration: APIConfiguration = {
+  serviceURL: DOCS_MOCK_REQRES_SERVICE,
+  token: null,
+  userName: null,
+  password: null,
+  authToken: null,
+  tokenProvider: null,
+};
+
+export const docsDemoReqresApiConfigurationKey =
+  new DataProviderKey<APIConfiguration>("docsDemoReqresApiConfiguration");
+
+set(docsDemoReqresApiConfigurationKey, reqresApiConfiguration);
+
+export const docsDemoPostRequestKey = new DataProviderKey<RegisterRequest>(
+  "docsDemoPostRequest",
+);
+/** Clé body distincte — la page doc monte les deux démos live en même temps. */
+export const docsDemoPostPublishRequestKey = new DataProviderKey<RegisterRequest>(
+  "docsDemoPostPublishRequest",
+);
+export const docsDemoPostTriggerKey = new DataProviderKey<number>(
+  "docsDemoPostTrigger",
+);
+export const docsDemoPostDynamicRequestKey = new DataProviderKey<SessionSyncRequest>(
+  "docsDemoPostDynamicRequest",
+);
+
+@customElement("demo-api-post")
+export class DemoApiPost extends LitElement {
+  static styles = [tailwind];
+
+  @post(
+    registerPostEndpoint,
+    docsDemoPostRequestKey,
+    docsDemoReqresApiConfigurationKey,
+    { triggerKey: docsDemoPostTriggerKey },
+  )
+  @state()
+  payload?: ApiResult<RegisterResult> | null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    set(docsDemoPostRequestKey, {
+      email: "demo@concorde.local",
+      password: "demo-password",
+    });
+    set(docsDemoPostTriggerKey, 0);
+  }
+
+  private send() {
+    set(docsDemoPostRequestKey, {
+      email: "demo@concorde.local",
+      password: "demo-password",
+    });
+  }
+
+  private resendSameBody() {
+    dp(docsDemoPostTriggerKey).invalidate();
+  }
+
+  render() {
+    const result = this.payload?.result;
+    const status = this.payload?.response?.status;
+    return html`
+      <div class="space-y-4">
+        <p class="text-sm text-neutral-600 dark:text-neutral-400">
+          <code>@post</code> vers le mock
+          <code>POST /docs-mock-api/api/register</code> — body lu depuis
+          <code>docsDemoPostRequest</code>.
+        </p>
+        <div class="flex flex-wrap gap-2">
+          <sonic-button @click=${this.send}>Set body &amp; POST</sonic-button>
+          <sonic-button variant="secondary" @click=${this.resendSameBody}>
+            invalidate trigger (re-POST)
+          </sonic-button>
+        </div>
+        <div
+          class="rounded border border-neutral-200 dark:border-neutral-700 p-3 text-sm space-y-1"
+        >
+          <p>HTTP status: <strong>${status ?? "—"}</strong></p>
+          ${result?.id != null
+            ? html`<p>id: <span class="font-mono">${result.id}</span></p>`
+            : nothing}
+          ${result?.email
+            ? html`<p>email: <span class="font-mono">${result.email}</span></p>`
+            : nothing}
+          ${result?.token
+            ? html`<p>
+                token:
+                <span class="font-mono break-all">${result.token}</span>
+              </p>`
+            : nothing}
+        </div>
+      </div>
+    `;
+  }
+}
+
+@customElement("demo-api-post-dynamic")
+export class DemoApiPostDynamic extends LitElement {
+  static styles = [tailwind];
+
+  @property({ type: String }) sessionId = "alpha";
+
+  @post(
+    sessionSyncPostEndpoint,
+    docsDemoPostDynamicRequestKey,
+    docsDemoReqresApiConfigurationKey,
+  )
+  @state()
+  payload?: ApiResult<SessionSyncResult> | null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    set(docsDemoPostDynamicRequestKey, { note: "docs @post dynamic path" });
+  }
+
+  private setSession(sessionId: string) {
+    this.sessionId = sessionId;
+  }
+
+  render() {
+    const result = this.payload?.result;
+    const status = this.payload?.response?.status;
+    const requestUrl = this.payload?.request?.url ?? "";
+    return html`
+      <div class="space-y-4">
+        <p class="text-sm text-neutral-600 dark:text-neutral-400">
+          <code>@post</code> vers
+          <code>api/sessions/${"${sessionId}"}/sync</code> — changer
+          <code>sessionId</code> sur l'hôte relance le POST (même body).
+        </p>
+        <div class="flex flex-wrap items-center gap-2">
+          <span class="text-sm text-neutral-500">sessionId :</span>
+          ${(["alpha", "beta", "gamma"] as const).map(
+            (id) => html`
+              <sonic-button
+                variant=${this.sessionId === id ? "primary" : "secondary"}
+                size="sm"
+                @click=${() => this.setSession(id)}
+              >
+                ${id}
+              </sonic-button>
+            `,
+          )}
+        </div>
+        <div
+          class="rounded border border-neutral-200 dark:border-neutral-700 p-3 text-sm space-y-1"
+        >
+          <p>HTTP status: <strong>${status ?? "—"}</strong></p>
+          <p>
+            Dernier path :
+            <span class="font-mono text-xs break-all">${requestUrl || "—"}</span>
+          </p>
+          <p>
+            Réponse <code>sessionId</code> :
+            <strong class="font-mono">${result?.sessionId ?? "—"}</strong>
+          </p>
+        </div>
+      </div>
+    `;
+  }
+}
+
+@customElement("demo-api-post-publish")
+export class DemoApiPostPublish extends LitElement {
+  static styles = [tailwind];
+
+  @post(
+    registerPostEndpoint,
+    docsDemoPostPublishRequestKey,
+    docsDemoReqresApiConfigurationKey,
+  )
+  @publish(
+    registerPostEndpoint.getDataProviderKey() as DataProviderKey<
+      ApiResult<RegisterResult>
+    >,
+  )
+  @state()
+  payload?: ApiResult<RegisterResult> | null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    set(docsDemoPostPublishRequestKey, {
+      email: "publish@concorde.local",
+      password: "secret",
+    });
+  }
+
+  render() {
+    const email = this.payload?.result?.email;
+    return html`
+      <div class="space-y-3 text-sm">
+        <p class="text-neutral-600 dark:text-neutral-400">
+          <code>@post</code> + <code>@publish</code> sur le même champ — même
+          pattern que <code>@get</code> + <code>@publish</code>.
+        </p>
+        <p>
+          Result email:
+          <strong class="font-mono">${email ?? "—"}</strong>
+        </p>
+      </div>
+    `;
+  }
+}

package/src/docs/example/decorators-demo-subscribe-publish-get-demos.ts

@@ -3,7 +3,7 @@ import { customElement, property, state } from "lit/decorators.js";
 import { get, handle, publish, subscribe } from "@supersoniks/concorde/decorators";
 import type {
   APIConfiguration,
-  ApiGetResult,
+  ApiResult,
 } from "@supersoniks/concorde/core/utils/api";
 import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
 import { sub } from "@supersoniks/concorde/directives";
@@ -92,7 +92,7 @@ export class DemoApiGet extends LitElement {
 
   @get(geoCommunesApiGetEndpoint, docsDemoGeoApiConfigurationKey)
   @state()
-  geoApiPayload?: ApiGetResult<GeoCommuneRow[]>;
+  geoApiPayload?: ApiResult<GeoCommuneRow[]>;
 
   render() {
     const rows = this.geoApiPayload?.result;
@@ -102,7 +102,7 @@ export class DemoApiGet extends LitElement {
         <p class="text-sm text-neutral-600 dark:text-neutral-400">
           <code>@get</code> — même service que
           <code>sonic-queue</code> (<code>/docs-mock-api/geo/</code>).
-          Propriété typée <code>ApiGetResult&lt;T&gt;</code>.
+          Propriété typée <code>ApiResult&lt;T&gt;</code>.
         </p>
         ${status != null
           ? html`<p class="text-xs text-neutral-500">HTTP ${status}</p>`
@@ -141,7 +141,7 @@ export class DemoApiGetConfigurationKey extends LitElement {
 
   @get(geoCommunesApiGetEndpointDynamic, docsDemoDynApiConfKeyTemplate)
   @state()
-  geoApiPayloadDyn?: ApiGetResult<GeoCommuneRow[]>;
+  geoApiPayloadDyn?: ApiResult<GeoCommuneRow[]>;
 
   private touchCurrentConfigPublisher() {
     const key =
@@ -237,7 +237,7 @@ export class DemoApiGetPublishSubscribe extends LitElement {
   @get(geoCommunesApiGetEndpoint)
   @publish(geoCommunesApiGetPublishKey)
   @state()
-  geoApiPayloadPublished: ApiGetResult<GeoCommuneRow[]> | null = null;
+  geoApiPayloadPublished: ApiResult<GeoCommuneRow[]> | null = null;
 
   @state()
   @subscribe(geoCommunesApiGetPublishKey.result)

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

@@ -24,6 +24,7 @@ import {
 import { tailwind } from "../tailwind";
 import "./decorators-demo-bind-demos";
 import "./decorators-demo-subscribe-publish-get-demos";
+import "./decorators-demo-post";
 
 @customElement("demo-ancestor-attribute")
 export class DemoAncestorAttribute extends LitElement {

package/src/docs/example/docs-api-config-demos.ts

@@ -1,7 +1,7 @@
 import { html, LitElement, nothing } from "lit";
 import { customElement, state } from "lit/decorators.js";
 import { get } from "@supersoniks/concorde/core/decorators/api";
-import type { ApiGetResult } from "@supersoniks/concorde/core/utils/api";
+import type { ApiResult } from "@supersoniks/concorde/core/utils/api";
 import { Endpoint } from "@supersoniks/concorde/core/utils/endpoint";
 import { set } from "@supersoniks/concorde/core/utils/PublisherProxy";
 import { wording } from "@supersoniks/concorde/core/directives/Wording";
@@ -33,7 +33,7 @@ type ProtectedResult = {
 
 const protectedEndpoint = new Endpoint<ProtectedResult>("api/config/protected");
 
-function resultPanel(payload: ApiGetResult<ProtectedResult> | null | undefined) {
+function resultPanel(payload: ApiResult<ProtectedResult> | null | undefined) {
   const status = payload?.response?.status;
   const r = payload?.result;
   if (payload === null) {
@@ -66,7 +66,7 @@ export class DocsApiConfigBearerDemo extends LitElement {
 
   @get(protectedEndpoint, docsApiConfBearerKey)
   @state()
-  private payload: ApiGetResult<ProtectedResult> | null = null;
+  private payload: ApiResult<ProtectedResult> | null = null;
 
   render() {
     return html`
@@ -86,7 +86,7 @@ export class DocsApiConfigTokenProviderDemo extends LitElement {
 
   @get(protectedEndpoint, docsApiConfTokenProviderKey)
   @state()
-  private payload: ApiGetResult<ProtectedResult> | null = null;
+  private payload: ApiResult<ProtectedResult> | null = null;
 
   render() {
     return html`
@@ -107,7 +107,7 @@ export class DocsApiConfigStaleTokenDemo extends LitElement {
 
   @get(protectedEndpoint, docsApiConfStaleTokenKey)
   @state()
-  private payload: ApiGetResult<ProtectedResult> | null = null;
+  private payload: ApiResult<ProtectedResult> | null = null;
 
   render() {
     const refreshed =

package/src/docs/mock-api/router.ts

@@ -180,6 +180,26 @@ export async function handleDocsMockApiRequest(
     );
   }
 
+  const sessionSyncMatch = subPath.match(/^\/api\/sessions\/([^/]+)\/sync$/);
+  if (sessionSyncMatch && method === "POST") {
+    const sessionId = decodeURIComponent(sessionSyncMatch[1]);
+    let body: Record<string, unknown> = {};
+    try {
+      const text = await request.text();
+      if (text.trim()) {
+        body = JSON.parse(text) as Record<string, unknown>;
+      }
+    } catch {
+      body = {};
+    }
+    return json({
+      ok: true,
+      sessionId,
+      serverTime: Date.now(),
+      echo: body,
+    });
+  }
+
   if (subPath === "/api/register/echo" && method === "GET") {
     const email = url.searchParams.get("email") ?? "";
     const password = url.searchParams.get("password") ?? "";

package/src/docs/navigation/navigation.ts

@@ -153,6 +153,18 @@ export class DocsNavigation extends LitElement {
       label: "@get",
       href: "#docs/_decorators/get.md/get",
     },
+    {
+      label: "@post",
+      href: "#docs/_decorators/post.md/post",
+    },
+    {
+      label: "@put",
+      href: "#docs/_decorators/put.md/put",
+    },
+    {
+      label: "@patch",
+      href: "#docs/_decorators/patch.md/patch",
+    },
     {
       label: "@onAssign",
       href: "#docs/_decorators/on-assign.md/on-assign",
@@ -174,6 +186,10 @@ export class DocsNavigation extends LitElement {
       label: "Endpoint",
       href: "#docs/_misc/endpoint.md/endpoint",
     },
+    {
+      label: "Dynamic paths",
+      href: "#docs/_misc/dynamic-path.md/dynamic-path",
+    },
     {
       label: "API configuration",
       href: "#docs/_misc/api-configuration.md/api-configuration",