@sportsdataverse/sdvtables 0.1.0 → 0.2.0

package/README.md

@@ -90,115 +90,6 @@ fonts yourself (`fontsLink(fonts)` builds the same tag). `toElement` moves the l
 Decoration CSS is scoped to the table `#id`. Two renders of the same spec on one page therefore need distinct ids:
 call `.id("a")` / `.id("b")` on the builder.
 
-## **TanStack Table interop (recipe)**
-
-sdvtables has its own headless engine and takes no TanStack dependency. If your app already renders tables with
-`@tanstack/react-table` 8, map a `TableSpec` to `ColumnDef`s: the header comes from the spec, and each
-cell reuses the markup `renderHTML` draws (logos, pills, bars), read back from `toElement()` by `data-row` / `data-col`.
-Sorting uses the spec's `sortable` and `compare`, the fields [the engine](#interactive) reads: a column without
-`compare` falls back to TanStack's default sort, and `compare` stays ascending because TanStack inverts it for
-descending itself.
-
-`toElement` needs a `document`, and a `"use client"` component is still server-rendered in Next, so build the columns
-only after mount: in a `useEffect` (below), or load the table component with `next/dynamic(..., { ssr: false })`.
-
-```tsx
-import type { TableSpec } from "@sportsdataverse/sdvtables";
-import { columnLabel, toElement } from "@sportsdataverse/sdvtables/html";
-import type { ColumnDef } from "@tanstack/react-table";
-
-/** sdvtables columns -> TanStack column defs. Cells reuse renderHTML's own markup (logos, pills, bars); wrap the
- *  table in `<div className={themeKey(spec.theme)}>` and emit `<style>{styleSheet(spec)}</style>` once. */
-export function toTanStackColumns<Row>(
-  spec: TableSpec<Row>,
-  rows: readonly Row[],
-): ColumnDef<Row, unknown>[] {
-  const cells = new Map<string, Element>(); // "row|col" -> sdvtables' <td>
-  // needs a DOM (throws TableSpecError without a document): call this after mount, never during render
-  for (const td of Array.from(toElement(spec, rows).querySelectorAll("tr[data-row] > td[data-col]")))
-    cells.set(`${td.parentElement?.getAttribute("data-row")}|${td.getAttribute("data-col")}`, td);
-  return spec.columns.map(
-    (c): ColumnDef<Row, unknown> => ({
-      id: c.key,
-      accessorFn: (row) => row[c.key],
-      header: columnLabel(c),
-      enableSorting: c.sortable !== false,
-      ...(c.compare ? { sortingFn: (a, b, id) => c.compare?.(a.getValue(id), b.getValue(id)) ?? 0 } : {}),
-      cell: (ctx) => {
-        const cell = cells.get(`${ctx.row.index}|${c.key}`); // row.index is the input order, as data-row is
-        // pill / rank fills live on sdvtables' own <td style>, so carry that over too
-        return (
-          <div
-            ref={(n) => n?.setAttribute("style", cell?.getAttribute("style") ?? "")}
-            // biome-ignore lint/security/noDangerouslySetInnerHtml: sdvtables escapes every value it renders
-            dangerouslySetInnerHTML={{ __html: cell?.innerHTML ?? "" }}
-          />
-        );
-      },
-    }),
-  );
-}
-```
-
-```tsx
-"use client";
-import type { TableSpec } from "@sportsdataverse/sdvtables";
-import { prepare, styleSheet, themeKey } from "@sportsdataverse/sdvtables/html";
-import { type ColumnDef, flexRender, getCoreRowModel, getSortedRowModel, useReactTable } from "@tanstack/react-table";
-import { type ReactElement, useEffect, useState } from "react";
-import { toTanStackColumns } from "./to-tanstack-columns"; // the first fence
-
-export function StandingsTable<Row>({ spec, rows }: { spec: TableSpec<Row>; rows: Row[] }): ReactElement {
-  // empty on the server and on the first client render; filled once the effect has run
-  const [columns, setColumns] = useState<ColumnDef<Row, unknown>[]>([]);
-  useEffect(() => {
-    let live = true;
-    void prepare(spec).then(() => {
-      if (live) setColumns(toTanStackColumns(spec, rows));
-    });
-    return () => {
-      live = false;
-    };
-  }, [spec, rows]);
-
-  const table = useReactTable({
-    data: rows, // keep this reference stable: a new array every render makes TanStack loop
-    columns,
-    getCoreRowModel: getCoreRowModel(),
-    getSortedRowModel: getSortedRowModel(),
-  });
-  return (
-    <div className={themeKey(spec.theme)}>
-      <style>{styleSheet(spec)}</style>
-      <table>
-        <thead>
-          {table.getHeaderGroups().map((g) => (
-            <tr key={g.id}>
-              {g.headers.map((h) => (
-                <th key={h.id}>{flexRender(h.column.columnDef.header, h.getContext())}</th>
-              ))}
-            </tr>
-          ))}
-        </thead>
-        <tbody>
-          {table.getRowModel().rows.map((r) => (
-            <tr key={r.id}>
-              {r.getVisibleCells().map((c) => (
-                <td key={c.id}>{flexRender(c.column.columnDef.cell, c.getContext())}</td>
-              ))}
-            </tr>
-          ))}
-        </tbody>
-      </table>
-    </div>
-  );
-}
-```
-
-Limits: `snake` and tier layouts change which `<tr>` holds which row, so the recipe covers plain specs; table-level
-decorations (title, caption, stripes) are not cells and are not carried over. Written for `@tanstack/react-table` 8
-(sdv-web pins `^8.21.3`); v9 is a breaking major and is not covered.
-
 ## **Themes**
 
 20 themes: the 18 gtUtils themes plus `sdv` (light/dark) and `sdvTeam`. Set one with
@@ -227,10 +118,12 @@ decorations (title, caption, stripes) are not cells and are not carried over. Wr
 
 ## **Surface**
 
-- 21 column kinds on the `c` factory (`text`, `num`, `int`, `pct`, `rank`, `delta`, `tally`, `logo`, `wordmark`,
+- 29 column kinds on the `c` factory (`text`, `num`, `int`, `pct`, `rank`, `delta`, `tally`, `logo`, `wordmark`,
   `headshot`, `colorPills`, `colorRanks`, `colorResults`, `percentileBar`, `indicatorBox`, `highlight`,
-  `highlightNa`, `mergeStackTeamColor`, `teamColorBar`, `teamColorBg`, `image`; `fmtRank`/`fmtTally` alias
-  `rank`/`tally`).
+  `highlightNa`, `mergeStackTeamColor`, `teamColorBar`, `teamColorBg`, `image`, and the reactablefmtr formatters
+  `dataBar`, `iconSet`, `iconAssign`, `mergeStack`, `bubble`, and the in-cell charts `sparkline`, `sparkbar`, `gauge`
+  (inline SVG, array-valued columns for the first two); `fmtRank`/`fmtTally` alias `rank`/`tally`).
+  Any column takes `tooltip: true` (the value as a `title` attribute).
 - 25 table decorations as builder methods (titles, legends, cutlines, row accents, snake layout, tiers, watermark, ...).
 - Conditions are data predicates (`{ key, op, value }`), not callbacks, so specs stay serializable.
 - Number cells display negatives with U+2212 (a true minus); `formatValue`-style labels (legends, notes) stay ASCII.
@@ -348,6 +241,71 @@ function Standings() {
 sort, filters, page and selection; only a structural `spec` change builds a new engine. Without `interactive` the
 component renders the static table. The `react` entry is marked `"use client"`.
 
+### MUI X Data Grid
+
+```tsx
+import { DataGrid } from "@mui/x-data-grid"; // peer: @mui/x-data-grid >= 9.15.0 (MIT; never -pro or -premium)
+import { prepare } from "@sportsdataverse/sdvtables/html";
+import { dataGridProps } from "@sportsdataverse/sdvtables/mui";
+
+await prepare(spec);
+<DataGrid rows={rows} {...dataGridProps(spec, rows, { teamRows: { key: "team", league: "nfl" } })} autoHeight />;
+```
+
+`dataGridProps(spec, rows, o)` maps a spec onto MUI X Data Grid: one `GridColDef` per column (label, alignment, px
+width, sdvtables' number formats through `valueFormatter`), logo, wordmark and headshot cells through `renderCell`,
+`teamColorBg` / `teamColorBar` cells and `teamRows` in sdvplot's team palette (`@sportsdataverse/sdvplot/mui`'s
+`teamColorPalette`) with black or white text by contrast, and the theme's fonts, colours, stripes and density as the
+grid's `sx` and `density`. It never imports MUI. Kinds drawn in HTML or SVG (pills, bars, sparklines...) show their
+plain value, with one warning per kind. Guide: [MUI X Data Grid](https://plot.sportsdataverse.org/guides/mui-x-data-grid).
+
+### AG Grid
+
+```ts
+import { AllCommunityModule, ModuleRegistry, createGrid, themeQuartz } from "ag-grid-community"; // peer: >= 36.2.0 (MIT)
+import { gridOptions } from "@sportsdataverse/sdvtables/aggrid";
+import { prepare } from "@sportsdataverse/sdvtables/html";
+
+ModuleRegistry.registerModules([AllCommunityModule]);
+await prepare(spec);
+const el = document.querySelector("#grid")!; // AG Grid fills its container: size it, or use domLayout: "autoHeight"
+createGrid(el, {
+  ...gridOptions(spec, rows, { theme: themeQuartz, teamRows: { key: "team", league: "nfl" } }),
+  domLayout: "autoHeight",
+});
+```
+
+`gridOptions(spec, rows, o)` maps a spec onto AG Grid Community: one column definition per column (label, alignment,
+px width, sdvtables' number formats through `valueFormatter`, sdvtables' sort with missing values last both ways),
+logo, wordmark and headshot cells through cell renderer classes that work in plain JavaScript and in ag-grid-react,
+`teamColorBg` / `teamColorBar` cells and `teamRows` in sdvplot's team palette with black or white text by contrast
+(kept through AG Grid's hover and selection), unique row ids, and, given AG Grid's `themeQuartz` (or another base), the
+theme's fonts and colours through AG Grid's Theming API. It never imports AG Grid at runtime. Community only: nothing
+here uses or needs `ag-grid-enterprise`. Guide: [AG Grid](https://plot.sportsdataverse.org/guides/ag-grid).
+
+### TanStack Table v9
+
+`@sportsdataverse/sdvtables/tanstack-table` turns a spec into TanStack Table v9 options:
+`tanstackTable(spec, rows, { features, render })` returns `options` for React's `useTable` or Svelte's `createTable`
+(`features` is your own `tableFeatures({ rowSortingFeature, sortedRowModel: createSortedRowModel() })`, passed through)
+and `columnStyle`, each column's alignment and width. Columns keep the HTML table's labels and number text (a
+`scaleNote` and ordinals included), sort with sdvtables' comparator with missing values last both ways, and take their
+row ids from the spec's `rowKey` (a repeated or blank value throws). Logo, wordmark, headshot and superscript-rank cells
+come to your `render` as plain data (`CellPart`), which you turn into a React element or a Svelte component; a team or
+player with no image keeps its text and warns once. It imports table-core's types only and touches no DOM, so it runs on
+a server. Peer: `@tanstack/table-core` >= 9.3.1, optional (its types are in the declarations, so TypeScript needs it
+installed). Call `await prepare(spec)` first.
+
+The guide, [TanStack Table](https://plot.sportsdataverse.org/guides/tanstack-table), shows a sortable React component
+and a Svelte 5 one (`examples/snippets/tanstack-table/SdvTable.tsx` and `examples/snippets/svelte/TanstackStandings.svelte`
+in this repository), both compiled and rendered by the tests.
+
+**From the v8 recipe.** This README used to carry an untested recipe for `@tanstack/react-table` 8 (`toTanStackColumns`,
+reading each cell's markup back from `toElement()`). TanStack Table v9 changed its API: `useTable` replaces
+`useReactTable`, features and row models are registered in `tableFeatures` (`createSortedRowModel()` where v8 took
+`getSortedRowModel()`), `sortingFn` is `sortFn`, and `ColumnDef` takes the features' type first. Use `tanstackTable`
+instead; it needs no DOM, so the columns no longer wait for a mount.
+
 ## **Export (Node; peer: playwright)**
 
 `@sportsdataverse/sdvtables/export` renders tables to PNG in headless Chromium. Its functions port sdvplotR's