@shortlink-org/portolan 0.1.0

package/src/table/infer.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { inferColumnType, inferColumnTypes } from "./infer";
+
+describe("inferColumnType", () => {
+  it("calls a column of integers a number, not a version", () => {
+    expect(inferColumnType(["1", "2", "10"])).toBe("number");
+  });
+
+  it("calls a dotted column a version", () => {
+    expect(inferColumnType(["v1", "v2.1", "10.0.3"])).toBe("version");
+  });
+
+  it("calls an ISO column a date", () => {
+    expect(inferColumnType(["2024-01-01", "2024-11-30"])).toBe("date");
+  });
+
+  it("accepts an ISO timestamp", () => {
+    expect(inferColumnType(["2024-01-01T09:30:00Z"])).toBe("date");
+  });
+
+  it("refuses a date that only Date.parse would accept", () => {
+    expect(inferColumnType(["Jan 3", "Sat"])).toBe("text");
+  });
+
+  it("falls back to text on one disagreeing cell", () => {
+    expect(inferColumnType(["1", "2", "many"])).toBe("text");
+  });
+
+  it("ignores empty cells when sampling", () => {
+    expect(inferColumnType(["1", "", "  ", "2"])).toBe("number");
+  });
+
+  it("calls an empty column text", () => {
+    expect(inferColumnType(["", " "])).toBe("text");
+  });
+
+  it("rejects an impossible ISO date", () => {
+    expect(inferColumnType(["2024-13-45"])).toBe("text");
+  });
+});
+
+describe("inferColumnTypes", () => {
+  it("infers each column on its own", () => {
+    const body = [
+      ["a", "1", "2024-01-01"],
+      ["b", "2", "2024-02-01"],
+    ];
+    expect(inferColumnTypes(body, 3)).toEqual(["text", "number", "date"]);
+  });
+
+  it("treats a short row as empty in the columns it lacks", () => {
+    expect(inferColumnTypes([["1"], ["2", "3"]], 2)).toEqual([
+      "number",
+      "number",
+    ]);
+  });
+});

package/src/table/infer.ts

@@ -0,0 +1,50 @@
+// What a markdown table's columns are, when nobody declared them.
+//
+// An index page says what its columns hold. A README cannot, so the column
+// type is read out of the cells themselves - and only when EVERY non-empty
+// cell in the column agrees. One ambiguous cell and the column is text, which
+// is the type that is never wrong, only unhelpful.
+
+import type { ColumnType } from "./types";
+
+const NUMBER_RE = /^-?\d+(\.\d+)?$/;
+const VERSION_RE = /^v?\d+(\.\d+)*$/;
+/**
+ * Deliberately narrower than `Date.parse`, which accepts "1" as a year and
+ * "Sat" as a weekday. A README column is a date when it is written like one:
+ * ISO, with or without a time.
+ */
+const DATE_RE = /^\d{4}-\d{2}-\d{2}([T ][\d:.]+(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+function every(cells: string[], test: (cell: string) => boolean): boolean {
+  return cells.every(test);
+}
+
+/**
+ * The type of one column, from its body cells. The header is not a sample —
+ * "version" is a word, and a column of versions headed "version" would infer
+ * as text if it were counted.
+ *
+ * Order matters and is the spec's: numeric wins over version, so a column of
+ * bare integers is a number and only "1.2.3" shapes become versions.
+ */
+export function inferColumnType(cells: readonly string[]): ColumnType {
+  const values = cells.map((cell) => cell.trim()).filter((cell) => cell !== "");
+  // A column with nothing in it is text: there is no evidence for anything else.
+  if (values.length === 0) return "text";
+  if (every(values, (cell) => NUMBER_RE.test(cell))) return "number";
+  if (every(values, (cell) => VERSION_RE.test(cell))) return "version";
+  if (every(values, (cell) => DATE_RE.test(cell) && !Number.isNaN(Date.parse(cell))))
+    return "date";
+  return "text";
+}
+
+/** Every column's type, from a body given as rows of plain-text cells. */
+export function inferColumnTypes(
+  rows: readonly (readonly string[])[],
+  columns: number,
+): ColumnType[] {
+  return Array.from({ length: columns }, (_, i) =>
+    inferColumnType(rows.map((row) => row[i] ?? "")),
+  );
+}

package/src/table/persist.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import {
+  EMPTY_MEMORY,
+  hiddenOf,
+  parseMemory,
+  serializeMemory,
+  visibilityOf,
+} from "./persist";
+
+describe("parseMemory", () => {
+  it("round-trips what it wrote", () => {
+    const memory = { sizing: { title: 320 }, hidden: ["scope"], group: "status" };
+    expect(parseMemory(serializeMemory(memory))).toEqual(memory);
+  });
+
+  it("drops a group that is not a column id", () => {
+    expect(parseMemory(JSON.stringify({ group: 4 })).group).toBeNull();
+    expect(parseMemory(JSON.stringify({ group: "" })).group).toBeNull();
+    expect(parseMemory(JSON.stringify({ group: null })).group).toBeNull();
+  });
+
+  it("reads nothing out of nothing", () => {
+    expect(parseMemory(null)).toEqual(EMPTY_MEMORY);
+  });
+
+  it("survives a value that is not JSON", () => {
+    expect(parseMemory("{not json")).toEqual(EMPTY_MEMORY);
+  });
+
+  it("survives JSON that is not an object", () => {
+    expect(parseMemory("42")).toEqual(EMPTY_MEMORY);
+    expect(parseMemory("null")).toEqual(EMPTY_MEMORY);
+  });
+
+  it("drops a width that is not a width", () => {
+    const raw = JSON.stringify({
+      sizing: { a: 100, b: "wide", c: -5, d: 0 },
+      hidden: [],
+    });
+    expect(parseMemory(raw).sizing).toEqual({ a: 100 });
+  });
+
+  it("drops a hidden entry that is not a column id", () => {
+    const raw = JSON.stringify({ sizing: {}, hidden: ["a", 7, null] });
+    expect(parseMemory(raw).hidden).toEqual(["a"]);
+  });
+
+  it("tolerates a half-written shape", () => {
+    expect(parseMemory('{"hidden":["a"]}')).toEqual({
+      sizing: {},
+      hidden: ["a"],
+      group: null,
+    });
+  });
+});
+
+describe("visibilityOf", () => {
+  it("marks hidden columns with an explicit false", () => {
+    expect(visibilityOf(["scope", "date"])).toEqual({
+      scope: false,
+      date: false,
+    });
+  });
+
+  it("says nothing about columns that are shown", () => {
+    expect(visibilityOf([])).toEqual({});
+  });
+
+  it("inverts back to the same list", () => {
+    expect(hiddenOf(visibilityOf(["a", "b"]))).toEqual(["a", "b"]);
+  });
+
+  it("ignores columns explicitly switched on", () => {
+    expect(hiddenOf({ a: true, b: false })).toEqual(["b"]);
+  });
+});

package/src/table/persist.ts

@@ -0,0 +1,112 @@
+// What a table remembers about itself.
+//
+// Column widths, hidden columns and the column the rows are grouped by are per
+// table id, because they are answers to "what am I looking at" rather than a
+// global preference: a reader who widened the title column on the decisions
+// index has said nothing about the schema table on an event page. Zebra
+// striping is the opposite - it is a statement about tables in general - so it
+// is stored once.
+//
+// localStorage is a thing that fails: private mode throws on write, and what
+// comes back was last written by an older build, or by hand. Everything here
+// treats a bad read as no read.
+
+const TABLE_KEY = (id: string) => `portolan.table.${id}`;
+const ZEBRA_KEY = "portolan.table.zebra";
+
+export interface TableMemory {
+  /** Column id to dragged width in px. */
+  sizing: Record<string, number>;
+  /** Column ids the reader has switched off. */
+  hidden: string[];
+  /** The column the rows are folded under, or null for a flat table. */
+  group: string | null;
+}
+
+export const EMPTY_MEMORY: TableMemory = { sizing: {}, hidden: [], group: null };
+
+/** Reads whatever is in storage into the shape the table expects, or nothing. */
+export function parseMemory(raw: string | null): TableMemory {
+  if (!raw) return EMPTY_MEMORY;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return EMPTY_MEMORY;
+  }
+  if (typeof parsed !== "object" || parsed === null) return EMPTY_MEMORY;
+  const record = parsed as { sizing?: unknown; hidden?: unknown; group?: unknown };
+
+  const sizing: Record<string, number> = {};
+  if (typeof record.sizing === "object" && record.sizing !== null) {
+    for (const [id, width] of Object.entries(record.sizing)) {
+      // A width that is not a positive number is not a width.
+      if (typeof width === "number" && Number.isFinite(width) && width > 0) {
+        sizing[id] = width;
+      }
+    }
+  }
+
+  const hidden = Array.isArray(record.hidden)
+    ? record.hidden.filter((id): id is string => typeof id === "string")
+    : [];
+
+  // A group is a column id or nothing; whether the column still exists is
+  // for the table to say.
+  const group =
+    typeof record.group === "string" && record.group !== "" ? record.group : null;
+
+  return { sizing, hidden, group };
+}
+
+export function serializeMemory(memory: TableMemory): string {
+  return JSON.stringify(memory);
+}
+
+export function readMemory(tableId: string): TableMemory {
+  try {
+    return parseMemory(localStorage.getItem(TABLE_KEY(tableId)));
+  } catch {
+    return EMPTY_MEMORY;
+  }
+}
+
+export function writeMemory(tableId: string, memory: TableMemory): void {
+  try {
+    localStorage.setItem(TABLE_KEY(tableId), serializeMemory(memory));
+  } catch {
+    /* private mode: this session still resizes, it just does not persist */
+  }
+}
+
+export function readZebra(): boolean {
+  try {
+    return localStorage.getItem(ZEBRA_KEY) === "on";
+  } catch {
+    return false;
+  }
+}
+
+export function writeZebra(on: boolean): void {
+  try {
+    localStorage.setItem(ZEBRA_KEY, on ? "on" : "off");
+  } catch {
+    /* see above */
+  }
+}
+
+/**
+ * TanStack's visibility state, from the list of ids the reader switched off.
+ * Only an explicit `false` hides a column; a column that is absent is shown,
+ * which is why this cannot be built by listing what IS visible.
+ */
+export function visibilityOf(hidden: readonly string[]): Record<string, boolean> {
+  return Object.fromEntries(hidden.map((id) => [id, false]));
+}
+
+/** The inverse, for writing back. */
+export function hiddenOf(visibility: Record<string, boolean>): string[] {
+  return Object.entries(visibility)
+    .filter(([, visible]) => visible === false)
+    .map(([id]) => id);
+}

package/src/table/sort-url.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { formatSort, parseSort, sameSort } from "./sort-url";
+
+const COLUMNS = ["name", "consumers", "date"];
+
+describe("parseSort", () => {
+  it("reads one term", () => {
+    expect(parseSort("name.desc", COLUMNS)).toEqual([
+      { id: "name", desc: true },
+    ]);
+  });
+
+  it("reads a secondary key in order", () => {
+    expect(parseSort("consumers.desc,name.asc", COLUMNS)).toEqual([
+      { id: "consumers", desc: true },
+      { id: "name", desc: false },
+    ]);
+  });
+
+  it("drops a column this table does not have", () => {
+    expect(parseSort("nonsense.asc,name.asc", COLUMNS)).toEqual([
+      { id: "name", desc: false },
+    ]);
+  });
+
+  it("drops a direction that is not a direction", () => {
+    expect(parseSort("name.sideways", COLUMNS)).toEqual([]);
+  });
+
+  it("drops a repeated column", () => {
+    expect(parseSort("name.asc,name.desc", COLUMNS)).toEqual([
+      { id: "name", desc: false },
+    ]);
+  });
+
+  it("keeps a column id that contains a dot", () => {
+    expect(parseSort("a.b.desc", ["a.b"])).toEqual([{ id: "a.b", desc: true }]);
+  });
+
+  it("reads nothing out of nothing", () => {
+    expect(parseSort(null, COLUMNS)).toEqual([]);
+    expect(parseSort("", COLUMNS)).toEqual([]);
+  });
+});
+
+describe("formatSort", () => {
+  it("round-trips", () => {
+    const sort = parseSort("consumers.desc,name.asc", COLUMNS);
+    expect(formatSort(sort)).toBe("consumers.desc,name.asc");
+  });
+
+  it("writes nothing for an unsorted table", () => {
+    expect(formatSort([])).toBe("");
+  });
+});
+
+describe("sameSort", () => {
+  it("compares by value and by order", () => {
+    expect(sameSort([{ id: "a", desc: false }], [{ id: "a", desc: false }])).toBe(
+      true,
+    );
+    expect(
+      sameSort(
+        [
+          { id: "a", desc: false },
+          { id: "b", desc: false },
+        ],
+        [
+          { id: "b", desc: false },
+          { id: "a", desc: false },
+        ],
+      ),
+    ).toBe(false);
+  });
+});

package/src/table/sort-url.ts

@@ -0,0 +1,52 @@
+// A sorted view is a place, so it has an address.
+//
+// ?sort=name.desc, or ?sort=severity.desc,age.asc for a shift-clicked second
+// key. Only index pages carry it: a table inside a README has no URL of its
+// own to write to, and two READMEs open in two panes would fight over one.
+
+/** The shape the table keeps its sort in. Mirrors TanStack's SortingState. */
+export interface SortEntry {
+  id: string;
+  desc: boolean;
+}
+
+export const SORT_PARAM = "sort";
+
+/**
+ * Reads "name.desc,age.asc". Anything malformed, or naming a column this
+ * table does not have, is dropped rather than thrown: a URL is user input,
+ * and a stale link should land on an unsorted table, not an error.
+ */
+export function parseSort(
+  raw: string | null | undefined,
+  columnIds: readonly string[],
+): SortEntry[] {
+  if (!raw) return [];
+  const known = new Set(columnIds);
+  const seen = new Set<string>();
+  const out: SortEntry[] = [];
+  for (const term of raw.split(",")) {
+    const at = term.lastIndexOf(".");
+    if (at <= 0) continue;
+    const id = term.slice(0, at);
+    const dir = term.slice(at + 1);
+    if (dir !== "asc" && dir !== "desc") continue;
+    if (!known.has(id) || seen.has(id)) continue;
+    seen.add(id);
+    out.push({ id, desc: dir === "desc" });
+  }
+  return out;
+}
+
+/** The inverse. An empty sort has no term, so the param drops out entirely. */
+export function formatSort(sort: readonly SortEntry[]): string {
+  return sort.map((s) => `${s.id}.${s.desc ? "desc" : "asc"}`).join(",");
+}
+
+/** True when two sorts say the same thing, so an effect can decline to write. */
+export function sameSort(
+  a: readonly SortEntry[],
+  b: readonly SortEntry[],
+): boolean {
+  return formatSort(a) === formatSort(b);
+}

package/src/table/types.ts

@@ -0,0 +1,80 @@
+// What a column is, before anything knows how to draw one.
+//
+// A column here is not "a header and a render function": it is a declared
+// type, and the type is what decides how the column sorts, which way it is
+// aligned, whether it offers a chip-set to filter by, and what a cell looks
+// like. Declaring `version` once is what stops v10 from sorting before v2 on
+// one page and after it on the next.
+
+import type { ReactNode } from "react";
+
+export type ColumnType =
+  | "text"
+  /** Ids, paths, type names — anything the reader will paste somewhere else. */
+  | "mono"
+  | "number"
+  /** Semver-ish: v2 sorts before v10, never after it. */
+  | "version"
+  /** ISO in, "3 days ago" on screen, the timestamp on hover. */
+  | "date"
+  /** verified > declared > unresolved. */
+  | "status"
+  /** A DDD kind, in taxonomy order rather than alphabetical. */
+  | "kind"
+  /** A number that is also a link to the things it counted. */
+  | "count";
+
+/**
+ * What a cell is worth to everything that is not the renderer: the sort, the
+ * filter, the export. `undefined` is the empty cell, and it is the only empty
+ * there is — an accessor that would return null or "" returns undefined, so
+ * that one value can be sorted last in both directions by one rule.
+ */
+export type CellValue = string | number | undefined;
+
+export interface ColumnSpec<T> {
+  /** Stable across renders and reloads: widths and hidden state key off it. */
+  id: string;
+  header: string;
+  type: ColumnType;
+  /** The sortable, filterable, exportable value. */
+  value: (row: T) => CellValue;
+  /** The cell, when the value alone is not the whole of it. */
+  cell?: (row: T) => ReactNode;
+  /** Where a `count` cell points. */
+  href?: (row: T) => string | null | undefined;
+  /** Title attribute, for the cell that has more to say than it can show. */
+  title?: (row: T) => string | undefined;
+  /** Offer this column as a chip-set in the toolbar. status/kind/context. */
+  facet?: boolean;
+  /** The cell that carries the row link and the j/k focus. Defaults to first. */
+  primary?: boolean;
+  /** Starting width in px. The reader's dragged width wins over this. */
+  size?: number;
+  minSize?: number;
+  /** Default true, except for the primary column, which cannot be hidden. */
+  enableHiding?: boolean;
+  enableSorting?: boolean;
+  /** Overrides the alignment the type would pick. */
+  align?: "left" | "right";
+}
+
+/** Numbers line up on the right; everything a reader reads lines up on the left. */
+export function defaultAlign(type: ColumnType): "left" | "right" {
+  return type === "number" || type === "count" ? "right" : "left";
+}
+
+/** Which types the free-text filter searches. The spec's rule, in one place. */
+export function isTextish(type: ColumnType): boolean {
+  return type === "text" || type === "mono";
+}
+
+/** Which types offer a chip-set when the column asks for one. */
+export function canFacet(type: ColumnType): boolean {
+  return type === "status" || type === "kind" || type === "text";
+}
+
+/** The string a cell exports as, and the string the text filter matches. */
+export function cellText(value: CellValue): string {
+  return value === undefined ? "" : String(value);
+}