codetrail-cli 1.4.1__py3-none-any.whl

codetrail/web/static/js/main.js

@@ -0,0 +1,38 @@
+// Codetrail's page script. Each module wires one part of the page; the security policy allows no inline code,
+// so this file and the theme's first-paint script are all the page runs; D2 runs in its own worker (d2-worker.js).
+import { post } from "./api.js";
+import { setUpAsk } from "./ask.js";
+import { setUpDiagrams } from "./diagram.js";
+import { setUpDocumentation } from "./documentation.js";
+import { setUpLearning } from "./learning.js";
+import { setUpOutline } from "./outline.js";
+import { setUpPalette } from "./palette.js";
+import { setUpRepository } from "./repository.js";
+import { setUpResize } from "./resize.js";
+import { setUpShortcuts } from "./shortcuts.js";
+import { setUpSidebar } from "./sidebar.js";
+import { setUpTheme } from "./theme.js";
+import { setUpUpdate } from "./update.js";
+
+function setUpLanguage() {
+  const form = document.querySelector("[data-language-form]");
+  form?.addEventListener("change", async () => {
+    const response = await post("/settings/language", { language: form.elements.language.value });
+    if (response.ok) window.location.reload();
+  });
+}
+
+setUpTheme();
+setUpLanguage();
+setUpLearning();
+setUpAsk();
+setUpPalette();
+setUpUpdate();
+setUpShortcuts();
+setUpOutline();
+setUpResize();
+setUpDiagrams();
+setUpRepository();
+setUpDocumentation();
+setUpSidebar();
+document.documentElement.dataset.ready = "true"; // every handler is in place

codetrail/web/static/js/outline.js

@@ -0,0 +1,44 @@
+// "On this page": an outline of the reading column's headings that follows the reader (design section 16.1).
+const outline = document.querySelector("[data-outline]");
+
+function slug(text, used) {
+  const base = text.toLowerCase().normalize("NFKD").replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "") || "section";
+  let candidate = base;
+  for (let number = 2; used.has(candidate) || document.getElementById(candidate); number += 1) {
+    candidate = `${base}-${number}`;
+  }
+  used.add(candidate);
+  return candidate;
+}
+
+export function setUpOutline() {
+  if (!outline) return;
+  const headings = [...document.querySelectorAll("main .prose h2, main .prose h3, main .checks > h2")];
+  const list = outline.querySelector("ol");
+  if (headings.length < 2 || !list) return;
+  const used = new Set();
+  const links = new Map();
+  for (const heading of headings) {
+    if (!heading.id) heading.id = slug(heading.textContent, used);
+    const item = document.createElement("li");
+    item.className = heading.tagName === "H3" ? "depth-3" : "depth-2";
+    const link = document.createElement("a");
+    link.href = `#${heading.id}`;
+    link.textContent = heading.textContent;
+    item.append(link);
+    list.append(item);
+    links.set(heading, link);
+  }
+  outline.hidden = false;
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue;
+        for (const link of links.values()) link.removeAttribute("aria-current");
+        links.get(entry.target)?.setAttribute("aria-current", "location");
+      }
+    },
+    { rootMargin: "-70px 0px -70% 0px" },
+  );
+  for (const heading of headings) observer.observe(heading);
+}

codetrail/web/static/js/palette.js

@@ -0,0 +1,211 @@
+// The command palette (design section 16.3): search the guide and run a few actions, all from the keyboard.
+// Results are drawn with textContent and <mark> elements only; nothing from the server is parsed as markup.
+import { getJSON } from "./api.js";
+import { openAsk } from "./ask.js";
+import { cycleTheme } from "./theme.js";
+import { startUpdate } from "./update.js";
+
+const dialog = document.querySelector("[data-palette]");
+const input = dialog?.querySelector("[data-palette-input]");
+const list = dialog?.querySelector("[data-palette-list]");
+const status = dialog?.querySelector("[data-palette-status]");
+const GROUPS = [
+  ["pages", ["area", "concept", "path", "digest"]],
+  ["answers", ["answer"]],
+  ["decisions", ["decision"]],
+  ["facts", ["fact"]],
+];
+let options = [];
+let active = -1;
+let pending = null;
+let timer = null;
+
+function label(name, query = "") {
+  return (dialog.dataset[name] ?? "").replace("{query}", query);
+}
+
+// Resolved the way the browser will follow it: a check on the text alone misses `/\host` and `/<tab>/host`,
+// which browsers read as `//host`. A `blob:` URL takes the origin of the URL inside it, so the scheme is checked too.
+function isLocalLink(link) {
+  if (typeof link !== "string") return false;
+  try {
+    const url = new URL(link, window.location.origin);
+    return url.origin === window.location.origin && (url.protocol === "http:" || url.protocol === "https:");
+  } catch {
+    return false;
+  }
+}
+
+function heading(text) {
+  const item = document.createElement("li");
+  item.className = "palette-group";
+  item.setAttribute("role", "presentation");
+  item.textContent = text;
+  list.append(item);
+}
+
+function option(title, detail, run, kind) {
+  const item = document.createElement("li");
+  item.className = "palette-option";
+  item.id = `palette-option-${options.length}`;
+  item.setAttribute("role", "option");
+  item.setAttribute("aria-selected", "false");
+  const line = document.createElement("span");
+  line.className = "title";
+  line.textContent = title;
+  if (kind) {
+    line.lang = "en"; // a result from the guide, which is English; its kind is in the reader's language
+    line.dir = "ltr";
+    const badge = document.createElement("span");
+    badge.className = "kind";
+    badge.lang = document.documentElement.lang;
+    badge.dir = document.documentElement.dir;
+    badge.textContent = label(`kind${kind[0].toUpperCase()}${kind.slice(1)}`) || kind;
+    line.append(" ", badge);
+  }
+  item.append(line);
+  if (detail) item.append(detail);
+  item.addEventListener("mousedown", (event) => event.preventDefault()); // keep focus in the input
+  item.addEventListener("click", () => activate(options.indexOf(entry)));
+  const entry = { item, run };
+  options.push(entry);
+  list.append(item);
+}
+
+function snippet(segments) {
+  if (!Array.isArray(segments) || !segments.length) return null;
+  const line = document.createElement("span");
+  line.className = "snippet";
+  line.lang = "en";
+  line.dir = "ltr";
+  for (const [text, matched] of segments) {
+    if (matched) {
+      const mark = document.createElement("mark");
+      mark.textContent = String(text);
+      line.append(mark);
+    } else {
+      line.append(String(text));
+    }
+  }
+  return line;
+}
+
+function select(index) {
+  if (!options.length) {
+    active = -1;
+    input.removeAttribute("aria-activedescendant");
+    return;
+  }
+  active = (index + options.length) % options.length;
+  options.forEach((entry, position) => entry.item.setAttribute("aria-selected", String(position === active)));
+  const current = options[active].item;
+  input.setAttribute("aria-activedescendant", current.id);
+  current.scrollIntoView({ block: "nearest" });
+}
+
+function activate(index) {
+  const entry = options[index];
+  if (!entry) return;
+  dialog.close();
+  entry.run();
+}
+
+function actions(query) {
+  heading(label("groupActions"));
+  if (query) {
+    option(label("actionAsk", query), null, () => openAsk(query));
+    option(label("actionAll", query), null, () => {
+      window.location.href = `/search?q=${encodeURIComponent(query)}`;
+    });
+  }
+  option(label("actionUpdate"), null, () => startUpdate());
+  option(label("actionProgress"), null, () => {
+    window.location.href = "/progress";
+  });
+  option(label("actionTheme"), null, () => cycleTheme());
+}
+
+function draw(query, results, message) {
+  list.replaceChildren();
+  options = [];
+  for (const [group, kinds] of GROUPS) {
+    const found = results.filter((result) => kinds.includes(result.kind) && isLocalLink(result.link));
+    if (!found.length) continue;
+    heading(label(`group${group[0].toUpperCase()}${group.slice(1)}`));
+    for (const result of found) {
+      option(String(result.title), snippet(result.snippet), () => {
+        window.location.href = result.link;
+      }, result.kind);
+    }
+  }
+  actions(query);
+  status.textContent = message;
+  input.setAttribute("aria-expanded", "true");
+  select(0);
+}
+
+async function search() {
+  const query = input.value.trim();
+  pending?.abort();
+  if (!query) {
+    draw("", [], "");
+    return;
+  }
+  pending = new AbortController();
+  status.textContent = label("labelSearching");
+  try {
+    const { results, available } = await getJSON(`/search/results?q=${encodeURIComponent(query)}`, {
+      signal: pending.signal,
+    });
+    let message = "";
+    if (!available) message = label("labelUnavailable");
+    else if (!results.length) message = label("labelEmpty", query);
+    draw(query, results, message);
+  } catch (error) {
+    if (error.name !== "AbortError") draw(query, [], label("labelUnavailable"));
+  }
+}
+
+export function openPalette(initial = "") {
+  if (!dialog || dialog.open) return;
+  input.value = initial;
+  dialog.showModal();
+  input.focus();
+  search();
+}
+
+export function setUpPalette() {
+  if (!dialog) return;
+  input.addEventListener("input", () => {
+    clearTimeout(timer);
+    timer = setTimeout(search, 120);
+  });
+  input.addEventListener("keydown", (event) => {
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      select(active + 1);
+    } else if (event.key === "ArrowUp") {
+      event.preventDefault();
+      select(active - 1);
+    } else if (event.key === "Enter" && !event.isComposing) {
+      event.preventDefault();
+      activate(active);
+    }
+  });
+  dialog.addEventListener("close", () => {
+    pending?.abort();
+    input.setAttribute("aria-expanded", "false");
+  });
+  dialog.addEventListener("click", (event) => {
+    if (event.target === dialog) dialog.close(); // a click on the backdrop
+  });
+  const form = document.querySelector("[data-search-form]");
+  form?.addEventListener("submit", (event) => {
+    event.preventDefault();
+    openPalette(form.elements.q.value);
+  });
+  form?.elements.q.addEventListener("focus", (event) => {
+    event.target.blur();
+    openPalette(event.target.value);
+  });
+}