@varialkit/table 0.1.1

package/docs.md

@@ -0,0 +1,617 @@
+# Table
+
+`Table` is Solara's presentation wrapper around TanStack Table.
+
+- TanStack owns data modeling and feature logic.
+- Solara owns list/grid rendering, menu UX, and style tokens.
+
+The goal is a stable Solara API that can express both classic table views and card-grid views without forking data logic.
+- We want a Solara-first API for visuals, sizing, and behaviors that stays consistent across apps.
+- We still want TanStack's core logic (sorting, filtering, pinning, virtual-friendly row models) for performance and
+  correctness.
+- We need an escape hatch so we can layer custom behavior now and incrementally replace TanStack pieces later if needed.
+
+**Long-term strategy:**
+
+- TanStack stays as the default engine for table state and row models.
+- Solara owns rendering, styling, and extension points.
+- We expose hooks (`renderBody`, `renderRow`, `renderCell`, `tableOptions`) so we can add custom logic without API churn.
+- If we ever replace TanStack, we keep the same Solara API surface and swap the engine behind it.
+
+## Architecture Notes
+
+- `Table` is intentionally thin: it composes TanStack row models and renders standard HTML tables.
+- Custom behavior should sit in `tableOptions` (state + features) or in render overrides.
+- Header actions are rendered as a dedicated `<th>` so they remain aligned with header rows and stay in the tab order.
+- The built-in column manager uses TanStack column visibility + column order state under the hood.
+
+## Quick Start
+
+```tsx
+import { Table } from "@solara/table";
+import { createColumnHelper } from "@tanstack/react-table";
+
+type Person = {
+  avatar: string;
+  name: string;
+  role: string;
+  status: string;
+  lastActive: string;
+};
+
+const helper = createColumnHelper<Person>();
+
+const columns = [
+  helper.accessor("name", { header: "Name" }),
+  helper.accessor("role", { header: "Role" }),
+  helper.accessor("status", { header: "Status" }),
+  helper.accessor("lastActive", { header: "Last Active" }),
+];
+
+<Table data={data} columns={columns} enableSorting enableColumnControls />;
+```
+
+## Basic Usage
+
+The default usage pattern is still a list table powered by TanStack models.
+
+```tsx
+export function Example() {
+  return <Table data={data} columns={columns} enableSorting />;
+}
+```
+
+## Example Index
+
+All examples live in [examples.tsx](/Users/craigaucutt/repo/solara/packages/core/components/table/examples.tsx).
+
+- `Playground`: base props, density, list/grid switching
+- `Grid Default`: image-first grid with hidden-by-default detail fields
+- `Grid Masonry`: same card model with masonry flow + granular spacing
+- `List Only Layout`: list surfaces that intentionally do not expose grid mode
+- `Overview`: standard list with built-in controls
+- `Sticky Header`: sticky list header behavior
+- `Pinned Columns`: TanStack pinning + sticky/pinning styles
+- `Pagination`: TanStack pagination state wiring
+- `Pagination Controls`: built-in Solara pagination footer (`showPagination`)
+- `Virtualized Rows`: list virtualization via `renderBody`
+- `Expandable Rows`: TanStack expanding rows
+- `Selectable Rows`: TanStack selection rows
+- `Large Data Performance`: loading + pagination guardrails
+
+## Architecture
+
+Think in 3 layers:
+
+1. Data layer (TanStack)
+2. Mode layer (`layoutMode`)
+3. Presentation layer (Solara)
+
+### 1) Data Layer
+
+Inputs:
+
+- `data`
+- `columns`
+- `tableOptions`
+
+TanStack owns:
+
+- row model (`table.getRowModel().rows`)
+- sorting/filtering/pagination
+- base column visibility and ordering
+- pinning state
+
+### 2) Mode Layer
+
+`layoutMode` controls presentation only:
+
+- `list` (default): semantic `<table>`
+- `grid`: card layout
+
+Both modes read from the same TanStack rows/cells.
+If you want list-only surfaces, pass `layoutModeOptions={["list"]}`.
+
+### 3) Presentation Layer
+
+Solara adds:
+
+- built-in action menu
+- optional action menu surface override (`actionMenuSurfaceStyle`)
+- density styling
+- list markup + sticky/pinned split behavior
+- grid media/detail composition
+- render overrides
+
+## List Mode Details
+
+List mode is the canonical table behavior and stays TanStack-first.
+
+### What list mode supports
+
+- semantic table markup for accessibility (`table`, `thead`, `tbody`, `tr`, `th`, `td`)
+- sortable headers when `enableSorting` is true
+- sticky headers (`stickyHeader`)
+- pinned columns (via TanStack + `getHeaderProps` / `getCellProps`)
+- custom list rendering via `renderBody`, `renderRow`, `renderCell`
+
+### Pinned columns: state wiring + style wiring
+
+Pinning is managed by TanStack state; visual stickiness is applied through header/cell prop resolvers.
+
+```tsx
+const [columnPinning, setColumnPinning] = useState({
+  left: ["name"],
+  right: [],
+});
+
+<Table
+  data={data}
+  columns={columns}
+  tableOptions={{
+    enableColumnPinning: true,
+    state: { columnPinning },
+    onColumnPinningChange: setColumnPinning,
+  }}
+  getHeaderProps={(header) =>
+    header.column.getIsPinned()
+      ? {
+          style: { left: header.column.getStart("left") },
+          className: "solara-table__header-cell--pinned",
+        }
+      : {}
+  }
+  getCellProps={(cell) =>
+    cell.column.getIsPinned()
+      ? {
+          style: { left: cell.column.getStart("left") },
+          className: "solara-table__cell--pinned",
+        }
+      : {}
+  }
+/>
+```
+
+### Sticky + pinned behavior
+
+- `transparentSticky` + sticky/pinning can trigger split panes to prevent visual underlap.
+- Center pane owns horizontal scroll; pinned panes mirror vertical scroll.
+- Custom `renderBody` is list-focused and best used when pinned split behavior is not active.
+
+If you want to validate vertical scrolling with pinned columns, constrain wrapper height:
+
+```tsx
+<Table
+  data={[...data, ...data, ...data, ...data]}
+  columns={columns}
+  stickyHeader
+  transparentSticky
+  wrapperProps={{ style: { maxHeight: 220, overflow: "auto" } }}
+  tableOptions={{
+    enableColumnPinning: true,
+    state: { columnPinning },
+    onColumnPinningChange: setColumnPinning,
+  }}
+/>
+```
+
+## Grid Mode Details
+
+Grid mode is a card presentation on top of TanStack rows.
+
+### Grid availability
+
+Grid can be enabled per surface instead of globally:
+
+- `layoutModeOptions={["list", "grid"]}` keeps both modes available.
+- `layoutModeOptions={["list"]}` makes the surface list-only.
+- The built-in `View` section only appears when `enableLayoutToggle` is true and more than one view is available.
+
+Why this matters:
+
+- Some surfaces are operational/dense by design and should remain list-only for consistency.
+- Other surfaces benefit from browse-first card exploration, so offering both `list` and `grid` improves workflow.
+- Keeping availability at the table-instance level avoids one-size-fits-all behavior across the app.
+
+### Cell content fallback order
+
+1. `gridCellRenderers[column.id]`
+2. `renderGridCell(cell, row, table)`
+3. `renderCell(cell)`
+4. TanStack `columnDef.cell`
+
+This keeps list and grid content aligned by default.
+
+### Grid structure controls
+
+Use `gridColumnConfig` by column id:
+
+- `variant: "detail" | "media"`
+- `hiddenByDefault`
+- `showLabel`
+- `unpadded`
+- `className`
+
+`media` cells render in a dedicated top section (good for images/video hero blocks).
+`detail` cells render in the labeled details section.
+
+### Grid visibility overlay (important)
+
+Grid has its own visibility layer:
+
+- controlled with `gridVisibleColumnIds` / `onGridVisibleColumnIdsChange`
+- seeded by `gridColumnConfig.hiddenByDefault` in uncontrolled mode
+
+Rules:
+
+- TanStack-hidden columns are always hidden in both layouts.
+- Grid overlay only applies to TanStack-visible columns.
+- This allows different defaults in grid without mutating list visibility.
+
+### Grid type and spacing
+
+Use `gridType` for card flow behavior:
+
+- `grid` (default): auto-fit CSS grid
+- `masonry`: masonry-style column flow
+
+When `enableColumnControls` is enabled, users can switch these in the action menu (`View` section).
+
+How to choose:
+
+- Use `grid` when alignment and scanability matter most (consistent rows/tracks).
+- Use `masonry` when media varies in height and you want tighter visual packing.
+- Keep `gridMinColumnWidth` stable across both so only flow behavior changes, not card target size.
+
+Use `gridSpacing` for granular spacing overrides:
+
+- `gap`: fallback for row/column gap
+- `columnGap`: horizontal card spacing
+- `rowGap`: vertical card spacing
+- `detailsGap`: gap between detail fields inside each card
+- `detailsPadding`: details section padding inside each card
+
+Practical layering strategy:
+
+- Start with `density` for broad rhythm changes shared across list + grid.
+- Add `gridSpacing` only when one surface needs finer card/detail tuning.
+- Prefer setting `columnGap` + `rowGap` explicitly when switching to masonry so vertical rhythm stays intentional.
+- `gridSpacing` values override density-driven spacing tokens for the fields you set (`gap`, `columnGap`, `rowGap`, `detailsGap`, `detailsPadding`).
+  If density appears to do nothing in grid/masonry spacing, check for explicit `gridSpacing` overrides first.
+
+```tsx
+<Table
+  data={data}
+  columns={columns}
+  layoutMode="grid"
+  gridType="masonry"
+  gridSpacing={{
+    columnGap: "1rem",
+    rowGap: "1.25rem",
+    detailsGap: "0.625rem",
+    detailsPadding: "0.875rem",
+  }}
+/>
+```
+
+## Built-in Action Menu
+
+Menu sections:
+
+- `Columns` (if `enableColumnControls`)
+- `Density`
+- `View` (if `enableLayoutToggle` and more than one view is available)
+
+Behavior notes:
+
+- `Columns` remains layout-aware (TanStack visibility in list, grid overlay visibility in grid).
+- `View` combines layout + grid-type switching into one control (`List`, `Standard grid`, `Masonry grid`).
+- `View` uses the same controlled/uncontrolled pattern as `Density` and coordinates `layoutMode` + `gridType` when selecting grid variants.
+
+`Columns` is layout-aware:
+
+- list: toggles TanStack visibility
+- grid: toggles grid visibility overlay
+
+There is intentionally one shared column section (no duplicate grid section).
+
+## Header Actions (Action Column)
+
+`headerActions` renders in a dedicated right-aligned header action cell. Use it for table-level controls such as:
+
+- custom view/filter menus
+- export actions
+- bulk action triggers
+- saved view pickers
+
+```tsx
+<Table data={data} columns={columns} headerActions={<MyControl />} />
+```
+
+If both `headerActions` and `enableColumnControls` are set, they are stacked in the same action area.
+
+## Custom Menu Patterns
+
+You can fully replace built-in controls with your own menu surface:
+
+```tsx
+<Table data={data} columns={columns} headerActions={<MyCustomMenu />} />
+```
+
+Or combine custom actions with built-in controls:
+
+```tsx
+<Table
+  data={data}
+  columns={columns}
+  enableColumnControls
+  headerActions={<MyCustomMenu />}
+/>
+```
+
+This is the recommended approach when you need richer workflows (saved views, advanced filters, export presets) while
+still keeping quick built-in toggles.
+
+## Custom Rendering
+
+`renderCell`, `renderRow`, and `renderBody` let you customize rendering while preserving TanStack's data/state model.
+This is the main path for advanced list rendering, grouped layouts, and virtualization integration.
+
+```tsx
+<Table
+  data={data}
+  columns={columns}
+  renderRow={(row, cells) => (
+    <tr key={row.id} className={row.index % 2 === 0 ? "even" : "odd"}>
+      {cells}
+    </tr>
+  )}
+/>
+```
+
+Hook guidance:
+
+- `renderCell`: custom content per cell, keeps default row/table structure
+- `renderRow`: custom `<tr>` composition with provided cell nodes
+- `renderBody`: full `<tbody>` control (best for virtualization/windowing)
+
+## Density Behavior
+
+`density` is shared across list and grid.
+
+- `compact`
+- `standard`
+- `spacious`
+
+List impact:
+
+- row/cell padding
+- list typography scale
+
+Grid impact:
+
+- card-to-card spacing
+- detail section gap/padding
+- media minimum height
+- card value typography
+
+This keeps spacing decisions centralized and consistent when switching layouts.
+
+### Density usage notes
+
+- `density` is a presentation control, not a data/state control.
+- In list mode, it changes table rhythm (row/cell density).
+- In grid mode, it changes card rhythm (gap/padding/media height + typography).
+- If you pass `onDensityChange`, density is controlled and should come from your state.
+
+```tsx
+const [density, setDensity] = useState<TableDensity>("standard");
+
+<Table
+  data={data}
+  columns={columns}
+  density={density}
+  onDensityChange={setDensity}
+  enableColumnControls
+/>;
+```
+
+## Pagination
+
+Pagination remains TanStack-driven.
+
+### Client-side Pagination
+
+Use TanStack's pagination row model and wire the state through `tableOptions`. The UI is yours to render, so you can
+build a slim pager, a full footer, or a custom layout without changing how the table works.
+
+```tsx
+import { getPaginationRowModel } from "@tanstack/react-table";
+
+const [pagination, setPagination] = useState({
+  pageIndex: 0,
+  pageSize: 20,
+});
+
+<Table
+  data={data}
+  columns={columns}
+  tableOptions={{
+    state: { pagination },
+    onPaginationChange: setPagination,
+    getPaginationRowModel: getPaginationRowModel(),
+  }}
+/>;
+```
+
+### Built-in footer
+
+Use `showPagination` to render Solara pagination controls.
+
+```tsx
+<Table
+  data={data}
+  columns={columns}
+  showPagination
+  tableOptions={{
+    state: { pagination },
+    onPaginationChange: setPagination,
+    getPaginationRowModel: getPaginationRowModel(),
+  }}
+/>
+```
+
+### Server-side pagination
+
+Use TanStack manual pagination in `tableOptions`.
+
+```tsx
+<Table
+  data={rows}
+  columns={columns}
+  tableOptions={{
+    manualPagination: true,
+    pageCount,
+    state: { pagination },
+    onPaginationChange: setPagination,
+  }}
+/>
+```
+
+### Custom footer pattern (state-driven with `Table`)
+
+If you want your own footer UI, keep pagination controlled in `tableOptions` and render your own controls from the same state.
+
+```tsx
+function PaginationFooter({
+  pagination,
+  pageCount,
+  onPrevious,
+  onNext,
+}: {
+  pagination: { pageIndex: number };
+  pageCount: number;
+  onPrevious: () => void;
+  onNext: () => void;
+}) {
+  return (
+    <div className="table-footer">
+      <button onClick={onPrevious} disabled={pagination.pageIndex === 0}>
+        Prev
+      </button>
+      <span>
+        Page {pagination.pageIndex + 1} of {pageCount}
+      </span>
+      <button
+        onClick={onNext}
+        disabled={pageCount > 0 ? pagination.pageIndex + 1 >= pageCount : false}
+      >
+        Next
+      </button>
+    </div>
+  );
+}
+```
+
+### TanStack table-instance footer pattern (reference)
+
+If you are working directly with a TanStack table instance, this is the canonical footer structure:
+
+```tsx
+import type { Table as TanStackTable } from "@tanstack/react-table";
+
+function TableFooter({ table }: { table: TanStackTable<Person> }) {
+  return (
+    <div className="table-footer">
+      <button onClick={() => table.previousPage()} disabled={!table.getCanPreviousPage()}>
+        Prev
+      </button>
+      <span>
+        Page {table.getState().pagination.pageIndex + 1} of {table.getPageCount()}
+      </span>
+      <button onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>
+        Next
+      </button>
+    </div>
+  );
+}
+```
+
+## Virtualization
+
+Current recommended path is list virtualization with `renderBody`.
+See `Virtualized Rows` example in [examples.tsx](/Users/craigaucutt/repo/solara/packages/core/components/table/examples.tsx).
+
+Guidelines:
+
+- Virtualize `rows` from TanStack's current row model.
+- Keep sticky/scroll container logic explicit via `wrapperProps`.
+- Use stable row heights when possible.
+- Keep spacer rows above/below visible slice for correct scroll height.
+
+Grid virtualization is possible with custom `renderGridRow` composition, but the built-in virtualization example is list mode today.
+
+## Best Practices
+
+1. Put feature/state logic in TanStack (`tableOptions`) first.
+2. Use grid overlay APIs only for grid-specific presentation differences.
+3. Keep `list` as canonical tabular mode for dense workflows.
+4. Use `grid` for browse/discovery layouts and media-forward cards.
+5. Prefer `gridCellRenderers` map over one large conditional in `renderGridCell`.
+6. Use controlled props for persisted preferences (`layoutMode`, `density`, grid-visible fields).
+7. Treat pagination controls as state views; avoid duplicating competing pagination state sources.
+8. Avoid effect-driven setState loops by guarding no-op updates when syncing derived ids/visibility.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `TData[]` | — | Row data. |
+| `columns` | `ColumnDef<TData, unknown>[]` | — | TanStack columns. |
+| `tableOptions` | `Omit<TableOptions<TData>, "data" \| "columns">` | — | TanStack option passthrough. |
+| `getRowId` | `TableOptions<TData>["getRowId"]` | — | Optional TanStack row id resolver. |
+| `layoutMode` | `"list" \| "grid"` | `"list"` | Active/default layout mode. |
+| `layoutModeOptions` | `Array<"list" \| "grid">` | `['list', 'grid']` | Allowed layout modes used by the built-in `View` picker. |
+| `enableLayoutToggle` | `boolean` | `false` | Enables the built-in `View` picker menu. |
+| `onLayoutModeChange` | `(mode) => void` | — | Controlled layout callback. |
+| `gridTypeOptions` | `Array<"grid" \| "masonry">` | `['grid', 'masonry']` | Grid-type choices used by the built-in `View` picker for grid variants. |
+| `enableColumnControls` | `boolean` | `false` | Enables built-in Columns controls. |
+| `gridColumnConfig` | `Record<string, TableGridColumnConfig>` | — | Grid-only column presentation config. |
+| `gridVisibleColumnIds` | `string[]` | — | Controlled grid-visible column ids. |
+| `onGridVisibleColumnIdsChange` | `(ids) => void` | — | Controlled grid-visible callback. |
+| `density` | `"compact" \| "standard" \| "spacious"` | `"standard"` | Shared list/grid density mode. |
+| `densityOptions` | `TableDensity[]` | `['compact', 'standard', 'spacious']` | Density options in menu. |
+| `onDensityChange` | `(density) => void` | — | Controlled density callback. |
+| `renderHeaderCell` | `(header) => ReactNode` | — | List header cell override. |
+| `renderCell` | `(cell) => ReactNode` | — | Shared cell fallback override. |
+| `renderGridCell` | `(cell, row, table) => ReactNode` | — | Global grid cell override. |
+| `gridCellRenderers` | `Record<string, (cell, row, table) => ReactNode>` | — | Per-column grid renderers. |
+| `renderGridRow` | `(row, cells, table) => ReactNode` | — | Full custom grid card renderer. |
+| `renderRow` | `(row, cells) => ReactNode` | — | Custom list row renderer. |
+| `renderBody` | `(table, rows) => ReactNode` | — | Custom list body renderer. |
+| `gridType` | `"grid" \| "masonry"` | `"grid"` | Grid flow behavior when `layoutMode` is `grid`. |
+| `onGridTypeChange` | `(gridType) => void` | — | Controlled grid type callback. |
+| `gridSpacing` | `{ gap?, columnGap?, rowGap?, detailsGap?, detailsPadding? }` | — | Granular grid spacing overrides. |
+| `gridMinColumnWidth` | `number \| string` | `260` | Min card width for auto-fit grid columns. |
+| `emptyState` | `ReactNode` | `"No results."` | Empty-state content. |
+| `onRowClick` | `(row, event) => void` | — | Row/card click callback. |
+| `stickyHeader` | `boolean` | `false` | Sticky list header mode. |
+| `transparentSticky` | `boolean` | `false` | Transparent sticky treatment. |
+| `transparentBackground` | `boolean` | `false` | Force transparent table surfaces. |
+| `showHeader` | `boolean` | `true` | Show/hide list header. |
+| `className` | `string` | — | Wrapper class. |
+| `tableClassName` | `string` | — | `<table>` class (list). |
+| `headerClassName` | `string` | — | `<thead>` class (list). |
+| `bodyClassName` | `string` | — | `<tbody>` class (list). |
+| `rowClassName` | `(row) => string` | — | Row/card class resolver. |
+| `cellClassName` | `(cell) => string` | — | Cell class resolver. |
+| `headerCellClassName` | `(header) => string` | — | Header class resolver. |
+| `wrapperProps` | `HTMLAttributes<HTMLDivElement>` | — | Wrapper props. |
+| `tableProps` | `HTMLAttributes<HTMLTableElement>` | — | Table props (list). |
+| `getRowProps` | `(row) => HTMLAttributes<HTMLTableRowElement>` | — | List row props resolver. |
+| `getCellProps` | `(cell) => HTMLAttributes<HTMLTableCellElement>` | — | List cell props resolver. |
+| `getHeaderProps` | `(header) => HTMLAttributes<HTMLTableCellElement>` | — | List header props resolver. |
+| `enableSorting` | `boolean` | `false` | Enables TanStack sorting row model + sortable headers. |
+| `showPagination` | `boolean` | `false` | Enables built-in pagination footer. |
+| `paginationLabels` | `TablePaginationLabels` | — | Pagination footer label overrides. |
+| `paginationPageSizes` | `number[]` | `[5, 10, 20, 50]` | Pagination page-size options. |

package/examples/index.tsx

@@ -0,0 +1 @@
+export * from '../examples';