@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/src/docs/decorators/put.md

@@ -0,0 +1,51 @@
+# @put
+
+Sends the value of a publisher as the body of a `PUT` request, to replace a resource, and stores the response in an `ApiResult<T>` property. It takes the same arguments, options and `send(component)` handle as [@post](/docs/decorators/post); only the HTTP method differs.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { put, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The full passenger record is sent on connect and after each body mutation. Placeholders such as `${passengerId}` are resolved on the host component.
+
+<sonic-code language="typescript">
+  <template>
+type Passenger = { name: string; flight: string; seat: string };
+
+const passengerKey = new DataProviderKey&lt;Passenger&gt;("passengerForm");
+const savePassenger = put(
+  new Endpoint&lt;Passenger, { passengerId: string }&gt;("passengers/${passengerId}"),
+  passengerKey,
+  { autoPostOnBodyMutation: false },
+);
+
+@property() passengerId = "ada-lindqvist";
+
+@savePassenger
+@state()
+payload?: ApiResult&lt;Passenger&gt;;
+
+async save() {
+  await savePassenger.send(this);
+}
+  </template>
+</sonic-code>
+
+Triggers, the `send` method decorator and every option are described on [@post](/docs/decorators/post).
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `Endpoint<T>` | Resource path and response type |
+| `bodyKey` | `DataProviderKey<B>` | Publisher read as the full replacement body |
+| `configurationKey` | `DataProviderKey<APIConfiguration>` (optional) | API configuration publisher. Default: HTML scope |
+| `options` | `PutOptions` | Same as [@post options](/docs/decorators/post) |

package/src/docs/decorators/subscribe.md

@@ -0,0 +1,87 @@
+# @subscribe
+
+`@subscribe(key)` keeps a component property in sync with one path of the store: when a publisher assigns that path, the property updates and the component re-renders. It is read-only; use [@publish](/docs/decorators/publish) to write and [sub()](/docs/directives/sub) to read inside a template. See [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { subscribe } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+type Cockpit = { altitude: number };
+const cockpitKey = new DataProviderKey&lt;Cockpit&gt;("cockpit");
+
+@subscribe(cockpitKey.altitude)
+@state()
+altitude = 0;
+  </template>
+</sonic-code>
+
+## Static path
+
+The key is a [DataProviderKey](/docs/misc/dataProviderKey): the property type must match `T` at that path. Add `@state()` so Lit re-renders. Until the publisher holds a value, the property keeps its initializer.
+
+<sonic-code language="typescript">
+  <template>
+type Flight = { code: string; gate: string; status: string };
+const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
+
+@subscribe(flightKey)
+@state()
+flight: Flight | null = null;
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+`${prop}` placeholders resolve from properties of the same component. Declare them in the key's second generic so TypeScript requires them on the host. When `seatIndex` changes, the path is resolved again and `person` refreshes; while the placeholder is `null` or `undefined`, the subscription is inactive. Resolution rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+type OnBoard = { name: string; role: string; seat: string };
+const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
+  "demoOnBoard.${seatIndex}",
+);
+
+@property({ type: Number }) seatIndex = 0;
+
+@subscribe(personKey)
+@state()
+person: OnBoard | null = null;
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-subscribe-dynamic"></docs-demo-sources>
+    <demo-subscribe-dynamic></demo-subscribe-dynamic>
+  </template>
+</sonic-code>
+
+## Ancestor scope
+
+Inside a list row or a `dataProvider` wrapper, read the path from the closest ancestor with [@ancestorAttribute](/docs/decorators/ancestor-attribute), then use it as the placeholder.
+
+<sonic-code language="typescript">
+  <template>
+const rowKey = new DataProviderKey&lt;OnBoard, { dataProvider: string | null }&gt;(
+  "${dataProvider}",
+);
+
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+
+@subscribe(rowKey)
+@state()
+person: OnBoard | null = null;
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `key` | `DataProviderKey<T, U>` | Path to read. `U` lists the host properties used by `${…}` placeholders |
+
+The decorated property is typed `T` (optionally `| null` or `| undefined`). The subscription starts when the component connects and stops when it disconnects.

package/src/docs/decorators/wait-for-ancestors.md

@@ -0,0 +1,76 @@
+# @awaitConnectedAncestors
+
+Delays a component's `connectedCallback` until its matching ancestors are defined and connected, so context they set up (a `dataProvider`, a publisher, a fetched payload) is ready when the child starts. Pair it with `@dispatchConnectedEvent` on the ancestors, which signals readiness.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import {
+  awaitConnectedAncestors,
+  dispatchConnectedEvent,
+} from "@supersoniks/concorde/decorators";
+
+@customElement("flight-scope")
+@dispatchConnectedEvent()
+export class FlightScope extends LitElement {}
+
+@customElement("gate-panel")
+@awaitConnectedAncestors("flight-scope")
+export class GatePanel extends LitElement {}
+  </template>
+</sonic-code>
+
+## Wait for an ancestor
+
+Arguments are CSS selectors tested with `element.matches()` on each ancestor, across shadow roots. Here the parent element is not defined yet: the child stays uninitialized until you register it.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-wait-ancestors-section"></docs-demo-sources>
+    <demo-wait-ancestors-section></demo-wait-ancestors-section>
+  </template>
+</sonic-code>
+
+## Several ancestors
+
+With several selectors, the child waits for every matching ancestor. Register both to initialize it, in any order.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-wait-ancestors-multi-section"></docs-demo-sources>
+    <demo-wait-ancestors-multi-section></demo-wait-ancestors-multi-section>
+  </template>
+</sonic-code>
+
+## Ancestor already connected
+
+When the ancestor is already connected, or no ancestor matches, the child initializes immediately.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-wait-ancestors-ready-section"></docs-demo-sources>
+    <demo-wait-ancestors-ready-section></demo-wait-ancestors-ready-section>
+  </template>
+</sonic-code>
+
+## Signal readiness
+
+`@dispatchConnectedEvent()` dispatches a bubbling `sonic-connected` event (exported as `CONNECTED`) at the end of the ancestor's `connectedCallback`. You can listen to it anywhere:
+
+<sonic-code language="typescript">
+  <template>
+import { CONNECTED } from "@supersoniks/concorde/decorators";
+
+document.addEventListener(CONNECTED, (e) => console.log("ready:", e.target));
+  </template>
+</sonic-code>
+
+Elements without a hyphen in their tag name count as connected. A custom element ancestor that never dispatches the event releases the child after a **5 second** timeout, so decorate the ancestors you wait for.
+
+## API reference
+
+| Decorator | Argument | Description |
+|-----------|----------|-------------|
+| `@awaitConnectedAncestors` | `...selectors: string[]` | Class decorator. CSS selectors of the ancestors to wait for; with no selector, the class is left unchanged |
+| `@dispatchConnectedEvent` | none | Class decorator. Dispatches `CONNECTED` (`"sonic-connected"`, bubbles) after `connectedCallback` |

package/src/docs/directives/sub.md

@@ -0,0 +1,75 @@
+# sub()
+
+`sub(path)` is a Lit directive that renders the current value of a store path and updates in place on every assignment. Use it inside `html` templates for read-only display; in a decorator, the same path goes to [@subscribe](/docs/decorators/subscribe). See [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { sub } from "@supersoniks/concorde/directives";
+
+render() {
+  return html`&lt;p&gt;Altitude: ${sub("cockpit.altitude")} ft&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## DataProviderKey
+
+Pass a [DataProviderKey](/docs/misc/dataProviderKey) instead of a string to get a typo-safe path. Until the publisher holds a value, nothing is rendered.
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+const flightKey = new DataProviderKey&lt;{ code: string; gate: string }&gt;("flight");
+
+render() {
+  return html`&lt;p&gt;${sub(flightKey.code)} · gate ${sub(flightKey.gate)}&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+`${prop}` placeholders resolve from properties of the component that renders the template; the directive re-subscribes when they change. While a placeholder is `null` or `undefined`, nothing is rendered. Rules: [Dynamic paths](/docs/misc/dynamic-path). `skipEmptyPlaceholder` is not available on `sub()`.
+
+<sonic-code language="typescript">
+  <template>
+const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
+  "demoOnBoard.${seatIndex}",
+);
+
+@property({ type: Number }) seatIndex = 0;
+
+render() {
+  return html`&lt;strong&gt;${sub(personKey.name)}&lt;/strong&gt; · ${sub(personKey.role)}`;
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-sub-template"></docs-demo-sources>
+    <demo-sub-template></demo-sub-template>
+  </template>
+</sonic-code>
+
+## sub() or get()
+
+`get(path)` from `@supersoniks/concorde/utils` returns a one-time snapshot: in a template it never updates. Use `sub()` in templates and `get` / `set` / `dp` in imperative code.
+
+<sonic-code language="typescript">
+  <template>
+html`${sub(flightKey.gate)}`; // updates on gate change
+html`${get(flightKey.gate)}`; // frozen at first render
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `path` | `string` or `DataProviderKey<T, U>` | Path to read. Placeholders resolve on the template host |
+
+The directive subscribes when its part connects and unsubscribes when it disconnects.

package/src/docs/directives/t.md

@@ -0,0 +1,73 @@
+# t()
+
+Lit directive that renders a translated label by key. Keys are batched into one GET to the endpoint set by the nearest `wordingProvider` ancestor attribute, and results are cached in `localStorage`.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { t } from "@supersoniks/concorde/directives/Wording";
+  </template>
+</sonic-code>
+
+`wording` and `w` are aliases of `t`. In plain HTML, use the [`sonic-t`](/core/components/functional/translation) element.
+
+## Usage
+
+Set `serviceURL` and `wordingProvider` on the host component or one of its ancestors, then call `t(key)` in a template. Attributes on elements **inside** the component's own template are not read. Click the button to bump the version and reload the labels.
+
+<docs-lit-demo for="docs-api-config-wording-demo"></docs-lit-demo>
+
+## Endpoint contract
+
+All keys requested in the same tick are sent in one request, appended to `wordingProvider` as `labels[]`:
+
+<sonic-code language="shell">
+  <template>
+GET {serviceURL}/wording/labels?lang=fr&labels[]=greeting&labels[]=farewell
+  </template>
+</sonic-code>
+
+The response is a flat map of key to label:
+
+<sonic-code language="json">
+  <template>
+{ "greeting": "Bonjour", "farewell": "Au revoir" }
+  </template>
+</sonic-code>
+
+Until the label arrives, `t()` renders an empty string.
+
+## HTML labels
+
+`t()` escapes the label. Use `unsafeWording(key)` for labels that contain trusted HTML.
+
+<sonic-code language="typescript">
+  <template>
+import { unsafeWording } from "@supersoniks/concorde/directives/Wording";
+
+html`&lt;p&gt;${unsafeWording("terms.notice")}&lt;/p&gt;`;
+  </template>
+</sonic-code>
+
+## Reloading labels
+
+Labels are fetched again when:
+
+- the `lang` attribute of `<html>` changes
+- the number stored at `wordingVersionProvider` changes — bump it after publishing new labels to invalidate the `localStorage` cache
+
+## API reference
+
+| Function | Description |
+|----------|-------------|
+| `t(key)` · `wording(key)` · `w(key)` | Renders the escaped label for `key` |
+| `unsafeWording(key)` | Renders the label as HTML |
+| `isWordingReady(key)` | `true` once the label for `key` is loaded |
+
+| Ancestor attribute | Description |
+|--------------------|-------------|
+| `wordingProvider` | Endpoint path and query, relative to `serviceURL` |
+| `wordingVersionProvider` | DataProvider path holding a version number |
+
+Other ancestor attributes (`serviceURL`, `token`, …) apply as for any request: see [API configuration](/docs/misc/api-configuration).

package/src/docs/docs-location.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { docsPageHref, docsPagePath, parseDocsLocation } from "./docs-location";
+
+describe("docsPagePath / docsPageHref", () => {
+  it("builds pretty public pathnames", () => {
+    expect(docsPagePath("docs/getting-started/start.md")).toBe(
+      "/docs/getting-started/start",
+    );
+    expect(docsPageHref("core/components/ui/button/button.md")).toBe(
+      "/core/components/ui/button",
+    );
+    expect(docsPageHref("docs/decorators/get.md", "options")).toBe(
+      "/docs/decorators/get#options",
+    );
+    expect(
+      docsPagePath("core/components/functional/sdui/sdui-extension-points.md"),
+    ).toBe("/core/components/functional/sdui/sdui-extension-points");
+  });
+});
+
+describe("parseDocsLocation", () => {
+  it("maps root site pages to their markdown", () => {
+    const r = parseDocsLocation("/about");
+    expect(r.url).toBe("about.md");
+    expect(r.pagePath).toBe("/about");
+    expect(parseDocsLocation("/privacy#your-rights").anchor).toBe("your-rights");
+    expect(parseDocsLocation("/about/").url).toBe("about.md");
+    expect(parseDocsLocation("/developers").url).toBe("");
+    expect(parseDocsLocation("/unknown").url).toBe("");
+  });
+
+  it("parses pretty pathname doc URLs", () => {
+    const r = parseDocsLocation("/docs/getting-started/start");
+    expect(r.url).toBe("docs/getting-started/start.md");
+    expect(r.pagePath).toBe("/docs/getting-started/start");
+    expect(r.anchor).toBe("");
+  });
+
+  it("parses pretty component paths and heading fragments", () => {
+    const r = parseDocsLocation("/core/components/ui/button#Size");
+    expect(r.url).toBe("core/components/ui/button.md");
+    expect(r.anchor).toBe("Size");
+    expect(r.pagePath).toBe("/core/components/ui/button");
+  });
+
+  it("treats / as home", () => {
+    const r = parseDocsLocation("/");
+    expect(r.url).toBe("");
+    expect(r.pagePath).toBe("/");
+  });
+
+  it("ignores raw .md / .html file URLs (not SPA routes)", () => {
+    expect(parseDocsLocation("/docs/getting-started/start.md").url).toBe("");
+    expect(parseDocsLocation("/docs/getting-started/start.html").url).toBe("");
+  });
+});

package/src/docs/docs-location.ts

@@ -1,54 +1,155 @@
-/** 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.
+ * Docs site URLs use the pathname (pushState):
+ *   /docs/getting-started/start
+ *   /core/components/ui/button
+ * Optional fragment for in-page headings or router demos:
+ *   /core/components/functional/router#departures
+ *
+ * Docs markdown paths match the public URL; components keep `…/name/name.md` on disk.
  */
+
+import {
+  SITE_PAGE_SLUGS,
+  toPublicMdRel,
+  toPublicPath,
+  toSourceId,
+} from "../../scripts/docs-public-url.mjs";
+
+/** Pathname for a markdown file under `src/` (with or without `.md`). */
+export function docsPagePath(mdRel: string): string {
+  return toPublicPath(mdRel);
+}
+
+/** Full href for a doc page, optional heading / demo fragment. */
+export function docsPageHref(mdRel: string, fragment?: string): string {
+  const path = docsPagePath(mdRel);
+  if (!fragment) return path;
+  return `${path}#${fragment.replace(/^#/, "")}`;
+}
+
+/** Doc page path for `router.md` (pathname; demos append `#subRoute`). */
+export const DOC_ROUTER_PAGE_PATH = docsPagePath(
+  "core/components/functional/router/router.md",
+);
+
+/** @deprecated Use DOC_ROUTER_PAGE_PATH */
+export const DOC_ROUTER_PAGE_HASH = DOC_ROUTER_PAGE_PATH;
+
 export function parseDocsLocation(location: string): {
-  /** Path for markdown fetch (no leading `#`). */
+  /** Path for markdown fetch (public `….md`, no leading `/`). */
   url: string;
-  /** Page anchor (last segment before demo sub-hash). */
+  /** In-page heading id or demo sub-route (from `#…`, no leading `#`). */
   anchor: string;
-  /** In-page route segment after a second `#` (router demos). */
+  /** Same as `anchor` when used for sonic-router demos. */
   demoSubHash: string;
-  /** Full doc page hash including anchor, without demo sub-hash. */
+  /** Canonical page pathname (no hash), e.g. `/docs/getting-started/start`. */
+  pagePath: string;
+  /** @deprecated Prefer `pagePath`; kept for older call sites. */
   pageHash: string;
 } {
-  const sharpIdx = location.indexOf("#");
-  if (sharpIdx < 0) {
-    return { url: "", anchor: "", demoSubHash: "", pageHash: "" };
+  const empty = {
+    url: "",
+    anchor: "",
+    demoSubHash: "",
+    pagePath: "",
+    pageHash: "",
+  };
+
+  let pathname = "";
+  let hash = "";
+
+  if (/^https?:\/\//i.test(location) || location.startsWith("/")) {
+    try {
+      const base =
+        typeof document !== "undefined" && document.location?.origin
+          ? document.location.origin
+          : "https://concorde.supersoniks.org";
+      const u = new URL(location, base);
+      pathname = u.pathname;
+      hash = u.hash.replace(/^#/, "");
+    } catch {
+      return empty;
+    }
+  } else if (location.startsWith("#")) {
+    hash = location.slice(1);
+  } else {
+    const sharp = location.indexOf("#");
+    if (sharp >= 0) {
+      pathname = location.slice(0, sharp);
+      hash = location.slice(sharp + 1);
+    } else {
+      pathname = location;
+    }
+  }
+
+  pathname = pathname.replace(/\/index\.html$/i, "") || "/";
+  if (pathname !== "/" && pathname.endsWith("/")) {
+    pathname = pathname.slice(0, -1);
+  }
+
+  if (pathname === "/" || pathname === "") {
+    return { ...empty, pagePath: "/", 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);
+  if (
+    pathname.startsWith("/assets/") ||
+    pathname.startsWith("/crawl/") ||
+    pathname.startsWith("/src/") ||
+    pathname.startsWith("/hubs/") ||
+    pathname.endsWith(".md") ||
+    pathname.endsWith(".mdx") ||
+    pathname.endsWith(".html") ||
+    pathname === "/llms.txt" ||
+    pathname === "/llms-full.txt" ||
+    pathname === "/sitemap.xml" ||
+    pathname === "/robots.txt"
+  ) {
+    return empty;
   }
 
-  const parts = hashBody.split("/").filter(Boolean);
-  const anchor = decodeURIComponent(parts.pop() || "");
-  const url = parts.join("/");
+  const rel = pathname.replace(/^\//, "");
+  if (SITE_PAGE_SLUGS.includes(rel)) {
+    return {
+      url: `${rel}.md`,
+      anchor: hash,
+      demoSubHash: hash,
+      pagePath: pathname,
+      pageHash: pathname,
+    };
+  }
+  if (!rel || !isDocsContentPath(rel)) {
+    return empty;
+  }
+
+  const sourceId = toSourceId(rel);
+  const pagePath = toPublicPath(sourceId);
+  const url = toPublicMdRel(sourceId);
 
   return {
     url,
-    anchor,
-    demoSubHash,
-    pageHash: hashBody ? `#${hashBody}` : "",
+    anchor: hash,
+    demoSubHash: hash,
+    pagePath,
+    pageHash: pagePath,
   };
 }
 
-/** Navigate inside the current doc page without reloading markdown. */
-export function setDocsDemoSubHash(subRoute: string, pageHash?: string): void {
+function isDocsContentPath(rel: string): boolean {
+  return (
+    rel.startsWith("docs/") ||
+    rel.startsWith("core/components/") ||
+    rel.startsWith("core/")
+  );
+}
+
+/** Navigate inside the current doc page without reloading markdown (router demos). */
+export function setDocsDemoSubHash(subRoute: string, pagePath?: string): void {
   const loc = document.location;
   const base =
-    pageHash ||
-    parseDocsLocation(loc.pathname + loc.search + loc.hash).pageHash ||
-    loc.hash;
+    pagePath ||
+    parseDocsLocation(loc.pathname + loc.search + loc.hash).pagePath ||
+    loc.pathname;
   const sub = subRoute.replace(/^#/, "");
-  const nextHash = sub ? `${base}#${sub}` : base;
-  history.replaceState(history.state, "", `${loc.pathname}${loc.search}${nextHash}`);
+  const next = sub ? `${base}#${sub}` : base;
+  history.replaceState(history.state, "", `${next}`);
 }

package/src/docs/docs.ts

@@ -15,9 +15,8 @@ import "./home/home";
 import "./example/users";
 import "./example/docs-users-list";
 import "./example/docs-user-two-scopes";
-import "./example/docs-joke-demos";
+import "./example/docs-flight-demos";
 import "./example/docs-queue-demos";
-import "./example/docs-input-autocomplete-demos";
 import "./example/docs-toggle-demos";
 import "./example/docs-boarding-pass-demo";
 import "./example/docs-list-demos";