datalog-theme 0.6.0

data/assets/js/notebook.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Jupyter notebook rendering support.
+ * Handles Plotly, Vega visualizations, cell annotations, and scroll spy.
+ * @module notebook
+ */
+
+/**
+ * Dynamically loads a script if not already present.
+ * @param {string} src - The script URL to load
+ * @returns {Promise<void>} Resolves when script is loaded
+ */
+export const loadScript = (src) =>
+  new Promise((resolve, reject) => {
+    if (document.querySelector(`script[src="${src}"]`)) {
+      resolve();
+      return;
+    }
+    const script = document.createElement('script');
+    script.src = src;
+    script.async = true;
+    script.onload = () => resolve();
+    script.onerror = (event) => reject(event);
+    document.head.appendChild(script);
+  });
+
+/**
+ * Initializes Plotly visualizations from notebook output elements.
+ * @returns {Promise<void>} Resolves when all Plotly figures are rendered
+ */
+export const initPlotly = () => {
+  const plotlyTargets = document.querySelectorAll('.notebook-output-plotly');
+  if (!plotlyTargets.length) {
+    return Promise.resolve();
+  }
+
+  const ensurePlotly = () =>
+    typeof window.Plotly !== 'undefined'
+      ? Promise.resolve(window.Plotly)
+      : loadScript('https://cdn.plot.ly/plotly-2.27.0.min.js').then(() => window.Plotly);
+
+  return ensurePlotly().then((Plotly) => {
+    plotlyTargets.forEach((target) => {
+      try {
+        const spec = JSON.parse(target.dataset.plotly || '{}');
+        const layout = spec.layout || {};
+        const data = Array.isArray(spec.data) ? spec.data : Array.isArray(spec) ? spec : [];
+        Plotly.newPlot(target, data, layout, { responsive: true });
+      } catch (error) {
+        target.replaceChildren();
+        target.insertAdjacentHTML('afterbegin',
+          '<p class="notebook-output__warning">Plotly figure could not be rendered. Open in Binder or Colab to interact.</p>');
+      }
+    });
+  });
+};
+
+/**
+ * Initializes Vega/Vega-Lite visualizations from notebook output elements.
+ * @returns {Promise<void>} Resolves when all Vega specs are rendered
+ */
+export const initVega = () => {
+  const vegaTargets = document.querySelectorAll('.notebook-output-vega');
+  if (!vegaTargets.length) {
+    return Promise.resolve();
+  }
+
+  const ensureVega = () =>
+    loadScript('https://cdn.jsdelivr.net/npm/vega@5')
+      .then(() => loadScript('https://cdn.jsdelivr.net/npm/vega-lite@5'))
+      .then(() => loadScript('https://cdn.jsdelivr.net/npm/vega-embed@6'));
+
+  return ensureVega().then(() => {
+    vegaTargets.forEach((target) => {
+      try {
+        const spec = JSON.parse(target.dataset.vega || '{}');
+        window.vegaEmbed(target, spec, { actions: false });
+      } catch (error) {
+        target.replaceChildren();
+        target.insertAdjacentHTML('afterbegin',
+          '<p class="notebook-output__warning">Vega specification could not be parsed. Open in Binder for the interactive version.</p>');
+      }
+    });
+  });
+};
+
+/**
+ * Annotates notebook cells with anchor IDs for navigation.
+ * @returns {void}
+ */
+export const annotateCells = () => {
+  const segments = document.querySelectorAll('.notebook-segment');
+  segments.forEach((segment, index) => {
+    const anchorId = segment.id || `cell-${index + 1}`;
+    segment.id = anchorId;
+    segment.setAttribute('data-cell-anchor', anchorId);
+  });
+};
+
+/**
+ * Sets up scroll spy to highlight active cell in sidebar navigation.
+ * @returns {void}
+ */
+export const handleScrollSpy = () => {
+  const observerOptions = {
+    root: null,
+    rootMargin: '0px 0px -65%',
+    threshold: 0
+  };
+
+  const entries = document.querySelectorAll('.notebook-segment');
+  const sidebarLinks = document.querySelectorAll('[data-cell-anchor-link]');
+
+  if (!entries.length || !sidebarLinks.length) {
+    return;
+  }
+
+  const observer = new IntersectionObserver((changes) => {
+    changes.forEach((change) => {
+      if (change.isIntersecting) {
+        sidebarLinks.forEach((link) => {
+          link.classList.toggle('is-active', link.hash === `#${change.target.id}`);
+        });
+      }
+    });
+  }, observerOptions);
+
+  entries.forEach((entry) => observer.observe(entry));
+};
+
+/**
+ * Initializes all notebook features including visualizations and navigation.
+ * @returns {void}
+ */
+export const initNotebookFeatures = () => {
+  annotateCells();
+  initPlotly().catch(() => {
+    document.querySelectorAll('.notebook-output-plotly').forEach((target) => {
+      target.replaceChildren();
+      target.insertAdjacentHTML('afterbegin',
+        '<p class="notebook-output__warning">Plotly assets failed to load. Launch Binder/Colab to view the interactive chart.</p>');
+    });
+  });
+  initVega().catch(() => {
+    document.querySelectorAll('.notebook-output-vega').forEach((target) => {
+      target.replaceChildren();
+      target.insertAdjacentHTML('afterbegin',
+        '<p class="notebook-output__warning">Vega assets failed to load. Launch Binder/Colab to view the interactive chart.</p>');
+    });
+  });
+  handleScrollSpy();
+};
+
+// Auto-initialize when module loads (backward compatibility)
+if (typeof window !== 'undefined' && document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initNotebookFeatures);
+} else if (typeof window !== 'undefined') {
+  initNotebookFeatures();
+}

data/assets/js/search/analytics.js

@@ -0,0 +1,91 @@
+const ANALYTICS_STORAGE_KEY = "datalog-search-analytics";
+
+export function createAnalyticsManager({ panel, list, empty, onSelect }) {
+  if (!panel || !list || !empty) {
+    return {
+      record() {},
+      render() {}
+    };
+  }
+
+  const analytics = loadAnalytics();
+  let lastQuery = "";
+
+  function loadAnalytics() {
+    // Search queries become keys on this object, so it is built with a null
+    // prototype and filled by explicit own-key copy. A visitor searching for
+    // "__proto__" or "constructor" then records a plain entry instead of
+    // reaching Object.prototype.
+    const counts = Object.create(null);
+
+    try {
+      const stored = window.localStorage.getItem(ANALYTICS_STORAGE_KEY);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        if (parsed && typeof parsed === "object") {
+          Object.entries(parsed).forEach(([query, count]) => {
+            if (typeof count === "number" && Number.isFinite(count)) {
+              counts[query] = count;
+            }
+          });
+        }
+      }
+    } catch (error) {
+      console.warn("Unable to load stored analytics", error);
+    }
+
+    return counts;
+  }
+
+  function saveAnalytics() {
+    try {
+      window.localStorage.setItem(ANALYTICS_STORAGE_KEY, JSON.stringify(analytics));
+    } catch (error) {
+      console.warn("Unable to persist analytics", error);
+    }
+  }
+
+  function record(query) {
+    const value = (query || "").trim();
+    if (!value || value === lastQuery) {
+      return;
+    }
+    lastQuery = value;
+    analytics[value] = (analytics[value] || 0) + 1;
+    saveAnalytics();
+    render();
+  }
+
+  function render() {
+    const entries = Object.entries(analytics)
+      .filter(([query]) => query && query.trim().length > 1)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5);
+
+    list.replaceChildren();
+    if (entries.length === 0) {
+      empty.hidden = false;
+      return;
+    }
+
+    empty.hidden = true;
+    const fragment = document.createDocumentFragment();
+    entries.forEach(([query, count]) => {
+      const item = document.createElement("li");
+      const button = document.createElement("button");
+      button.type = "button";
+      button.className = "search-analytics__query";
+      button.textContent = `${query} (${count})`;
+      button.addEventListener("click", () => {
+        if (typeof onSelect === "function") {
+          onSelect(query);
+        }
+      });
+      item.appendChild(button);
+      fragment.appendChild(item);
+    });
+    list.appendChild(fragment);
+  }
+
+  return { record, render };
+}

data/assets/js/search/app.js

@@ -0,0 +1,271 @@
+import { createAnalyticsManager } from "./analytics.js";
+import { createAutocomplete } from "./autocomplete.js";
+import { createSearchEngine } from "./engine.js";
+import { renderTagFilters } from "./filters.js";
+import { renderResults } from "./render.js";
+
+const AUTOCOMPLETE_LIMIT = 8;
+
+export function initializeSearchApp() {
+  const app = document.querySelector("[data-search-app]");
+  if (!app) {
+    return;
+  }
+
+  const form = app.querySelector("[data-search-form]");
+  const input = app.querySelector("[data-search-input]");
+  const resultsList = app.querySelector("[data-search-results]");
+  const resultsMeta = app.querySelector("[data-search-meta]");
+  const emptyState = app.querySelector("[data-search-empty]");
+  const autocompletePanel = app.querySelector("[data-search-autocomplete]");
+  const analyticsPanel = app.querySelector("[data-search-analytics]");
+  const analyticsList = analyticsPanel ? analyticsPanel.querySelector(".search-app__analytics-list") : null;
+  const analyticsEmpty = analyticsPanel ? analyticsPanel.querySelector(".search-app__analytics-empty") : null;
+  const resultTemplate = document.getElementById("search-result-template");
+  const filterType = app.querySelector("[data-filter-type]");
+  const filterLanguage = app.querySelector("[data-filter-language]");
+  const filterDifficulty = app.querySelector("[data-filter-difficulty]");
+  const filterTagsContainer = app.querySelector("[data-filter-tags]");
+  const SEARCH_INDEX_URL = app.getAttribute("data-search-index") || "/search.json";
+
+  const selectedTags = new Set();
+  const searchEngine = createSearchEngine();
+  const analyticsManager = createAnalyticsManager({
+    panel: analyticsPanel,
+    list: analyticsList,
+    empty: analyticsEmpty,
+    onSelect: (query) => {
+      if (input) {
+        input.value = query;
+        executeSearch();
+      }
+    }
+  });
+  const autocomplete = createAutocomplete({
+    panel: autocompletePanel,
+    limit: AUTOCOMPLETE_LIMIT,
+    onSelect: (value) => {
+      if (value && input) {
+        input.value = value;
+        input.focus();
+        executeSearch();
+      }
+    }
+  });
+
+  let indexReady = false;
+
+  const params = new URLSearchParams(window.location.search);
+  if (input && params.has("q")) {
+    input.value = params.get("q") || "";
+  }
+  if (filterType && params.has("type")) {
+    filterType.value = params.get("type");
+  }
+  if (filterLanguage && params.has("language")) {
+    filterLanguage.value = params.get("language");
+  }
+  if (filterDifficulty && params.has("difficulty")) {
+    filterDifficulty.value = params.get("difficulty");
+  }
+  if (params.has("tags")) {
+    params
+      .get("tags")
+      .split(",")
+      .map((tag) => tag.trim().toLowerCase())
+      .filter(Boolean)
+      .forEach((tag) => selectedTags.add(tag));
+  }
+
+  focusShortcut(input, () => {
+    autocomplete.close();
+    executeSearch();
+  });
+
+  fetchIndex(SEARCH_INDEX_URL)
+    .then((data) => {
+      const documents = data.documents || [];
+      searchEngine.setDocuments(documents);
+      autocomplete.setSuggestions(searchEngine.suggestions());
+      renderTagFilters(filterTagsContainer, documents, selectedTags);
+      indexReady = true;
+      restoreInitialSearch();
+    })
+    .catch((error) => {
+      console.error("Failed to load search index", error);
+      if (resultsMeta) {
+        resultsMeta.textContent = "Unable to load the search index. Please try again later.";
+      }
+    });
+
+  if (form) {
+    form.addEventListener("submit", (event) => {
+      event.preventDefault();
+      executeSearch();
+    });
+  }
+
+  if (input) {
+    input.addEventListener("input", () => {
+      autocomplete.update(input.value);
+    });
+    input.addEventListener("keydown", (event) => {
+      autocomplete.handleNavigation(event, input);
+    });
+    input.addEventListener("focus", () => {
+      autocomplete.update(input.value);
+    });
+  }
+
+  if (filterType) {
+    filterType.addEventListener("change", executeSearch);
+  }
+  if (filterLanguage) {
+    filterLanguage.addEventListener("change", executeSearch);
+  }
+  if (filterDifficulty) {
+    filterDifficulty.addEventListener("change", executeSearch);
+  }
+
+  app.addEventListener("click", (event) => {
+    const trigger = event.target;
+    if (trigger.matches("[data-filter-tag]")) {
+      const tag = trigger.getAttribute("data-filter-tag");
+      if (tag) {
+        if (selectedTags.has(tag)) {
+          selectedTags.delete(tag);
+          trigger.setAttribute("aria-pressed", "false");
+        } else {
+          selectedTags.add(tag);
+          trigger.setAttribute("aria-pressed", "true");
+        }
+        executeSearch();
+      }
+    }
+  });
+
+  document.addEventListener("click", (event) => {
+    if (!autocompletePanel || autocompletePanel.hidden) {
+      return;
+    }
+    if (!app.contains(event.target)) {
+      autocomplete.close();
+    }
+  });
+
+  document.addEventListener("keydown", (event) => {
+    const activeTag = document.activeElement ? document.activeElement.tagName : "";
+    if (["INPUT", "TEXTAREA"].includes(activeTag)) {
+      return;
+    }
+    if (event.key === "/" && !event.ctrlKey && !event.metaKey && !event.altKey) {
+      event.preventDefault();
+      if (input) {
+        input.focus();
+        input.select();
+      }
+    } else if ((event.key === "k" || event.key === "K") && (event.ctrlKey || event.metaKey)) {
+      event.preventDefault();
+      if (input) {
+        input.focus();
+        input.select();
+      }
+    }
+  });
+
+  analyticsManager.render();
+
+  function restoreInitialSearch() {
+    if (input && input.value.trim()) {
+      executeSearch();
+    } else {
+      updateFiltersInUrl();
+    }
+  }
+
+  function executeSearch() {
+    if (!input) {
+      return;
+    }
+    if (!indexReady) {
+      if (resultsMeta) {
+        resultsMeta.textContent = "Loading technical index…";
+      }
+      return;
+    }
+
+    const rawQuery = input.value.trim();
+    const filters = {
+      type: filterType ? filterType.value : "",
+      language: filterLanguage ? filterLanguage.value : "",
+      difficulty: filterDifficulty ? filterDifficulty.value : "",
+      tags: selectedTags
+    };
+
+    const matches = searchEngine.search(rawQuery, filters);
+    renderResults(matches, rawQuery, {
+      resultsList,
+      resultsMeta,
+      emptyState,
+      template: resultTemplate
+    });
+    updateFiltersInUrl(rawQuery);
+    analyticsManager.record(rawQuery);
+  }
+
+  function updateFiltersInUrl(query) {
+    const next = new URL(window.location.href);
+    const urlParams = next.searchParams;
+    if (query) {
+      urlParams.set("q", query);
+    } else {
+      urlParams.delete("q");
+    }
+    if (filterType && filterType.value) {
+      urlParams.set("type", filterType.value);
+    } else {
+      urlParams.delete("type");
+    }
+    if (filterLanguage && filterLanguage.value) {
+      urlParams.set("language", filterLanguage.value);
+    } else {
+      urlParams.delete("language");
+    }
+    if (filterDifficulty && filterDifficulty.value) {
+      urlParams.set("difficulty", filterDifficulty.value);
+    } else {
+      urlParams.delete("difficulty");
+    }
+    if (selectedTags.size > 0) {
+      urlParams.set("tags", Array.from(selectedTags).join(","));
+    } else {
+      urlParams.delete("tags");
+    }
+    const queryString = urlParams.toString();
+    const nextUrl = queryString ? `${next.pathname}?${queryString}` : next.pathname;
+    window.history.replaceState({}, "", nextUrl);
+  }
+}
+
+function fetchIndex(url) {
+  return fetch(url, { credentials: "same-origin" }).then((response) => {
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return response.json();
+  });
+}
+
+function focusShortcut(target, onClear) {
+  if (!target) {
+    return;
+  }
+  target.addEventListener("keydown", (event) => {
+    if (event.key === "Escape") {
+      target.value = "";
+      if (typeof onClear === "function") {
+        onClear();
+      }
+    }
+  });
+}

data/assets/js/search/autocomplete.js

@@ -0,0 +1,120 @@
+import { highlightText } from "./utils.js";
+
+export function createAutocomplete({ panel, limit = 8, onSelect }) {
+  if (!panel) {
+    return {
+      setSuggestions() {},
+      update() {},
+      close() {},
+      handleNavigation() {}
+    };
+  }
+
+  let suggestions = [];
+  let suggestionIndex = -1;
+
+  function setSuggestions(values) {
+    suggestions = Array.isArray(values) ? [...values] : [];
+  }
+
+  function update(query) {
+    suggestionIndex = -1;
+    const value = (query || "").trim().toLowerCase();
+
+    if (!value) {
+      clear();
+      return;
+    }
+
+    const matches = suggestions
+      .filter((item) => item && item.toLowerCase().includes(value))
+      .slice(0, limit);
+
+    if (matches.length === 0) {
+      clear();
+      return;
+    }
+
+    const fragment = document.createDocumentFragment();
+    matches.forEach((item, index) => {
+      const option = document.createElement("button");
+      option.type = "button";
+      option.className = "search-autocomplete__option";
+      option.setAttribute("role", "option");
+      option.dataset.autocompleteOption = "";
+      option.dataset.value = item;
+      option.setAttribute("aria-selected", index === suggestionIndex ? "true" : "false");
+      option.replaceChildren();
+      option.insertAdjacentHTML("beforeend", highlightText(item, value));
+      fragment.appendChild(option);
+    });
+
+    panel.replaceChildren();
+    panel.appendChild(fragment);
+    panel.hidden = false;
+  }
+
+  function handleNavigation(event, input) {
+    if (panel.hidden) {
+      return;
+    }
+
+    const options = Array.from(panel.querySelectorAll("[data-autocomplete-option]"));
+    if (options.length === 0) {
+      return;
+    }
+
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      suggestionIndex = (suggestionIndex + 1) % options.length;
+      updateActive(options);
+    } else if (event.key === "ArrowUp") {
+      event.preventDefault();
+      suggestionIndex = (suggestionIndex - 1 + options.length) % options.length;
+      updateActive(options);
+    } else if (event.key === "Enter" && suggestionIndex >= 0) {
+      event.preventDefault();
+      const option = options[suggestionIndex];
+      const value = option ? option.dataset.value : "";
+      if (value && input) {
+        input.value = value;
+      }
+      if (typeof onSelect === "function") {
+        onSelect(value);
+      }
+      close();
+    }
+  }
+
+  function updateActive(options) {
+    options.forEach((option, index) => {
+      const isActive = index === suggestionIndex;
+      option.setAttribute("aria-selected", isActive ? "true" : "false");
+      option.classList.toggle("is-active", isActive);
+    });
+  }
+
+  function clear() {
+    panel.replaceChildren();
+    panel.hidden = true;
+    suggestionIndex = -1;
+  }
+
+  function close() {
+    clear();
+  }
+
+  panel.addEventListener("click", (event) => {
+    const target = event.target.closest("[data-autocomplete-option]");
+    if (!target) {
+      return;
+    }
+    const value = target.dataset.value || "";
+    if (value && typeof onSelect === "function") {
+      onSelect(value);
+    }
+    close();
+  });
+
+  return { setSuggestions, update, close, handleNavigation };
+}