@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui/components/table-view.ts

@@ -0,0 +1,219 @@
+// The ordering and paging rules behind `<Table>`, with no JSX and no Preact in
+// them, so `deno test` covers the comparison and the window math without a DOM.
+//
+// Both halves of the table story go through these functions. A hydrated caller
+// runs them per render through `useTableView`; a plain Fresh route that never
+// hydrates runs them on the server and renders links. Neither owns a rule the
+// other doesn't have.
+
+export type SortDirection = "asc" | "desc";
+export type SortState = { key: string; direction: SortDirection };
+export type SortValue = string | number | boolean | Date | null | undefined;
+
+// One collator for the process, with the locale nailed down: SSR runs in Deno
+// and hydration runs in the browser, so a comparison that reads the ambient
+// locale can order the same rows two ways and print a hydration diff. `numeric`
+// puts `app-2` before `app-10`; `sensitivity: "base"` stops `Zebra` sorting
+// above `apple`. Constructed once - a collator costs about as much to build as
+// the comparison it performs, and a sort calls this O(n log n) times.
+const collator = new Intl.Collator("en", { numeric: true, sensitivity: "base" });
+
+// "Nothing to compare", which is more than just `null`. An empty cell and a
+// missing one read identically in the table, so they have to sort identically
+// too, and a `NaN` that reached a numeric column is an absent measurement
+// rather than a value smaller than every other one.
+function isAbsent(value: SortValue): boolean {
+  return (
+    value === null ||
+    value === undefined ||
+    value === "" ||
+    (typeof value === "number" && Number.isNaN(value))
+  );
+}
+
+/**
+ * Order two cell values ascending.
+ *
+ * Numbers, dates and booleans compare by value; everything else goes through
+ * the collator as a string. Sorting a number column as text is the classic
+ * table bug (`9` above `10`, `900 KiB` above `1 GiB`), so the accessors are
+ * expected to hand back raw values and the formatting stays in the cell.
+ *
+ * Absent values sort last here as well, so a direct caller gets the same
+ * answer, but {@link sortRows} does its own absent check before the direction
+ * flip - see there for why.
+ */
+export function compareValues(a: SortValue, b: SortValue): number {
+  const aAbsent = isAbsent(a);
+  const bAbsent = isAbsent(b);
+  if (aAbsent || bAbsent) return aAbsent && bAbsent ? 0 : aAbsent ? 1 : -1;
+  // Dates fold into the numeric path rather than getting one of their own, so a
+  // column that yields `Date | number` still orders by value. The typeof guard
+  // keeps a mixed Date/string column out of it: `Number("a")` is NaN, a NaN
+  // comparator reads as 0 to `.sort`, and the result is not an order at all.
+  // Such a column falls through to the collator, which is at least total.
+  const av = a instanceof Date ? a.getTime() : a;
+  const bv = b instanceof Date ? b.getTime() : b;
+  if (typeof av === "number" && typeof bv === "number") return av - bv;
+  if (typeof av === "boolean" && typeof bv === "boolean") return Number(av) - Number(bv);
+  return collator.compare(String(av), String(bv));
+}
+
+/**
+ * A copy of `rows` ordered by one column, or `rows` itself when there is
+ * nothing to do.
+ *
+ * Three things this deliberately does not do:
+ *
+ * 1. It doesn't throw on a key it doesn't know. `sort` can arrive from a query
+ *    string, where anyone can type anything, and a listing that 500s on a bad
+ *    `?sort=` is worse than one that ignores it.
+ * 2. It doesn't flip absent values to the top on a descending sort. `null`,
+ *    `undefined`, `""` and `NaN` sort last in BOTH directions, which is why the
+ *    absent check sits outside the sign multiply. A descending sort that floats
+ *    the empties up fills page 1 with the rows nobody paginated to see.
+ * 3. It doesn't sort in place. `[...rows].sort()` also buys stability, which
+ *    has been spec-guaranteed since ES2019 and is what makes "sort by state,
+ *    then click name" keep the first key as the tiebreaker.
+ */
+export function sortRows<T>(
+  rows: readonly T[],
+  sort: SortState | null,
+  columns: Record<string, (row: T) => SortValue>,
+): readonly T[] {
+  if (!sort) return rows;
+  const accessor = columns[sort.key];
+  if (!accessor) return rows;
+  const sign = sort.direction === "desc" ? -1 : 1;
+  return [...rows].sort((x, y) => {
+    const a = accessor(x);
+    const b = accessor(y);
+    const aAbsent = isAbsent(a);
+    const bAbsent = isAbsent(b);
+    if (aAbsent || bAbsent) return aAbsent && bAbsent ? 0 : aAbsent ? 1 : -1;
+    return sign * compareValues(a, b);
+  });
+}
+
+/**
+ * What clicking a header does: the active column flips, any other column
+ * adopts its own `initial` direction.
+ *
+ * Carrying the current direction across to a new column is the wrong default -
+ * jumping from "newest first" to "targets, Z to A" is never what was meant.
+ * There is no third "unsorted" state on the way round: a table always has an
+ * order, and cycling back to the unsorted one just means an extra click to
+ * reach the direction you wanted.
+ */
+export function toggleSort(
+  current: SortState | null,
+  key: string,
+  initial: SortDirection = "asc",
+): SortState {
+  if (current?.key === key) {
+    return { key, direction: current.direction === "asc" ? "desc" : "asc" };
+  }
+  return { key, direction: initial };
+}
+
+/**
+ * A `?sort=&dir=` pair off a URL, or null if it names nothing this table has.
+ *
+ * Strict on both halves: the key has to be in the allowlist and the direction
+ * has to be spelled exactly, so a hand-edited URL degrades to the default view
+ * instead of half-applying. A caller that wants a per-column default direction
+ * supplies it (`parseSort(key, dir ?? defaultDirFor(key), columns)`) rather
+ * than having one baked in here.
+ */
+export function parseSort(
+  key: string | null | undefined,
+  direction: string | null | undefined,
+  columns: readonly string[],
+): SortState | null {
+  if (!key || !columns.includes(key)) return null;
+  if (direction !== "asc" && direction !== "desc") return null;
+  return { key, direction };
+}
+
+/**
+ * How many pages `total` rows fill.
+ *
+ * Never zero. Zero pages makes `clampPage` return 0 and the summary read "page
+ * 0 of 0"; an empty table is page 1 of 1, which is also the page the operator
+ * is looking at.
+ */
+export function pageCount(total: number, pageSize: number): number {
+  if (!Number.isFinite(pageSize) || pageSize <= 0) return 1;
+  return Math.max(1, Math.ceil(Math.max(0, total) / pageSize));
+}
+
+/** The nearest page that exists. Junk (`NaN`, `-3`, `1e9`) snaps into range. */
+export function clampPage(page: number, count: number): number {
+  const last = Math.max(1, Math.floor(count) || 1);
+  const wanted = Math.floor(page);
+  // NaN only. `Infinity` is junk too, but it is junk on the HIGH side, and
+  // `Math.min` already snaps it to the last page - bailing to 1 here would send
+  // "past the end" to the opposite end of the list from the one it asked for.
+  if (Number.isNaN(wanted) || wanted < 1) return 1;
+  return Math.min(wanted, last);
+}
+
+/** One page's worth of rows. A non-positive `pageSize` means "no paging". */
+export function pageSlice<T>(rows: readonly T[], page: number, pageSize: number): readonly T[] {
+  if (!Number.isFinite(pageSize) || pageSize <= 0) return rows;
+  const current = clampPage(page, pageCount(rows.length, pageSize));
+  const start = (current - 1) * pageSize;
+  return rows.slice(start, start + pageSize);
+}
+
+/**
+ * The position line under the table.
+ *
+ * `to` is clamped at `total` so a partial last page can't claim rows that
+ * aren't there ("Showing 1,201-1,250 of 1,234"), and so is `from`, so a page
+ * number past the end still reads as a position rather than as arithmetic.
+ * Fixed locale, again because this string is rendered on both sides of
+ * hydration.
+ */
+export function pageSummary(page: number, pageSize: number, total: number): string {
+  if (total <= 0) return "No results";
+  const n = (value: number) => value.toLocaleString("en-US");
+  const from = Math.min(Math.max(1, (page - 1) * pageSize + 1), total);
+  // Floored at `from` as well as capped at `total`: an unclamped page 0 would
+  // otherwise read "Showing 1-0 of 7", a range that runs backwards.
+  const to = Math.min(Math.max(page * pageSize, from), total);
+  return `Showing ${n(from)}-${n(to)} of ${n(total)}`;
+}
+
+/**
+ * The page numbers to render, with `"ellipsis"` standing in for the runs that
+ * are collapsed.
+ *
+ * The row is a **constant** width at a given `siblings` (`2 * siblings + 5`
+ * entries) for every page of a long list. A row that grows by two buttons the
+ * moment you leave page 1 slides the next button out from under the cursor
+ * between mousedown and click, which is a misclick the operator didn't make.
+ *
+ * The `left > 3` / `right < count - 2` guards are also what make an ellipsis
+ * standing in for a single page impossible, so there is no collapse fix-up
+ * pass: a gap is always at least two pages wide or it isn't a gap.
+ */
+export function pageWindow(page: number, count: number, siblings = 1): (number | "ellipsis")[] {
+  const last = Math.max(1, Math.floor(count) || 1);
+  const current = clampPage(page, last);
+  // `siblings` is a public prop. A negative one makes the middle range run
+  // backwards, which drops the current page out of its own window.
+  const wings = Math.max(0, Math.floor(siblings) || 0);
+  const range = (from: number, to: number): number[] =>
+    Array.from({ length: to - from + 1 }, (_, i) => from + i);
+
+  // first + last + current + 2 * siblings + 2 ellipses.
+  const slots = wings * 2 + 5;
+  if (last <= slots) return range(1, last);
+
+  const showLeft = current - wings > 3;
+  const showRight = current + wings < last - 2;
+  if (!showLeft) return [...range(1, wings * 2 + 3), "ellipsis", last];
+  if (!showRight) return [1, "ellipsis", ...range(last - (wings * 2 + 2), last)];
+  return [1, "ellipsis", ...range(current - wings, current + wings), "ellipsis", last];
+}