@x12i/connectix-docs 0.1.0 → 0.1.2

package/dist/web/app.js

@@ -22,6 +22,20 @@ function loadSite() {
   return loadJson("/site.json");
 }
 
+function loadSequences() {
+  return loadJson("/sequences.json").then((d) => d.sequences || d);
+}
+
+function loadChapters(bookId, audience) {
+  return loadJson(
+    "/downloads/books/" +
+      encodeURIComponent(bookId) +
+      "/" +
+      encodeURIComponent(audience) +
+      ".chapters.json",
+  );
+}
+
 function escapeHtml(s) {
   return String(s).replace(/[&<>"']/g, (c) =>
     ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c],
@@ -149,6 +163,135 @@ function hydrateUseCases(root) {
   });
 }
 
+function readHref(bookId, audience, chapter) {
+  return (
+    "/read?book=" +
+    encodeURIComponent(bookId) +
+    "&role=" +
+    encodeURIComponent(audience) +
+    (chapter ? "#" + encodeURIComponent(chapter) : "")
+  );
+}
+
+/* Compact chapter index into one book (tutorials section). */
+function hydrateTutorials(section) {
+  const bookId = section.getAttribute("data-book");
+  const audience = section.getAttribute("data-audience") || "developers";
+  const root = section.querySelector(".tutorials-root");
+  if (!bookId || !root) return;
+  loadChapters(bookId, audience)
+    .then((chapters) => {
+      const items = (chapters || [])
+        .filter((c) => c.slug !== "preamble")
+        .map(
+          (c, i) =>
+            `<li><span class="step-num">${i + 1}</span><span class="step-text"><a href="${readHref(bookId, audience, c.slug)}">${escapeHtml(c.title)}</a></span></li>`,
+        )
+        .join("");
+      root.innerHTML = `<ol class="step-list tutorials-list">${items}</ol>`;
+    })
+    .catch(() => {
+      /* keep the static "Start reading" fallback */
+    });
+}
+
+/* Interactive journey: ordered steps (required vs optional) → book chapters. */
+function hydrateJourney(root) {
+  Promise.all([loadSequences(), loadCatalog(), loadSite()]).then(
+    ([sequences, catalog, site]) => {
+      if (site.accent) document.body.style.setProperty("--accent", site.accent);
+      if (site.accentAlt)
+        document.body.style.setProperty("--accent-alt", site.accentAlt);
+
+      const bookTitle = (id) => {
+        const b = catalog.books.find((x) => x.id === id);
+        return b ? b.title : id;
+      };
+
+      let audienceFilter = "all";
+
+      const stepLinks = (step) =>
+        (step.links || [])
+          .filter(
+            (l) => audienceFilter === "all" || l.audience === audienceFilter,
+          )
+          .map((l) => {
+            const alt = l.audience === "builders";
+            const label =
+              l.label ||
+              bookTitle(l.bookId) + " — " + roleLabel(catalog, l.audience);
+            return `<a class="journey-link ${alt ? "alt" : ""}" href="${readHref(l.bookId, l.audience, (l.chapters || [])[0])}">${escapeHtml(label)} →</a>`;
+          })
+          .join("");
+
+      const render = () => {
+        const html = sequences
+          .map((seq) => {
+            const steps = (seq.steps || [])
+              .filter(
+                (s) =>
+                  audienceFilter === "all" ||
+                  !s.audience ||
+                  s.audience === audienceFilter,
+              )
+              .map((s, i) => {
+                const links = stepLinks(s);
+                const cls = s.required === false ? "journey-step optional" : "journey-step";
+                return `<li class="${cls}">
+  <button type="button" class="journey-step-head" data-journey-toggle aria-expanded="false">
+    <span class="journey-num">${i + 1}</span>
+    <span class="journey-label">${escapeHtml(s.label)}</span>
+    <span class="journey-flag">${s.required === false ? "optional" : "required"}</span>
+  </button>
+  <div class="journey-panel" hidden>
+    ${s.summary ? `<p class="journey-summary">${escapeHtml(s.summary)}</p>` : ""}
+    <div class="journey-links">${links || `<span class="journey-nolinks">No ${escapeHtml(audienceFilter)} chapter for this step — switch the filter.</span>`}</div>
+  </div>
+</li>`;
+              })
+              .join("");
+            return `<div class="journey-seq">
+  <h2 class="journey-title">${escapeHtml(seq.title)}</h2>
+  ${seq.lead ? `<p class="journey-lead">${escapeHtml(seq.lead)}</p>` : ""}
+  <ol class="journey-steps">${steps}</ol>
+</div>`;
+          })
+          .join("");
+
+        const filters = ["all", "developers", "builders"]
+          .map(
+            (f) =>
+              `<button type="button" class="journey-filter ${f === audienceFilter ? "active" : ""} ${f === "builders" ? "alt" : ""}" data-journey-filter="${f}">${f === "all" ? "All" : escapeHtml(roleLabel(catalog, f))}</button>`,
+          )
+          .join("");
+
+        root.innerHTML = `<div class="journey-toolbar"><span class="journey-toolbar-label">Show steps for</span>${filters}</div>${html}`;
+
+        root.querySelectorAll("[data-journey-toggle]").forEach((btn) => {
+          btn.addEventListener("click", () => {
+            const panel = btn.parentElement.querySelector(".journey-panel");
+            const open = !panel.hidden;
+            panel.hidden = open;
+            btn.setAttribute("aria-expanded", String(!open));
+            btn.parentElement.classList.toggle("open", !open);
+          });
+        });
+        root.querySelectorAll("[data-journey-filter]").forEach((btn) => {
+          btn.addEventListener("click", () => {
+            audienceFilter = btn.getAttribute("data-journey-filter");
+            render();
+          });
+        });
+      };
+
+      render();
+    },
+  ).catch(() => {
+    root.innerHTML =
+      '<p class="journey-loading">No journey published for this library yet.</p>';
+  });
+}
+
 function hydratePage(kind) {
   bindNavToggle();
   if (kind === "catalog") {
@@ -159,6 +302,312 @@ function hydratePage(kind) {
     const root = document.getElementById("use-cases-root");
     if (root) hydrateUseCases(root);
   }
+  if (kind === "journey") {
+    const root = document.getElementById("journey-root");
+    if (root) hydrateJourney(root);
+  }
+  document
+    .querySelectorAll('[data-hydrate="tutorials"]')
+    .forEach((section) => hydrateTutorials(section));
+  document
+    .querySelectorAll("[data-diagram-id]")
+    .forEach((el) => hydrateDiagram(el));
+  const searchRoot = document.getElementById("search-root");
+  if (searchRoot) hydrateSearch(searchRoot);
+}
+
+function hydrateSearch(root) {
+  root.innerHTML = `
+    <label class="search-label" for="docify-search">Search knowledge</label>
+    <input id="docify-search" type="search" class="search-input" placeholder="Concept, guide, diagram, API…" autocomplete="off" />
+    <div class="search-filters" role="group" aria-label="Filter by type">
+      <button type="button" class="journey-filter active" data-search-type="">All</button>
+      <button type="button" class="journey-filter" data-search-type="concept">Concepts</button>
+      <button type="button" class="journey-filter" data-search-type="guide">Guides</button>
+      <button type="button" class="journey-filter" data-search-type="scenario">Scenarios</button>
+      <button type="button" class="journey-filter" data-search-type="diagram">Diagrams</button>
+      <button type="button" class="journey-filter" data-search-type="use-case">Use cases</button>
+    </div>
+    <ul class="search-results" id="search-results" aria-live="polite"></ul>`;
+  let type = "";
+  let index = { records: [] };
+  loadJson("/SEARCH.json")
+    .catch(() => loadJson("/agent/SEARCH.json"))
+    .then((data) => {
+      index = data || { records: [] };
+    })
+    .catch(() => {});
+
+  const render = () => {
+    const q = (document.getElementById("docify-search").value || "").trim().toLowerCase();
+    let records = index.records || [];
+    if (type) records = records.filter((r) => r.type === type);
+    if (q) {
+      records = records.filter((r) =>
+        `${r.id} ${r.title} ${r.summary} ${(r.aliases || []).join(" ")} ${(r.tags || []).join(" ")}`
+          .toLowerCase()
+          .includes(q),
+      );
+    }
+    const ul = document.getElementById("search-results");
+    if (!records.length) {
+      ul.innerHTML = "<li class='search-empty'>No matches.</li>";
+      return;
+    }
+    ul.innerHTML = records
+      .slice(0, 40)
+      .map((r) => {
+        const href = r.webPath || ("/" + String(r.path || "").replace(/\.md$/, ""));
+        return `<li><a href="${escapeHtml(href)}"><span class="search-type">${escapeHtml(r.type)}</span> <strong>${escapeHtml(r.title)}</strong> — ${escapeHtml(r.summary)}</a></li>`;
+      })
+      .join("");
+  };
+
+  document.getElementById("docify-search").addEventListener("input", render);
+  root.querySelectorAll("[data-search-type]").forEach((btn) => {
+    btn.addEventListener("click", () => {
+      type = btn.getAttribute("data-search-type") || "";
+      root.querySelectorAll("[data-search-type]").forEach((b) => b.classList.toggle("active", b === btn));
+      render();
+    });
+  });
+}
+
+/**
+ * Accessible diagram: list + table views always; spatial SVG when nodes/edges exist.
+ * Never relies on color alone; keyboard-focusable nodes.
+ */
+function hydrateDiagram(el) {
+  const id = el.getAttribute("data-diagram-id");
+  const load = () =>
+    loadJson("/knowledge.json")
+      .then((k) => (k.diagrams || []).find((d) => d.id === id))
+      .catch(() => null);
+
+  load().then((diagram) => {
+    if (!diagram) {
+      el.innerHTML = "<p>Diagram not found.</p>";
+      return;
+    }
+    let view = "diagram";
+    const render = () => {
+      const tabs = ["diagram", "list", "table", "steps"]
+        .map(
+          (v) =>
+            `<button type="button" class="journey-filter ${v === view ? "active" : ""}" data-diagram-view="${v}">${v}</button>`,
+        )
+        .join("");
+      let body = "";
+      if (view === "list" || view === "steps") {
+        body =
+          `<ol class="diagram-list">` +
+          (diagram.nodes || [])
+            .map(
+              (n) =>
+                `<li tabindex="0"><strong>${escapeHtml(n.label)}</strong>${n.description ? " — " + escapeHtml(n.description) : ""}${n.conceptId ? ` · concept <code>${escapeHtml(n.conceptId)}</code>` : ""}</li>`,
+            )
+            .join("") +
+          `</ol>`;
+      } else if (view === "table") {
+        body =
+          `<table class="diagram-table"><caption>${escapeHtml(diagram.title)} relationships</caption><thead><tr><th>From</th><th>To</th><th>Label</th><th>Meaning</th></tr></thead><tbody>` +
+          (diagram.edges || [])
+            .map(
+              (e) =>
+                `<tr><td>${escapeHtml(e.from)}</td><td>${escapeHtml(e.to)}</td><td>${escapeHtml(e.label || "")}</td><td>${escapeHtml(e.description || "")}</td></tr>`,
+            )
+            .join("") +
+          `</tbody></table>`;
+      } else {
+        const nodes = diagram.nodes || [];
+        const w = Math.max(320, nodes.length * 140);
+        const h = 180;
+        const circles = nodes
+          .map((n, i) => {
+            const x = 60 + i * 140;
+            const y = 90;
+            return `<g tabindex="0" role="img" aria-label="${escapeHtml(n.label)}. ${escapeHtml(n.description || "")}">
+              <circle cx="${x}" cy="${y}" r="28" fill="var(--surface, #fff)" stroke="currentColor" stroke-width="2" />
+              <text x="${x}" y="${y + 4}" text-anchor="middle" font-size="11">${escapeHtml(n.label).slice(0, 12)}</text>
+            </g>`;
+          })
+          .join("");
+        const lines = (diagram.edges || [])
+          .map((e) => {
+            const fi = nodes.findIndex((n) => n.id === e.from);
+            const ti = nodes.findIndex((n) => n.id === e.to);
+            if (fi < 0 || ti < 0) return "";
+            const x1 = 60 + fi * 140;
+            const x2 = 60 + ti * 140;
+            return `<line x1="${x1 + 28}" y1="90" x2="${x2 - 28}" y2="90" stroke="currentColor" stroke-width="2" marker-end="url(#arrow)" />`;
+          })
+          .join("");
+        body = `<div class="diagram-spatial" role="region" aria-label="${escapeHtml(diagram.title)}">
+          <svg viewBox="0 0 ${w} ${h}" width="100%" height="${h}" role="img" aria-describedby="diagram-alt-${escapeHtml(diagram.id)}">
+            <defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="currentColor"/></marker></defs>
+            ${lines}${circles}
+          </svg>
+        </div>`;
+      }
+      el.innerHTML = `
+        <section class="diagram-block">
+          <header>
+            <h2>${escapeHtml(diagram.title)}</h2>
+            <p>${escapeHtml(diagram.summary)}</p>
+            <p><strong>Why:</strong> ${escapeHtml(diagram.why)}</p>
+            <p><strong>How to read:</strong> ${escapeHtml(diagram.howToRead)}</p>
+          </header>
+          <div class="diagram-toolbar" role="toolbar" aria-label="Diagram views">${tabs}</div>
+          ${body}
+          <p id="diagram-alt-${escapeHtml(diagram.id)}" class="diagram-text-alt"><strong>Text alternative:</strong> ${escapeHtml(diagram.textAlternative)}</p>
+          ${(diagram.keyTakeaways || []).length ? `<ul>${diagram.keyTakeaways.map((t) => `<li>${escapeHtml(t)}</li>`).join("")}</ul>` : ""}
+          ${diagram.mermaid ? `<details><summary>Mermaid source</summary><pre><code>${escapeHtml(diagram.mermaid)}</code></pre></details>` : ""}
+        </section>`;
+      el.querySelectorAll("[data-diagram-view]").forEach((btn) => {
+        btn.addEventListener("click", () => {
+          view = btn.getAttribute("data-diagram-view");
+          render();
+        });
+      });
+    };
+    render();
+  });
+}
+
+function hydrateRelationshipExplorer(root, panel) {
+  if (!root || !panel) return;
+  let view = "list";
+  let focusId = new URLSearchParams(location.search).get("id") || "";
+  let knowledge = { relationships: [] };
+
+  const render = () => {
+    const rels = knowledge.relationships || [];
+    const filtered = focusId
+      ? rels.filter((r) => r.from === focusId || r.to === focusId)
+      : rels;
+    root.innerHTML =
+      '<label for="explore-focus">Focus id</label>' +
+      '<input id="explore-focus" type="search" class="search-input" value="' +
+      escapeHtml(focusId) +
+      '" placeholder="concept or guide id" />' +
+      '<p class="muted">' +
+      filtered.length +
+      " declared relationship(s)</p>";
+    const input = document.getElementById("explore-focus");
+    input.addEventListener("change", (e) => {
+      focusId = e.target.value.trim();
+      const u = new URL(location.href);
+      if (focusId) u.searchParams.set("id", focusId);
+      else u.searchParams.delete("id");
+      history.replaceState(null, "", u);
+      render();
+    });
+
+    if (view === "table") {
+      panel.innerHTML =
+        '<table class="diagram-table"><caption>Declared relationships</caption><thead><tr><th>Type</th><th>From</th><th>To</th><th>Label</th></tr></thead><tbody>' +
+        filtered
+          .map(
+            (r) =>
+              "<tr><td>" +
+              escapeHtml(String(r.type)) +
+              '</td><td><a href="/explore?id=' +
+              encodeURIComponent(r.from) +
+              '">' +
+              escapeHtml(r.from) +
+              '</a></td><td><a href="/explore?id=' +
+              encodeURIComponent(r.to) +
+              '">' +
+              escapeHtml(r.to) +
+              "</a></td><td>" +
+              escapeHtml(r.label || r.description || "") +
+              "</td></tr>",
+          )
+          .join("") +
+        "</tbody></table>";
+    } else if (view === "diagram") {
+      const nodes = Array.from(new Set(filtered.flatMap((r) => [r.from, r.to])));
+      panel.innerHTML =
+        '<div class="diagram-spatial" role="region" aria-label="Relationship map"><svg viewBox="0 0 ' +
+        Math.max(320, nodes.length * 120) +
+        ' 160" width="100%" height="160">' +
+        nodes
+          .map((id, i) => {
+            const x = 50 + i * 120;
+            return (
+              '<g tabindex="0" role="img" aria-label="' +
+              escapeHtml(id) +
+              '"><circle cx="' +
+              x +
+              '" cy="80" r="24" fill="var(--surface,#fff)" stroke="currentColor" stroke-width="2"/><text x="' +
+              x +
+              '" y="84" text-anchor="middle" font-size="10">' +
+              escapeHtml(id).slice(0, 10) +
+              "</text></g>"
+            );
+          })
+          .join("") +
+        filtered
+          .map((r) => {
+            const a = nodes.indexOf(r.from);
+            const b = nodes.indexOf(r.to);
+            if (a < 0 || b < 0) return "";
+            return (
+              '<line x1="' +
+              (50 + a * 120) +
+              '" y1="80" x2="' +
+              (50 + b * 120) +
+              '" y2="80" stroke="currentColor" stroke-width="2"/>'
+            );
+          })
+          .join("") +
+        '</svg><p class="diagram-text-alt">Text alternative: ' +
+        (filtered.map((r) => r.from + " " + r.type + " " + r.to).join("; ") ||
+          "No relationships") +
+        ".</p></div>";
+    } else {
+      panel.innerHTML =
+        '<ul class="search-results">' +
+        (filtered
+          .map(
+            (r) =>
+              "<li><code>" +
+              escapeHtml(String(r.type)) +
+              '</code> <a href="/explore?id=' +
+              encodeURIComponent(r.from) +
+              '">' +
+              escapeHtml(r.from) +
+              '</a> → <a href="/explore?id=' +
+              encodeURIComponent(r.to) +
+              '">' +
+              escapeHtml(r.to) +
+              "</a>" +
+              (r.description ? " — " + escapeHtml(r.description) : "") +
+              "</li>",
+          )
+          .join("") || "<li>No declared relationships.</li>") +
+        "</ul>";
+    }
+  };
+
+  document.querySelectorAll("[data-explore-view]").forEach((btn) => {
+    btn.addEventListener("click", () => {
+      view = btn.getAttribute("data-explore-view") || "list";
+      document
+        .querySelectorAll("[data-explore-view]")
+        .forEach((b) => b.classList.toggle("active", b === btn));
+      render();
+    });
+  });
+
+  loadJson("/knowledge.json")
+    .then((k) => {
+      knowledge = k || knowledge;
+      render();
+    })
+    .catch(() => {
+      panel.innerHTML = "<p>No knowledge.json published yet.</p>";
+    });
 }
 
 bindNavToggle();