relaton 3.0.6 → 3.0.8

data/lib/relaton/cli/frontend/src/dev/main.ts

@@ -0,0 +1,100 @@
+// Dev-only entry: shard the sample dataset in memory, serve it over a stubbed
+// fetch, and boot the app exactly as a generated page would.
+// Excluded from the production library build (which uses src/app.ts).
+//
+// This mirrors what Relaton::Cli::IndexSiteGenerator writes — the mount-node
+// scalars plus `search-NNNN.json` / `detail-NNNN.json` — so `npm run dev`
+// exercises the real hydration path instead of a shortcut that only exists here.
+// The shard sizes are deliberately tiny so progressive loading is visible.
+import sample from "./sample-data.json";
+import type {
+  CompactRecord,
+  DetailRecord,
+  IndexData,
+  IndexDocument,
+} from "../lib/types";
+
+const SHARD_SIZE = 3;
+const DETAIL_SHARD_SIZE = 2;
+
+const data = sample as IndexData;
+const documents = data.documents ?? [];
+
+const SUMMARY_KEYS: readonly string[] = [
+  "id",
+  "title",
+  "doctype",
+  "stage",
+  "date",
+  "link",
+  "yaml",
+];
+
+function toCompact(doc: IndexDocument): CompactRecord {
+  return {
+    r: doc.id,
+    c: doc.title,
+    t: doc.doctype,
+    s: doc.stage,
+    d: doc.date,
+    u: doc.yaml,
+    l: doc.link,
+  };
+}
+
+function toDetail(doc: IndexDocument): DetailRecord | null {
+  const rest = Object.fromEntries(
+    Object.entries(doc).filter(([key]) => !SUMMARY_KEYS.includes(key)),
+  );
+  if (Object.keys(rest).length === 0) return null;
+  return { r: doc.id, ...rest } as DetailRecord;
+}
+
+function chunk<T>(items: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(items.slice(i, i + size));
+  }
+  return out;
+}
+
+const summaryShards = chunk(documents.map(toCompact), SHARD_SIZE);
+const detailShards = chunk(documents.map(toDetail), DETAIL_SHARD_SIZE);
+
+const files = new Map<string, unknown>();
+summaryShards.forEach((rows, i) => {
+  files.set(`search-${String(i).padStart(4, "0")}.json`, rows);
+});
+detailShards.forEach((rows, i) => {
+  files.set(`detail-${String(i).padStart(4, "0")}.json`, rows);
+});
+
+const realFetch = window.fetch.bind(window);
+window.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+  const url = typeof input === "string" ? input : String((input as Request).url ?? input);
+  const name = url.split("/").pop() ?? "";
+  const body = files.get(name);
+  if (body !== undefined) {
+    return Promise.resolve(
+      new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+  }
+  return realFetch(input as RequestInfo, init);
+}) as typeof window.fetch;
+
+const el = document.getElementById("relaton-index-app");
+if (el) {
+  el.dataset.title = data.title ?? "Relaton Index";
+  if (data.description) el.dataset.description = data.description;
+  if (data.generated) el.dataset.generated = data.generated;
+  el.dataset.total = String(documents.length);
+  el.dataset.shards = String(summaryShards.length);
+  el.dataset.shardSize = String(SHARD_SIZE);
+  el.dataset.detailShards = String(detailShards.length);
+  el.dataset.detailShardSize = String(DETAIL_SHARD_SIZE);
+}
+
+import("../app");

data/lib/relaton/cli/frontend/src/dev/sample-data.json

@@ -0,0 +1,71 @@
+{
+  "title": "BIPM Index",
+  "generated": "2026-08-05",
+  "documents": [
+    {
+      "id": "BIPM CCRI 21 (2009)",
+      "title": "21st meeting of the CCRI",
+      "doctype": "meeting-report",
+      "stage": "published",
+      "date": "2009-06-19",
+      "link": "https://www.bipm.org/en/committees/cc/ccri/21-2009",
+      "yaml": "https://raw.githubusercontent.com/relaton/relaton-data-bipm/v2/data/ccri/meeting/21.yaml",
+      "abstract": "Report of the 21st meeting of the Consultative Committee for Ionizing Radiation (CCRI), held at the BIPM.",
+      "languages": ["en", "fr"],
+      "publisher": "International Bureau of Weights and Measures",
+      "contributors": [
+        { "name": "International Bureau of Weights and Measures", "role": "publisher" }
+      ],
+      "docids": [
+        { "id": "CCRI 21st Meeting (2009)", "type": "BIPM", "language": "en" },
+        { "id": "CCRI 21e réunion (2009)", "type": "BIPM", "language": "fr" }
+      ],
+      "dates": [{ "type": "published", "value": "2009-06-19" }],
+      "relations": [
+        { "type": "obsoletedBy", "id": "BIPM CCRI 22 (2013)" },
+        { "type": "partOf", "id": "BIPM CGPM 26 (2018)" },
+        { "type": "updates", "id": "ISO/IEC/IEEE 60559:2011" }
+      ]
+    },
+    {
+      "id": "BIPM CCRI 22 (2013)",
+      "title": "22nd meeting of the CCRI",
+      "doctype": "meeting-report",
+      "stage": "published",
+      "date": "2013-05-15",
+      "link": null,
+      "yaml": "https://raw.githubusercontent.com/relaton/relaton-data-bipm/v2/data/ccri/meeting/22.yaml"
+    },
+    {
+      "id": "BIPM CGPM 26 (2018)",
+      "title": "26th meeting of the CGPM",
+      "doctype": "meeting-report",
+      "stage": "published",
+      "date": "2018-11-13",
+      "link": null,
+      "yaml": "https://raw.githubusercontent.com/relaton/relaton-data-bipm/v2/data/cgpm/meeting/26.yaml"
+    },
+    {
+      "id": "BIPM SI Brochure (2019)",
+      "title": "The International System of Units (SI), 9th edition",
+      "doctype": "brochure",
+      "stage": "published",
+      "date": "2019-05-20",
+      "link": null,
+      "yaml": "https://raw.githubusercontent.com/relaton/relaton-data-bipm/v2/data/si-brochure.yaml",
+      "abstract": "The SI Brochure is the defining document for the International System of Units, published by the BIPM.",
+      "edition": "9",
+      "languages": ["en", "fr"],
+      "keywords": ["metrology", "SI units", "base units"],
+      "publisher": "International Bureau of Weights and Measures",
+      "contributors": [
+        { "name": "International Bureau of Weights and Measures", "role": "publisher" }
+      ],
+      "docids": [{ "id": "SI Brochure (2019)", "type": "BIPM", "language": "en" }],
+      "dates": [
+        { "type": "published", "value": "2019-05-20" },
+        { "type": "created", "value": "2018" }
+      ]
+    }
+  ]
+}

data/lib/relaton/cli/frontend/src/lib/filter.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { applyFilters, compareDocuments, distinctValues, matchesQuery } from "./filter";
+import type { SortDir } from "./filter";
+import type { IndexDocument } from "./types";
+
+const doc = (over: Partial<IndexDocument>): IndexDocument => ({
+  id: "X 1",
+  title: "Title",
+  doctype: null,
+  stage: null,
+  date: null,
+  link: null,
+  yaml: null,
+  ...over,
+});
+
+const docs: IndexDocument[] = [
+  doc({ id: "CCRI 2", title: "Second meeting", doctype: "meeting-report", stage: "published", date: "2009-06-19" }),
+  doc({ id: "CCRI 10", title: "Tenth meeting", doctype: "meeting-report", stage: "draft", date: "2019-01-01" }),
+  doc({ id: "SI Brochure", title: "The SI", doctype: "brochure", stage: "published", date: "2019-05-20" }),
+];
+
+describe("matchesQuery", () => {
+  it("matches all terms case-insensitively", () => {
+    expect(matchesQuery(docs[0], "second CCRI")).toBe(true);
+    expect(matchesQuery(docs[0], "brochure")).toBe(false);
+    expect(matchesQuery(docs[0], "")).toBe(true);
+  });
+});
+
+describe("distinctValues", () => {
+  it("returns sorted distinct non-empty values", () => {
+    expect(distinctValues(docs, "doctype")).toEqual(["brochure", "meeting-report"]);
+    expect(distinctValues(docs, "stage")).toEqual(["draft", "published"]);
+  });
+});
+
+describe("compareDocuments", () => {
+  it("sorts ids naturally (2 before 10)", () => {
+    expect(compareDocuments(docs[0], docs[1], "id", "asc")).toBeLessThan(0);
+  });
+  it("reverses on desc", () => {
+    expect(compareDocuments(docs[0], docs[1], "id", "desc")).toBeGreaterThan(0);
+  });
+});
+
+describe("applyFilters", () => {
+  it("filters by facet and sorts", () => {
+    const out = applyFilters(docs, {
+      query: "",
+      doctypes: new Set(["meeting-report"]),
+      stages: new Set(),
+      sortKey: "id",
+      sortDir: "asc",
+    });
+    expect(out.map((d) => d.id)).toEqual(["CCRI 2", "CCRI 10"]);
+  });
+
+  it("combines search + stage facet", () => {
+    const out = applyFilters(docs, {
+      query: "meeting",
+      doctypes: new Set(),
+      stages: new Set(["published"]),
+      sortKey: "date",
+      sortDir: "asc",
+    });
+    expect(out.map((d) => d.id)).toEqual(["CCRI 2"]);
+  });
+});
+
+describe("date sort with missing dates", () => {
+  it("sorts undated documents last in both directions", () => {
+    const docs = [
+      doc({ id: "undated-a", title: "x" }),
+      doc({ id: "dated-2020", title: "x", date: "2020-01-01" }),
+      doc({ id: "undated-b", title: "x" }),
+      doc({ id: "dated-1999", title: "x", date: "1999-01-01" }),
+    ];
+    const opts = (sortDir: SortDir) => ({
+      query: "", doctypes: new Set<string>(), stages: new Set<string>(),
+      sortKey: "date" as const, sortDir,
+    });
+    expect(applyFilters(docs, opts("asc")).map((d) => d.id))
+      .toEqual(["dated-1999", "dated-2020", "undated-a", "undated-b"]);
+    expect(applyFilters(docs, opts("desc")).map((d) => d.id))
+      .toEqual(["dated-2020", "dated-1999", "undated-a", "undated-b"]);
+  });
+});

data/lib/relaton/cli/frontend/src/lib/filter.ts

@@ -0,0 +1,95 @@
+import type { IndexDocument } from "./types";
+
+export type SortKey = "id" | "date" | "title";
+export type SortDir = "asc" | "desc";
+
+/** Lowercased haystack for a document (id + title + doctype). */
+export function searchText(doc: IndexDocument): string {
+  return `${doc.id} ${doc.title} ${doc.doctype ?? ""}`.toLowerCase();
+}
+
+/** Case-insensitive AND-of-terms match over the search haystack. */
+export function matchesQuery(doc: IndexDocument, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (!q) return true;
+  const hay = searchText(doc);
+  return q.split(/\s+/).every((term) => hay.includes(term));
+}
+
+/** Distinct, sorted non-empty values of a field across documents. */
+export function distinctValues(
+  docs: IndexDocument[],
+  key: "doctype" | "stage",
+): string[] {
+  const set = new Set<string>();
+  for (const d of docs) {
+    const v = d[key];
+    if (v) set.add(v);
+  }
+  return Array.from(set).sort((a, b) => a.localeCompare(b));
+}
+
+// Natural (human) comparison so "CCRI 2" sorts before "CCRI 10".
+const collator = new Intl.Collator(undefined, {
+  numeric: true,
+  sensitivity: "base",
+});
+
+export function compareDocuments(
+  a: IndexDocument,
+  b: IndexDocument,
+  key: SortKey,
+  dir: SortDir,
+): number {
+  let cmp = 0;
+  switch (key) {
+    case "date": {
+      // Missing dates sort last regardless of direction. An empty string
+      // compared with localeCompare sorts FIRST ascending — with tens of
+      // thousands of undated records that made date-asc look like no-op.
+      const ad = a.date;
+      const bd = b.date;
+      if (!ad && !bd) return 0;
+      if (!ad) return 1;
+      if (!bd) return -1;
+      cmp = ad.localeCompare(bd);
+      break;
+    }
+    case "title":
+      cmp = collator.compare(a.title, b.title);
+      break;
+    case "id":
+    default:
+      cmp = collator.compare(a.id, b.id);
+      break;
+  }
+  return dir === "asc" ? cmp : -cmp;
+}
+
+export interface FilterOptions {
+  query: string;
+  doctypes: Set<string>;
+  stages: Set<string>;
+  sortKey: SortKey;
+  sortDir: SortDir;
+}
+
+/** Apply search + facet filters, then sort. Pure — safe to unit test. */
+export function applyFilters(
+  docs: IndexDocument[],
+  opts: FilterOptions,
+): IndexDocument[] {
+  const filtered = docs.filter((d) => {
+    if (!matchesQuery(d, opts.query)) return false;
+    if (opts.doctypes.size && !(d.doctype && opts.doctypes.has(d.doctype))) {
+      return false;
+    }
+    if (opts.stages.size && !(d.stage && opts.stages.has(d.stage))) {
+      return false;
+    }
+    return true;
+  });
+  return filtered.sort((a, b) =>
+    compareDocuments(a, b, opts.sortKey, opts.sortDir),
+  );
+}

data/lib/relaton/cli/frontend/src/lib/hydrate.test.ts

@@ -0,0 +1,102 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it } from "vitest";
+import { readShardInfo, resolveIndex } from "./hydrate";
+
+function mount(attrs: Record<string, string> = {}): HTMLElement {
+  const el = document.createElement("div");
+  el.id = "relaton-index-app";
+  Object.entries(attrs).forEach(([k, v]) => el.setAttribute(`data-${k}`, v));
+  document.body.appendChild(el);
+  return el;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  document.title = "";
+});
+
+describe("resolveIndex", () => {
+  it("reads the branding off the mount node", () => {
+    const el = mount({
+      title: "BIPM Index",
+      description: "The BIPM standards index.",
+      generated: "2026-01-01",
+    });
+    const { data } = resolveIndex(el);
+    expect(data.title).toBe("BIPM Index");
+    expect(data.description).toBe("The BIPM standards index.");
+    expect(data.generated).toBe("2026-01-01");
+  });
+
+  // Documents arrive from the shards; the shell carries none, so the app paints
+  // immediately with an empty list rather than awaiting anything.
+  it("starts with no documents", () => {
+    const { data } = resolveIndex(mount({ total: "42", shards: "3" }));
+    expect(data.documents).toEqual([]);
+  });
+
+  it("exposes the shard layout alongside the branding", () => {
+    const { shards } = resolveIndex(mount({ total: "42", shards: "3" }));
+    expect(shards.total).toBe(42);
+    expect(shards.shards).toBe(3);
+  });
+
+  it("falls back to the page h1, then document.title, then a default", () => {
+    document.title = "From document title";
+    expect(resolveIndex(mount()).data.title).toBe("From document title");
+
+    document.body.innerHTML = "";
+    const h1 = document.createElement("h1");
+    h1.textContent = "From heading";
+    document.body.appendChild(h1);
+    expect(resolveIndex(mount()).data.title).toBe("From heading");
+
+    document.body.innerHTML = "";
+    document.title = "";
+    expect(resolveIndex(mount()).data.title).toBe("Relaton Index");
+  });
+
+  it("reports no description when the attribute is absent or blank", () => {
+    expect(resolveIndex(mount()).data.description).toBeNull();
+    expect(resolveIndex(mount({ description: "" })).data.description).toBeNull();
+  });
+});
+
+describe("readShardInfo", () => {
+  it("reads the five scalars the generator writes", () => {
+    const el = mount({
+      total: "166658",
+      shards: "34",
+      "shard-size": "5000",
+      "detail-shards": "334",
+      "detail-shard-size": "500",
+    });
+    expect(readShardInfo(el)).toEqual({
+      total: 166658,
+      shards: 34,
+      shardSize: 5000,
+      detailShards: 334,
+      detailShardSize: 500,
+    });
+  });
+
+  // An index with zero shards renders as an empty but correctly branded page —
+  // better than throwing on a malformed shell.
+  it("treats missing, blank or non-numeric attributes as zero", () => {
+    expect(readShardInfo(mount())).toEqual({
+      total: 0,
+      shards: 0,
+      shardSize: 0,
+      detailShards: 0,
+      detailShardSize: 0,
+    });
+    expect(readShardInfo(mount({ shards: "" })).shards).toBe(0);
+    expect(readShardInfo(mount({ shards: "lots" })).shards).toBe(0);
+    expect(readShardInfo(mount({ shards: "-3" })).shards).toBe(0);
+  });
+
+  it("reports zero detail shards for a --no-detail build", () => {
+    const el = mount({ total: "2", shards: "1", "detail-shards": "0" });
+    expect(readShardInfo(el).detailShards).toBe(0);
+  });
+});

data/lib/relaton/cli/frontend/src/lib/hydrate.ts

@@ -0,0 +1,55 @@
+import type { IndexData, ShardInfo } from "./types";
+
+// Read the page's index metadata off the mount node. There is exactly one
+// delivery mode: the shell carries branding plus the shard layout, and the
+// documents themselves arrive from the `search-NNNN.json` shards (see
+// ./shards.ts). Nothing is fetched here, so this is synchronous and the app can
+// paint immediately instead of waiting on a manifest round-trip.
+export interface HydratedIndex {
+  /** Branding + an empty document list for the app to fill as shards land. */
+  data: IndexData;
+  shards: ShardInfo;
+}
+
+export function resolveIndex(el: HTMLElement): HydratedIndex {
+  return {
+    data: {
+      title: pageTitle(el),
+      description: pageDescription(el),
+      documents: [],
+      generated: el.dataset.generated || null,
+    },
+    shards: readShardInfo(el),
+  };
+}
+
+// A missing or unparseable attribute reads as 0 — an index with no shards,
+// which renders as an empty (but correctly branded) page rather than throwing.
+function count(value: string | undefined): number {
+  const n = Number.parseInt(value ?? "", 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+export function readShardInfo(el: HTMLElement): ShardInfo {
+  return {
+    total: count(el.dataset.total),
+    shards: count(el.dataset.shards),
+    shardSize: count(el.dataset.shardSize),
+    detailShards: count(el.dataset.detailShards),
+    detailShardSize: count(el.dataset.detailShardSize),
+  };
+}
+
+function pageTitle(el: HTMLElement): string {
+  return (
+    el.dataset.title ||
+    document.querySelector("h1")?.textContent?.trim() ||
+    document.title ||
+    "Relaton Index"
+  );
+}
+
+/** The site blurb, carried on the mount node (also the meta description). */
+function pageDescription(el: HTMLElement): string | null {
+  return el.dataset.description || null;
+}