@supersoniks/concorde 4.7.4 → 4.9.0

package/src/docs/_misc/dynamic-path.md

@@ -0,0 +1,71 @@
+# Dynamic path placeholders
+
+Decorators and `DataProviderKey` paths can include **placeholders** resolved on the host component at runtime:
+
+- `${prop}` or `{$prop}` — e.g. `"users/${userId}"`, `"api/sessions/${sessionId}/sync"`
+- Nested expressions — e.g. `"teams.${teamId}.members"`
+
+Resolution is done by [`resolveDynamicPath`](../../core/decorators/subscriber/dynamicPath.ts). The root property names (`userId`, `sessionId`, …) are watched via `requestAnimationFrame` (see `dynamicPropertyWatch.ts`).
+
+## Default behaviour (`ready` / `not ready`)
+
+| Placeholder value | Path `ready`? | Inserted segment | Notes |
+|-------------------|---------------|------------------|-------|
+| `undefined` | **no** | — | Wait until defined |
+| `null` | **no** | — | Same as undefined |
+| `""` | **yes** | empty string | e.g. `sessions//sync` — request may still run |
+| `0` | **yes** | `"0"` | Not treated as “missing” |
+| `false` | **yes** | `"false"` | |
+| `42`, `"alpha"` | **yes** | `"42"`, `"alpha"` | |
+
+When `ready: false`, decorators **do not** call the network (for `@get` / `@post` / `@put` / `@patch`), **unsubscribe** (`@bind` / `@subscribe`), or skip publisher binding (`@publish` / `@handle`). The decorated property is often left unchanged or set to `undefined` (HTTP decorators).
+
+When the placeholder later becomes valid, observers run again and behaviour resumes.
+
+## `skipEmptyPlaceholder` option
+
+Some APIs should not run while an id is still `""`. Opt in per decorator:
+
+```typescript
+@get(new Endpoint<User, { userId: string }>("users/${userId}"), {
+  skipEmptyPlaceholder: true,
+})
+```
+
+| Option | Scope |
+|--------|--------|
+| `skipEmptyPlaceholder?: boolean` | **Only** empty string `''` on a placeholder |
+| Default `false` | `""` is inserted into the path (legacy behaviour) |
+| `true` | `""` → `ready: false`, same as `null` / `undefined` for that segment |
+
+Does **not** affect `0`, `false`, `null`, or `undefined` (nullish stays “not ready” regardless).
+
+Available on:
+
+| API | Where |
+|-----|--------|
+| `@get` | 2nd or 3rd argument (`GetOptions`) |
+| `@post` / `@put` / `@patch` | `PostOptions` / `ApiSendOptions` |
+| `@bind` / `@subscribe` | `BindOptions` |
+| `@publish` | 2nd argument `PublishOptions` |
+| `@handle` | `HandleOptions` |
+
+## Per-decorator summary
+
+| Decorator | `ready: false` | `ready: true` |
+|-----------|----------------|---------------|
+| `@get` | No HTTP; `payload` → `undefined` | `ApiResult` assigned |
+| `@post` / `@put` / `@patch` | No HTTP; `payload` → `undefined` | `ApiResult` assigned |
+| `@subscribe` / `@bind` | Unsubscribe; prop keeps last value | Subscribe `onAssign` |
+| `@publish` | Internal publisher `null`; writes ignored | `publisher.set` on assign |
+| `@handle` | No subscription; with `waitForAllDefined`, method not called | Callback on assign |
+
+## See also
+
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — path syntax
+- [Endpoint](#docs/_misc/endpoint.md/endpoint) — HTTP paths + host generic `U`
+- HTTP: [@get](#docs/_decorators/get.md/get) · [@post](#docs/_decorators/post.md/post) · [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch)
+- Store: [@subscribe](#docs/_decorators/subscribe.md/subscribe) · [@bind](#docs/_decorators/bind.md/bind) · [@publish](#docs/_decorators/publish.md/publish) · [@handle](#docs/_decorators/handle.md/handle)
+- Legacy strings: [@onAssign](#docs/_decorators/on-assign.md/on-assign) (dynamic paths section)
+- Templates: [sub()](#docs/_directives/sub.md/sub) — dynamic paths in Lit (no `skipEmptyPlaceholder` yet)
+- Tutorial: [My first component](#docs/_getting-started/my-first-component.md/my-first-component) — `"${dataProvider}"` scope pattern

package/src/docs/_misc/endpoint.md

@@ -2,7 +2,7 @@
 
 `Endpoint<T, U>` describes a single HTTP path (or a path accepted by `API.get`) and carries the expected response type `T`. Unlike [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey), there is no dot-navigation: the path is one string.
 
-The optional second generic `U` (default `any`) describes host properties used to resolve dynamic segments in the path (`${…}` / `{$…}`), for example with the [@get](#docs/_decorators/get.md/get) decorator.
+The optional second generic `U` (default `any`) describes host properties used to resolve dynamic segments in the path (`${…}` / `{$…}`), for example with [@get](#docs/_decorators/get.md/get) or [@post](#docs/_decorators/post.md/post). See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for `null` / `undefined` / `""` / `0` and `skipEmptyPlaceholder`.
 
 ## Import
 
@@ -30,7 +30,7 @@ const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
 
 ## Publisher key for payloads
 
-`getDataProviderKey()` returns a typed publisher key whose `path` matches the endpoint path (payload typing follows `ApiGetResult` for this endpoint). Useful when pairing `@get` with `@publish` / `@subscribe` (see [@get](#docs/_decorators/get.md/get)).
+`getDataProviderKey()` returns a typed publisher key whose `path` matches the endpoint path (payload typing follows `ApiResult` for this endpoint). Useful when pairing `@get` with `@publish` / `@subscribe` (see [@get](#docs/_decorators/get.md/get)).
 
 ## Data-provider paths
 
@@ -39,5 +39,7 @@ const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
 ## See also
 
 - [API configuration](#docs/_misc/api-configuration.md/api-configuration) — `serviceURL`, token, wording (mock demos)
-- [@get](#docs/_decorators/get.md/get) — decorator that uses `Endpoint<T>`
+- [@get](#docs/_decorators/get.md/get) — GET decorator
+- [@post](#docs/_decorators/post.md/post) — POST decorator (body from a `DataProviderKey`)
+- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH decorators
 - [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed publisher paths (dot notation)

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

@@ -1,6 +1,14 @@
-import { html, LitElement, nothing } from "lit";
-import { customElement, property } from "lit/decorators.js";
+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, type DocsSource } from "./docs-source-link";
+import { DOCS_SOURCE_RAW } from "./docs-source-raw";
+import { resolveSourceExcerpt } from "./docs-source-excerpt";
+import "../prism/prism";
+import { prismCSS } from "../prism";
+import * as Prism from "prismjs";
+import "prismjs/components/prism-typescript";
 
 export type { DocsSource };
 
@@ -260,6 +268,30 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
     },
     { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
   ],
+  "demo-api-post": [
+    {
+      path: "src/docs/example/decorators-demo-post.ts",
+      line: 53,
+      label: "demo-api-post",
+    },
+    { path: "src/docs/mock-api/router.ts", label: "mock router" },
+  ],
+  "demo-api-post-dynamic": [
+    {
+      path: "src/docs/example/decorators-demo-post.ts",
+      line: 143,
+      label: "demo-api-post-dynamic",
+    },
+    { path: "src/docs/mock-api/router.ts", label: "mock router (sessions sync)" },
+  ],
+  "demo-api-post-publish": [
+    {
+      path: "src/docs/example/decorators-demo-post.ts",
+      line: 209,
+      label: "demo-api-post-publish",
+    },
+    { path: "src/docs/mock-api/router.ts", label: "mock router" },
+  ],
   "demo-handle": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
@@ -297,7 +329,19 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
     { 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" },
+    { path: "src/docs/example/decorators-demo.ts", line: 35, label: "demo-ancestor-attribute" },
+  ],
+  "demo-ancestor-attribute-dynamic-section": [
+    {
+      path: "src/docs/example/decorators-demo.ts",
+      line: 60,
+      label: "demo-ancestor-attribute-dynamic",
+    },
+    {
+      path: "src/docs/example/decorators-demo.ts",
+      line: 81,
+      label: "demo-ancestor-attribute-dynamic-section",
+    },
   ],
   "demo-on-assign": [
     { path: "src/docs/example/decorators-demo.ts", line: 43, label: "demo-on-assign" },
@@ -384,14 +428,81 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   ],
 };
 
+function highlightTs(code: string): string {
+  return Prism.highlight(code, Prism.languages.typescript, "typescript");
+}
+
 @customElement("docs-demo-sources")
 export class DocsDemoSources extends LitElement {
+  static styles = [
+    tailwind,
+    prismCSS,
+    css`
+      :host {
+        display: block;
+        margin-bottom: 0.75rem;
+      }
+      pre {
+        font-size: 13px !important;
+        margin: 0;
+      }
+    `,
+  ];
+
   /** Registry key matching the live demo custom element tag. */
   @property({ attribute: "for" }) forTag = "";
 
+  @property({ type: Boolean, attribute: "show-code" }) showCode = true;
+
+  @state() private highlighted = "";
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.refreshHighlight();
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has("forTag") || changed.has("showCode")) {
+      this.refreshHighlight();
+    }
+  }
+
+  private refreshHighlight() {
+    if (!this.showCode) {
+      this.highlighted = "";
+      return;
+    }
+    const sources = DOCS_DEMO_SOURCE_REGISTRY[this.forTag];
+    const primary = sources?.[0];
+    if (!primary) {
+      this.highlighted = "";
+      return;
+    }
+    const raw = DOCS_SOURCE_RAW[primary.path];
+    if (!raw) {
+      console.warn(`[docs-demo-sources] No raw source for ${primary.path}`);
+      this.highlighted = "";
+      return;
+    }
+    const excerpt = resolveSourceExcerpt(raw, this.forTag, {
+      line: primary.line,
+    });
+    this.highlighted = highlightTs(excerpt);
+  }
+
   render() {
     const sources = DOCS_DEMO_SOURCE_REGISTRY[this.forTag];
     if (!sources?.length) return nothing;
-    return docsSourceLinks(sources);
+    return html`
+      ${docsSourceLinks(sources)}
+      ${this.showCode && this.highlighted
+        ? html`
+            <pre
+              class="rounded-md custom-scroll language-typescript overflow-auto border border-neutral-200/80 dark:border-neutral-700/80"
+            ><code>${unsafeHTML(this.highlighted)}</code></pre>
+          `
+        : nothing}
+    `;
   }
 }

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

@@ -1,28 +1,4 @@
 /**
- * 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`.
+ * @deprecated Importez `DOCS_SOURCE_RAW` depuis `./docs-source-raw`.
  */
-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,
-};
+export { DOCS_LIT_DEMO_RAW, DOCS_SOURCE_RAW } from "./docs-source-raw";

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);