@posuta/posuta 0.0.0-stage → 0.1.0

package/src/remark-cite.js

@@ -0,0 +1,123 @@
+// Citations: `bibliography: refs.bib` in frontmatter, `[@key]` or `[@a; @b]` in the text, and
+// `<References />` where the list goes. Numbered in order of first citation (frontmatter text
+// first, for md()), with DOI and URL links and the BibTeX note. In the text each citation is a
+// span.posuta-cite. The cited entries are also on frontmatter.references, for References.Root/Item.
+// The list is formatted with a CSL style: vancouver (default), apa, harvard1, or a .csl file.
+// shortcut: in-text citations are always numbers [1]; add author-date markers if a style needs them.
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { Cite, plugins } from "@citation-js/core";
+import "@citation-js/plugin-bibtex";
+import "@citation-js/plugin-csl";
+
+export const CITE = /\[(@[\w:.\-/+]+(?:\s*;\s*@[\w:.\-/+]+)*)\]/g;
+const HAS_CITE = new RegExp(CITE.source); // no /g: .test() must not keep state
+const URL_RE = /(https?:\/\/\S*[^\s.,;:)\]])/; // trailing punctuation stays text
+
+/** Reference text → alternating [text, url, text, …], for linking the URLs in it. */
+export const urlParts = (text) => text.split(URL_RE);
+
+/** A CSL style name, or the path of a .csl file (registered on first use). */
+function template(style) {
+  const styles = plugins.config.get("@csl").styles;
+  if (style.endsWith(".csl")) {
+    if (!styles.has(style)) styles.add(style, readFileSync(style, "utf8"));
+  } else if (!styles.has(style)) {
+    throw new Error(`posuta: unknown citation style "${style}"; use vancouver, apa, harvard1 or a path to a .csl file`);
+  }
+  return style;
+}
+
+/**
+ * One CSL-JSON entry as plain text in a CSL style, without its list number or DOI (posuta adds
+ * the DOI as a link).
+ * @param {object} entry CSL-JSON, e.g. from new Cite(bibtex).data
+ * @param {string} [style] vancouver (default), apa, harvard1, or an absolute path to a .csl file
+ */
+export function formatReference(entry, style = "vancouver") {
+  return new Cite(entry).format("bibliography", { format: "text", template: template(style) })
+    .trim().replace(/^\[?\d+[.\]]\s*/, "")
+    .replace(/\s*(Available (at|from):?\s*)?(doi:\s*|https?:\/\/(dx\.)?doi\.org\/)\S+$/i, "");
+}
+
+/** @param {{ style?: string }} [options] style: as for formatReference */
+export default function remarkCite({ style = "vancouver" } = {}) {
+  template(style); // fail at startup on an unknown style
+  return (tree, file) => {
+    const order = [];
+    let refsNode = null;
+    let hasParts = false;
+    let entries = null;
+    const bib = () => {
+      if (entries) return entries;
+      const path = file.data.astro?.frontmatter?.bibliography;
+      if (!path) throw new Error(`${file.path}: [@key] citations need \`bibliography: refs.bib\` in the frontmatter`);
+      const data = new Cite(readFileSync(resolve(dirname(file.path), path), "utf8")).data;
+      return (entries = new Map(data.map((e) => [e.id, e])));
+    };
+
+    const walk = (node) => {
+      if (!node.children) return;
+      for (let i = 0; i < node.children.length; i++) {
+        const child = node.children[i];
+        if ((child.type === "mdxJsxFlowElement" || child.type === "mdxJsxTextElement") && /^References(\.|$)/.test(child.name ?? "")) {
+          if (child.name === "References") refsNode = { parent: node, child };
+          else { hasParts = true; walk(child); }
+          continue;
+        }
+        if (child.type !== "text" || !HAS_CITE.test(child.value)) { walk(child); continue; }
+        const parts = [];
+        let last = 0;
+        for (const m of child.value.matchAll(CITE)) {
+          if (m.index > last) parts.push({ type: "text", value: child.value.slice(last, m.index) });
+          const keys = m[1].split(";").map((k) => k.trim().slice(1));
+          const links = keys.map((key) => {
+            if (!bib().has(key)) throw new Error(`${file.path}: [@${key}] is not in the bibliography`);
+            if (!order.includes(key)) order.push(key);
+            return { type: "link", url: `#ref-${key}`, children: [{ type: "text", value: String(order.indexOf(key) + 1) }] };
+          });
+          const inner = [{ type: "text", value: "[" }];
+          links.forEach((l, j) => inner.push(...(j ? [{ type: "text", value: ", " }] : []), l));
+          inner.push({ type: "text", value: "]" });
+          parts.push({ type: "cite", data: { hName: "span", hProperties: { className: ["posuta-cite"] } }, children: inner });
+          last = m.index + m[0].length;
+        }
+        if (last < child.value.length) parts.push({ type: "text", value: child.value.slice(last) });
+        node.children.splice(i, 1, ...parts);
+        i += parts.length - 1;
+      }
+    };
+    // Frontmatter text (a lede, a stat label) comes first on the poster, so it is numbered first.
+    const fm = file.data.astro?.frontmatter;
+    const strings = (v) => (typeof v === "string" ? [v] : v && typeof v === "object" ? Object.values(v).flatMap(strings) : []);
+    for (const str of strings(fm)) for (const m of str.matchAll(CITE)) {
+      for (const key of m[1].split(";").map((k) => k.trim().slice(1))) {
+        if (!bib().has(key)) throw new Error(`${file.path}: [@${key}] in the frontmatter is not in the bibliography`);
+        if (!order.includes(key)) order.push(key);
+      }
+    }
+    walk(tree);
+
+    if (!order.length && !refsNode && !hasParts) return;
+    if (!refsNode && !hasParts) throw new Error(`${file.path}: add <References /> where the reference list should go`);
+    const refs = order.map((key, i) => {
+      const e = bib().get(key);
+      let text = formatReference(e, style);
+      if (e.note && !text.includes(e.note)) text += ` (${e.note})`; // as BibTeX prints it
+      return { key, n: i + 1, text, ...(e.DOI && { doi: e.DOI }) };
+    });
+    if (fm) fm.references = refs;
+    if (!refsNode) return;
+    const list = {
+      type: "list", ordered: true, spread: false, data: { hProperties: { className: ["posuta-refs"] } },
+      children: refs.map(({ key, text, doi }) => {
+        const children = urlParts(text + (doi ? " " : "")).map((p, j) => (j % 2
+          ? { type: "link", url: p, children: [{ type: "text", value: p }] } : { type: "text", value: p }));
+        if (doi) children.push({ type: "link", url: `https://doi.org/${doi}`, children: [{ type: "text", value: `doi:${doi}` }] });
+        return { type: "listItem", spread: false, data: { hProperties: { id: `ref-${key}` } }, children: [{ type: "paragraph", children }] };
+      }),
+    };
+    const { parent, child } = refsNode;
+    parent.children.splice(parent.children.indexOf(child), 1, list);
+  };
+}

package/src/svg.js

@@ -0,0 +1,27 @@
+// An SVG file as inline markup for <Figure.Media>: the file's own attributes kept, `class` added to
+// its own, other attributes set, and $…$ in its text rendered with KaTeX (as in charts).
+import { readFileSync } from "node:fs";
+import { parseHTML } from "linkedom";
+import { katex } from "#dom";
+import { mathify } from "./plot.js";
+
+/** @param {string} path @param {Record<string, unknown>} attrs */
+export function inlineSvg(path, { class: cls, ...attrs } = {}) {
+  // Parsed as HTML, like the page it goes into: browsers restore SVG tag case (linearGradient).
+  const text = readFileSync(path, "utf8");
+  const { document } = parseHTML(`<!doctype html><html><body>${text}</body></html>`);
+  const svg = document.querySelector("svg");
+  if (!svg) throw new Error(`posuta: ${path} has no <svg> element`);
+  // linkedom reads the HTML in a foreignObject (KaTeX from texSvg) as SVG and writes its empty
+  // spans as <span/>, which browsers misread; set the file's own markup again, parsed as HTML.
+  const raw = [...text.matchAll(/<foreignObject\b[^>]*>([\s\S]*?)<\/foreignObject>/gi)].map((m) => m[1]);
+  svg.querySelectorAll("foreignobject").forEach((fo, i) => { fo.innerHTML = raw[i] ?? fo.innerHTML; });
+  for (const a of ["xmlns", "xmlns:xlink", "version"]) svg.removeAttribute(a); // not needed inline
+  if (cls) svg.classList.add(...String(cls).split(/\s+/).filter(Boolean));
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === false || v == null) continue;
+    svg.setAttribute(k, v === true ? "" : String(v));
+  }
+  mathify(svg, katex);
+  return svg.outerHTML;
+}

package/src/tex.js

@@ -0,0 +1,29 @@
+// $…$ in plain text → KaTeX: as HTML (tex) or as an SVG label (texSvg). Charts and hand-drawn
+// SVG use these. At build time KaTeX is built in; in the browser pass it in:
+//   tex("$\\omega_n$", (await import("katex")).default)
+import { katex as builtIn } from "#dom";
+
+export const MATH = /\$[^$]+\$/;
+export const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/** Text with $…$ → HTML: the maths rendered with KaTeX, the rest escaped. */
+export function tex(s, katex = builtIn) {
+  if (!katex) throw new Error('posuta tex: in the browser, pass KaTeX: tex(s, (await import("katex")).default)');
+  return String(s).split(/(\$[^$]+\$)/).map((p) => (p.length > 2 && p.startsWith("$") && p.endsWith("$")
+    ? katex.renderToString(p.slice(1, -1), { throwOnError: true, output: "html" }) : esc(p))).join("");
+}
+
+/**
+ * An SVG label with its baseline at (x, y): a <text> for plain text, or KaTeX in a foreignObject
+ * when it holds $…$ (the maths takes the SVG's font size and colour).
+ * @param {{ anchor?: "start" | "middle" | "end", class?: string, size?: number, katex?: any }} [o]
+ */
+export function texSvg(s, x, y, { anchor = "start", class: cls, size, katex } = {}) {
+  const c = cls ? ` class="${esc(cls)}"` : "";
+  if (!MATH.test(s)) {
+    return `<text${c} x="${x}" y="${y}" text-anchor="${anchor}" fill="currentColor"${size ? ` font-size="${size}"` : ""}>${esc(s)}</text>`;
+  }
+  const tx = { start: "0", middle: "-50%", end: "-100%" }[anchor] ?? "0";
+  return `<foreignObject x="${x}" y="${y}" width="1" height="1" overflow="visible"><div xmlns="http://www.w3.org/1999/xhtml"` +
+    ` class="posuta-tex${cls ? " " + esc(cls) : ""}" style="transform:translate(${tx},-80%)">${tex(s, katex)}</div></foreignObject>`;
+}