@shortlink-org/portolan 0.1.0

package/src/table/Facets.tsx

@@ -0,0 +1,54 @@
+// The chip-set a status, kind or context column offers.
+//
+// Values come from the data, never from a list written next to it: a facet
+// that offers "deprecated" on a page where nothing is deprecated is a filter
+// that can only ever return nothing. The count next to each value is what
+// makes the set worth reading before it is clicked.
+
+import type { ReactNode } from "react";
+
+export interface FacetValue {
+  value: string;
+  count: number;
+  label?: ReactNode;
+}
+
+export function Facets({
+  label,
+  values,
+  selected,
+  onToggle,
+}: {
+  /** Names the group for a reader who cannot see it. The column's header. */
+  label: string;
+  values: readonly FacetValue[];
+  selected: readonly string[];
+  onToggle: (value: string) => void;
+}) {
+  if (values.length === 0) return null;
+  return (
+    <div className="seg" role="group" aria-label={`Filter by ${label}`}>
+      {values.map((facet) => {
+        const on = selected.includes(facet.value);
+        return (
+          <button
+            key={facet.value}
+            type="button"
+            onClick={() => onToggle(facet.value)}
+            aria-pressed={on}
+            /* A value with nothing behind it is left in place rather than
+               removed: a set that changes shape as it is used is a set the
+               reader has to re-read after every click. */
+            disabled={facet.count === 0 && !on}
+            className={`flex items-center gap-1.5 ${on ? "is-on" : ""} ${
+              facet.count === 0 && !on ? "opacity-40" : ""
+            }`}
+          >
+            {facet.label ?? facet.value}
+            <span className="tnum text-muted">{facet.count}</span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/table/GroupMenu.tsx

@@ -0,0 +1,69 @@
+// Which column the rows fold under.
+//
+// Only offered where a chip-set is: a column worth filtering by is a column
+// worth folding by, and no other column is. One choice at a time, so the menu
+// closes on the pick - unlike the columns menu, where a pick is usually one of
+// several.
+
+import { Menu, MenuButton, MenuItem, MenuItems } from "@headlessui/react";
+import { Check, Group } from "lucide-react";
+import type { GroupOption } from "./grouping";
+
+export function GroupMenu({
+  options,
+  value,
+  onChange,
+}: {
+  options: readonly GroupOption[];
+  /** The column the rows are grouped by, or null for a flat table. */
+  value: string | null;
+  onChange: (id: string | null) => void;
+}) {
+  const current = options.find((option) => option.id === value);
+  const items: { id: string | null; header: string }[] = [
+    { id: null, header: "none" },
+    ...options,
+  ];
+  return (
+    <Menu>
+      <MenuButton
+        aria-label="Group rows"
+        title="Group rows by a column"
+        className={({ open }) => `tbtn ${open || value !== null ? "tbtn-on" : ""}`}
+      >
+        <Group size={13} aria-hidden />
+        {current ? `group: ${current.header}` : "group"}
+      </MenuButton>
+      <MenuItems
+        anchor={{ to: "bottom end", gap: 4, padding: 8 }}
+        className="palette-in z-50 max-h-72 min-w-44 overflow-y-auto rounded-control border bg-canvas py-1 border-line-strong shadow-md focus:outline-none"
+      >
+        {items.map((item) => {
+          const on = item.id === value;
+          return (
+            <MenuItem key={item.id ?? "none"}>
+              {({ focus }) => (
+                <button
+                  type="button"
+                  onClick={() => onChange(item.id)}
+                  aria-pressed={on}
+                  className={`mono flex w-full cursor-pointer items-center gap-2 px-2 py-1 text-left ${
+                    focus ? "bg-raised" : ""
+                  }`}
+                >
+                  <Check
+                    size={12}
+                    aria-hidden
+                    className="shrink-0"
+                    style={{ opacity: on ? 1 : 0, color: "var(--accent)" }}
+                  />
+                  <span className="truncate">{item.header}</span>
+                </button>
+              )}
+            </MenuItem>
+          );
+        })}
+      </MenuItems>
+    </Menu>
+  );
+}

package/src/table/Toolbar.tsx

@@ -0,0 +1,190 @@
+// What sits above a table, once a table is big enough to need anything.
+//
+// The threshold matters more than the contents: a filter over six rows is a
+// control that costs more attention than the scanning it saves. Above it, the
+// order is the order a reader reaches for - narrow it, see how much is left,
+// then take it somewhere.
+
+import { Menu, MenuButton, MenuItem, MenuItems } from "@headlessui/react";
+import { Download, Ellipsis, Rows3, Search, X } from "lucide-react";
+import type { ReactNode } from "react";
+import { Facets } from "./Facets";
+import { ColumnsMenu } from "./ColumnsMenu";
+import type { ColumnToggle } from "./ColumnsMenu";
+import { GroupMenu } from "./GroupMenu";
+import type { FacetGroup } from "./facet-groups";
+import type { GroupOption } from "./grouping";
+
+export type { FacetGroup } from "./facet-groups";
+
+export interface ExportActions {
+  copyMarkdown: () => void;
+  copyCsv: () => void;
+  downloadCsv: () => void;
+}
+
+/** Copy that reports itself, because a clipboard write is otherwise silent. */
+function ExportMenu({ actions, note }: { actions: ExportActions; note: string }) {
+  const items: [string, () => void, ReactNode][] = [
+    ["Copy as Markdown", actions.copyMarkdown, null],
+    ["Copy as CSV", actions.copyCsv, null],
+    [
+      "Download CSV",
+      actions.downloadCsv,
+      <Download key="i" size={12} aria-hidden className="ml-auto shrink-0" />,
+    ],
+  ];
+  return (
+    <Menu>
+      <MenuButton
+        aria-label="Export this view"
+        title={`Export ${note}`}
+        className={({ open }) => `tbtn ${open ? "tbtn-on" : ""}`}
+      >
+        <Ellipsis size={13} aria-hidden />
+      </MenuButton>
+      <MenuItems
+        anchor={{ to: "bottom end", gap: 4, padding: 8 }}
+        className="palette-in z-50 min-w-48 rounded-control border bg-canvas py-1 border-line-strong shadow-md focus:outline-none"
+      >
+        <p className="meta px-2 py-1">{note}</p>
+        {items.map(([label, run, trailing]) => (
+          <MenuItem key={label}>
+            {({ focus }) => (
+              <button
+                type="button"
+                onClick={run}
+                className={`mono flex w-full cursor-pointer items-center gap-2 px-2 py-1 text-left ${
+                  focus ? "bg-raised" : ""
+                }`}
+              >
+                {label}
+                {trailing}
+              </button>
+            )}
+          </MenuItem>
+        ))}
+      </MenuItems>
+    </Menu>
+  );
+}
+
+export function Toolbar({
+  filter,
+  onFilter,
+  facets,
+  onToggleFacet,
+  shown,
+  total,
+  filtersActive,
+  onClearFilters,
+  columns,
+  onToggleColumn,
+  groupBy = null,
+  groupOptions,
+  onGroupBy,
+  zebra,
+  onToggleZebra,
+  exports,
+}: {
+  filter: string;
+  onFilter: (value: string) => void;
+  /** Empty on a markdown table: a README gets a text filter and nothing else. */
+  facets: readonly FacetGroup[];
+  onToggleFacet: (columnId: string, value: string) => void;
+  shown: number;
+  total: number;
+  filtersActive: boolean;
+  onClearFilters: () => void;
+  /** Omitted below six columns, where there is nothing worth hiding. */
+  columns?: readonly ColumnToggle[];
+  onToggleColumn?: (id: string) => void;
+  /** The column the rows are folded under. */
+  groupBy?: string | null;
+  /** The columns that may fold the rows: the ones with a chip-set. Omitted on a markdown table. */
+  groupOptions?: readonly GroupOption[];
+  onGroupBy?: (id: string | null) => void;
+  zebra: boolean;
+  /** Omitted on a markdown table, which offers a text filter and nothing else. */
+  onToggleZebra?: () => void;
+  exports?: ExportActions;
+}) {
+  return (
+    <div className="mb-2 flex flex-wrap items-center gap-2">
+      <label className="tbtn gap-1.5 focus-within:border-line-strong">
+        <Search size={13} aria-hidden className="shrink-0" />
+        <input
+          type="search"
+          value={filter}
+          onChange={(event) => onFilter(event.target.value)}
+          placeholder="filter"
+          aria-label="Filter rows"
+          /* Sized to a search term, not to the toolbar: an input that grows
+             to fill the row makes every table look like a search page. */
+          className="mono w-32 bg-transparent text-ink placeholder:text-muted focus:outline-none"
+        />
+      </label>
+
+      {facets.map((group) => (
+        <Facets
+          key={group.columnId}
+          label={group.label}
+          values={group.values}
+          selected={group.selected}
+          onToggle={(value) => onToggleFacet(group.columnId, value)}
+        />
+      ))}
+
+      {/* The count is the answer to the question the filter just asked. */}
+      <span className="mono text-muted">
+        <span className="tnum">{shown}</span> of{" "}
+        <span className="tnum">{total}</span>
+      </span>
+
+      {filtersActive ? (
+        <button
+          type="button"
+          onClick={onClearFilters}
+          className="mono flex items-center gap-1 rounded-control text-muted hover:text-ink"
+        >
+          <X size={12} aria-hidden />
+          clear filters
+        </button>
+      ) : null}
+
+      <div className="ml-auto flex items-center gap-2">
+        {/* Still offered while a grouping is on, even if the set that
+            offered it has since shrunk: a fold the reader cannot undo is a
+            trap. */}
+        {onGroupBy && groupOptions && (groupOptions.length > 0 || groupBy !== null) ? (
+          <GroupMenu options={groupOptions} value={groupBy} onChange={onGroupBy} />
+        ) : null}
+        {onToggleZebra ? (
+          <button
+            type="button"
+            onClick={onToggleZebra}
+            aria-pressed={zebra}
+            title="Stripe alternate rows"
+            aria-label="Stripe alternate rows"
+            className={`tbtn ${zebra ? "tbtn-on" : ""}`}
+          >
+            <Rows3 size={13} aria-hidden />
+          </button>
+        ) : null}
+        {columns && onToggleColumn ? (
+          <ColumnsMenu columns={columns} onToggle={onToggleColumn} />
+        ) : null}
+        {exports ? (
+          <ExportMenu
+            actions={exports}
+            note={
+              shown === total
+                ? `all ${total} rows`
+                : `${shown} of ${total} rows`
+            }
+          />
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/table/cells.tsx

@@ -0,0 +1,117 @@
+// How a cell of each type is drawn.
+//
+// The point of declaring a column's type is that this file is the only place
+// that decides what the type looks like. A date is relative on screen and
+// absolute on hover everywhere; an id is copyable everywhere; a version is
+// tabular everywhere. Nothing downstream gets to disagree.
+
+import { Link } from "react-router";
+import type { ReactNode } from "react";
+import type { Status } from "../catalog";
+import type { Kind } from "../lib/kinds";
+import { KIND_LABEL } from "../lib/kinds";
+import { KindIcon } from "../components/kind";
+import { StatusChip } from "../components/primitives";
+import { Ident } from "../components/Ident";
+import { absoluteTime, middleTruncate, relativeTime } from "../lib/format";
+import type { CellValue, ColumnType } from "./types";
+import { cellText } from "./types";
+
+const STATUSES = new Set<string>(["verified", "declared", "unresolved"]);
+const KINDS = new Set<string>([
+  "context",
+  "service",
+  "aggregate",
+  "event",
+  "vo",
+  "entity",
+  "command",
+  "query",
+  "def",
+  "flow",
+  "adr",
+]);
+
+/**
+ * How wide a mono cell gets before its middle is dropped. Narrower than the
+ * default in format.ts: a table column has less room than a line of prose,
+ * and the full value is one hover away.
+ */
+const MONO_MAX = 32;
+
+/** A date the reader can read, with the timestamp they can quote on hover. */
+function DateCell({ iso }: { iso: string }) {
+  const absolute = absoluteTime(iso);
+  return (
+    <time dateTime={iso} title={absolute} className="whitespace-nowrap">
+      {relativeTime(iso)}
+    </time>
+  );
+}
+
+/**
+ * The default cell for a type. A column that passes its own `cell` never
+ * reaches here; everything else does, which is what makes the types worth
+ * declaring.
+ */
+export function defaultCell(
+  type: ColumnType,
+  value: CellValue,
+  href?: string | null,
+): ReactNode {
+  // The empty cell is a dash, not a blank: a blank reads as a layout bug.
+  if (value === undefined) return <span className="text-muted">—</span>;
+  const text = cellText(value);
+
+  switch (type) {
+    case "mono":
+      return (
+        <Ident value={text} className="text-muted">
+          {middleTruncate(text, MONO_MAX)}
+        </Ident>
+      );
+
+    case "number":
+      return <span className="tnum">{text}</span>;
+
+    case "version":
+      return <span className="mono">{text}</span>;
+
+    case "date":
+      return <DateCell iso={text} />;
+
+    case "status":
+      // A column typed `status` can still hold a word from another vocabulary
+      // - an ADR status, say. Those get the plain text rather than a chip
+      // that would paint them with a meaning they do not have.
+      return STATUSES.has(text) ? (
+        <StatusChip status={text as Status} />
+      ) : (
+        <span className="mono text-muted">{text}</span>
+      );
+
+    case "kind":
+      return KINDS.has(text) ? (
+        <span className="mono inline-flex items-center gap-1.5 text-muted">
+          <KindIcon kind={text as Kind} />
+          {KIND_LABEL[text as Kind]}
+        </span>
+      ) : (
+        <span className="mono text-muted">{text}</span>
+      );
+
+    case "count":
+      // A count is a promise that the things counted are somewhere. When the
+      // column says where, the number is the way in.
+      return href ? (
+        <Link to={href} className="tnum rounded-control text-accent hover:underline">
+          {text}
+        </Link>
+      ) : (
+        <span className="tnum">{text}</span>
+      );
+
+    case "text":
+      return <span>{text}</span>;
+  }
+}

package/src/table/compare.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import {
+  compareDate,
+  compareKind,
+  compareStatus,
+  compareText,
+  compareVersion,
+  comparatorFor,
+} from "./compare";
+
+const sorted = (values: string[], cmp: (a: string, b: string) => number) =>
+  [...values].sort(cmp);
+
+describe("compareVersion", () => {
+  it("orders by segment value, not by spelling", () => {
+    expect(sorted(["v10", "v2", "v1"], compareVersion)).toEqual([
+      "v1",
+      "v2",
+      "v10",
+    ]);
+  });
+
+  it("compares every segment numerically", () => {
+    expect(sorted(["1.10.0", "1.2.0", "1.9.30"], compareVersion)).toEqual([
+      "1.2.0",
+      "1.9.30",
+      "1.10.0",
+    ]);
+  });
+
+  it("treats a missing segment as zero", () => {
+    expect(compareVersion("1.2", "1.2.0")).toBe(0);
+  });
+
+  it("ignores a leading v on either side", () => {
+    expect(compareVersion("v3", "3")).toBe(0);
+  });
+
+  it("puts a prerelease before the release it leads to", () => {
+    expect(sorted(["1.0.0", "1.0.0-rc.1", "1.0.0-alpha"], compareVersion)).toEqual(
+      ["1.0.0-alpha", "1.0.0-rc.1", "1.0.0"],
+    );
+  });
+
+  it("compares numeric prerelease identifiers as numbers", () => {
+    expect(compareVersion("1.0.0-rc.2", "1.0.0-rc.10")).toBeLessThan(0);
+  });
+
+  it("keeps the whole prerelease when it contains a hyphen", () => {
+    // Truncating at the second hyphen would make these two the same version.
+    expect(compareVersion("1.0.0-rc-2", "1.0.0-rc")).not.toBe(0);
+    expect(compareVersion("1.0.0-rc-2", "1.0.0-rc-2")).toBe(0);
+  });
+
+  it("drops build metadata from precedence", () => {
+    expect(compareVersion("1.0.0+abc", "1.0.0+zzz")).toBe(0);
+  });
+
+  it("sorts anything unversioned after every version", () => {
+    expect(sorted(["latest", "v2", "v1"], compareVersion)).toEqual([
+      "v1",
+      "v2",
+      "latest",
+    ]);
+  });
+});
+
+describe("compareStatus", () => {
+  it("orders verified, declared, unresolved", () => {
+    expect(sorted(["unresolved", "verified", "declared"], compareStatus)).toEqual(
+      ["verified", "declared", "unresolved"],
+    );
+  });
+
+  it("puts a value outside the vocabulary last", () => {
+    expect(compareStatus("verified", "made up")).toBeLessThan(0);
+  });
+});
+
+describe("compareKind", () => {
+  it("orders by the taxonomy, not the alphabet", () => {
+    expect(
+      sorted(["vo", "query", "event", "entity", "command"], compareKind),
+    ).toEqual(["event", "command", "query", "entity", "vo"]);
+  });
+});
+
+describe("compareDate", () => {
+  it("orders oldest first", () => {
+    expect(compareDate("2024-01-01", "2024-02-01")).toBeLessThan(0);
+  });
+
+  it("falls back to text when neither side parses", () => {
+    expect(compareDate("someday", "never")).toBe(compareText("someday", "never"));
+  });
+});
+
+describe("compareText", () => {
+  it("ignores case first and breaks the tie deterministically", () => {
+    expect(compareText("alpha", "Beta")).toBeLessThan(0);
+    expect(compareText("a", "A")).not.toBe(0);
+  });
+});
+
+describe("comparatorFor", () => {
+  it("sorts counts as numbers rather than strings", () => {
+    const cmp = comparatorFor("count");
+    expect(cmp(9, 10)).toBeLessThan(0);
+  });
+
+  it("puts undefined last whichever side it is on", () => {
+    const cmp = comparatorFor("text");
+    expect(cmp(undefined, "a")).toBeGreaterThan(0);
+    expect(cmp("a", undefined)).toBeLessThan(0);
+    expect(cmp(undefined, undefined)).toBe(0);
+  });
+});