react-glide-table 1.1.9 → 1.3.0

package/README.md

@@ -18,24 +18,24 @@ Peer dependencies: `react` and `react-dom` (`^18` or `^19`).
 
 The package is marked `"sideEffects": false` for tree-shaking. Prefer subpath imports when you only need one surface:
 
-| Import | Contents |
-| --- | --- |
-| `react-glide-table` | Full barrel (compound + core) |
-| `react-glide-table/compound` | `createTable` / `Table` / `DataTable` + related types |
-| `react-glide-table/core` | `useGlideTable` + feature hooks/helpers (no compound UI) |
+| Import                       | Contents                                                 |
+| ---------------------------- | -------------------------------------------------------- |
+| `react-glide-table`          | Full barrel (compound + core)                            |
+| `react-glide-table/compound` | `createTable` / `Table` / `DataTable` + related types    |
+| `react-glide-table/core`     | `useGlideTable` + feature hooks/helpers (no compound UI) |
 
 ## Quick start (compound)
 
 ```tsx
-import { createTable } from "react-glide-table/compound"
-import { useState } from "react"
+import { createTable } from "react-glide-table/compound";
+import { useState } from "react";
 
-type Product = { id: string; name: string; qty: number }
+type Product = { id: string; name: string; qty: number };
 
-const ProductTable = createTable<Product>()
+const ProductTable = createTable<Product>();
 
 export function Products({ data }: { data: Product[] }) {
-  const [page, setPage] = useState(1)
+  const [page, setPage] = useState(1);
 
   return (
     <ProductTable
@@ -59,26 +59,26 @@ export function Products({ data }: { data: Product[] }) {
       </ProductTable.Header>
       <ProductTable.Pagination page={page} pageSize={10} onChange={setPage} />
     </ProductTable>
-  )
+  );
 }
 ```
 
 ### Customization surface
 
-| Slot / prop | Role |
-| --- | --- |
-| `classNames` | Per-part Tailwind/utility classes (`root`, `scroll`, `row`, `cell`, `toolbar`, …) |
-| `slots.Toolbar` | Top summary / actions region |
-| `slots.Row` | Full row replacement (cells, selection, edit UI) |
-| `slots.Pending` / `slots.Empty` | Loading and empty states |
-| `className` / column `className` / `headerClassName` | Extra class hooks |
-| `labels` / `summary` / `toolbar` | Copy and slot nodes |
-| `Column.render` | Cell content custom render |
+| Slot / prop                                          | Role                                                                              |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `classNames`                                         | Per-part Tailwind/utility classes (`root`, `scroll`, `row`, `cell`, `toolbar`, …) |
+| `slots.Toolbar`                                      | Top summary / actions region                                                      |
+| `slots.Row`                                          | Full row replacement (cells, selection, edit UI)                                  |
+| `slots.Pending` / `slots.Empty`                      | Loading and empty states                                                          |
+| `className` / column `className` / `headerClassName` | Extra class hooks                                                                 |
+| `labels` / `summary` / `toolbar`                     | Copy and slot nodes                                                               |
+| `Column.render`                                      | Cell content custom render                                                        |
 
 Row/cell **state** is exposed as `data-*` attributes for Tailwind variants:
 
 - row: `data-selected`, `data-hovered`, `data-expandable`, `data-expanded`
-- cell: `data-merged`, `data-selection-fill`, `data-editable`, `data-editing`, …
+- cell: `data-merged`, `data-selection-fill`, `data-editable`, `data-editing`, `data-frozen`, …
 
 Example: `row: "data-[selected]:bg-blue-600"`.
 
@@ -87,16 +87,16 @@ Row-level UI → `slots.Row`. Cell content → `Column.render`. Header/Cell are
 ## Escape hatch (`useGlideTable`)
 
 ```tsx
-import { flexRender } from "@tanstack/react-table"
-import { useGlideTable } from "react-glide-table/core"
-import type { ColumnDef } from "react-glide-table/core"
+import { flexRender } from "@tanstack/react-table";
+import { useGlideTable } from "react-glide-table/core";
+import type { ColumnDef } from "react-glide-table/core";
 
-type Product = { id: string; name: string; qty: number }
+type Product = { id: string; name: string; qty: number };
 
 const columns: ColumnDef<Product, unknown>[] = [
   { accessorKey: "name", header: "Name" },
   { accessorKey: "qty", header: "Qty" },
-]
+];
 
 export function ProductTable({ data }: { data: Product[] }) {
   const { table, rows, scrollRef } = useGlideTable({
@@ -104,7 +104,7 @@ export function ProductTable({ data }: { data: Product[] }) {
     columns,
     getRowId: (row) => row.id,
     rowSelectionMode: "multi",
-  })
+  });
 
   return (
     <div ref={scrollRef}>
@@ -116,7 +116,10 @@ export function ProductTable({ data }: { data: Product[] }) {
                 <th key={header.id}>
                   {header.isPlaceholder
                     ? null
-                    : flexRender(header.column.columnDef.header, header.getContext())}
+                    : flexRender(
+                        header.column.columnDef.header,
+                        header.getContext(),
+                      )}
                 </th>
               ))}
             </tr>
@@ -135,7 +138,7 @@ export function ProductTable({ data }: { data: Product[] }) {
         </tbody>
       </table>
     </div>
-  )
+  );
 }
 ```
 
@@ -145,17 +148,17 @@ Wire `rowContextValue` into your own row/cell components for edit, selection, ex
 
 Cell selection ships with clipboard shortcuts. The table parses TSV and emits structured payloads; **your app applies domain conversion and updates data**.
 
-| Shortcut | Behavior |
-| --- | --- |
-| Ctrl/Cmd+C | Copy the active selection (visible rows) |
-| Ctrl/Cmd+Shift+C | Copy including collapsed tree descendants (`enableSubtreeCopy`) |
-| Ctrl/Cmd+V | Paste **overwrite** into the selection (`onRowsPaste`, `mode: "overwrite"`) |
+| Shortcut         | Behavior                                                                               |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| Ctrl/Cmd+C       | Copy the active selection (visible rows)                                               |
+| Ctrl/Cmd+Shift+C | Copy including collapsed tree descendants (`enableSubtreeCopy`)                        |
+| Ctrl/Cmd+V       | Paste **overwrite** into the selection (`onRowsPaste`, `mode: "overwrite"`)            |
 | Ctrl/Cmd+Shift+V | Paste **insert** rows after the selection (`mode: "insert"`, when `enableInsertPaste`) |
 
 Subtree copy encodes relative tree depth as leading tabs in the TSV so paste can rebuild parent/child nesting via `payload.depths`. Depth is only inferred when the clipboard looks like subtree indentation (first row unindented, at least one later row indented). Otherwise leading empty cells are kept as real values (e.g. Excel/Sheets blank first column) and `depths` stay `0`.
 
 ```tsx
-import type { RowsPastePayload } from "react-glide-table/compound"
+import type { RowsPastePayload } from "react-glide-table/compound";
 
 <ProductTable
   data={data}
@@ -164,27 +167,91 @@ import type { RowsPastePayload } from "react-glide-table/compound"
   onRowsPaste={(payload: RowsPastePayload) => {
     // overwrite: update cells from startRow using payload.values / columnIds
     // insert: create rows after payload.endRow (or payload.anchorRowId for trees)
-    setData((prev) => applyMyPaste(prev, payload))
+    setData((prev) => applyMyPaste(prev, payload));
   }}
 >
   {/* columns… */}
-</ProductTable>
+</ProductTable>;
 ```
 
 Related props: `onRowsPaste`, `enableInsertPaste`, `enableSubtreeCopy`, `onCopyActionsReady`.  
 Helpers (`/core`): `buildRowsPastePayload`, `parseClipboardTSV`, `parseClipboardTSVWithDepths`, `serializeSelectionToTSV`, …
 
+## Column resize
+
+Opt in with `enableColumnResize`. Drag the handle on the right edge of a header cell; double-click resets to the column’s default `width` / `size`.
+
+```tsx
+<ProductTable
+  data={data}
+  enableColumnResize
+  // optional controlled sizing
+  // columnSizing={sizing}
+  // onColumnSizingChange={setSizing}
+>
+  <ProductTable.Header>
+    <ProductTable.Column field="name" width={200} minWidth={80} maxWidth={480}>
+      Name
+    </ProductTable.Column>
+    <ProductTable.Column field="sku" resizable={false}>
+      SKU
+    </ProductTable.Column>
+  </ProductTable.Header>
+</ProductTable>
+```
+
+| Prop                                     | Role                                         |
+| ---------------------------------------- | -------------------------------------------- |
+| `enableColumnResize`                     | Turn on header drag resize (default `false`) |
+| `columnSizing` / `onColumnSizingChange`  | Controlled width map `{ [columnId]: px }`    |
+| `columnResizeMode`                       | `"onChange"` (live) or `"onEnd"`             |
+| `Column.width` / `minWidth` / `maxWidth` | Default / clamp sizes                        |
+| `Column.resizable={false}`               | Disable resize for one column                |
+| `classNames.resizeHandle`                | Style hook for the drag handle               |
+
+## Column freeze
+
+Opt in with `enableColumnFreeze`. Mark columns with `frozen` — sticky insets are stacked so frozen cells never overlap, and **column order is unchanged** (middle columns may also freeze).
+
+```tsx
+<ProductTable data={data} enableColumnFreeze>
+  <ProductTable.Header>
+    <ProductTable.Column field="name" frozen width={200}>
+      Name
+    </ProductTable.Column>
+    <ProductTable.Column field="sku">SKU</ProductTable.Column>
+    <ProductTable.Column field="qty" frozen="left">
+      Qty
+    </ProductTable.Column>
+    <ProductTable.Column field="status" frozen="right">
+      Status
+    </ProductTable.Column>
+  </ProductTable.Header>
+</ProductTable>
+```
+
+| Prop                               | Role                                    |
+| ---------------------------------- | --------------------------------------- |
+| `enableColumnFreeze`               | Turn on sticky freeze (default `false`) |
+| `Column.frozen` / `meta.frozen`    | `true` / `"left"` or `"right"`          |
+| `data-frozen`                      | `"left"` / `"right"` on frozen cells    |
+| `data-freeze-edge`                 | `"left"` / `"right"` / `"both"` on island boundaries |
+
+Helpers (`/core`): `buildColumnFreezeOffsets`, `getColumnFreezeEdgeAttr`, `getColumnFreezeStyle`, `resolveColumnFreezeSide`.
+
+Contiguous same-side freezes share one island (shadow only on the outer boundary). A gap between frozen columns creates separate islands, so both sides of the gap get an edge shadow.
+
 ## Public API
 
-| Export | Path | Role |
-| --- | --- | --- |
-| `createTable` / `Table` | `/compound` | Compound column DSL (`Header` / `Column` / `Body` / `Pagination`) |
-| `DataTable` | `/compound` | Unstyled default renderer (semantic HTML + slots/props) |
-| `useGlideTable` | `/core` | Headless engine escape hatch |
-| `useCellEdit` / `useCellSelection` / `useConvertTreeData` | `/core` | Feature hooks |
-| `applyCellEdit`, `applyFillData`, `buildRowsPastePayload`, `buildColumnRowSpanMap`, … | `/core` | Pure helpers |
-| `DEFAULT_DATA_TABLE_LABELS` / `resolveDataTableLabels` | `/core` | Optional English UI copy helpers |
-| Tree field defaults | `/core` | `id` / `parentId` / `children` / `qty` |
+| Export                                                                                | Path        | Role                                                              |
+| ------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
+| `createTable` / `Table`                                                               | `/compound` | Compound column DSL (`Header` / `Column` / `Body` / `Pagination`) |
+| `DataTable`                                                                           | `/compound` | Unstyled default renderer (semantic HTML + slots/props)           |
+| `useGlideTable`                                                                       | `/core`     | Headless engine escape hatch                                      |
+| `useCellEdit` / `useCellSelection` / `useConvertTreeData`                             | `/core`     | Feature hooks                                                     |
+| `applyCellEdit`, `applyFillData`, `buildRowsPastePayload`, `buildColumnRowSpanMap`, … | `/core`     | Pure helpers                                                      |
+| `DEFAULT_DATA_TABLE_LABELS` / `resolveDataTableLabels`                                | `/core`     | Optional English UI copy helpers                                  |
+| Tree field defaults                                                                   | `/core`     | `id` / `parentId` / `children` / `qty`                            |
 
 Root `react-glide-table` re-exports both surfaces. Related types: `TableProps`, `TableColumnProps`, `DataTableProps`, `DataTableSlots`, `TableCompoundComponent`, `ColumnDef`, `RowsPastePayload`, `PasteMode`, …
 
@@ -192,7 +259,7 @@ Root `react-glide-table` re-exports both surfaces. Related types: `TableProps`,
 
 - **Row span + virtualization**: when `enableRowSpan` is on, virtualization is forced off (HTML `<table>` + `rowspan` cannot safely share a virtual window).
 - **Paste is app-owned**: the library does not mutate `data` on paste — handle `onRowsPaste` (coerce types, ids, tree shape, row-span keys).
-- **Flat tree parent order**: `useConvertTreeData` attaches each child to the nearest *preceding* row whose toggle key matches `parentId` (duplicate keys after paste resolve this way). Flat inputs must list parents before their children; a child whose parent appears later becomes a root. Nested `children` arrays are flattened parent-before-child automatically.
+- **Flat tree parent order**: `useConvertTreeData` attaches each child to the nearest _preceding_ row whose toggle key matches `parentId` (duplicate keys after paste resolve this way). Flat inputs must list parents before their children; a child whose parent appears later becomes a root. Nested `children` arrays are flattened parent-before-child automatically.
 - **No shipped CSS**: the default renderer emits class hooks only. Bring your own styles (see playground for a CSS-skinned example).
 
 ## Local playground