Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Instructions for AI coding agents working in this repository. [CONTRIBUTING.md](

## What this is

`@codemancers/sheets` is a spreadsheet-style data grid for React, built on TanStack Table v8. It's one package with three entry points:
`@codemancers/sheets` is a spreadsheet-style data grid for React, built on TanStack Table v9. It's one package with three entry points:

| Import | Source (`packages/sheets/`) | Contents |
| -------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------ |
Expand Down
2 changes: 1 addition & 1 deletion apps/playground/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,6 @@
},
"dependencies": {
"@codemancers/sheets": "workspace:*",
"@tanstack/react-table": "^8.21.3"
"@tanstack/react-table": "^9.3.1"
}
}
13 changes: 9 additions & 4 deletions apps/playground/src/app/demos/editing-demo.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
import { useState, useContext } from 'react';
import { createColumnHelper } from '@tanstack/react-table';
import { useCellStatus, useRowChanges, useSheet } from '@codemancers/sheets';
import {
useCellStatus,
useRowChanges,
useSheet,
type SheetFeatures,
} from '@codemancers/sheets';
import {
Sheet,
SheetEditableTextCell,
Expand All @@ -10,9 +15,9 @@ import {
import { makeTasks, requiredTitle, saveTask, type Task } from '../data';
import { RtlContext } from '../direction';

const task = createColumnHelper<Task>();
const task = createColumnHelper<SheetFeatures, Task>();

const columns = [
const columns = task.columns([
task.accessor('title', {
header: 'Title',
size: 320,
Expand Down Expand Up @@ -43,7 +48,7 @@ const columns = [
header: 'Status',
cell: ({ getValue }) => <SheetTextCell muted>{getValue()}</SheetTextCell>,
}),
];
]);

export function EditingDemo() {
const rtl = useContext(RtlContext);
Expand Down
21 changes: 13 additions & 8 deletions apps/playground/src/app/demos/large-demo.tsx
Original file line number Diff line number Diff line change
@@ -1,39 +1,44 @@
import { useContext } from 'react';
import { createColumnHelper } from '@tanstack/react-table';
import { textFilter, useSheet, valuesFilter } from '@codemancers/sheets';
import {
textFilter,
useSheet,
valuesFilter,
type SheetFeatures,
} from '@codemancers/sheets';
import { Sheet } from '@codemancers/sheets/ui';
import { RtlContext } from '../direction';
import { makeTasks, type Task } from '../data';

const TASKS = makeTasks(1000);
const task = createColumnHelper<Task>();
const task = createColumnHelper<SheetFeatures, Task>();

// Group headers, and a header that renders markup instead of a string.
const columns = [
const columns = task.columns([
task.group({
id: 'task',
header: 'Task',
columns: [
columns: task.columns([
task.accessor('title', {
header: 'Title',
size: 300,
filterFn: textFilter,
}),
task.accessor('status', { header: 'Status', filterFn: valuesFilter }),
],
]),
}),
task.group({
id: 'assignment',
header: 'Assignment',
columns: [
columns: task.columns([
task.accessor('owner', { header: 'Owner', filterFn: valuesFilter }),
task.accessor('due', {
header: () => <abbr title="Due date">Due</abbr>,
size: 120,
}),
],
]),
}),
];
]);

/** Sorted and filtered in the browser, the default. No virtualization yet. */
export function LargeDemo() {
Expand Down
8 changes: 4 additions & 4 deletions apps/playground/src/app/demos/task-columns.tsx
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
import { createColumnHelper } from '@tanstack/react-table';
import type { CellCommitResult } from '@codemancers/sheets';
import type { CellCommitResult, SheetFeatures } from '@codemancers/sheets';
import {
SheetEditableTextCell,
SheetPrimaryCell,
SheetTextCell,
} from '@codemancers/sheets/ui';
import type { Task } from '../data';

const task = createColumnHelper<Task>();
const task = createColumnHelper<SheetFeatures, Task>();

/** A row being filled in to create a task: its title cell is an editor. */
export type NewTaskRow = {
Expand All @@ -21,7 +21,7 @@ export function taskColumns(
onOpen?: (task: Task) => void,
newRow?: NewTaskRow,
) {
return [
return task.columns([
task.accessor('title', {
header: 'Title',
size: 300,
Expand Down Expand Up @@ -52,5 +52,5 @@ export function taskColumns(
// Plain values need no cell renderer.
task.accessor('owner', { header: 'Owner' }),
task.accessor('due', { header: 'Due', size: 120 }),
];
]);
}
4 changes: 2 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ const sheet = useSheet({
return <Sheet instance={sheet} openRowId={drawer.openRowId} />;
```

`useSheet` takes everything `useReactTable` takes, plus `cellStatus` and `rowChanges`. It returns `{ table, cellStatus, rowChanges }`, and `Sheet` renders from that.
`useSheet` takes everything TanStack's `useTable` takes, plus `cellStatus` and `rowChanges`. It returns `{ table, cellStatus, rowChanges }`, and `Sheet` renders from that. The table is built from the sheet's own feature set, `sheetFeatures`.

`useCellStatus` and `useRowChanges` are separate hooks, not part of `useSheet`, because the columns refer to them: a cell's handlers are written before the table that uses those columns exists. When the app passes no `cellStatus`, `useSheet` creates its own, so cells always have somewhere to report validation and save failures.

Expand Down Expand Up @@ -69,7 +69,7 @@ flowchart TD

- **One grid for every row.** The root sets `--sheet-columns` to `40px`, then each visible leaf column's size in pixels, then `1fr`: the row-number column, the data columns, and a spacer that fills the rest. Header, body, empty, loading and add-row rows all lay out on `var(--sheet-columns)` (`src/ui/grid.ts`), so the columns line up without a `<table>`. A group header spans its leaf columns with `grid-column: span n`.
- **Pinned rows.** The body renders TanStack's pinned top rows, then the rest, then the pinned bottom rows, so a pinned row stays put whatever the sort. Apps pin a new row being filled in to the bottom. TanStack memoises the three lists, so the combined one keeps its identity for `SheetBody`'s memo.
- **Resizing re-renders little.** While a column is dragged, only the header and the root's variable change. `SheetBody` skips re-rendering while `columnSizingInfo.isResizingColumn` is set and its other props are unchanged. This is TanStack's advice for `columnResizeMode: 'onChange'`. It depends on `useCellStatus` and `useRowChanges` returning memoised objects.
- **Resizing re-renders little.** While a column is dragged, only the header and the root's variable change. `SheetBody` skips re-rendering while `columnResizing.isResizingColumn` is set and its other props are unchanged. This is TanStack's advice for `columnResizeMode: 'onChange'`. It depends on `useCellStatus` and `useRowChanges` returning memoised objects.
- **Cells.** `SheetCellContent` calls the column's `cell` function itself, without `flexRender`, so a column array that's rebuilt on every render doesn't remount the cells. A string or number result is wrapped in `SheetTextCell` for its padding. Headers do use `flexRender`.
- **Headers.** The sort button calls TanStack's toggle handler, and shows on hover or keyboard focus. Leaf columns get a resize handle: a focusable separator that takes the mouse, touch, the arrow keys (10 px a step, 50 px with Shift, flipped for `columnResizeDirection: 'rtl'`), and a double-click to reset the width.
- **Filters.** A column whose `filterFn` is `textFilter` or `valuesFilter` gets a filter button (`SheetColumnFilter`). It opens a native popover, which sits in the top layer above the scroll container, placed under the button with CSS anchor positioning. The controls mount only while it's open: a text input, or a checklist built from TanStack's faceted values (`getFacetedUniqueValues`, which counts each value with the other columns' filters applied). Both write to TanStack's `columnFilters` through `column.setFilterValue`, and TanStack's filtered row model does the rest. The body shows "no matches" and a clear button when the column filters leave no rows.
Expand Down
7 changes: 4 additions & 3 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,21 @@ When you make a choice that a future contributor would question, add it here.
- **Built with `tsc` to ES modules, with no bundler.** Each source file becomes one module and keeps its `'use client'` directive, which the Next.js App Router needs.
- **No runtime dependencies.** The icons are inlined from Heroicons and Lucide, with their licence notices, and a small `cx` helper replaces `clsx`.
- **TanStack Table is a peer dependency.** Apps import `createColumnHelper` and TanStack's types themselves, and extend `ColumnMeta` and `TableMeta` through module augmentation. Under pnpm an app can only augment a module it has installed. A peer dependency also keeps a single copy of TanStack in the app.
- **TanStack Table v8.** Moving to v9 is planned for a later release.
- **TanStack Table v9.** v8 and v9 can't share a peer range: v9's types take the feature set as their first argument, and its tables are built from registered features. `@codemancers/sheets` 0.2 is the last release for v8.
- **React 19 only.** The apps that use the package are on React 19, so React 18 isn't tested or supported.
- **The components need Tailwind v4.** They're styled with Tailwind classes, and `styles.css` adds those classes to the app's Tailwind build, so there's no separate stylesheet to load or override. An app without Tailwind can add it, or build its own markup on the headless layer.
- **The package ships its source.** `styles.css` contains `@source './'`, which makes the app's Tailwind build scan the package's source files for class names. That only works if `src/` is published.

## API

- **Plain TanStack options and column definitions.** `useSheet` takes everything `useReactTable` takes, and columns are TanStack `ColumnDef`s. An earlier custom column type covered only part of TanStack, and had to be translated. With the plain API, every TanStack option and guide applies as it is.
- **Plain TanStack options and column definitions.** `useSheet` takes everything `useTable` takes, and columns are TanStack `ColumnDef`s. An earlier custom column type covered only part of TanStack, and had to be translated. With the plain API, every TanStack option and guide applies as it is.
- **Sheet defaults that any option overrides:**
- Sorting and filtering run in the browser. TanStack skips them when `manualSorting` or `manualFiltering` is set, which is how an app sorts or filters on the server.
- Columns resize live as they're dragged.
- TanStack's faceting is on, so a values filter can list a column's values and count them. It costs nothing until a filter asks.
- **Options passed as `undefined` are dropped.** TanStack spreads the options over its defaults, so `onSortingChange: undefined` replaced TanStack's internal handler, and sorting and resizing silently did nothing.
- **`autoResetPageIndex` is off.** There's no pagination UI, and resetting the page index on every data change loops forever when an app passes data that isn't memoised.
- **One fixed feature set.** TanStack v9 includes only registered features, and types every table by its feature set. The sheet registers what it renders with (sorting, column filtering and faceting, sizing, resizing, visibility, row pinning) and what v8 gave apps for free that the README documents (global filtering, column order). Apps can't pass their own set: v9's docs type tables and components with one set, and a component can't be typed for any set that includes the sheet's without casting the table's types away. The cost is that features the sheet doesn't register, such as row selection, aren't available, and a `valuesFilter` checklist can't take its values from a server. When an app needs a feature, it's added to the set.
- **Only the sort and filter functions TanStack picks by itself are registered.** v9 resolves a name, and `'auto'`, from the registered functions only, and its full registries are deprecated because they defeat tree-shaking. Registering the ones `'auto'` chooses keeps columns sorting and filtering as they did in v8. Any other function goes straight on the column as its `sortFn` or `filterFn`.
- **A column opts into a header filter through its `filterFn`.** Setting `filterFn: textFilter` or `filterFn: valuesFilter` both filters the column and gives its header the matching control, so one property says what the filter does and what the user sees. Filters aren't on for every column, though TanStack allows that: its `'auto'` filter function is picked from the first row's value, which gives a column of objects or numbers a filter that doesn't work. A `ColumnMeta` flag was the other option, but it would need a matching `filterFn` set alongside it, in a second place to keep in step.
- **Visual settings are `Sheet` props.** `rowHeight`, `highlightedRowId`, `openRowId` and `labels` only affect the rendering, so they aren't table state.
- **Rows are identified by TanStack's `row.id`.** Statuses, staged values, and the highlighted and open rows all use it, so `getRowId` makes them follow a record through sorting and refetches.
Expand Down
Loading