@sportsdataverse/sdvtables 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SportsDataverse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,4 @@
+# Notices
+
+- `@sportsdataverse/sdvtables` ports the `great_tables` helpers of **sdvplot** (Python, MIT) and the `gt_*` table functions of **sdvplotR** (MIT). Team logos, headshots and colors come from `@sportsdataverse/sdvplot`.
+- The social icons in `src/html/social-icons.ts` are Font Awesome Free 6 paths (https://fontawesome.com), licensed CC BY 4.0.

package/README.md

@@ -1,3 +1,520 @@
-# Temporary Holding Version
+# **@sportsdataverse/sdvtables** <a href='https://plot.sportsdataverse.org/'><img src='https://raw.githubusercontent.com/sportsdataverse/sdvplot-js/main/docs/static/img/sdvplot-js-logo.png' align="right" width="25%" min-width="120px" alt="sdvplot-js hex logo" /></a>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<!-- badges: start -->
+
+[![npm](https://img.shields.io/npm/v/@sportsdataverse/sdvtables?label=sdvtables&logo=npm&style=for-the-badge)](https://www.npmjs.com/package/@sportsdataverse/sdvtables)
+[![Downloads](https://img.shields.io/npm/dm/@sportsdataverse/sdvtables?style=for-the-badge)](https://www.npmjs.com/package/@sportsdataverse/sdvtables)
+[![Total downloads](https://img.shields.io/npm/dt/@sportsdataverse/sdvtables?style=for-the-badge)](https://www.npmjs.com/package/@sportsdataverse/sdvtables)
+[![Node](https://img.shields.io/node/v/@sportsdataverse/sdvtables?logo=nodedotjs&logoColor=white&style=for-the-badge)](https://nodejs.org/)
+[![Unpacked size](https://img.shields.io/npm/unpacked-size/@sportsdataverse/sdvtables?style=for-the-badge)](https://www.npmjs.com/package/@sportsdataverse/sdvtables?activeTab=code)
+[![ci](https://img.shields.io/github/actions/workflow/status/sportsdataverse/sdvplot-js/ci.yml?branch=main&label=ci&logo=github&style=for-the-badge)](https://github.com/sportsdataverse/sdvplot-js/actions/workflows/ci.yml)
+[![release](https://img.shields.io/github/actions/workflow/status/sportsdataverse/sdvplot-js/release.yml?branch=main&label=release&logo=github&style=for-the-badge)](https://github.com/sportsdataverse/sdvplot-js/actions/workflows/release.yml)
+[![docs](https://img.shields.io/github/deployments/sportsdataverse/sdvplot-js/Production?label=docs&logo=vercel&style=for-the-badge)](https://plot.sportsdataverse.org)
+[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg?style=for-the-badge&logo=github)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+[![License](https://img.shields.io/github/license/sportsdataverse/sdvplot-js?style=for-the-badge)](https://github.com/sportsdataverse/sdvplot-js/blob/main/LICENSE)
+[![Contributors](https://img.shields.io/github/contributors/sportsdataverse/sdvplot-js?style=for-the-badge)](https://github.com/sportsdataverse/sdvplot-js/graphs/contributors)
+[![Twitter Follow](https://img.shields.io/twitter/follow/SportsDataverse?color=blue&label=%40SportsDataverse&logo=x&style=for-the-badge)](https://x.com/SportsDataverse)
+
+<!-- badges: end -->
+
+Serializable table specs rendered to HTML (static, or interactive with a headless engine) and to PNG, with
+SportsDataverse team identity and themes. A `TableSpec` is plain
+data (JSON-safe), so the same spec renders in Node, the browser and notebooks. Zero runtime dependencies beyond
+[`@sportsdataverse/sdvplot`](https://plot.sportsdataverse.org) (team logos, headshots and colors).
+
+Siblings: [sdvplot](https://sdvplot.sportsdataverse.org/) (Python, `great_tables` helpers) and
+[sdvplotR](https://sdvplotR.sportsdataverse.org/) (R, `gt_*`). This package ports both; the name map is
+[below](#gtutils--sdvplotr-names).
+
+Part of [sdvplot-js](https://github.com/sportsdataverse/sdvplot-js#readme) · [Documentation](https://plot.sportsdataverse.org) · [API reference](https://plot.sportsdataverse.org/api/sdvtables/) ·
+[Gallery](https://plot.sportsdataverse.org/gallery/sdvtables/) · [Notebooks](https://plot.sportsdataverse.org/notebooks/) · [Source](https://github.com/sportsdataverse/sdvplot-js/tree/main/packages/sdvtables)
+
+## **Installation**
+
+```sh
+npm install @sportsdataverse/sdvtables @sportsdataverse/sdvplot
+# or
+pnpm add @sportsdataverse/sdvtables @sportsdataverse/sdvplot
+# or
+yarn add @sportsdataverse/sdvtables @sportsdataverse/sdvplot
+```
+
+ESM only, Node >= 20.18.1. `@sportsdataverse/sdvplot` is a required peer (npm 7+ and pnpm install it for you).
+
+## **Quick start**
+
+```ts
+import { defineTable } from "@sportsdataverse/sdvtables";
+import { prepare, renderHTML, toElement } from "@sportsdataverse/sdvtables/html";
+
+const spec = defineTable<{ team: string; wins: number }>()
+  .columns((c) => [c.logo("team", { league: "nfl", includeName: true }), c.int("wins")])
+  .theme("midnight")
+  .title("AFC West")
+  .build();
+const rows = [
+  { team: "KC", wins: 15 },
+  { team: "LAC", wins: 11 },
+  { team: "DEN", wins: 10 },
+  { team: "LV", wins: 4 },
+]; // the 2024 AFC West
+
+await prepare(spec); // loads leagues, team names and gsis ids the spec needs
+const html = renderHTML(spec, rows); // string (Node, SSR, notebooks)
+document.body.append(toElement(spec, rows)); // browser; Observable: html`${renderHTML(spec, rows)}`
+```
+
+`prepare(spec)` must be awaited before `renderHTML`. `renderHTMLAsync` does both.
+
+## **Hosts and CSS**
+
+Every themed value is a `--sdvt-*` custom property on the table wrapper, and each element carries at most one
+`style` attribute. By default `renderHTML` inlines a scoped `<style>` block. A page that renders many tables should
+emit the stylesheet once per theme and render the tables with `css: "none"`:
+
+```ts
+import { renderHTML, styleSheet, themeKey } from "@sportsdataverse/sdvtables/html";
+const seen = new Set<string>();
+const parts = specs.map((spec) => {
+  const key = themeKey(spec.theme);
+  const sheet = seen.has(key) ? "" : `<style>${styleSheet(spec)}</style>`; // once per themeKey
+  seen.add(key);
+  return sheet + renderHTML(spec, rows, { css: "none" });
+});
+```
+
+`css: "none"` drops only the shared theme sheet. Each table still carries its own `#id`-scoped decoration `<style>`
+and the Google Fonts `<link>` for its theme and `.font()` faces; pass `fonts: false` to drop the link and load the
+fonts yourself (`fontsLink(fonts)` builds the same tag). `toElement` moves the link into `document.head`, once per URL.
+
+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.
+
+## **Themes**
+
+20 themes: the 18 gtUtils themes plus `sdv` (light/dark) and `sdvTeam`. Set one with
+`.theme(name, { density, options })`.
+
+| Theme | Options | Default density |
+|---|---|---|
+| `sdv` | `style` (`light`/`dark`) | comfortable |
+| `sdvTeam` | `league` (required), `team` | comfortable |
+| `almanac` | `accent`, `stripe` (`"none"` for no banding) | compact |
+| `broadsheet` | `accent`, `paper` | comfortable |
+| `drench` | `color` | comfortable |
+| `sofa`, `tier` | `style` | comfortable |
+| `scoreboard`, `terminal` | `accent` | compact |
+| `booktabs`, `brutalist`, `midnight`, `swiss`, `tufte` | `accent` | comfortable |
+| `athletic`, `gtutils`, `kenpom`, `ncaa`, `pl`, `savant` | none | comfortable |
+
+| Density | body | padding | title | subtitle | label | group | source |
+|---|---|---|---|---|---|---|---|
+| `comfortable` | 14 | 6 | 26 | 15 | 10 | 11 | 11 |
+| `compact` | 12 | 3 | 22 | 13 | 9 | 10 | 10 |
+| `social` | 17 | 9 | 34 | 19 | 12 | 13 | 13 |
+
+`themePreview(spec, rows, themes?, { n, density })` from `@sportsdataverse/sdvtables/html` returns
+`Record<themeName, html>` (first `n` rows, compact).
+
+## **Surface**
+
+- 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`, 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.
+- Unknown team ids warn once per call per set and render as plain text.
+
+## **Interactive**
+
+`createTable(spec, rows, options)` is the package's own headless engine (no table library): sort, per-column and
+global text filters, paging, column visibility and row selection, with immutable snapshots and `subscribe`. Every
+column sorts unless `sortable: false`, missing values sort last in both directions, and a column's `compare(a, b)`
+replaces the kind's comparator. `filterable: true` gives a column its own filter box; the search box searches every
+shown column. The page size is `options.pageSize`, else `spec.interactive.pageSize`, else one page.
+
+```ts
+import { createTable, defineTable } from "@sportsdataverse/sdvtables";
+import { hydrate, prepare, renderHTML } from "@sportsdataverse/sdvtables/html";
+
+// 2024 AFC regular season (nflverse games)
+const rows = [
+  { team: "KC", division: "West", wins: 15, losses: 2, pf: 385, pa: 326 },
+  { team: "LAC", division: "West", wins: 11, losses: 6, pf: 402, pa: 301 },
+  { team: "DEN", division: "West", wins: 10, losses: 7, pf: 425, pa: 311 },
+  { team: "LV", division: "West", wins: 4, losses: 13, pf: 309, pa: 434 },
+  { team: "BUF", division: "East", wins: 13, losses: 4, pf: 525, pa: 368 },
+  { team: "MIA", division: "East", wins: 8, losses: 9, pf: 345, pa: 364 },
+  { team: "NYJ", division: "East", wins: 5, losses: 12, pf: 338, pa: 404 },
+  { team: "NE", division: "East", wins: 4, losses: 13, pf: 289, pa: 417 },
+];
+type Row = (typeof rows)[number];
+const spec = defineTable<Row>()
+  .columns((c) => [
+    c.logo("team", { league: "nfl", includeName: true }),
+    c.text("division", { filterable: true }),
+    c.int("wins"),
+    c.int("losses"),
+    c.int("pf", { label: "PF" }),
+    c.int("pa", { label: "PA" }),
+  ])
+  .title("AFC")
+  .subtitle("2024 regular season")
+  .rowKey("team")
+  .build();
+
+await prepare(spec);
+const table = createTable(spec, rows, { pageSize: 4, sort: { col: "wins", dir: "desc" } });
+const host = document.querySelector("#standings")!;
+host.innerHTML = renderHTML(table); // the same string renders on a server or a static site
+const stop = hydrate(host.querySelector(".sdvt")!, table); // sort, filter, page and select without React
+table.setFilter("division", "east"); // BUF, MIA, NYJ, NE; back to the first page
+```
+
+`renderHTML(table)` draws sort buttons in the headers (`aria-sort` on the sorted one), a search box and the filter
+boxes above the table, and a pager below it. `hydrate(el, table)` attaches delegated listeners and re-renders only the
+table block and the pager, once, on the next animation frame, however many changes land in it; it returns a teardown.
+A click, pointer move or key that arrives while a change to the rows (a sort, filter, page turn or `setRows`) waits for
+that frame draws it first, so the event never acts on an old row at a new row's index; Enter or Space on a row that
+draw replaced is consumed, so the page does not scroll. A change that keeps the rows (a selection, or a live feed
+re-sending a keyed row as a new object) waits for its frame. Render the markup from the same table state you hydrate:
+attaching does not reconcile the two. Hydrating an element again draws any change its previous binding still owed. A
+teardown drops a render still owed; hydrating that element again redraws it first, so React StrictMode's mount,
+cleanup, mount leaves no stale rows.
+
+Inside an interactive table: j/k (↓/↑) move between the rows of the page and never turn it (the pager does), h/l
+(←/→) pick a column, s sorts it, / jumps to the search box, Enter or Space toggles the row's selection;
+`interactive: { hotkeys: false }` on the spec keeps only the arrows, Enter and Space. The table is a `role="grid"`
+whose rows share one tab stop, the current row; the current column's header carries
+`aria-current="true"` and a selected row `aria-selected="true"`. Keys pressed with Ctrl, Meta or Alt, during IME
+composition, or in a text field are left alone. Clicking a row toggles its selection too.
+
+In an interactive table, colour scales, legends, outlier limits and row-accent palettes are computed from all of the
+table's rows, not the page on screen, so a value keeps its colour while the user pages, filters or sorts. Row
+selectors by index (`.boldRows([0])`) count in the rows passed to `createTable`. `snake` layouts are static only: an
+interactive render of a `.snake()` spec throws `TableSpecError`.
+
+Linking a table to a figure: with `.rowKey("team")`, a row's id is `String(row.team)` (without one, its index in the
+input rows). `setSelection(ids)` / `getSelection()`, `setExternalFilter((row) => …)` (ANDed with the table's own
+filters) and `setHover(id)` drive the table from outside, and `subscribe` reports `select`, `hover` and `change`
+events. Setting the same selection or filter again notifies nobody, so a two-way link does not loop.
+`@sportsdataverse/sdvplot/interact`'s `linkSelection` does this wiring against a selection store.
+
+Every interactive table, linked or not, underlines the row under the pointer, or the row a linked figure hovers
+(`setHover`): the row gets the `sdvt-hover` class, which re-renders nothing and survives the next re-render. A table
+holds one hover id, so a linked table lights the first id the figure hovers. `getHover()` returns it, so a view
+attached later (a remount, a second hydrate) shows it. Unmounting while the pointer is on a row leaves that hover in
+place, because a removed row fires no `mouseleave`. reactable's `highlight` defaults to `FALSE`; to drop the underline,
+add `tr.sdvt-hover>td.sdvt-cell{background-image:none}` to the page. The built-in rule is wrapped in `:where()`, so
+this one plain rule wins wherever the page puts it. A selection or brush from a linked figure
+rebuilds the table body, so a scroll position inside a cell resets.
+
+Engine non-goals: virtualization, column resize/reorder/pin, a grouping UI and server-side paging (slice the rows
+before `createTable`).
+
+### React
+
+```tsx
+import { fontsLinkFor } from "@sportsdataverse/sdvtables/html";
+import { SdvTable, useTable } from "@sportsdataverse/sdvtables/react"; // peer: react >= 18
+
+// spec and rows from above; await prepare(spec) before the first render, server included
+<SdvTable spec={spec} rows={rows} interactive pageSize={4} />; // SSR markup === renderHTML(table, { fonts: false })
+
+function Standings() {
+  const { table, snapshot } = useTable(spec, rows, { pageSize: 4 });
+  return (
+    <>
+      <p>{snapshot.filteredCount} teams</p>
+      <SdvTable table={table} interactive />
+    </>
+  );
+}
+```
+
+`<SdvTable/>` writes no fonts `<link>`: put the tag `fontsLinkFor(spec)` returns in the page `<head>`. `pageSize` and
+`sort` are initial state, like React's `default*` props. A new `rows` array, even an equal copy, keeps the user's
+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
+`gt_save_crop`, `gt_social_crop`, `gt_save_batch`, `gt_grid` and `gt_stack_tables`, with the Python package's
+defaults. Install the optional peer and its browser once:
+
+```sh
+pnpm add -D playwright
+pnpm exec playwright install chromium
+```
+
+Without `playwright` the functions throw `OptionalDependencyError` (from `@sportsdataverse/sdvplot`), and a missing
+browser says to run `playwright install chromium`. Arguments are checked before any browser starts.
+
+```ts
+import { batchToPNG, gridTables, htmlToPNG, socialCrop, stackTables, tableToPNG } from "@sportsdataverse/sdvtables/export";
+
+// spec and rows from the Interactive example; await prepare(spec) first
+await tableToPNG(spec, rows, { file: "afc.png" }); // gt_save_crop
+await socialCrop(spec, rows, { aspect: "4:5", file: "afc-post.png" }); // gt_social_crop
+const west = { spec, rows: rows.filter((r) => r.division === "West") };
+const east = { spec, rows: rows.filter((r) => r.division === "East") };
+await htmlToPNG(gridTables([west, east], { ncol: 2, title: "AFC by division" }), { file: "grid.png" }); // gt_grid
+await htmlToPNG(stackTables([west, east], { title: "AFC by division" }), { file: "stack.png" }); // gt_stack_tables
+await batchToPNG(rows, "division", (groupRows) => ({ spec, rows: groupRows }), "afc-{group}.png", { dir: "out" });
+// gt_save_batch: out/afc-west.png and out/afc-east.png
+```
+
+- `tableToPNG`, `socialCrop` and `htmlToPNG` return the PNG bytes and also write `file` when given (it must end in
+  `.png`); `batchToPNG` returns the paths it wrote.
+- An image past Chromium's canvas limit (65,535 px a side, 268,435,456 px in all: near 1,000 plain rows at the
+  default zoom) throws `SdvplotError` naming its size, and nothing is written. Put fewer rows in each image
+  (`rows.slice()` a page at a time, `batchToPNG` by a group column, `gridTables` side by side) or lower
+  `deviceScaleFactor`.
+- Options (`PNGOptions`; `SocialCropOptions` and `BatchOptions` build on it) are in image pixels, as in Python:
+  `deviceScaleFactor` (the zoom, default 2), `whitespace` (the margin left around the trimmed content, default 50, or
+  60 for `socialCrop`), `background` (default white), `width` (the final image width; absent, the rendered width) and
+  `fontLinks` (extra stylesheets to wait for).
+- `socialCrop` puts the table on an `aspect` canvas (`"1:1"` by default, `"16:9"`, `"4:5"`, `"9:16"`, `"1.91:1"` or
+  a number), placed by `gravity` (one of the nine ImageMagick names, `"center"` by default); the table is never cropped.
+- `batchToPNG` writes one image per value of the group column, with `{group}` replaced by `slug(value)`, all widened
+  to the widest (`matchWidth: false` keeps each width). A group whose table fails to build is skipped and named in one
+  warning, as in Python.
+- `gridTables` and `stackTables` return HTML: the tables with a page title, subtitle, caption and source note around
+  them, styled with the Python defaults. A spec used twice gets distinct ids, so each copy keeps its decorations.
+- For an SVG figure, use `toPNG` and `socialCard` from `@sportsdataverse/sdvplot/export` instead (no browser).
+
+## **gtUtils / sdvplotR names**
+
+All 74 sdvplotR `gt_*` / `pal_*` / `reactable_sdv_*` exports map as below (`GT_ALIASES` and `aliasFor(name)` expose
+the same table in code). Builder methods are on `defineTable()`, `c.*` inside `.columns(c => [...])`.
+
+| sdvplotR / gtUtils | sdvtables | status |
+|---|---|---|
+| `gt_sdv_logos` | `c.logo(key, {league, includeName, season, variant, height})` | ported |
+| `gt_sdv_wordmarks` | `c.wordmark(key, {league, season, variant, height})` | ported |
+| `gt_sdv_headshots` | `c.headshot(key, {league, idSystem, height})` | ported |
+| `gt_sdv_cols_label` | image labels are not ported; use `.titleHeader()` or `subheader` | not ported (labels are text) |
+| `gt_merge_stack_team_color` | `c.mergeStackTeamColor(top, stack, team, {league, fontSizeTop, fontSizeBottom, color, background})` | ported |
+| `gt_theme_sdv` / `gt_theme_sdv_team` | `.theme("sdv", {options:{style}})` / `.theme("sdvTeam", {options:{league, team}})` | ported |
+| `gt_theme_<name>` (18) | `.theme("<name>", {density, options:{accent\|stripe\|paper\|color\|style}})` | ported |
+| `gt_theme_preview` | `themePreview(spec, rows, themes?, {n, density})` from `/html` | ported (dict of HTML, not a grid) |
+| `pal_midnight` | `PAL_MIDNIGHT` (`["#5B8DEF","#3FBF87","#E8E9ED","#9498A3","#24272E"]`) | ported |
+| `gt_538_caption` | `.caption538({top, bottom, ruleColor, ruleWidth, size, align})` | ported |
+| `gt_bold_rows` | `.boldRows(rows, {textColor, highlightColor})` | ported |
+| `gt_border_bars_top/bottom` | `.borderBars("top"\|"bottom", colors, {...})` | ported (bars outside the `<table>`) |
+| `gt_border_grid` | `.borderGrid({color, weight, includeLabels})` | ported |
+| `gt_color_pills` | `c.colorPills(key, {...})` | ported (sRGB ramp, as great_tables) |
+| `gt_color_ranks` | `c.colorRanks(key, {palette, domain, reverse})` | ported |
+| `gt_color_results` | `c.colorResults(key, {...})`: a column kind that fills its row by W/L/T | ported |
+| `gt_column_subheaders` | the `subheader` option of every `c.*` kind | ported |
+| `gt_cutline` | `.cutline(after, {label, color, weight, style, labelColor, labelSize, labelPosition, gap})` | ported |
+| `gt_delta` | `c.delta(from, to, {...})` | ported |
+| `gt_fmt_rank` / `gt_fmt_tally` | `c.rank` / `c.tally` (also `c.fmtRank` / `c.fmtTally`) | ported |
+| `gt_group_stripes` | `.groupBy(key).groupStripes({color, start})` | ported |
+| `gt_highlight_cells` | `c.highlight(key, predicate, {fill, textColor, bold})` | ported (data predicate, not a formula) |
+| `gt_highlight_na` | `c.highlightNa(key, {...})` | ported |
+| `gt_indicator_boxes` | `c.indicatorBox(key, {truthy, fill, neutral, size, showOnly})` | ported (value list, not a rule) |
+| `gt_legend_continuous` / `gt_legend_discrete` (deprecated gtUtils names `gt_color_legend` / `gt_centered_legend`) | `.legendContinuous({...})` / `.legendDiscrete(key\|"recorded", {...})` | ported |
+| `gt_marginalia` | `.marginalia(columns, {...})` | ported |
+| `gt_outliers` | `.outliers(columns, {method, threshold, bounds, side, fill, color, bold, symbol, note})` | ported |
+| `gt_percentile_bar` | `c.percentileBar(key, {...})` | ported |
+| `gt_row_accent` | `.rowAccent(key, {palette, rows, width, side, hide, naColor})` | ported |
+| `gt_scale_note` | `.scaleNote(columns, {divisor, note, where, labelSuffix, decimals})` | ported |
+| `gt_set_font` | `.font(family, {google, weight, style})` | ported |
+| `gt_significance` | `.significance(pairs, {levels, symbols, superscript, note})` | ported |
+| `gt_snake` / `gt_snake_align` | `.snake({nCols, rowsPerCol, gap, fill, cleanGaps})` / `snakeAlign(rows, opts)` | ported |
+| `gt_social_tag` | `.socialTag(accounts, {...})` | ported (inline Font Awesome 6 SVG) |
+| `gt_spotlight` | `.spotlight(rows, {...})` | ported |
+| `gt_tiers` | `.tiers(levels, tierKey, imageColumns, {colors, imgHeight, style})` | ported |
+| `gt_title_header` | `.titleHeader(title, {subtitle, kicker, date, *Style})` | ported |
+| `gt_watermark` | `.watermark({text, image, opacity, size, position, color, angle, font})` | ported |
+| `gt_wrap_labels` | `.wrapLabels({columns, width, balance})` | ported |
+| `gt_save_crop` / `gt_save_batch` | `tableToPNG` / `batchToPNG` (`/export`) | ported |
+| `gt_social_crop` | `socialCrop` (`/export`) | ported |
+| `gt_grid` / `gt_stack_tables` | `gridTables` / `stackTables` (`/export`) | ported |
+| `reactable_sdv_logos/wordmarks/headshots` | `c.logo` / `c.wordmark` / `c.headshot` | ported |
+| `reactable_sdv_cols_label` | as `gt_sdv_cols_label` | not ported |
+| `reactable_sdv_team_color_bar` / `_bg` | `c.teamColorBar(key, {league, which, naColor, barWidth})` / `c.teamColorBg(key, {league, which, alpha, naColor})` | ported |
+
+## **Known differences from Python and R**
+
+- Indicator boxes take a value list and carry no text; legends draw discrete steps, not a gradient bar.
+- Tier images have an empty `alt`. `tally`'s column-mode share is not ported.
+- `snake` keeps the first block's row styles for every block.
+- A decoration's row fill always beats a kind's own cell background (Python's outcome depends on call order).
+- `socialTag` accepts a fixed alias set (`x`/`twitter`, `ig`, `bsky`, `gh`, `yt`, `fb`, `web`/`website`/`link`,
+  `email`/`mail`), not every Font Awesome name; `tiktok`, `threads` and `substack` are unavailable, as in faicons.
+- `kicker` always renders uppercase; `cutline` y positions round half-up.
+- `wrapLabels` keeps internal whitespace of a label as given.
+
+## **Visual pass (contributors)**
+
+The unit snapshots pin each theme's CSS text, not what it draws. The visual pass renders every registered theme's
+`themePreview` of a 2024 AFC standings table (title, subtitle, division groups, source note) through the `tableToPNG`
+path, one PNG per theme:
+
+```sh
+pnpm --filter @sportsdataverse/sdvtables exec playwright install chromium # once
+pnpm --filter @sportsdataverse/sdvtables render:themes # writes packages/sdvtables/theme-pass/<theme>.png
+SDV_RENDER_TESTS=1 pnpm --filter @sportsdataverse/sdvtables test # the unit tests plus the chromium export tests
+```
+
+Open the PNGs after changing a theme or the base sheet: this pass caught tufte and booktabs running the title and the
+subtitle together on one line. `theme-pass/` is gitignored; `SDV_THEME_PASS_DIR=<dir>` writes elsewhere. An always-on
+test fails if a registered theme is missing from the pass. In CI the `render-tests` job runs the same pass, lists the
+PNGs and any failed theme in the job summary, and uploads them as the `sdvtables-theme-pass` artifact; a failing theme
+never fails the build.
+
+## **Documentation**
+
+The [**sdvplot-js** documentation website](https://plot.sportsdataverse.org) has the
+[sdvtables gallery](https://plot.sportsdataverse.org/gallery/sdvtables/), the [notebooks](https://plot.sportsdataverse.org/notebooks/) and the
+[sdvtables API reference](https://plot.sportsdataverse.org/api/sdvtables/), one page per subpath, plus:
+
+**Guides:**
+[Tables: the spec](https://plot.sportsdataverse.org/guides/tables) ·
+[Table themes](https://plot.sportsdataverse.org/guides/table-themes) ·
+[Cell kinds](https://plot.sportsdataverse.org/guides/cell-kinds) ·
+[Decorations](https://plot.sportsdataverse.org/guides/decorations) ·
+[HTML, SSR and the host page](https://plot.sportsdataverse.org/guides/tables-html) ·
+[Export to PNG](https://plot.sportsdataverse.org/guides/export) ·
+[Node and SSR](https://plot.sportsdataverse.org/guides/node-ssr)
+
+**Examples:**
+[Linked figures and tables](https://plot.sportsdataverse.org/examples/linked) ·
+[From sdvplot (Python) and sdvplotR](https://plot.sportsdataverse.org/guides/migrating)
+
+The [repository README](https://github.com/sportsdataverse/sdvplot-js#readme) covers all three packages and development.
+
+## **Logos, trademarks and data**
+
+Team names, logos, wordmarks and player headshots are trademarks or copyrighted works of their respective leagues,
+teams, schools and other rights holders. `@sportsdataverse/sdvtables` is not affiliated with, sponsored by or endorsed
+by any of them, and using it to draw a mark grants no right to use it. The package ships no logo or headshot files:
+it draws them through `@sportsdataverse/sdvplot`, which carries only an index of team names, ids and colors, and
+the marks are fetched at runtime from the [SportsDataverse logo archive](https://github.com/sportsdataverse/sdv-assets),
+headshots from ESPN (or, for NFL gsis ids, the headshot URLs in nflverse's player table). Use of any mark in your own
+work is governed by that owner's terms, and following them is your responsibility.
+
+Logos, headshots and team colors come from `@sportsdataverse/sdvplot`; the package makes no network requests of
+its own beyond the optional Google Fonts `<link>` (`fonts: false` omits it). Social icons are Font Awesome Free 6
+paths ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), https://fontawesome.com). The table helpers port
+sdvplot's `great_tables` helpers (Python, MIT) and sdvplotR's `gt_*` functions (MIT).
+
+The [MIT license](https://github.com/sportsdataverse/sdvplot-js/blob/main/LICENSE) covers the code; team data belongs to its respective owners and sources.
+[NOTICE.md](https://github.com/sportsdataverse/sdvplot-js/blob/main/packages/sdvtables/NOTICE.md) records the sdvplot/sdvplotR and Font Awesome material and its licences.
+
+## **The SportsDataverse**
+
+`@sportsdataverse/sdvtables` is one of the three [sdvplot-js](https://github.com/sportsdataverse/sdvplot-js#readme) packages, with [`@sportsdataverse/sdvplot`](https://github.com/sportsdataverse/sdvplot-js/tree/main/packages/sdvplot#readme) and [`@sportsdataverse/sporty`](https://github.com/sportsdataverse/sdvplot-js/tree/main/packages/sporty#readme).
+
+| Package | Sport / Scope |
+| --- | --- |
+| [**sdvplot**](https://sdvplot.sportsdataverse.org/) | The Python package sdvplot-js ports |
+| [**sdvplotR**](https://sdvplotR.sportsdataverse.org/) | The R package sdvplot mirrors |
+| [**sportyR**](https://github.com/sportsdataverse/sportyR) · [**sportypy**](https://sportypy.sportsdataverse.org/) | Playing-surface plots for R and Python, which `@sportsdataverse/sporty` ports |
+| [**sportsdataverse.js**](https://js.sportsdataverse.org/) | SportsDataverse data for Node.js and TypeScript |
+| [**sportsdataverse-py**](https://py.sportsdataverse.org/) | SportsDataverse data for Python: NFL, CFB, NBA, WNBA, MBB, WBB, MLB, NHL, PWHL, soccer and more |
+| [**sportsdataverse-R**](https://r.sportsdataverse.org/) | The R packages: hoopR, wehoop, cfbfastR, fastRhockey, baseballr and more |
+
+See the full ecosystem at [sportsdataverse.org](https://sportsdataverse.org/).
+
+## **Follow the [SportsDataverse](https://x.com/SportsDataverse) on X and star this repo**
+
+[![Twitter Follow](https://img.shields.io/twitter/follow/SportsDataverse?color=blue&label=%40SportsDataverse&logo=x&style=for-the-badge)](https://x.com/SportsDataverse)
+[![GitHub stars](https://img.shields.io/github/stars/sportsdataverse/sdvplot-js.svg?color=eee&logo=github&style=for-the-badge&label=Star%20sdvplot-js&maxAge=2592000)](https://github.com/sportsdataverse/sdvplot-js/stargazers)
+
+## **Our Authors**
+
+- [Saiem Gilani](https://x.com/saiemgilani)
+  <a href="https://x.com/saiemgilani" target="blank"><img src="https://img.shields.io/twitter/follow/saiemgilani?color=blue&label=%40saiemgilani&logo=x&style=for-the-badge" alt="@saiemgilani" /></a>
+  <a href="https://github.com/saiemgilani" target="blank"><img src="https://img.shields.io/github/followers/saiemgilani?color=eee&logo=Github&style=for-the-badge" alt="@saiemgilani" /></a>
+
+## **Citations**
+
+To cite [**`@sportsdataverse/sdvtables`**](https://plot.sportsdataverse.org) in publications, cite sdvplot-js:
+
+BibTeX Citation
+
+```bibtex
+@misc{gilani_2026_sdvplot_js,
+  author = {Gilani, Saiem},
+  title = {sdvplot-js: Team identity, colors, logos, surfaces and tables for JavaScript and TypeScript plots},
+  url = {https://plot.sportsdataverse.org},
+  year = {2026}
+}
+```
+
+## **License**
+
+MIT. See [NOTICE.md](https://github.com/sportsdataverse/sdvplot-js/blob/main/packages/sdvtables/NOTICE.md) for the sdvplot/sdvplotR and Font Awesome material.