@supersoniks/concorde 4.5.2 → 4.7.0

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,
+};

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>
+  `;
+}