relaton 3.0.6 → 3.0.8

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

@@ -0,0 +1,151 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  docHref,
+  readDocFromUrl,
+  readPageFromUrl,
+  writeDocToUrl,
+  writePageToUrl,
+} from "./url";
+
+beforeEach(() => {
+  // Start every test from a clean, param-free URL.
+  window.history.replaceState(null, "", "/");
+});
+
+describe("readPageFromUrl", () => {
+  it("parses a valid page param", () => {
+    expect(readPageFromUrl("?page=3")).toBe(3);
+  });
+
+  it("falls back to 1 when the param is missing", () => {
+    expect(readPageFromUrl("")).toBe(1);
+    expect(readPageFromUrl("?foo=1")).toBe(1);
+  });
+
+  it("falls back to 1 for zero, negative, fractional, or non-numeric values", () => {
+    expect(readPageFromUrl("?page=0")).toBe(1);
+    expect(readPageFromUrl("?page=-2")).toBe(1);
+    expect(readPageFromUrl("?page=2.5")).toBe(1);
+    expect(readPageFromUrl("?page=abc")).toBe(1);
+  });
+
+  it("reads the page param alongside other params", () => {
+    expect(readPageFromUrl("?foo=1&page=4")).toBe(4);
+  });
+
+  it("defaults to the live location when no search string is given", () => {
+    window.history.replaceState(null, "", "/?page=7");
+    expect(readPageFromUrl()).toBe(7);
+  });
+});
+
+describe("writePageToUrl", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("sets ?page=N while preserving other params", () => {
+    window.history.replaceState(null, "", "/?foo=bar");
+    writePageToUrl(2);
+    const params = new URLSearchParams(window.location.search);
+    expect(params.get("page")).toBe("2");
+    expect(params.get("foo")).toBe("bar");
+  });
+
+  it("deletes the page param for page 1 (clean canonical URL)", () => {
+    window.history.replaceState(null, "", "/?page=5");
+    writePageToUrl(1);
+    expect(new URLSearchParams(window.location.search).has("page")).toBe(false);
+  });
+
+  it("uses replaceState by default", () => {
+    const replace = vi.spyOn(window.history, "replaceState");
+    const push = vi.spyOn(window.history, "pushState");
+    writePageToUrl(3);
+    expect(replace).toHaveBeenCalledTimes(1);
+    expect(push).not.toHaveBeenCalled();
+  });
+
+  it("uses pushState when mode is 'push'", () => {
+    const replace = vi.spyOn(window.history, "replaceState");
+    const push = vi.spyOn(window.history, "pushState");
+    writePageToUrl(3, "push");
+    expect(push).toHaveBeenCalledTimes(1);
+    expect(replace).not.toHaveBeenCalled();
+  });
+});
+
+describe("readDocFromUrl", () => {
+  it("returns the decoded doc id when present", () => {
+    expect(readDocFromUrl("?doc=CCRI%2021%20(2009)")).toBe("CCRI 21 (2009)");
+  });
+
+  it("returns null when the param is missing or blank", () => {
+    expect(readDocFromUrl("")).toBeNull();
+    expect(readDocFromUrl("?page=2")).toBeNull();
+    expect(readDocFromUrl("?doc=")).toBeNull();
+  });
+
+  it("reads the doc param alongside other params", () => {
+    expect(readDocFromUrl("?page=3&doc=ISO%201234")).toBe("ISO 1234");
+  });
+
+  it("defaults to the live location when no search string is given", () => {
+    window.history.replaceState(null, "", "/?doc=X%201");
+    expect(readDocFromUrl()).toBe("X 1");
+  });
+});
+
+describe("writeDocToUrl", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("sets a path-based /doc/ID URL (encoded) while preserving page", () => {
+    window.history.replaceState(null, "", "/?page=2");
+    writeDocToUrl("CCRI 21 (2009)");
+    expect(window.location.pathname).toBe("/doc/CCRI%2021%20(2009)");
+    expect(new URLSearchParams(window.location.search).get("page")).toBe("2");
+  });
+
+  it("round-trips an id with spaces and parens", () => {
+    writeDocToUrl("BIPM SI Brochure (2019)");
+    expect(readDocFromUrl()).toBe("BIPM SI Brochure (2019)");
+  });
+
+  it("reads a path-based id written by the 404 fallback or a shared link", () => {
+    window.history.replaceState(null, "", "/doc/BCP%203?page=1");
+    expect(readDocFromUrl()).toBe("BCP 3");
+  });
+
+  it("returns to the list path when passed null", () => {
+    window.history.replaceState(null, "", "/doc/X?page=2");
+    writeDocToUrl(null);
+    expect(window.location.pathname).toBe("/");
+    expect(new URLSearchParams(window.location.search).get("page")).toBe("2");
+  });
+
+  it("uses replaceState by default and pushState when asked", () => {
+    const replace = vi.spyOn(window.history, "replaceState");
+    const push = vi.spyOn(window.history, "pushState");
+    writeDocToUrl("A");
+    expect(replace).toHaveBeenCalledTimes(1);
+    expect(push).not.toHaveBeenCalled();
+    writeDocToUrl("B", "push");
+    expect(push).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("docHref", () => {
+  it("builds a relative path-based /doc/ link", () => {
+    window.history.replaceState(null, "", "/");
+    expect(docHref("ISO 1234:2020")).toBe("/doc/ISO%201234%3A2020");
+  });
+
+  it("encodes ids so they round-trip through readDocFromUrl", () => {
+    const id = "CCRI 21st Meeting (2009)";
+    window.history.replaceState(null, "", docHref(id));
+    expect(readDocFromUrl()).toBe(id);
+  });
+});

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

@@ -0,0 +1,111 @@
+// Reflects two pieces of view state in the URL so a reload / shared / bookmarked
+// link restores it: the pagination page (`?page=N`) and the open detail document
+// (`?doc=<id>`). Both go through the History API, preserve any other params, and
+// are synced back on Back/Forward via a `popstate` listener in App.vue.
+// (search/facets/sort stay in-memory; view/theme use localStorage.) Page 1 and a
+// closed detail omit their param to keep the canonical URL clean.
+
+const PARAM = "page";
+const DOC_PARAM = "doc";
+
+/**
+ * Parse the `page` query param. Returns an integer >= 1, or 1 for anything
+ * invalid (missing, zero, negative, fractional, non-numeric).
+ */
+export function readPageFromUrl(
+  search: string = typeof window !== "undefined" ? window.location.search : "",
+): number {
+  const raw = new URLSearchParams(search).get(PARAM);
+  if (raw === null) return 1;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 ? n : 1;
+}
+
+/**
+ * Reflect `page` into the URL, preserving any other query params. Page 1 drops
+ * the param. `mode: "push"` adds a history entry (user navigation, so
+ * Back/Forward walk pages); `"replace"` (default) updates in place (restore,
+ * clamp, filter-reset).
+ */
+export function writePageToUrl(
+  page: number,
+  mode: "push" | "replace" = "replace",
+): void {
+  if (typeof window === "undefined" || !window.history) return;
+  const url = new URL(window.location.href);
+  if (page <= 1) url.searchParams.delete(PARAM);
+  else url.searchParams.set(PARAM, String(page));
+  // Relative target avoids origin surprises across dev/gem/host contexts.
+  const target = `${url.pathname}${url.search}${url.hash}`;
+  if (mode === "push") window.history.pushState(window.history.state, "", target);
+  else window.history.replaceState(window.history.state, "", target);
+}
+
+/**
+ * A relative, shareable link to a document's detail page. Used for the real
+ * anchors that SPA-navigation intercepts — the list rows and the intra-dataset
+ * relation links — so middle-click / open-in-new-tab still work. Built with the
+ * same `URLSearchParams` encoding as `writeDocToUrl`, so the two agree exactly.
+ */
+export function docHref(id: string): string {
+  return `${docPathBase()}/doc/${encodeURIComponent(id)}`;
+}
+
+// The app root (site base path) for path-based doc URLs: whatever precedes a
+// trailing `/doc/<id>` segment on the current pathname, or the full pathname
+// when none (the list view at `/` or `/index.html`).
+function docPathBase(): string {
+  const p = window.location.pathname;
+  const cut = p.lastIndexOf("/doc/");
+  const base = cut >= 0 ? p.slice(0, cut) : p.replace(/\/index\.html$/, "");
+  return base === "/" ? "" : base.replace(/\/+$/, "");
+}
+
+/**
+ * Parse the `doc` query param (the open detail document's id). Returns the
+ * decoded id, or null when absent/blank. `URLSearchParams` handles decoding, so
+ * ids with spaces/parens round-trip with `writeDocToUrl`.
+ */
+export function readDocFromUrl(
+  search: string = typeof window !== "undefined" ? window.location.search : "",
+): string | null {
+  if (search === (typeof window !== "undefined" ? window.location.search : "")) {
+    // Path-based URLs first: `/doc/<id>` served via the 404 fallback (GitHub
+    // Pages has no rewrites) or written by writeDocToUrl below.
+    const m = window.location.pathname.match(/\/doc\/([^/?#]+)$/);
+    if (m) {
+      const fromPath = decodeURIComponent(m[1]);
+      if (fromPath.trim() !== "") return fromPath;
+    }
+  }
+  const raw = new URLSearchParams(search).get(DOC_PARAM);
+  return raw && raw.trim() !== "" ? raw : null;
+}
+
+/**
+ * Reflect the open detail document into the URL, preserving other params (e.g.
+ * `page`, so closing the detail returns to the same list page). A null id drops
+ * the param. `mode: "push"` adds a history entry (opening/closing a detail, so
+ * Back/Forward walk in and out of it); `"replace"` (default) updates in place.
+ */
+export function writeDocToUrl(
+  id: string | null,
+  mode: "push" | "replace" = "replace",
+): void {
+  if (typeof window === "undefined" || !window.history) return;
+  const url = new URL(window.location.href);
+  if (id) {
+    // Canonical per-document URLs are path-based (`<root>/doc/<id>`) so each
+    // document has a shareable address; `?doc=` remains readable for links
+    // written before paths existed and by the 404 fallback redirect.
+    const base = docPathBase();
+    const target = `${base}/doc/${encodeURIComponent(id)}${url.search && url.searchParams.has(PARAM) ? `?${url.searchParams}` : ""}${url.hash}`;
+    if (mode === "push") window.history.pushState(window.history.state, "", target);
+    else window.history.replaceState(window.history.state, "", target);
+    return;
+  }
+  url.searchParams.delete(DOC_PARAM);
+  const target = `${docPathBase()}/${url.search}${url.hash}`;
+  if (mode === "push") window.history.pushState(window.history.state, "", target);
+  else window.history.replaceState(window.history.state, "", target);
+}

data/lib/relaton/cli/frontend/src/shims-vue.d.ts

@@ -0,0 +1,5 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>;
+  export default component;
+}

data/lib/relaton/cli/frontend/src/styles/index.css

@@ -0,0 +1,27 @@
+@import "tailwindcss";
+
+/* Drive the `dark:` variant from a `.dark` class on any ancestor (we toggle it
+   on <html>), rather than the OS media query alone, so the in-page theme toggle
+   works. Falls back to the OS preference on first load (see app.ts). */
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* Design tokens. Kept small; components use Tailwind utilities on top. */
+@theme {
+  --color-brand: #1e6bb8;
+  --color-brand-dark: #4a9fe0;
+  --font-sans: "Inter", ui-sans-serif, system-ui, -apple-system, "Segoe UI",
+    Roboto, Helvetica, Arial, sans-serif;
+}
+
+/* Scope a couple of base rules to the app so we don't fight a host page's CSS. */
+#relaton-index-app {
+  font-family: var(--font-sans);
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* Hide the server-rendered crawler DOM once Vue has taken over (Vue mounts into
+   the same node and replaces its children, but guard against a flash). */
+#relaton-index-app > .documents[hidden] {
+  display: none;
+}

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

@@ -0,0 +1,58 @@
+import { vi } from "vitest";
+
+// Minimal fetch stub for the shard loaders. Routes are keyed by the file name
+// (the last path segment), which is how the loaders address shards.
+//
+// A route value may be:
+//   * a value          — served as JSON with status 200
+//   * a number         — served as that HTTP status with no body (for 404 tests)
+//   * a Promise        — resolved when it resolves (for out-of-order tests)
+//   * a function       — called per request, returning any of the above
+// An unrouted path 404s, so a test only declares the shards it cares about.
+
+export type Route = unknown | Promise<unknown> | (() => unknown);
+
+export interface FetchStub {
+  /** Paths requested, in call order. */
+  calls: string[];
+  restore: () => void;
+}
+
+function respond(body: unknown): Response {
+  if (typeof body === "number") {
+    return new Response(null, { status: body });
+  }
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export function stubFetch(routes: Record<string, Route>): FetchStub {
+  const calls: string[] = [];
+
+  const impl = async (input: RequestInfo | URL): Promise<Response> => {
+    const url =
+      typeof input === "string" ? input : String((input as Request).url ?? input);
+    calls.push(url);
+
+    const name = url.split("/").pop() ?? "";
+    if (!(name in routes)) return new Response(null, { status: 404 });
+
+    let value = routes[name];
+    if (typeof value === "function") value = (value as () => unknown)();
+    return respond(await value);
+  };
+
+  vi.stubGlobal("fetch", vi.fn(impl));
+  return { calls, restore: () => vi.unstubAllGlobals() };
+}
+
+/** A promise plus the handle to settle it, for controlling resolution order. */
+export function deferred<T>(): { promise: Promise<T>; resolve: (v: T) => void } {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}

data/lib/relaton/cli/frontend/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "preserve",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": { "@/*": ["src/*"] }
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"],
+  "exclude": ["dist", "node_modules"]
+}

data/lib/relaton/cli/frontend/vite.config.ts

@@ -0,0 +1,42 @@
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import tailwindcss from "@tailwindcss/vite";
+import { resolve } from "node:path";
+
+const root = import.meta.dirname;
+
+// Library-mode build that emits exactly ONE self-executing bundle
+// (`dist/app.iife.js`) plus one stylesheet (`dist/style.css`). Vue and
+// Tailwind are bundled in, so the output is fully self-contained and can be
+// inlined verbatim into a generated HTML page by the relaton-cli generator.
+//
+// `formats: ["iife"]` + `inlineDynamicImports: true` guarantees a single JS
+// chunk (no code-splitting), matching the lutaml-xsd embedding pattern.
+export default defineConfig({
+  plugins: [vue(), tailwindcss()],
+  resolve: {
+    alias: { "@": resolve(root, "src") },
+  },
+  build: {
+    target: "es2020",
+    cssCodeSplit: false,
+    minify: "terser",
+    terserOptions: { compress: { drop_console: true } },
+    // Library + iife format already emits a single self-executing chunk with no
+    // code-splitting, so the bundle is one JS file the generator can inline.
+    lib: {
+      entry: resolve(root, "src/app.ts"),
+      name: "RelatonIndex",
+      fileName: () => "app.iife.js",
+      formats: ["iife"],
+    },
+    rollupOptions: {
+      output: {
+        assetFileNames: "style.css",
+      },
+    },
+  },
+  define: {
+    "process.env.NODE_ENV": JSON.stringify("production"),
+  },
+});

data/lib/relaton/cli/frontend/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "vitest/config";
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    // Per-file override via `// @vitest-environment happy-dom` where DOM is
+    // needed; pure logic tests stay in the default node environment.
+    environment: "node",
+  },
+});

data/lib/relaton/cli/frontend_assets.rb

@@ -0,0 +1,58 @@
+module Relaton
+  module Cli
+    # Resolves the compiled frontend bundle (`app.iife.js` + `style.css`) that is
+    # built from `gems/relaton-cli/frontend/` at gem-build time and shipped inside
+    # the gem under `frontend/dist/`. Both the installed gem and a git checkout
+    # place `frontend/dist` at the gem root, so one relative path covers both.
+    #
+    # If the bundle is missing (a fresh checkout that hasn't run the frontend
+    # build), raise a clear, actionable error rather than emitting a broken page.
+    module FrontendAssets
+      class BuildMissingError < StandardError; end
+
+      # gem root = up three from lib/relaton/cli
+      DEFAULT_DIST = File.expand_path("frontend/dist", __dir__).freeze
+
+      class << self
+        # Overridable so specs can point at a fixture dist without a Node build.
+        attr_writer :dist_dir
+
+        def dist_dir
+          @dist_dir || DEFAULT_DIST
+        end
+
+        # Run a block with a temporary dist dir, restoring the previous one.
+        def with_dist_dir(dir)
+          previous = @dist_dir
+          @dist_dir = dir
+          yield
+        ensure
+          @dist_dir = previous
+        end
+
+        def iife
+          read("app.iife.js")
+        end
+
+        def stylesheet
+          read("style.css")
+        end
+
+        def built?
+          File.exist?(File.join(dist_dir, "app.iife.js"))
+        end
+
+        def read(name)
+          path = File.join(dist_dir, name)
+          unless File.exist?(path)
+            raise BuildMissingError,
+                  "Frontend build missing (#{name} not found in #{dist_dir}). " \
+                  "Run `bundle exec rake build_frontend` in gems/relaton-cli " \
+                  "(or `cd frontend && npm install && npm run build`) first."
+          end
+          File.read(path, encoding: "utf-8")
+        end
+      end
+    end
+  end
+end

data/lib/relaton/cli/full_text_search.rb

@@ -0,0 +1,98 @@
+require "set"
+
+module Relaton
+  class FullTextSeatch
+    # Instance variables added by lutaml-model that form back-references
+    # (cycles) when a model is serialized. Skipping them keeps recursive
+    # traversal of a bibitem's object graph finite.
+    INTERNAL_IVARS = %i[
+      @using_default @lutaml_register @lutaml_parent @lutaml_root @register_records
+    ].freeze
+
+    # @return Regexp
+    attr_reader :regex
+
+    # @param collection [Relaton::Bibcollection]
+    def initialize(collection)
+      @collection = collection
+    end
+
+    # @param text [String]
+    # @return [Array<Hash>]
+    def search(text)
+      @regex = %{(.*?)(.{0,20})(#{text})(.{0,20})(.*)}
+      @matches = @collection.items.reduce({}) do |m, item|
+        res = result item, Set.new
+        m[item.id] = res if res.any?
+        m
+      end
+    end
+
+    def print_results
+      @matches.each do |docid, attrs|
+        puts "  Document ID: #{docid}"
+        print_attrs attrs, 4
+      end
+    end
+
+    # @return [Boolean]
+    def any?
+      @matches.any?
+    end
+
+    private
+
+    # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+    def print_attrs(attrs, indent)
+      ind = " " * indent
+      if attrs.is_a? String then puts ind + attrs
+      elsif attrs.is_a? Hash
+        attrs.each do |key, val|
+          pref = "#{ind}#{key}:"
+          if val.is_a? String then puts pref + " " + val
+          else
+            puts pref
+            print_attrs val, indent + 2
+          end
+        end
+      elsif attrs.is_a? Array then attrs.each { |v| print_attrs v, indent + 2 }
+      end
+    end
+
+    # @param item [Relaton::Bibdata]
+    # @param seen [Set<Integer>] object_ids already visited on this path
+    # @return [Hash]
+    def result(item, seen)
+      if item.is_a? String
+        message $~ if item.match regex
+      elsif item.respond_to? :reduce
+        item.reduce([]) do |m, i|
+          res = result i, seen
+          m << res if res && !res.empty?
+          m
+        end
+      else
+        return {} unless seen.add?(item.object_id)
+
+        item.instance_variables.reduce({}) do |m, var|
+          next m if INTERNAL_IVARS.include?(var)
+
+          res = result item.instance_variable_get(var), seen
+          m[var.to_s.tr(":@", "")] = res if res && !res.empty?
+          m
+        end
+      end
+    end
+    # rubocop:enable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+
+    # @param match [MatchData]
+    # @return [String]
+    def message(match)
+      msg = ""
+      msg += "..." unless match[1].empty?
+      msg += "#{match[2]}\e[4m#{match[3]}\e[24m#{match[4]}"
+      msg += "..." unless match[5].empty?
+      msg
+    end
+  end
+end

data/lib/relaton/cli/i18n.yaml

@@ -0,0 +1 @@
+label: label