add interactive BBQ knowledge atlas

.github/workflows/ci.yml

@@ -20,3 +20,4 @@ jobs:
       - run: python scripts/calculate_metrics.py docs/experiments/EXP-001-covered-vs-uncovered-brisket/results.csv --check
       - run: python scripts/build_experiment_index.py --check
       - run: mkdocs build --strict
+      - run: python scripts/check_site_links.py site --base-path /meat-science/

.github/workflows/deploy-docs.yml

@@ -26,6 +26,7 @@ jobs:
       - run: python -m pip install -e ".[docs]"
       - run: python scripts/validate_content.py --strict
       - run: mkdocs build --strict
+      - run: python scripts/check_site_links.py site --base-path /meat-science/
       - uses: actions/upload-pages-artifact@v3
         with:
           path: site

.gitignore

@@ -5,6 +5,7 @@ __pycache__/
 .venv/
 venv/
 site/
+site-*/
 build/
 *.egg-info/
 .DS_Store

docs/assets/javascripts/atlas.js

@@ -0,0 +1,224 @@
+(() => {
+  "use strict";
+
+  const LINKS = [
+    ["bbq", "beef-map"], ["bbq", "pork-map"], ["bbq", "fire-smoke"],
+    ["bbq", "compound"], ["bbq", "salt"], ["bbq", "browning"],
+    ["beef-map", "brisket"], ["beef-map", "beef-ribs"], ["beef-map", "dry-heat"],
+    ["pork-map", "pork-shoulder"], ["pork-map", "pork-belly"], ["pork-map", "moist-heat"],
+    ["lamb", "compound"], ["lamb", "spices"], ["chicken", "dry-heat"],
+    ["chicken", "salt"], ["brisket", "collagen"], ["brisket", "smoking"],
+    ["brisket", "salt"], ["beef-ribs", "collagen"], ["beef-ribs", "fire-smoke"],
+    ["pork-shoulder", "collagen"], ["pork-shoulder", "smoking"],
+    ["pork-belly", "fat"], ["pork-belly", "curing"], ["muscle", "heat"],
+    ["muscle", "dry-heat"], ["collagen", "moist-heat"], ["collagen", "sous-vide"],
+    ["water-salt", "salt"], ["water-salt", "sausage"], ["water-salt", "acid"],
+    ["heat", "dry-heat"], ["heat", "sous-vide"], ["fat", "sausage"],
+    ["fat", "compound"], ["browning", "dry-heat"], ["browning", "sugar"],
+    ["fire-smoke", "smoking"], ["fire-smoke", "curing"],
+    ["sausage", "salt"], ["sausage", "curing"], ["sausage", "spices"],
+    ["dry-heat", "compound"], ["moist-heat", "compound"],
+    ["smoking", "compound"], ["sous-vide", "compound"],
+    ["salt", "umami"], ["acid", "enzymes"], ["sugar", "spices"],
+    ["umami", "spices"]
+  ];
+
+  const CATEGORY_NAMES = {
+    core: "总览",
+    cuts: "肉与部位",
+    science: "肉类科学",
+    methods: "烹饪方法",
+    ingredients: "调料与处理剂"
+  };
+
+  function initAtlas() {
+    const root = document.getElementById("bbq-atlas");
+    if (!root || root.dataset.initialized === "true") return;
+    root.dataset.initialized = "true";
+
+    const canvas = root.querySelector(".atlas-canvas");
+    const svg = root.querySelector(".atlas-lines");
+    const search = root.querySelector("#atlas-search");
+    const count = root.querySelector(".atlas-count");
+    const status = root.querySelector("#atlas-status");
+    const reset = root.querySelector(".atlas-reset");
+    const filters = Array.from(root.querySelectorAll(".atlas-filter"));
+    const nodeElements = Array.from(root.querySelectorAll(".atlas-node"));
+    const nodes = new Map(nodeElements.map((node) => [node.dataset.node, node]));
+    const detailKicker = root.querySelector(".atlas-detail-kicker");
+    const detailTitle = root.querySelector(".atlas-detail-title");
+    const detailSummary = root.querySelector(".atlas-detail-summary");
+    const detailLink = root.querySelector(".atlas-detail-link");
+    const relatedList = root.querySelector(".atlas-related-list");
+    let activeCategory = "all";
+    let selectedId = "bbq";
+    let frameId = 0;
+
+    function relatedIds(id) {
+      const ids = new Set();
+      LINKS.forEach(([a, b]) => {
+        if (a === id) ids.add(b);
+        if (b === id) ids.add(a);
+      });
+      return ids;
+    }
+
+    function isVisible(node) {
+      return !node.hidden;
+    }
+
+    function drawLines() {
+      window.cancelAnimationFrame(frameId);
+      frameId = window.requestAnimationFrame(() => {
+        const canvasRect = canvas.getBoundingClientRect();
+        svg.setAttribute("viewBox", `0 0 ${canvasRect.width} ${canvasRect.height}`);
+        svg.replaceChildren();
+        if (window.matchMedia("(max-width: 52rem)").matches) return;
+
+        LINKS.forEach(([a, b]) => {
+          const first = nodes.get(a);
+          const second = nodes.get(b);
+          if (!first || !second || !isVisible(first) || !isVisible(second)) return;
+          const firstRect = first.getBoundingClientRect();
+          const secondRect = second.getBoundingClientRect();
+          const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
+          line.setAttribute("x1", String(firstRect.left + firstRect.width / 2 - canvasRect.left));
+          line.setAttribute("y1", String(firstRect.top + firstRect.height / 2 - canvasRect.top));
+          line.setAttribute("x2", String(secondRect.left + secondRect.width / 2 - canvasRect.left));
+          line.setAttribute("y2", String(secondRect.top + secondRect.height / 2 - canvasRect.top));
+          line.classList.add("atlas-line");
+          line.dataset.a = a;
+          line.dataset.b = b;
+          svg.append(line);
+        });
+        updateHighlights();
+      });
+    }
+
+    function updateHighlights() {
+      const related = relatedIds(selectedId);
+      nodeElements.forEach((node) => {
+        const id = node.dataset.node;
+        node.classList.toggle("is-selected", id === selectedId);
+        node.classList.toggle("is-related", related.has(id));
+        node.classList.toggle("is-dimmed", Boolean(selectedId) && id !== selectedId && !related.has(id));
+        if (id === selectedId) node.setAttribute("aria-current", "true");
+        else node.removeAttribute("aria-current");
+      });
+      svg.querySelectorAll(".atlas-line").forEach((line) => {
+        const connected = line.dataset.a === selectedId || line.dataset.b === selectedId;
+        line.classList.toggle("is-related", connected);
+        line.classList.toggle("is-muted", Boolean(selectedId) && !connected);
+      });
+    }
+
+    function renderDetail(id, announce = true) {
+      const node = nodes.get(id);
+      if (!node) return;
+      selectedId = id;
+      const related = Array.from(relatedIds(id)).filter((relatedId) => {
+        const relatedNode = nodes.get(relatedId);
+        return relatedNode && isVisible(relatedNode);
+      });
+      detailKicker.textContent = CATEGORY_NAMES[node.dataset.category] || "知识节点";
+      detailTitle.textContent = node.dataset.title;
+      detailSummary.textContent = node.dataset.summary;
+      relatedList.replaceChildren();
+      related.forEach((relatedId) => {
+        const relatedNode = nodes.get(relatedId);
+        const item = document.createElement("li");
+        const button = document.createElement("button");
+        button.type = "button";
+        button.textContent = relatedNode.dataset.title;
+        button.addEventListener("click", () => {
+          renderDetail(relatedId);
+          relatedNode.focus({ preventScroll: true });
+        });
+        item.append(button);
+        relatedList.append(item);
+      });
+      detailLink.hidden = !node.getAttribute("href");
+      if (node.getAttribute("href")) detailLink.setAttribute("href", node.getAttribute("href"));
+      updateHighlights();
+      if (announce) status.textContent = `已选择${node.dataset.title}，显示 ${related.length} 个直接关系。`;
+    }
+
+    function applyFilters() {
+      const query = search.value.trim().toLocaleLowerCase("zh-CN");
+      let visibleCount = 0;
+      nodeElements.forEach((node) => {
+        const inCategory = activeCategory === "all" || node.dataset.category === activeCategory || node.dataset.category === "core";
+        const haystack = `${node.dataset.title} ${node.dataset.keywords || ""}`.toLocaleLowerCase("zh-CN");
+        const matchesQuery = !query || haystack.includes(query);
+        node.hidden = !(inCategory && matchesQuery);
+        if (!node.hidden) visibleCount += 1;
+      });
+      const selected = nodes.get(selectedId);
+      if (!selected || selected.hidden) selectedId = nodes.get("bbq").hidden ? "" : "bbq";
+      count.textContent = `${visibleCount} 个节点`;
+      status.textContent = visibleCount ? `当前显示 ${visibleCount} 个知识节点。` : "没有匹配结果，请尝试其他关键词。";
+      if (selectedId) renderDetail(selectedId, false);
+      else {
+        detailKicker.textContent = "没有匹配结果";
+        detailTitle.textContent = "换一个搜索词试试";
+        detailSummary.textContent = "可以搜索部位、机制、方法或调料，例如“胶原”“烟熏”“盐”。";
+        relatedList.replaceChildren();
+        detailLink.hidden = true;
+        updateHighlights();
+      }
+      drawLines();
+    }
+
+    nodeElements.forEach((node, index) => {
+      node.addEventListener("click", (event) => {
+        event.preventDefault();
+        renderDetail(node.dataset.node);
+      });
+      node.addEventListener("keydown", (event) => {
+        if (!['ArrowRight', 'ArrowDown', 'ArrowLeft', 'ArrowUp'].includes(event.key)) return;
+        const visibleNodes = nodeElements.filter(isVisible);
+        const currentIndex = visibleNodes.indexOf(node);
+        const direction = event.key === 'ArrowRight' || event.key === 'ArrowDown' ? 1 : -1;
+        const next = visibleNodes[(currentIndex + direction + visibleNodes.length) % visibleNodes.length];
+        if (next) {
+          event.preventDefault();
+          next.focus();
+        }
+      });
+      node.style.setProperty("--atlas-order", String(index));
+    });
+
+    filters.forEach((filter) => {
+      filter.addEventListener("click", () => {
+        activeCategory = filter.dataset.category;
+        filters.forEach((item) => item.setAttribute("aria-pressed", String(item === filter)));
+        applyFilters();
+      });
+    });
+
+    search.addEventListener("input", applyFilters);
+    reset.addEventListener("click", () => {
+      search.value = "";
+      activeCategory = "all";
+      selectedId = "bbq";
+      filters.forEach((filter) => filter.setAttribute("aria-pressed", String(filter.dataset.category === "all")));
+      applyFilters();
+      search.focus();
+    });
+    root.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        selectedId = "bbq";
+        renderDetail("bbq");
+      }
+    });
+
+    if ("ResizeObserver" in window) new ResizeObserver(drawLines).observe(canvas);
+    else window.addEventListener("resize", drawLines);
+    renderDetail("bbq", false);
+    drawLines();
+  }
+
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", initAtlas);
+  else initAtlas();
+  if (typeof document$ !== "undefined") document$.subscribe(initAtlas);
+})();