@supersoniks/concorde 5.1.0 → 5.1.2

package/src/docs/navigation/navigation.ts

@@ -1,240 +1,227 @@
 import { html, LitElement, PropertyValues } from "lit";
 import { customElement, property } from "lit/decorators.js";
+
+/** Sidebar order: strings are section titles, objects are pages. */
+export const docsNavigation: Array<string | { label: string; href: string }> = [
+  "Getting Started",
+  { label: "Introduction", href: "/docs/getting-started/start" },
+  {
+    label: "Components",
+    href: "/docs/getting-started/components",
+  },
+  {
+    label: "Installation",
+    href: "/docs/getting-started/installation",
+  },
+  {
+    label: "My first component",
+    href: "/docs/getting-started/my-first-component",
+  },
+  {
+    label: "Theming",
+    href: "/docs/getting-started/theming",
+  },
+  {
+    label: "Data flow",
+    href: "/docs/getting-started/dataFlow",
+  },
+  {
+    label: "AI agents (skills)",
+    href: "/docs/getting-started/ai-agents",
+  },
+  "Functional components",
+  { label: "Date", href: "/core/components/functional/date" },
+  {
+    label: "Fetch",
+    href: "/core/components/functional/fetch",
+  },
+  { label: "If", href: "/core/components/functional/if" },
+  { label: "List", href: "/core/components/functional/list" },
+  { label: "Mix", href: "/core/components/functional/mix" },
+  {
+    label: "Jsonata",
+    href: "/core/components/functional/jsonata",
+  },
+  {
+    label: "Queue",
+    href: "/core/components/functional/queue",
+  },
+  {
+    label: "Router",
+    href: "/core/components/functional/router",
+  },
+  { label: "SDUI", href: "/core/components/functional/sdui" },
+  {
+    label: "States",
+    href: "/core/components/functional/states",
+  },
+  {
+    label: "Submit",
+    href: "/core/components/functional/submit",
+  },
+  //{label: "Subscriber", href: "/core/components/functional/subscriber"},
+  {
+    label: "Translation",
+    href: "/core/components/functional/translation",
+  },
+  {
+    label: "Value",
+    href: "/core/components/functional/value",
+  },
+  "UI components",
+  { label: "Alert", href: "/core/components/ui/alert" },
+  { label: "Badge", href: "/core/components/ui/badge" },
+  { label: "Button", href: "/core/components/ui/button" },
+  {
+    label: "Captcha",
+    href: "/core/components/ui/captcha",
+  },
+  { label: "Card", href: "/core/components/ui/card" },
+  {
+    label: "Checkbox",
+    href: "/core/components/ui/form/checkbox",
+  },
+  {
+    label: "Divider",
+    href: "/core/components/ui/divider",
+  },
+  {
+    label: "Fieldset",
+    href: "/core/components/ui/form/fieldset",
+  },
+  {
+    label: "Form actions",
+    href: "/core/components/ui/form/form-actions",
+  },
+  {
+    label: "Form layout",
+    href: "/core/components/ui/form/form-layout",
+  },
+  { label: "Group", href: "/core/components/ui/group" },
+  { label: "Icon", href: "/core/components/ui/icon" },
+  { label: "Image", href: "/core/components/ui/image" },
+  { label: "Input", href: "/core/components/ui/form/input" },
+  { label: "Link", href: "/core/components/ui/link" },
+  { label: "Loader", href: "/core/components/ui/loader" },
+  { label: "Menu", href: "/core/components/ui/menu" },
+  { label: "Modal", href: "/core/components/ui/modal" },
+  { label: "Pop", href: "/core/components/ui/pop" },
+  {
+    label: "Progress",
+    href: "/core/components/ui/progress",
+  },
+  { label: "Radio", href: "/core/components/ui/form/radio" },
+  {
+    label: "Select",
+    href: "/core/components/ui/form/select",
+  },
+  {
+    label: "Switch",
+    href: "/core/components/ui/form/switch",
+  },
+  { label: "Table", href: "/core/components/ui/table" },
+  {
+    label: "Textarea",
+    href: "/core/components/ui/form/textarea",
+  },
+  {
+    label: "Theme",
+    href: "/core/components/ui/theme",
+  },
+  { label: "Toast", href: "/core/components/ui/toast" },
+  {
+    label: "Tooltip",
+    href: "/core/components/ui/tooltip",
+  },
+  "Decorators",
+  {
+    label: "@ancestorAttribute",
+    href: "/docs/decorators/ancestor-attribute",
+  },
+  {
+    label: "@bind",
+    href: "/docs/decorators/bind",
+  },
+  {
+    label: "@subscribe",
+    href: "/docs/decorators/subscribe",
+  },
+  {
+    label: "@handle",
+    href: "/docs/decorators/handle",
+  },
+  {
+    label: "@publish",
+    href: "/docs/decorators/publish",
+  },
+  {
+    label: "@get",
+    href: "/docs/decorators/get",
+  },
+  {
+    label: "@post",
+    href: "/docs/decorators/post",
+  },
+  {
+    label: "@put",
+    href: "/docs/decorators/put",
+  },
+  {
+    label: "@patch",
+    href: "/docs/decorators/patch",
+  },
+  {
+    label: "@onAssign",
+    href: "/docs/decorators/on-assign",
+  },
+  {
+    label: "@autoSubscribe",
+    href: "/docs/decorators/auto-subscribe",
+  },
+  {
+    label: "@awaitConnectedAncestors",
+    href: "/docs/decorators/wait-for-ancestors",
+  },
+  "Directives",
+  {
+    label: "sub()",
+    href: "/docs/directives/sub",
+  },
+  {
+    label: "t()",
+    href: "/docs/directives/t",
+  },
+  "Misc",
+  {
+    label: "DataProviderKey",
+    href: "/docs/misc/dataProviderKey",
+  },
+  {
+    label: "Endpoint",
+    href: "/docs/misc/endpoint",
+  },
+  {
+    label: "Dynamic paths",
+    href: "/docs/misc/dynamic-path",
+  },
+  {
+    label: "API configuration",
+    href: "/docs/misc/api-configuration",
+  },
+  {
+    label: "HTML integration",
+    href: "/docs/misc/html-integration",
+  },
+  {
+    label: "Local API demos",
+    href: "/docs/misc/docs-mock-api",
+  },
+];
+
 const tagName = "docs-navigation"; // For Astro.build
 @customElement(tagName)
 export class DocsNavigation extends LitElement {
-  @property() navigation = [
-    { label: "Introduction", href: "#docs/_getting-started/start.md/start" },
-    "Getting Started",
-    {
-      label: "Installation",
-      href: "#docs/_getting-started/concorde-outside.md/concorde-outside",
-    },
-    {
-      label: "AI agents (skills)",
-      href: "#docs/_getting-started/ai-agents.md/ai-agents",
-    },
-    {
-      label: "My first component",
-      href: "#docs/_getting-started/my-first-component.md/my-first-component",
-    },
-    {
-      label: "Customization",
-      href: "#docs/_getting-started/theming.md/theming",
-    },
-    "Core concept",
-    {
-      label: "Lit + Tailwind + Vite",
-      href: "#docs/_core-concept/overview.md/overview",
-    },
-    {
-      label: "Data flow",
-      href: "#docs/_core-concept/dataFlow.md/dataFlow",
-    },
-    "Functionnal components",
-    { label: "Date", href: "#core/components/functional/date/date.md/date" },
-    {
-      label: "Fetch",
-      href: "#core/components/functional/fetch/fetch.md/fetch",
-    },
-    { label: "If", href: "#core/components/functional/if/if.md/if" },
-    { label: "List", href: "#core/components/functional/list/list.md/list" },
-    { label: "Mix", href: "#core/components/functional/mix/mix.md/mix" },
-    {
-      label: "Jsonata",
-      href: "#core/components/functional/jsonata/jsonata.md/jsonata",
-    },
-    {
-      label: "Queue",
-      href: "#core/components/functional/queue/queue.md/queue",
-    },
-    {
-      label: "Router",
-      href: "#core/components/functional/router/router.md/router",
-    },
-    { label: "SDUI", href: "#core/components/functional/sdui/sdui.md/sdui" },
-    {
-      label: "States",
-      href: "#core/components/functional/states/states.md/states",
-    },
-    {
-      label: "Submit",
-      href: "#core/components/functional/submit/submit.md/submit",
-    },
-    //{label: "Subscriber", href: "#core/components/functional/subscriber/subscriber.md/subscriber"},
-    {
-      label: "Value",
-      href: "#core/components/functional/value/value.md/value",
-    },
-    "UI components",
-    { label: "Alert", href: "#core/components/ui/alert/alert.md/alert" },
-    { label: "Badge", href: "#core/components/ui/badge/badge.md/badge" },
-    { label: "Button", href: "#core/components/ui/button/button.md/button" },
-    {
-      label: "Captcha",
-      href: "#core/components/ui/captcha/captcha.md/captcha",
-    },
-    { label: "Card", href: "#core/components/ui/card/card.md/card" },
-    {
-      label: "Checkbox",
-      href: "#core/components/ui/form/checkbox/checkbox.md/checkbox",
-    },
-    {
-      label: "Divider",
-      href: "#core/components/ui/divider/divider.md/divider",
-    },
-    {
-      label: "Fieldset",
-      href: "#core/components/ui/form/fieldset/fieldset.md/fieldset",
-    },
-    {
-      label: "Form actions",
-      href: "#core/components/ui/form/form-actions/form-actions.md/form-actions",
-    },
-    {
-      label: "Form layout",
-      href: "#core/components/ui/form/form-layout/form-layout.md/form-layout",
-    },
-    { label: "Group", href: "#core/components/ui/group/group.md/group" },
-    { label: "Icon", href: "#core/components/ui/icon/icon.md/icon" },
-    { label: "Image", href: "#core/components/ui/image/image.md/image" },
-    { label: "Input", href: "#core/components/ui/form/input/input.md/input" },
-    {
-      label: "Input autocomplete",
-      href: "#core/components/ui/form/input-autocomplete/input-autocomplete.md/input-autocomplete",
-    },
-    { label: "Link", href: "#core/components/ui/link/link.md/link" },
-    { label: "Loader", href: "#core/components/ui/loader/loader.md/loader" },
-    { label: "Menu", href: "#core/components/ui/menu/menu.md/menu" },
-    { label: "Modal", href: "#core/components/ui/modal/modal.md/modal" },
-    { label: "Pop", href: "#core/components/ui/pop/pop.md/pop" },
-    {
-      label: "Progress",
-      href: "#core/components/ui/progress/progress.md/progress",
-    },
-    { label: "Radio", href: "#core/components/ui/form/radio/radio.md/radio" },
-    {
-      label: "Select",
-      href: "#core/components/ui/form/select/select.md/select",
-    },
-    {
-      label: "Switch",
-      href: "#core/components/ui/form/switch/switch.md/switch",
-    },
-    { label: "Table", href: "#core/components/ui/table/table.md/table" },
-    {
-      label: "Textarea",
-      href: "#core/components/ui/form/textarea/textarea.md/textarea",
-    },
-    {
-      label: "Theme",
-      href: "#core/components/ui/theme/theme.md/theme",
-    },
-    { label: "Toast", href: "#core/components/ui/toast/toast.md/toast" },
-    {
-      label: "Tooltip",
-      href: "#core/components/ui/tooltip/tooltip.md/tooltip",
-    },
-    "Decorators",
-    {
-      label: "@ancestorAttribute",
-      href: "#docs/_decorators/ancestor-attribute.md/ancestor-attribute",
-    },
-    {
-      label: "@bind",
-      href: "#docs/_decorators/bind.md/bind",
-    },
-    {
-      label: "@subscribe",
-      href: "#docs/_decorators/subscribe.md/subscribe",
-    },
-    {
-      label: "@handle",
-      href: "#docs/_decorators/handle.md/handle",
-    },
-    {
-      label: "@publish",
-      href: "#docs/_decorators/publish.md/publish",
-    },
-    {
-      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",
-    },
-    {
-      label: "@autoSubscribe",
-      href: "#docs/_decorators/auto-subscribe.md/auto-subscribe",
-    },
-    {
-      label: "@awaitConnectedAncestors",
-      href: "#docs/_decorators/wait-for-ancestors.md/wait-for-ancestors",
-    },
-    "Misc",
-    {
-      label: "DataProviderKey",
-      href: "#docs/_misc/dataProviderKey.md/dataProviderKey",
-    },
-    {
-      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",
-    },
-    {
-      label: "sub()",
-      href: "#docs/_directives/sub.md/sub",
-    },
-    {
-      label: "HTML integration",
-      href: "#docs/_misc/html-integration.md/html-integration",
-    },
-    {
-      label: "FormElement / Subscriber removal",
-      href: "#docs/_misc/formelement-subscriber-removal.md/formelement-subscriber-removal",
-    },
-    {
-      label: "Local API demos",
-      href: "#docs/_misc/docs-mock-api.md/docs-mock-api",
-    },
-    "Legacy",
-    {
-      label: "Manual installation (Vite)",
-      href: "#docs/_getting-started/concorde-manual-install.md/concorde-manual-install",
-    },
-    {
-      label: "Subscriber mixin",
-      href: "#docs/_core-concept/subscriber.md/subscriber",
-    },
-    {
-      label: "Sharing data (Publisher)",
-      href: "#docs/_getting-started/pubsub.md/pubsub",
-    },
-    {
-      label: "My first subscriber",
-      href: "#docs/_getting-started/my-first-subscriber.md/my-first-subscriber",
-    },
-  ];
+  @property({ attribute: false }) navigation = docsNavigation;
 
   /**
    * Save the scroll position when the component is disconnected

package/src/docs/navigation/pager.ts

@@ -0,0 +1,67 @@
+import { html, LitElement, nothing } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import { parseDocsLocation } from "../docs-location";
+import { tailwind } from "../tailwind";
+import { docsNavigation } from "./navigation";
+import { DOCS_PAGE_RENDERED } from "./toc";
+
+type Page = { label: string; href: string };
+
+const pages = docsNavigation.filter((item): item is Page => typeof item !== "string");
+const pageUrl = (href: string) => parseDocsLocation(href).url;
+
+const tagName = "docs-pager";
+/** Previous / next page links, following the sidebar order. */
+@customElement(tagName)
+export class DocsPager extends LitElement {
+  static styles = [tailwind];
+
+  @state() index = -1;
+
+  connectedCallback() {
+    super.connectedCallback();
+    window.addEventListener(DOCS_PAGE_RENDERED, this.locate);
+    this.locate();
+  }
+
+  disconnectedCallback() {
+    window.removeEventListener(DOCS_PAGE_RENDERED, this.locate);
+    super.disconnectedCallback();
+  }
+
+  private locate = () => {
+    const current = parseDocsLocation(document.location.href).url;
+    this.index = pages.findIndex((p) => pageUrl(p.href) === current);
+  };
+
+  private link(page: Page | undefined, direction: "previous" | "next") {
+    if (!page) return html`<div class="hidden sm:block"></div>`;
+    const next = direction === "next";
+    return html`<sonic-button
+      variant="outline"
+      size="lg"
+      shape="block"
+      pushState
+      align=${next ? "right" : "left"}
+      href=${page.href}
+      @click=${() => window.scrollTo({ top: 0, behavior: "instant" })}
+    >
+      <sonic-icon
+        slot=${next ? "suffix" : "prefix"}
+        name=${next ? "arrow-right" : "arrow-left"}
+        library="iconoir"
+      ></sonic-icon>
+      ${page.label}
+    </sonic-button>`;
+  }
+
+  render() {
+    if (this.index < 0) return nothing;
+    return html`
+      <div class="grid grid-cols-[minmax(0,1fr)] sm:grid-cols-2 gap-3">
+        ${this.link(pages[this.index - 1], "previous")}
+        ${this.link(pages[this.index + 1], "next")}
+      </div>
+    `;
+  }
+}

package/src/docs/navigation/toc.ts

@@ -0,0 +1,101 @@
+import { html, LitElement, nothing } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import { parseDocsLocation } from "../docs-location";
+
+/** Fired on window by `docs-markdown-renderer` once a page is in the DOM. */
+export const DOCS_PAGE_RENDERED = "docs-page-rendered";
+
+type TocEntry = { id: string; label: string };
+
+const tagName = "docs-toc";
+/**
+ * "On this page" navigation: lists the h2 of the rendered markdown
+ * and highlights the section currently in view.
+ */
+@customElement(tagName)
+export class DocsToc extends LitElement {
+  @state() entries: TocEntry[] = [];
+  @state() activeId = "";
+
+  private observer?: IntersectionObserver;
+  private visible = new Set<string>();
+
+  connectedCallback() {
+    super.connectedCallback();
+    window.addEventListener(DOCS_PAGE_RENDERED, this.collect);
+    this.collect();
+  }
+
+  disconnectedCallback() {
+    window.removeEventListener(DOCS_PAGE_RENDERED, this.collect);
+    this.observer?.disconnect();
+    super.disconnectedCallback();
+  }
+
+  private headings(): HTMLElement[] {
+    return Array.from(
+      document.querySelectorAll<HTMLElement>("docs-markdown-renderer h2[id]"),
+    ).filter((h) => !h.closest("sonic-code, docs-lit-demo, docs-demo-sources"));
+  }
+
+  private collect = () => {
+    const headings = this.headings();
+    this.entries = headings.map((h) => ({
+      id: h.id,
+      label: h.textContent?.trim() || h.id,
+    }));
+    this.activeId = this.entries[0]?.id || "";
+
+    this.observer?.disconnect();
+    this.visible.clear();
+    this.observer = new IntersectionObserver(
+      (records) => {
+        records.forEach((r) => {
+          if (r.isIntersecting) this.visible.add(r.target.id);
+          else this.visible.delete(r.target.id);
+        });
+        const first = this.entries.find((e) => this.visible.has(e.id));
+        if (first) this.activeId = first.id;
+      },
+      { rootMargin: "-80px 0px -55% 0px" },
+    );
+    headings.forEach((h) => this.observer?.observe(h));
+  };
+
+  private goTo(id: string) {
+    const target = document.getElementById(id);
+    if (!target) return;
+    this.activeId = id;
+    target.scrollIntoView({ behavior: "smooth", block: "start" });
+    // Keep the URL shareable without triggering a markdown reload.
+    const { pagePath } = parseDocsLocation(document.location.href);
+    if (pagePath && pagePath !== "/") {
+      history.replaceState(
+        history.state,
+        "",
+        `${pagePath}#${encodeURIComponent(id)}`,
+      );
+    }
+  }
+
+  render() {
+    if (this.entries.length < 2) return nothing;
+    return html`
+      <sonic-divider class="uppercase" align="left" size="xs"
+        >On this page</sonic-divider
+      >
+      <sonic-menu size="xs">
+        ${this.entries.map(
+          (e) => html`<sonic-menu-item
+            type="neutral"
+            size="xs"
+            ?active=${e.id === this.activeId}
+            @click=${() => this.goTo(e.id)}
+            >${e.label}</sonic-menu-item
+          >`,
+        )}
+      </sonic-menu>
+    `;
+  }
+}
+