wiki-formant 0.19.0 → 0.20.0

package/README.md

@@ -370,6 +370,7 @@ const block = licenseBlock({ license, scope: 'The protocol compilation and prose
 
 ```ts
 addCopyButtons(el);            // every <pre> gets one, once
+sortTables(el);                // every column-headed table sorts by its headers
 hydrateTweetEmbeds(el);        // placeholders get a live src
 const off = onTweetResize(h => sizeTweetEmbeds(el, h));
 ```
@@ -378,6 +379,8 @@ const off = onTweetResize(h => sizeTweetEmbeds(el, h));
 
 `activateTabGroups` turns stored `[data-tabs]` markup into a working tab group. The editor persists tabs as nested divs, which is the right thing to store — it survives a markdown twin, a plain HTML render and a reader with JavaScript off, all of which show every tab in order. Making one of them pressable is a reader-side job, and it sits beside the other passes rather than inside a component.
 
+`sortTables` makes the tables stored in article HTML sortable by their headers. They arrive as a string a `dangerouslySetInnerHTML` wrote, so React never sees their rows and cannot sort them. A column is dates if every filled cell starts with one, numbers if every one does, and text otherwise — one stray value makes the whole column text, which beats sorting half of it by one rule and half by another. A third press restores the author's order, which is often chronological or ranked and otherwise needs a reload. Label/value tables and tables with merged cells are left alone. The markup it writes — `aria-sort` on the cell, a `.sort-header` button inside it — is the markup a React sortable header should write too, so both kinds of table draw their arrows from one stylesheet rule.
+
 `TWITTER_ORIGIN` is written down once. It is both the embed host and the allow-list `onTweetResize` checks before believing a posted height, and it had been spelled out at four call sites across two repos. Any page can `postMessage`; only the embed host may size the embed.
 
 ## Editor nodes

package/dist/dom.d.ts

@@ -65,3 +65,27 @@ export interface TabGroupClassNames {
  * silently reset it to the first tab.
  */
 export declare function activateTabGroups(root: ParentNode, classNames?: TabGroupClassNames): void;
+export interface SortTablesOptions {
+    /** Class on the injected header button. Style it in your own stylesheet. */
+    className?: string;
+}
+/**
+ * Make every column-headed table under `root` sortable by its headers, once.
+ *
+ * Pressing a header sorts by that column. Text sorts A–Z first and numbers and
+ * dates largest first, the same as a React table sorted by `useTableSort`. A
+ * second press reverses the order and a third restores the author's order,
+ * which is often meaningful (chronological, or ranked) and otherwise could only
+ * be recovered by a reload.
+ *
+ * Tables stored in article HTML arrive as a string a `dangerouslySetInnerHTML`
+ * wrote, so React never sees their rows and cannot sort them — which is why
+ * this is a DOM pass beside `addCopyButtons` rather than a component. The
+ * markup it writes, `aria-sort` on the cell and a button inside it, is the
+ * markup a React sortable header should write too, so both kinds of table draw
+ * their arrows from one stylesheet rule.
+ *
+ * Skipped: tables with merged cells, where moving a row would break the grid;
+ * tables with fewer than two rows to sort; and rows that span several `<tbody>`s.
+ */
+export declare function sortTables(root: ParentNode, options?: SortTablesOptions): void;

package/dist/dom.js

@@ -163,3 +163,138 @@ export function activateTabGroups(root, classNames = {}) {
         group.appendChild(tabPanels);
     }
 }
+const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december'];
+const monthIndex = (name) => MONTHS.findIndex(m => m.startsWith(name.toLowerCase()));
+// A dash, a question mark or "n/a" means the cell has no value. It sorts last
+// in both directions, so it never lands above real values.
+const BLANK = /^(?:[-–—?]|n\/?a|tb[ad])?$/i;
+const DAY_FIRST = /^(\d{1,2})(?:st|nd|rd|th)?\s+([a-z]{3,9})\.?,?\s+(\d{4})(?:,?\s+(\d{1,2}):(\d{2})(?::(\d{2}))?)?/i;
+const MONTH_FIRST = /^([a-z]{3,9})\.?\s+(?:(\d{1,2})(?:st|nd|rd|th)?,?\s+)?(\d{4})/i;
+/** The time a cell starts with, as ms. Accepts ISO dates, "4 Jun 2026", "June 4, 2026", "June 2026" and a bare year. */
+function parseDate(s) {
+    const iso = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?(?:[ T](\d{2}):(\d{2}))?)?(?![\d,.])/.exec(s);
+    if (iso)
+        return Date.UTC(+iso[1], +(iso[2] ?? 1) - 1, +(iso[3] ?? 1), +(iso[4] ?? 0), +(iso[5] ?? 0));
+    const d = DAY_FIRST.exec(s);
+    if (d && monthIndex(d[2]) >= 0)
+        return Date.UTC(+d[3], monthIndex(d[2]), +d[1], +(d[4] ?? 0), +(d[5] ?? 0), +(d[6] ?? 0));
+    const m = MONTH_FIRST.exec(s);
+    if (m && monthIndex(m[1]) >= 0)
+        return Date.UTC(+m[3], monthIndex(m[1]), +(m[2] ?? 1));
+    return null;
+}
+const MULTIPLIER = {
+    k: 1e3, thousand: 1e3, m: 1e6, million: 1e6, b: 1e9, bn: 1e9, billion: 1e9, t: 1e12, trillion: 1e12,
+    kb: 1e3, mb: 1e6, gb: 1e9, tb: 1e12, kib: 2 ** 10, mib: 2 ** 20, gib: 2 ** 30, tib: 2 ** 40,
+};
+// The number a cell starts with: "~$3,500", "+137%", "−0.4", "142M XRD",
+// "14.00 million", "3.4 MB". A version string like "1.18.4" is not a number, so a column
+// of versions falls through to the natural text order, where 1.9 comes before 1.10.
+const NUMBER = /^[~≈<>≤≥]?\s*([+\-−]?)\s*[#$€£¥]?\s*(\d[\d,]*(?:\.\d+)?|\.\d+)(?![.\d])(?:\s*(%|(?:thousand|million|billion|trillion|[kmgt]i?b|bn|[kmbt])(?![a-z])))?/i;
+function parseNumber(s) {
+    const n = NUMBER.exec(s);
+    if (!n)
+        return null;
+    const value = parseFloat(n[2].replace(/,/g, '')) * (MULTIPLIER[n[3]?.toLowerCase() ?? ''] ?? 1);
+    return n[1] && n[1] !== '+' ? -value : value;
+}
+/**
+ * The column's sort keys. A column is dates if every filled cell starts with a
+ * date, numbers if every one starts with a number, and text otherwise. One
+ * stray value makes the whole column text, which is better than sorting it half
+ * by one rule and half by another.
+ */
+function columnKeys(cells) {
+    const blank = cells.map(c => BLANK.test(c));
+    for (const parse of [parseDate, parseNumber]) {
+        const keys = cells.map((c, i) => (blank[i] ? null : parse(c)));
+        if (keys.every((k, i) => k !== null || blank[i]))
+            return keys;
+    }
+    return cells.map((c, i) => (blank[i] ? null : c));
+}
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+function compare(a, b, direction) {
+    if (a === null || b === null)
+        return a === b ? 0 : a === null ? 1 : -1;
+    const order = typeof a === 'number' && typeof b === 'number' ? a - b : collator.compare(String(a), String(b));
+    return direction === 'ascending' ? order : -order;
+}
+/**
+ * The row whose cells label the columns: the last row of a `<thead>`, or the
+ * first row when every cell in it is a `<th>`. The editor writes the second
+ * form. An infobox's label/value table has neither form, so it is left alone.
+ */
+function headerRow(table) {
+    const head = table.tHead?.rows;
+    if (head?.length)
+        return head[head.length - 1];
+    const first = table.rows[0];
+    return first && Array.from(first.cells).every(c => c.tagName === 'TH') ? first : undefined;
+}
+/**
+ * Make every column-headed table under `root` sortable by its headers, once.
+ *
+ * Pressing a header sorts by that column. Text sorts A–Z first and numbers and
+ * dates largest first, the same as a React table sorted by `useTableSort`. A
+ * second press reverses the order and a third restores the author's order,
+ * which is often meaningful (chronological, or ranked) and otherwise could only
+ * be recovered by a reload.
+ *
+ * Tables stored in article HTML arrive as a string a `dangerouslySetInnerHTML`
+ * wrote, so React never sees their rows and cannot sort them — which is why
+ * this is a DOM pass beside `addCopyButtons` rather than a component. The
+ * markup it writes, `aria-sort` on the cell and a button inside it, is the
+ * markup a React sortable header should write too, so both kinds of table draw
+ * their arrows from one stylesheet rule.
+ *
+ * Skipped: tables with merged cells, where moving a row would break the grid;
+ * tables with fewer than two rows to sort; and rows that span several `<tbody>`s.
+ */
+export function sortTables(root, options = {}) {
+    const { className = 'sort-header' } = options;
+    for (const table of Array.from(root.querySelectorAll('table:not([data-sort-init])'))) {
+        table.setAttribute('data-sort-init', '');
+        const head = headerRow(table);
+        if (!head)
+            continue;
+        const rows = Array.from(table.tBodies).flatMap(b => Array.from(b.rows)).filter(r => r !== head);
+        const body = rows[0]?.parentElement;
+        if (!body || rows.length < 2 || rows.some(r => r.parentElement !== body))
+            continue;
+        if (Array.from(table.querySelectorAll('th, td')).some(c => c.colSpan > 1 || c.rowSpan > 1))
+            continue;
+        const headers = Array.from(head.cells);
+        const sortBy = (col, th) => {
+            const keys = columnKeys(rows.map(r => r.cells[col]?.textContent?.trim() ?? ''));
+            const first = typeof keys.find(k => k !== null) === 'string' ? 'ascending' : 'descending';
+            const current = th.getAttribute('aria-sort');
+            const next = current === first ? (first === 'ascending' ? 'descending' : 'ascending') : current === 'none' ? first : null;
+            for (const h of headers)
+                if (h.hasAttribute('aria-sort'))
+                    h.setAttribute('aria-sort', 'none');
+            if (next)
+                th.setAttribute('aria-sort', next);
+            const order = next
+                ? rows.map((row, i) => ({ row, key: keys[i] ?? null })).sort((a, b) => compare(a.key, b.key, next)).map(x => x.row)
+                : rows;
+            body.append(...order);
+        };
+        headers.forEach((th, col) => {
+            // A header with no label has nothing to press, and a link inside a
+            // button would fire both.
+            if (!th.textContent?.trim() || th.querySelector('a, button'))
+                return;
+            const button = document.createElement('button');
+            button.type = 'button';
+            button.className = className;
+            // The editor wraps every cell's text in a <p>, which a button cannot hold.
+            const label = th.children.length === 1 && th.firstElementChild?.tagName === 'P' ? th.firstElementChild : th;
+            button.append(...Array.from(label.childNodes));
+            button.onclick = () => sortBy(col, th);
+            th.replaceChildren(button);
+            th.scope ||= 'col';
+            th.setAttribute('aria-sort', 'none');
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, and conditional-GET plumbing.",
   "type": "module",
   "license": "MIT",
@@ -193,6 +193,7 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "jose": "^6.2.10",
+    "jsdom": "^30.1.0",
     "react": "^19.2.4",
     "typescript": "^5.9.0"
   },
@@ -200,18 +201,18 @@
     "@radixdlt/rola": ">=2",
     "@tiptap/core": ">=2.10",
     "@tiptap/extension-code-block": ">=2.10",
-    "@tiptap/extension-youtube": ">=2.10",
-    "@tiptap/react": ">=2.10",
-    "jose": ">=5",
-    "react": ">=18",
-    "@tiptap/starter-kit": ">=2.10",
-    "@tiptap/extension-link": ">=2.10",
     "@tiptap/extension-image": ">=2.10",
+    "@tiptap/extension-link": ">=2.10",
+    "@tiptap/extension-placeholder": ">=2.10",
     "@tiptap/extension-table": ">=2.10",
-    "@tiptap/extension-table-row": ">=2.10",
     "@tiptap/extension-table-cell": ">=2.10",
     "@tiptap/extension-table-header": ">=2.10",
-    "@tiptap/extension-placeholder": ">=2.10"
+    "@tiptap/extension-table-row": ">=2.10",
+    "@tiptap/extension-youtube": ">=2.10",
+    "@tiptap/react": ">=2.10",
+    "@tiptap/starter-kit": ">=2.10",
+    "jose": ">=5",
+    "react": ">=18"
   },
   "peerDependenciesMeta": {
     "react": {