react-glide-table 1.1.0 → 1.1.2

package/README.md

@@ -1,8 +1,10 @@
 # react-glide-table
 
-Headless React table primitives built on [@tanstack/react-table](https://tanstack.com/table) and [@tanstack/react-virtual](https://tanstack.com/virtual).
+Headless React table built on [@tanstack/react-table](https://tanstack.com/table) and [@tanstack/react-virtual](https://tanstack.com/virtual).
 
-You own the markup and styles. This package exposes state, handlers, and pure helpers for selection, editing, fill, row spanning, tree expand, and virtualization.
+Primary DX is a **compound API** (`createTable` / `Table.Column`) with an unstyled semantic HTML shell. Customize with `className` hooks, `slots`, and column `render`. `useGlideTable` remains the lower-level escape hatch when you need full control of markup.
+
+The package ships **no CSS** — class names like `DataTableJSX` / `data-table` are opt-in hooks for your own styles.
 
 ## Installation
 
@@ -14,12 +16,66 @@ pnpm add react-glide-table
 
 Peer dependencies: `react` and `react-dom` (`^18` or `^19`).
 
-## Quick start
+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) |
+
+## Quick start (compound)
+
+```tsx
+import { createTable } from "react-glide-table/compound"
+import { useState } from "react"
+
+type Product = { id: string; name: string; qty: number }
+
+const ProductTable = createTable<Product>()
+
+export function Products({ data }: { data: Product[] }) {
+  const [page, setPage] = useState(1)
+
+  return (
+    <ProductTable
+      data={data}
+      getRowId={(row) => row.id}
+      className="my-table"
+      // Optional: replace Toolbar / Row / Pending / Empty
+      // slots={{ Toolbar: MyToolbar, Row: MyRow, Empty: MyEmpty }}
+    >
+      <ProductTable.Header>
+        <ProductTable.Column field="name">Name</ProductTable.Column>
+        <ProductTable.Column field="qty" editable>
+          Qty
+        </ProductTable.Column>
+      </ProductTable.Header>
+      <ProductTable.Pagination page={page} pageSize={10} onChange={setPage} />
+    </ProductTable>
+  )
+}
+```
+
+### Customization surface
+
+| Slot / prop | Role |
+| --- | --- |
+| `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` | Class hooks (style yourself) |
+| `labels` / `summary` / `toolbar` | Copy and slot nodes |
+| `Column.render` | Cell content custom render |
+
+Row-level UI → `slots.Row`. Cell content → `Column.render`. Header/Cell are not separate slots.
+
+## Escape hatch (`useGlideTable`)
 
 ```tsx
 import { flexRender } from "@tanstack/react-table"
-import { useGlideTable } from "react-glide-table"
-import type { ColumnDef } from "react-glide-table"
+import { useGlideTable } from "react-glide-table/core"
+import type { ColumnDef } from "react-glide-table/core"
 
 type Product = { id: string; name: string; qty: number }
 
@@ -69,22 +125,26 @@ export function ProductTable({ data }: { data: Product[] }) {
 }
 ```
 
-Wire `rowContextValue` into your own row/cell components for edit, selection, expand, and row-span behavior. See the `playground/` app for a full reference UI built on top of `useGlideTable`.
+Wire `rowContextValue` into your own row/cell components for edit, selection, expand, and row-span behavior.
 
 ## Public API
 
-| Export | Role |
-| --- | --- |
-| `useGlideTable` | Headless table engine (TanStack instance, virtualization, selection/edit/expand state) |
-| `useCellEdit` / `useCellSelection` / `useConvertTreeData` | Feature hooks |
-| `applyCellEdit`, `applyFillData`, `buildColumnRowSpanMap`, … | Pure helpers |
-| `DEFAULT_DATA_TABLE_LABELS` / `resolveDataTableLabels` | Optional English UI copy helpers |
-| Tree field defaults | `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`, `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`, …
 
 ## Notable constraints
 
 - **Row span + virtualization**: when `enableRowSpan` is on, virtualization is forced off (HTML `<table>` + `rowspan` cannot safely share a virtual window).
-- **No shipped CSS / opinionated components**: bring your own DOM. The published package does not export the reference UI components under `src/components/ui` (but some feature helpers are re-exported and shipped).
+- **No shipped CSS**: the default renderer emits class hooks only. Bring your own styles (see playground for a CSS-skinned example).
 
 ## Local playground
 
@@ -93,7 +153,7 @@ pnpm install
 pnpm dev
 ```
 
-The playground imports a reference `createTable` / `DataTable` UI from the repo source to exercise the headless core.
+The playground uses `createTable` with a local CSS skin (`src/styles/index.css`) to exercise the compound API and headless core.
 
 ## License