@shortlink-org/portolan 0.1.0

package/src/table/compare.ts

@@ -0,0 +1,196 @@
+// One comparator per column type.
+//
+// Every one of these returns an ASCENDING comparison and nothing else: the
+// table reverses the result itself when a column is sorted descending, so a
+// comparator that flips its own sign flips it twice. Empty cells never reach
+// here — an empty cell is `undefined`, and the table places undefined last in
+// both directions before it asks anyone to compare anything.
+
+import type { Status } from "../catalog";
+import type { Kind } from "../lib/kinds";
+import type { CellValue, ColumnType } from "./types";
+
+/** Ascending status order. The strongest claim about reality comes first. */
+const STATUS_RANK: Record<Status, number> = {
+  verified: 0,
+  declared: 1,
+  unresolved: 2,
+};
+
+/**
+ * Ascending kind order: the five building blocks in the order the spec names
+ * them, then everything else in tree order, so a `kind` column of mixed rows
+ * still has one answer rather than an alphabetical accident.
+ */
+const KIND_RANK: Record<Kind, number> = {
+  event: 0,
+  command: 1,
+  query: 2,
+  entity: 3,
+  vo: 4,
+  enum: 5,
+  def: 5,
+  aggregate: 6,
+  // What the outside can call sits between the model and where it is kept: it
+  // is not one of the building blocks, and it is not infrastructure either.
+  endpoint: 7,
+  // The schema an interface was declared in, between what it offers and where
+  // its state is kept - the same place the palette ranks it.
+  module: 8,
+  // Where the model is kept comes after the model itself, and a store before
+  // the tables in it - the same order the palette ranks them in.
+  store: 9,
+  table: 10,
+  view: 11,
+  service: 12,
+  context: 13,
+  external: 13,
+  flow: 14,
+  adr: 15,
+  term: 16,
+};
+
+/** Case-insensitive, then case-sensitive, so the order is never arbitrary. */
+export function compareText(a: string, b: string): number {
+  const folded = a.localeCompare(b, undefined, { sensitivity: "base" });
+  if (folded !== 0) return folded;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function compareNumber(a: number, b: number): number {
+  return a - b;
+}
+
+const VERSION_RE = /^[vV]?\d+(\.\d+)*([-+].*)?$/;
+
+/** Splits "v1.2.3-rc.1" into [1, 2, 3] and "rc.1". */
+function parseVersion(
+  raw: string,
+): { release: number[]; pre: string[] } | null {
+  if (!VERSION_RE.test(raw)) return null;
+  // Build metadata is not part of precedence; a "+build" suffix is dropped.
+  const body = raw.replace(/^[vV]/, "").split("+")[0] ?? "";
+  // Split at the FIRST hyphen only: "1.0.0-rc-2" has one prerelease, not two.
+  const dash = body.indexOf("-");
+  const core = dash === -1 ? body : body.slice(0, dash);
+  const prerelease = dash === -1 ? "" : body.slice(dash + 1);
+  return {
+    release: core.split(".").map((part) => Number(part)),
+    pre: prerelease === "" ? [] : prerelease.split("."),
+  };
+}
+
+/**
+ * Semver precedence, and the reason this file exists: 2 before 10, every time.
+ * Anything that is not shaped like a version falls back to text, so a column
+ * that turns out to hold "latest" still has a defined order.
+ */
+export function compareVersion(a: string, b: string): number {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (!va || !vb) {
+    // A version always precedes a word: "1.0" is a release, "latest" is a wish.
+    if (va) return -1;
+    if (vb) return 1;
+    return compareText(a, b);
+  }
+
+  const depth = Math.max(va.release.length, vb.release.length);
+  for (let i = 0; i < depth; i++) {
+    // A missing segment is zero: 1.2 and 1.2.0 are the same version.
+    const diff = (va.release[i] ?? 0) - (vb.release[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+
+  // A prerelease precedes the release it leads to; 1.0.0-rc.1 < 1.0.0.
+  if (va.pre.length === 0 && vb.pre.length === 0) return 0;
+  if (va.pre.length === 0) return 1;
+  if (vb.pre.length === 0) return -1;
+
+  const parts = Math.max(va.pre.length, vb.pre.length);
+  for (let i = 0; i < parts; i++) {
+    const pa = va.pre[i];
+    const pb = vb.pre[i];
+    // The shorter prerelease wins when everything before it matched.
+    if (pa === undefined) return -1;
+    if (pb === undefined) return 1;
+    const na = /^\d+$/.test(pa) ? Number(pa) : null;
+    const nb = /^\d+$/.test(pb) ? Number(pb) : null;
+    if (na !== null && nb !== null) {
+      if (na !== nb) return na - nb;
+      continue;
+    }
+    // Numeric identifiers rank below alphanumeric ones.
+    if (na !== null) return -1;
+    if (nb !== null) return 1;
+    const text = compareText(pa, pb);
+    if (text !== 0) return text;
+  }
+  return 0;
+}
+
+/** Oldest first. An unparseable date compares as the text it is. */
+export function compareDate(a: string, b: string): number {
+  const ta = Date.parse(a);
+  const tb = Date.parse(b);
+  const okA = Number.isFinite(ta);
+  const okB = Number.isFinite(tb);
+  if (!okA || !okB) {
+    if (okA) return -1;
+    if (okB) return 1;
+    return compareText(a, b);
+  }
+  return ta - tb;
+}
+
+export function compareStatus(a: string, b: string): number {
+  const ra = STATUS_RANK[a as Status];
+  const rb = STATUS_RANK[b as Status];
+  // A value outside the vocabulary sorts after every value inside it.
+  if (ra === undefined || rb === undefined) {
+    if (ra !== undefined) return -1;
+    if (rb !== undefined) return 1;
+    return compareText(a, b);
+  }
+  return ra - rb;
+}
+
+export function compareKind(a: string, b: string): number {
+  const ra = KIND_RANK[a as Kind];
+  const rb = KIND_RANK[b as Kind];
+  if (ra === undefined || rb === undefined) {
+    if (ra !== undefined) return -1;
+    if (rb !== undefined) return 1;
+    return compareText(a, b);
+  }
+  return ra - rb;
+}
+
+/** The comparator a column of this type sorts by. */
+export function comparatorFor(
+  type: ColumnType,
+): (a: CellValue, b: CellValue) => number {
+  return (a, b) => {
+    // Defensive only: the table filters undefined out before it gets here.
+    if (a === undefined || b === undefined) {
+      if (a === b) return 0;
+      return a === undefined ? 1 : -1;
+    }
+    switch (type) {
+      case "number":
+      case "count":
+        return compareNumber(Number(a), Number(b));
+      case "version":
+        return compareVersion(String(a), String(b));
+      case "date":
+        return compareDate(String(a), String(b));
+      case "status":
+        return compareStatus(String(a), String(b));
+      case "kind":
+        return compareKind(String(a), String(b));
+      case "text":
+      case "mono":
+        return compareText(String(a), String(b));
+    }
+  };
+}

package/src/table/export.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { csvFilename, toCsv, toExcelCsv, toMarkdown } from "./export";
+
+const SHEET = {
+  headers: ["name", "consumers"],
+  rows: [
+    ["order.placed", "3"],
+    ["order.cancelled", "1"],
+  ],
+};
+
+describe("toMarkdown", () => {
+  it("writes a header, a delimiter and one line per row", () => {
+    expect(toMarkdown(SHEET)).toBe(
+      [
+        "| name | consumers |",
+        "| --- | --- |",
+        "| order.placed | 3 |",
+        "| order.cancelled | 1 |",
+      ].join("\n"),
+    );
+  });
+
+  it("escapes a pipe so the row keeps its width", () => {
+    const out = toMarkdown({ headers: ["a"], rows: [["x | y"]] });
+    expect(out.split("\n")[2]).toBe("| x \\| y |");
+  });
+
+  it("flattens a newline rather than breaking the row", () => {
+    const out = toMarkdown({ headers: ["a"], rows: [["one\ntwo"]] });
+    expect(out.split("\n")).toHaveLength(3);
+    expect(out.split("\n")[2]).toBe("| one two |");
+  });
+
+  it("pads a short row out to the header width", () => {
+    const out = toMarkdown({ headers: ["a", "b"], rows: [["x"]] });
+    expect(out.split("\n")[2]).toBe("| x |  |");
+  });
+
+  it("writes nothing when there are no columns", () => {
+    expect(toMarkdown({ headers: [], rows: [] })).toBe("");
+  });
+});
+
+describe("toCsv", () => {
+  it("writes CRLF rows", () => {
+    expect(toCsv(SHEET)).toBe(
+      "name,consumers\r\norder.placed,3\r\norder.cancelled,1",
+    );
+  });
+
+  it("quotes a cell holding a comma", () => {
+    expect(toCsv({ headers: ["a"], rows: [["x,y"]] })).toBe('a\r\n"x,y"');
+  });
+
+  it("doubles an embedded quote", () => {
+    expect(toCsv({ headers: ["a"], rows: [['say "hi"']] })).toBe(
+      'a\r\n"say ""hi"""',
+    );
+  });
+
+  it("keeps a newline inside its quotes", () => {
+    expect(toCsv({ headers: ["a"], rows: [["one\ntwo"]] })).toBe(
+      'a\r\n"one\ntwo"',
+    );
+  });
+
+  it("neutralizes spreadsheet formulas without changing negative numbers", () => {
+    expect(toCsv({ headers: ["a"], rows: [["=CMD()"], ["@SUM(A:A)"], ["-42"], ["-SUM(A:A)"]] })).toBe(
+      "a\r\n'=CMD()\r\n'@SUM(A:A)\r\n-42\r\n'-SUM(A:A)",
+    );
+  });
+
+  it("adds a UTF-8 BOM only for the Excel download", () => {
+    expect(toExcelCsv(SHEET).charCodeAt(0)).toBe(0xfeff);
+    expect(toCsv(SHEET).charCodeAt(0)).not.toBe(0xfeff);
+  });
+});
+
+describe("csvFilename", () => {
+  it("slugs the table id", () => {
+    expect(csvFilename("adr.index")).toBe("adr-index.csv");
+  });
+
+  it("falls back when the id slugs to nothing", () => {
+    expect(csvFilename("///")).toBe("table.csv");
+  });
+});

package/src/table/export.ts

@@ -0,0 +1,66 @@
+// The table, taken elsewhere.
+//
+// What leaves is the CURRENT view: filtered, sorted, visible columns only, in
+// the order on screen. That is the whole value of it - a reader who has just
+// narrowed forty rows to the four that matter wants those four in the issue,
+// not the forty they started with, and not in a different order.
+
+/** A view, flattened: the header line and the body, already in display order. */
+export interface Sheet {
+  headers: string[];
+  rows: string[][];
+}
+
+/** A cell that would break the row it is in, made safe for one line of GFM. */
+function markdownCell(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/\|/g, "\\|")
+    // A GFM row is a line. A cell that contains a newline is not a cell.
+    .replace(/\r?\n/g, " ")
+    .trim();
+}
+
+/**
+ * Valid GFM: a header row, a delimiter row of the same width, and one line
+ * per row. Column widths are not padded - a diff of a padded table is a diff
+ * of every line, and this is written to be pasted into an issue.
+ */
+export function toMarkdown({ headers, rows }: Sheet): string {
+  if (headers.length === 0) return "";
+  const line = (cells: string[]) =>
+    `| ${headers.map((_, i) => markdownCell(cells[i] ?? "")).join(" | ")} |`;
+  return [
+    line(headers),
+    `| ${headers.map(() => "---").join(" | ")} |`,
+    ...rows.map(line),
+  ].join("\n");
+}
+
+/** RFC 4180: quote when the cell holds a comma, a quote, or a line break. */
+function csvCell(value: string): string {
+	// A CSV is often opened as a spreadsheet. Keep text that starts like a
+	// formula as text; negative numbers remain numbers.
+	if (/^[\t\r ]*[=+@]/.test(value) || /^[\t\r ]*-(?!\d+(?:[.,]\d+)?$)/.test(value)) {
+		value = `'${value}`;
+	}
+  if (!/[",\r\n]/.test(value)) return value;
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+export function toCsv({ headers, rows }: Sheet): string {
+  const line = (cells: string[]) =>
+    headers.map((_, i) => csvCell(cells[i] ?? "")).join(",");
+  return [line(headers), ...rows.map(line)].join("\r\n");
+}
+
+/** UTF-8 CSV as Excel expects it when opened directly from a download. */
+export function toExcelCsv(sheet: Sheet): string {
+  return `\uFEFF${toCsv(sheet)}`;
+}
+
+/** A filename a download can carry without quoting anything. */
+export function csvFilename(tableId: string): string {
+  const slug = tableId.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return `${slug === "" ? "table" : slug}.csv`;
+}

package/src/table/facet-groups.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { facetGroupFrom, facetValuesFrom } from "./facet-groups";
+import type { ColumnSpec } from "./types";
+
+type Row = { status: string; note?: string };
+
+const status: ColumnSpec<Row> = {
+  id: "status",
+  header: "status",
+  type: "status",
+  value: (row) => row.status,
+  facet: true,
+};
+
+describe("facetValuesFrom", () => {
+  it("skips the empty cell and counts the rest", () => {
+    const counts = new Map<unknown, number>([
+      ["declared", 2],
+      [undefined, 5],
+      ["verified", 3],
+    ]);
+    expect(facetValuesFrom(counts, "status")).toEqual([
+      { value: "verified", count: 3 },
+      { value: "declared", count: 2 },
+    ]);
+  });
+
+  it("is no facet at all when there is only one value", () => {
+    const counts = new Map<unknown, number>([["verified", 9], [undefined, 1]]);
+    expect(facetValuesFrom(counts, "status")).toEqual([]);
+  });
+
+  it("merges keys that read the same", () => {
+    const counts = new Map<unknown, number>([[1, 2], ["1", 3], ["2", 1]]);
+    expect(facetValuesFrom(counts, "text")).toEqual([
+      { value: "1", count: 5 },
+      { value: "2", count: 1 },
+    ]);
+  });
+
+  it("orders kinds by the taxonomy, not the alphabet", () => {
+    const counts = new Map<unknown, number>([["service", 1], ["event", 1], ["aggregate", 1]]);
+    expect(facetValuesFrom(counts, "kind").map((facet) => facet.value)).toEqual([
+      "event",
+      "aggregate",
+      "service",
+    ]);
+  });
+});
+
+describe("facetGroupFrom", () => {
+  const counts = new Map<unknown, number>([["verified", 1], ["declared", 1]]);
+
+  it("builds the group the toolbar draws", () => {
+    expect(facetGroupFrom(status, counts, ["declared"])).toEqual({
+      columnId: "status",
+      label: "status",
+      values: [
+        { value: "verified", count: 1 },
+        { value: "declared", count: 1 },
+      ],
+      selected: ["declared"],
+    });
+  });
+
+  it("offers nothing for a column that is not a facet, or cannot be one", () => {
+    expect(facetGroupFrom({ ...status, facet: false }, counts, [])).toBeNull();
+    expect(facetGroupFrom({ ...status, type: "number" }, counts, [])).toBeNull();
+  });
+
+  it("offers nothing when the values would make a set of one", () => {
+    expect(facetGroupFrom(status, new Map([["verified", 4]]), [])).toBeNull();
+  });
+});

package/src/table/facet-groups.ts

@@ -0,0 +1,56 @@
+// The chip-sets, read off the table's own model.
+//
+// TanStack counts the distinct values of a column once, memoised against the
+// rows; this turns that count into what the toolbar draws. Nothing here walks
+// the data a second time, and nothing here decides which rows are in - the
+// counts are the whole table's, so the set never changes shape under the
+// reader's hand.
+
+import type { FacetValue } from "./Facets";
+import { comparatorFor } from "./compare";
+import type { ColumnSpec, ColumnType } from "./types";
+import { canFacet, cellText } from "./types";
+
+export interface FacetGroup {
+  columnId: string;
+  label: string;
+  values: FacetValue[];
+  selected: string[];
+}
+
+/**
+ * The chips of one column, from TanStack's unique-value map. The empty cell is
+ * not a value to filter by; a set of one is not a filter at all. Values read
+ * in the column's own order, so a status set is not alphabetical and a kind
+ * set is not either.
+ */
+export function facetValuesFrom(
+  counts: ReadonlyMap<unknown, number>,
+  type: ColumnType,
+): FacetValue[] {
+  const merged = new Map<string, number>();
+  for (const [key, count] of counts) {
+    // The map is keyed by what the accessor returned; two keys that read the
+    // same are one chip.
+    const value = cellText(key as string | number | undefined);
+    if (value === "") continue;
+    merged.set(value, (merged.get(value) ?? 0) + count);
+  }
+  if (merged.size < 2) return [];
+  const compare = comparatorFor(type);
+  return [...merged.entries()]
+    .sort(([a], [b]) => compare(a, b))
+    .map(([value, count]) => ({ value, count }));
+}
+
+/** One toolbar group, or nothing when the column does not offer one. */
+export function facetGroupFrom<T>(
+  spec: ColumnSpec<T>,
+  counts: ReadonlyMap<unknown, number>,
+  selected: string[],
+): FacetGroup | null {
+  if (!spec.facet || !canFacet(spec.type)) return null;
+  const values = facetValuesFrom(counts, spec.type);
+  if (values.length === 0) return null;
+  return { columnId: spec.id, label: spec.header, values, selected };
+}

package/src/table/grouping.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import {
+  activeGroup,
+  groupOptions,
+  groupingSorting,
+  leafRows,
+  stripeParity,
+} from "./grouping";
+
+describe("activeGroup", () => {
+  it("keeps a remembered column this table may fold by", () => {
+    expect(activeGroup("scope", ["status", "scope"])).toBe("scope");
+  });
+
+  it("drops a column the table lacks, or may not fold by", () => {
+    expect(activeGroup("date", ["status", "scope"])).toBeNull();
+    expect(activeGroup(null, ["status"])).toBeNull();
+  });
+});
+
+describe("groupingSorting", () => {
+  const readers = [{ id: "date", desc: true }, { id: "title", desc: false }];
+
+  it("hands back the reader's sort untouched when nothing is grouped", () => {
+    expect(groupingSorting(readers, null)).toBe(readers);
+  });
+
+  it("puts the grouping column first, ascending, ahead of the reader's keys", () => {
+    expect(groupingSorting(readers, "scope")).toEqual([
+      { id: "scope", desc: false },
+      { id: "date", desc: true },
+      { id: "title", desc: false },
+    ]);
+  });
+
+  it("keeps the reader's own direction on the grouping column, once", () => {
+    expect(groupingSorting([{ id: "title", desc: false }, { id: "scope", desc: true }], "scope")).toEqual([
+      { id: "scope", desc: true },
+      { id: "title", desc: false },
+    ]);
+  });
+});
+
+describe("stripeParity", () => {
+  it("gives a header no parity and starts the count again beneath it", () => {
+    expect(stripeParity([true, false, false, false, true, false, false])).toEqual([
+      null, true, false, true, null, true, false,
+    ]);
+  });
+
+  it("is plain alternation without headers", () => {
+    expect(stripeParity([false, false, false])).toEqual([true, false, true]);
+  });
+});
+
+describe("groupOptions", () => {
+  it("offers exactly the columns that have a chip-set", () => {
+    expect(
+      groupOptions([
+        { columnId: "status", label: "status", values: [], selected: [] },
+        { columnId: "scope", label: "scope", values: [], selected: [] },
+      ]),
+    ).toEqual([
+      { id: "status", header: "status" },
+      { id: "scope", header: "scope" },
+    ]);
+  });
+});
+
+describe("leafRows", () => {
+  type R = { id: string; subRows: R[]; getIsGrouped: () => boolean };
+  const leaf = (id: string): R => ({ id, subRows: [], getIsGrouped: () => false });
+  const group = (id: string, subRows: R[]): R => ({ id, subRows, getIsGrouped: () => true });
+
+  it("walks into every group, open or not, and keeps the display order", () => {
+    const rows = [group("g1", [leaf("a"), leaf("b")]), group("g2", [leaf("c")])];
+    expect(leafRows(rows).map((row) => row.id)).toEqual(["a", "b", "c"]);
+  });
+
+  it("is the identity on an ungrouped table", () => {
+    const rows = [leaf("a"), leaf("b")];
+    expect(leafRows(rows)).toEqual(rows);
+  });
+});

package/src/table/grouping.ts

@@ -0,0 +1,82 @@
+// Folding a table by one of its columns.
+//
+// Grouping is the reader's, one column at a time, chosen from the columns
+// that already offer a chip-set: a column worth filtering by is a column
+// worth folding by, and no other column is. TanStack builds the groups; what
+// is decided here is which column may be one, how the groups are ordered, and
+// how the stripes read once a header row sits between two leaves.
+
+import type { FacetGroup } from "./facet-groups";
+import type { SortEntry } from "./sort-url";
+
+export interface GroupOption {
+  id: string;
+  header: string;
+}
+
+/** The remembered column, if this table still has it and may fold by it. */
+export function activeGroup(
+  remembered: string | null,
+  eligible: readonly string[],
+): string | null {
+  return remembered !== null && eligible.includes(remembered) ? remembered : null;
+}
+
+/**
+ * The sort the table runs when grouped: the grouping column first, so the
+ * groups follow that column's own order, then the reader's keys, which order
+ * the leaves inside each group. The reader's own direction on the grouping
+ * column is kept, so clicking its header turns the groups around.
+ *
+ * Derived, never written back: the URL and the page's memory still say only
+ * what the reader clicked.
+ */
+export function groupingSorting(
+  sorting: readonly SortEntry[],
+  groupBy: string | null,
+): SortEntry[] {
+  if (groupBy === null) return sorting as SortEntry[];
+  const own = sorting.find((entry) => entry.id === groupBy);
+  return [
+    { id: groupBy, desc: own?.desc ?? false },
+    ...sorting.filter((entry) => entry.id !== groupBy),
+  ];
+}
+
+/**
+ * Stripe parity per display row. A header row carries no parity, so the
+ * stripe rule cannot match it, and the count starts again beneath it: every
+ * group then opens on the same stripe, and a header with its first row always
+ * reads as the same pair.
+ */
+export function stripeParity(isGroup: readonly boolean[]): (boolean | null)[] {
+  let leaf = 0;
+  return isGroup.map((group) => {
+    if (group) {
+      leaf = 0;
+      return null;
+    }
+    return leaf++ % 2 === 0;
+  });
+}
+
+/** The columns the picker offers: exactly the columns with a chip-set. */
+export function groupOptions(groups: readonly FacetGroup[]): GroupOption[] {
+  return groups.map((group) => ({ id: group.columnId, header: group.label }));
+}
+
+/**
+ * The leaves under a list of rows, in display order, whether or not their
+ * group is open. An export is the view, and a folded group is still in it.
+ */
+export function leafRows<R extends { subRows: R[]; getIsGrouped: () => boolean }>(
+  rows: readonly R[],
+): R[] {
+  const out: R[] = [];
+  const walk = (row: R) => {
+    if (row.getIsGrouped()) row.subRows.forEach(walk);
+    else out.push(row);
+  };
+  rows.forEach(walk);
+  return out;
+}