puppertino-table 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0 — 2026-10-12
+
+- Add typed row/cell DOM customization callbacks and a leading-rows slot to the complete table.
+- Expose `usePuppertinoTable` for shared sorting, selection and persisted-sizing initialization in custom layouts.
+- Share resize gesture state and global listeners per table, with safe active-handle removal and coordinated columns.
+- Support uncontrolled sorting/selection with initial values and change notifications; controlled state without callbacks is read-only.
+- Supply typed body context and data attributes to customization callbacks; infer primitive resize labels from headers.
+- Document complete-component and primitive integrations, including server-owned pagination.
+
 ## 0.1.1 — 2026-10-12
 
 - Correct npm installation and publication-status documentation.

package/README.md

@@ -2,6 +2,8 @@
 
 A generic React table styled with [Puppertino](https://puppertino.com/) and powered by [TanStack Table](https://tanstack.com/table). Bring your own data, columns and cell renderers.
 
+- Complete component customization and a reusable state hook for custom layouts.
+- One shared resize controller per table, including standalone handles.
 - Typed column definitions for arbitrary row shapes, including grouped headers.
 - Host-controlled sorting by default, with optional local sorting.
 - Checkbox selection with Shift-click ranges and keyboard toggling.
@@ -15,7 +17,7 @@ A generic React table styled with [Puppertino](https://puppertino.com/) and powe
 The package includes built ESM and TypeScript declarations. Install it from npm:
 
 ```sh
-pnpm add puppertino-table@0.1.1 @tanstack/react-table@9.2.8 @codedgar/puppertino@2 react react-dom
+pnpm add puppertino-table@0.2.0 @tanstack/react-table@9.2.8 @codedgar/puppertino@2 react react-dom
 ```
 
 React, TanStack Table and Puppertino are peer dependencies; the library does not bundle another copy of them. For Git-based installation, use `github:kahwee/puppertino-table` and pin a commit or tag for reproducibility.
@@ -59,6 +61,8 @@ export function Example() {
 }
 ```
 
+For simpler tables, omit `sorting` and `onSortingChange` to let the library own sort state; set `manualSorting={false}` for local ordering. `initialSorting` and `initialRowSelection` seed uncontrolled state on mount. You can provide change callbacks as notifications while leaving state uncontrolled. If you provide controlled `sorting` or `rowSelection` without its matching callback, that state is read-only. Do not switch between controlled and uncontrolled ownership while a table is mounted.
+
 The example uses local sorting and uncontrolled checkbox selection. Pass both `rowSelection` and `onRowSelectionChange` for controlled selection. Controlled selection without a change callback is read-only. Keep column definitions and data references stable when possible.
 
 ### Sorting and pagination
@@ -73,9 +77,118 @@ Drag a header's right edge. Double-click or Enter resets that column to its defi
 
 `cancelMediaQuery` is optional: set it when your layout removes the table at a responsive breakpoint. A narrow table that remains visible can simply scroll horizontally.
 
-### Custom layouts
+### Choose an integration path
+
+Use **`PuppertinoTable`** for the complete semantic table: headers, sort buttons, optional selection, bounded resize handles, scrolling and memoized data rows. Customize it with `getRowProps(row)`, `getCellProps(cell)` and `leadingRows` before building a separate layout.
+
+```tsx
+<PuppertinoTable
+  data={items} columns={columns} getRowId={item => item.id}
+  sorting={sorting} onSortingChange={setSorting} ariaLabel="Items" selectable
+  getRowProps={row => ({
+    className: row.id === activeId ? 'active-row' : undefined,
+    'aria-current': row.id === activeId ? 'true' : undefined,
+    onClick: () => setActiveId(row.id),
+    onContextMenu: event => { event.preventDefault(); openMenu(row.original, event.clientX, event.clientY); },
+  })}
+  getCellProps={cell => ({ title: String(cell.getValue() ?? '') })}
+  leadingRows={(_table, context) => (
+    <tr><td colSpan={context.columnCount}>
+      <button type="button" onClick={openFolder}>Open folder</button>
+    </td></tr>
+  )}
+/>
+```
+
+Callbacks receive typed TanStack row/cell objects, including `original`, IDs and state methods. Their second argument is `PuppertinoBodyContext`: `{ table, columnCount, selectable, disabled }`. Typed `data-*` attributes are supported on row and cell props; return `undefined` to leave a row or cell unchanged. Row props are applied to data `<tr>` elements and cell props to data `<td>` elements. The selection cell stays library-owned. Custom row classes are combined with `p-selected`; selection checkbox clicks do not bubble to the row. The library retains row/cell children and React keys. Keep callbacks stable when possible so sizing updates can reuse the memoized body. Callbacks can attach events, styles and DOM attributes; the app owns context-menu rendering and keyboard access to its actions.
+
+`leadingRows` accepts React content or a function receiving the table. Its second argument is the same body context, with `columnCount` including the selection column. Return semantic `<tr>` elements with `<th>`/`<td>` children. It renders inside `<tbody>` before data rows, including when there are no data rows; the empty-state row still renders. Use `context.columnCount` for full-width row `colSpan`. Leading rows are app-owned: they do not enter the data row model, sorting, selection ranges or the row/cell callbacks.
+
+Use **`usePuppertinoTable` and the primitives** when you own the table markup, selection controls or header layout. The hook returns a `PuppertinoTableInstance` and shares the complete component's column bounds, persisted initial sizing, sorting ownership and controlled/uncontrolled selection rules. It accepts the state/data options from `PuppertinoTable`, without rendering options such as `ariaLabel` or `leadingRows`.
+
+```tsx
+import { useState } from 'react';
+import type { SortingState } from '@tanstack/react-table';
+import { usePuppertinoTable, ColumnResizeHandle } from 'puppertino-table';
+
+function CustomItems() {
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const table = usePuppertinoTable({
+    data: items, columns, getRowId: item => item.id,
+    sorting, onSortingChange: setSorting, manualSorting: false, selectable: true,
+    storageKey: 'my-app.custom-items.columns.v1',
+  });
+  return <table.Subscribe source={table.atoms.columnSizing}>{() => (
+    <table className="p-table pt-table" aria-label="Items" style={{ width: table.getTotalSize() }}>
+      <colgroup>{table.getAllLeafColumns().map(column => <col key={column.id} style={{ width: column.getSize() }} />)}</colgroup>
+      <thead>{table.getHeaderGroups().map(group => <tr key={group.id}>{group.headers.map(header => (
+        <th key={header.id} colSpan={header.colSpan} scope={header.column.columns.length ? 'colgroup' : 'col'}
+          aria-sort={header.column.getIsSorted() === 'asc' ? 'ascending' : header.column.getIsSorted() === 'desc' ? 'descending' : undefined}>
+          {!header.isPlaceholder && (header.column.getCanSort()
+            ? <button type="button" onClick={() => header.column.toggleSorting()}><table.FlexRender header={header} /></button>
+            : <table.FlexRender header={header} />)}
+          <ColumnResizeHandle table={table} header={header} label={header.column.id}
+            options={{ storageKey: 'my-app.custom-items.columns.v1' }} />
+        </th>
+      ))}</tr>)}</thead>
+      <tbody>{table.getRowModel().rows.map(row => <tr key={row.id}>
+        {row.getAllCells().map((cell, index) => <td key={cell.id}>
+          {index === 0 && <input type="checkbox" aria-label={`Select ${row.original.name}`}
+            checked={row.getIsSelected()} disabled={!row.getCanSelect()} onChange={row.getToggleSelectedHandler()} />}
+          <table.FlexRender cell={cell} />
+        </td>)}
+      </tr>)}</tbody>
+    </table>
+  )}</table.Subscribe>;
+}
+```
+
+The hook initializes sizing but does not install resize listeners. `ColumnResizeHandle` infers its accessible label from a string header or column ID; pass `label` for a custom or translated name. Its props type is exported as `ColumnResizeHandleProps`. `ColumnResizeHandle` and `useColumnResize` automatically share a controller keyed by the table's sizing store, with one pair of global keydown/blur listeners and one active gesture. The initiating handle's options govern that gesture; pass consistent storage and responsive settings to all handles. Removing the active handle, disabling it or changing its resize settings cancels its preview. Removing other handles leaves the gesture running. Separate tables remain independent. Pass `options={{ enabled: false }}` to hide a primitive handle when your layout is disabled; the hook's `disabled` controls selection, while primitive UI controls remain yours to disable.
+
+For more specialized state wiring, the existing `puppertinoTableFeatures`, `PuppertinoTableInstance`, sizing helpers and TanStack `useTable` remain available. In custom layouts, memoize your row body separately from the `columnSizing` subscription to avoid rerendering cells during drags.
+
+### Server-paginated complete table
+
+The server owns pagination and order. This example receives one page and its total from the host's loader; it makes no assumption about an API URL. `loadPage` must honor its abort signal. Updating the sort resets the page; stale requests cannot replace newer results. Use stable IDs across pages and keep selection state in the host if selections must survive page changes.
+
+```tsx
+import { useEffect, useState } from 'react';
+import type { SortingState, RowSelectionState } from '@tanstack/react-table';
+import { PuppertinoTable } from 'puppertino-table';
+
+type PageLoader = (query: { page: number; pageSize: number; sorting: SortingState; signal: AbortSignal }) => Promise<{ rows: Item[]; total: number }>;
+
+function ServerItems({ loadPage }: { loadPage: PageLoader }) {
+  const [query, setQuery] = useState({ page: 0, sorting: [] as SortingState });
+  const [selection, setSelection] = useState<RowSelectionState>({});
+  const [result, setResult] = useState<{ rows: Item[]; total: number }>({ rows: [], total: 0 });
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+  const pageSize = 25;
+  useEffect(() => {
+    const controller = new AbortController();
+    setLoading(true); setError('');
+    loadPage({ ...query, pageSize, signal: controller.signal })
+      .then(value => { if (!controller.signal.aborted) setResult(value); })
+      .catch(() => { if (!controller.signal.aborted) setError('Could not load items.'); })
+      .finally(() => { if (!controller.signal.aborted) setLoading(false); });
+    return () => controller.abort();
+  }, [loadPage, query]);
+  return <>
+    {error && <p role="alert">{error}</p>}
+    <PuppertinoTable data={result.rows} columns={columns} getRowId={item => item.id} ariaLabel="Items"
+      manualSorting sorting={query.sorting}
+      onSortingChange={update => setQuery(previous => ({ page: 0, sorting: typeof update === 'function' ? update(previous.sorting) : update }))}
+      selectable rowSelection={selection} onRowSelectionChange={setSelection} disabled={loading}
+      emptyContent={loading ? 'Loading items…' : 'No items'} />
+    <p role="status">{loading ? 'Loading items…' : `${result.total} items`}</p>
+    <button type="button" disabled={loading || query.page === 0} onClick={() => setQuery(previous => ({ ...previous, page: previous.page - 1 }))}>Previous page</button>
+    <button type="button" disabled={loading || (query.page + 1) * pageSize >= result.total} onClick={() => setQuery(previous => ({ ...previous, page: previous.page + 1 }))}>Next page</button>
+  </>;
+}
+```
 
-Use `puppertinoTableFeatures`, `PuppertinoTableInstance`, `useColumnResize`, `ColumnResizeHandle`, and the sizing helpers with your own `useTable` instance. The features enable sorting, sizing and row selection. Subscribe to `table.atoms.columnSizing` around table geometry and keep the row body memoized. Optional hook settings let you choose persistence, a cancellation media query and a drag CSS class.
+Keep `loadPage` stable (for example, a module-level function or `useCallback`). Selection IDs may include unloaded pages, so counts and bulk actions should use the host's selection state, not just the current row model. Use the same data, query and selection options with `usePuppertinoTable` for a server-paginated custom layout. Leave `manualSorting` enabled in both paths so a loaded page never gets re-sorted as if it were the complete dataset.
 
 The package adds scoped `.pt-*` enhancements to Puppertino's `p-table` styles. Import Puppertino's CSS in your application, then the package stylesheet. Theme tokens remain owned by Puppertino and your application. Include Puppertino's dark-mode stylesheet when using its dark theme.
 
@@ -92,7 +205,7 @@ pnpm dev             # standalone 267-row fictional-data demo
 pnpm build:storybook # static Storybook in storybook-static/
 ```
 
-Stories cover local sorting, host-owned order, range selection, keyboard resizing, dark mode, narrow layouts, empty/disabled/read-only states, grouped headers, and a different row schema with currency cells. Story controls expose selection, resizing, disabled state and sorting ownership.
+Stories cover local sorting, host-owned order, range selection, keyboard resizing, dark mode, narrow layouts, empty/disabled/read-only states, grouped headers, a different row schema with currency cells, customized/leading rows, and a custom hook layout. Story controls expose selection, resizing, disabled state and sorting ownership.
 
 ## Verification
 
@@ -100,7 +213,7 @@ Stories cover local sorting, host-owned order, range selection, keyboard resizin
 pnpm check
 ```
 
-Checks include TypeScript, preference/schema unit tests, library/demo/Storybook builds, and Chromium regression tests. The browser suite exercises 512 repeated pointer drags, width limits, reset/cancellation/persistence, selection, unmount/disabled recovery, standalone-control removal and grouped-header resizing, all 267 demo rows across six pages, six light/dark accessibility layouts, all twelve Storybook stories, and tarball installation with typed imports, server rendering and CSS exports in fresh React 18 and React 19 consumers. Set `PLAYWRIGHT_CHROMIUM_EXECUTABLE` to a system Chromium path, or install a browser with `pnpm exec playwright install chromium`.
+Checks include TypeScript, preference/schema unit tests, library/demo/Storybook builds, and Chromium regression tests. The browser suite exercises 512 repeated pointer drags, width limits, reset/cancellation/persistence, selection, unmount/disabled recovery, standalone-control removal and grouped-header resizing, all 267 demo rows across six pages, six light/dark accessibility layouts, all seventeen Storybook stories, and tarball installation with typed imports, server rendering and CSS exports in fresh React 18 and React 19 consumers. Set `PLAYWRIGHT_CHROMIUM_EXECUTABLE` to a system Chromium path, or install a browser with `pnpm exec playwright install chromium`.
 
 GitHub Actions runs the same checks and uploads Storybook plus browser evidence as an artifact. Browser tests use fictional data and do not claim Safari, physical-device or latency coverage.
 
@@ -110,7 +223,7 @@ The unscoped **`puppertino-table`** package is public on npm. Stable releases us
 
 ```sh
 pnpm check
-npm publish test-results/package/puppertino-table-0.1.1.tgz --dry-run --ignore-scripts --access public
+npm publish test-results/package/puppertino-table-0.2.0.tgz --dry-run --ignore-scripts --access public
 ```
 
 `pnpm check` builds and packs the library, checks the tarball file list, and installs it in isolated React 18 and React 19 consumers. `prepack` rebuilds JavaScript and declarations so a locally packed release cannot silently use stale output. Only the compiled library, CSS, package metadata, README, changelog and MIT license ship; Storybook, the demo and tests stay out of the npm package.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { PuppertinoTable, type PuppertinoTableProps } from './table.js';
+export { PuppertinoTable, type PuppertinoTableProps, type PuppertinoRow, type PuppertinoCell, type PuppertinoRowProps, type PuppertinoCellProps, type PuppertinoDataAttributes, type PuppertinoBodyContext } from './table.js';
 export { createPuppertinoColumnHelper, puppertinoTableFeatures, type PuppertinoTableInstance, type PuppertinoColumnDef } from './model.js';
 export { useColumnResize, type ColumnResizeOptions } from './use-column-resize.js';
-export { ColumnResizeHandle } from './resize-handle.js';
+export { ColumnResizeHandle, type ColumnResizeHandleProps } from './resize-handle.js';
 export { readColumnSizing, columnSizeBounds, clampSize, type ColumnSizeBounds } from './sizing.js';
+export { usePuppertinoTable, type PuppertinoTableOptions } from './use-puppertino-table.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export { createPuppertinoColumnHelper, puppertinoTableFeatures } from './model.j
 export { useColumnResize } from './use-column-resize.js';
 export { ColumnResizeHandle } from './resize-handle.js';
 export { readColumnSizing, columnSizeBounds, clampSize } from './sizing.js';
+export { usePuppertinoTable } from './use-puppertino-table.js';

package/dist/resize-handle.d.ts

@@ -3,9 +3,11 @@ import type { ColumnResizeOptions } from './use-column-resize.js';
 import type { PuppertinoTableInstance } from './model.js';
 import type { Header } from '@tanstack/react-table';
 import { puppertinoTableFeatures } from './model.js';
-export declare function ColumnResizeHandle<T extends RowData>({ table, header, label, options }: {
+export interface ColumnResizeHandleProps<T extends RowData> {
     table: PuppertinoTableInstance<T>;
     header: Header<typeof puppertinoTableFeatures, T>;
-    label: string;
+    /** Defaults to a string header or the stable column ID. */
+    label?: string;
     options?: ColumnResizeOptions;
-}): import("react").JSX.Element | null;
+}
+export declare function ColumnResizeHandle<T extends RowData>({ table, header, label, options }: ColumnResizeHandleProps<T>): import("react").JSX.Element | null;

package/dist/resize-handle.js

@@ -2,8 +2,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useColumnResize } from './use-column-resize.js';
 export function ColumnResizeHandle({ table, header, label, options }) {
+    const resolvedLabel = label ?? (typeof header.column.columnDef.header === 'string' ? header.column.columnDef.header : header.column.id);
     const { handle } = useColumnResize(table, options);
     if (options?.enabled === false || header.isPlaceholder || header.column.columns.length > 0)
         return null;
-    return _jsx("span", { className: "pt-resizer", role: "separator", tabIndex: 0, "aria-orientation": "vertical", "aria-label": `Resize ${label} column`, "aria-valuemin": header.column.columnDef.minSize ?? 20, "aria-valuemax": header.column.columnDef.maxSize ?? 1200, "aria-valuenow": header.getSize(), "aria-valuetext": `${header.getSize()} pixels`, title: "Drag to resize. Double-click or Enter to reset. Arrow keys adjust width; Escape cancels a drag.", ...handle(header.column.id) });
+    return _jsx("span", { className: "pt-resizer", role: "separator", tabIndex: 0, "aria-orientation": "vertical", "aria-label": `Resize ${resolvedLabel} column`, "aria-valuemin": header.column.columnDef.minSize ?? 20, "aria-valuemax": header.column.columnDef.maxSize ?? 1200, "aria-valuenow": header.getSize(), "aria-valuetext": `${header.getSize()} pixels`, title: "Drag to resize. Double-click or Enter to reset. Arrow keys adjust width; Escape cancels a drag.", ...handle(header.column.id) });
 }

package/dist/table.d.ts

@@ -1,27 +1,32 @@
-import type { RowData } from '@tanstack/react-table';
-import { type ReactNode } from 'react';
-import { type SortingState, type RowSelectionState, type OnChangeFn } from '@tanstack/react-table';
-import { type PuppertinoColumnDef } from './model.js';
-export interface PuppertinoTableProps<T extends RowData> {
-    data: readonly T[];
-    columns: readonly PuppertinoColumnDef<T>[];
-    getRowId: (row: T, index: number) => string;
-    sorting: SortingState;
-    onSortingChange: OnChangeFn<SortingState>;
-    /** True for server-owned order/pagination; false enables local TanStack sorting. */
-    manualSorting?: boolean;
-    rowSelection?: RowSelectionState;
-    onRowSelectionChange?: OnChangeFn<RowSelectionState>;
+import type { RowData, Row, Cell } from '@tanstack/react-table';
+import { type ReactNode, type ComponentPropsWithoutRef } from 'react';
+import { puppertinoTableFeatures, type PuppertinoTableInstance } from './model.js';
+import { type PuppertinoTableOptions } from './use-puppertino-table.js';
+export type PuppertinoRow<T extends RowData> = Row<typeof puppertinoTableFeatures, T>;
+export type PuppertinoCell<T extends RowData> = Cell<typeof puppertinoTableFeatures, T>;
+export type PuppertinoDataAttributes = {
+    [key: `data-${string}`]: string | number | boolean | null | undefined;
+};
+export interface PuppertinoBodyContext<T extends RowData> {
+    table: PuppertinoTableInstance<T>;
+    /** Leaf columns plus the optional selection column. */
+    columnCount: number;
+    selectable: boolean;
+    disabled: boolean;
+}
+export type PuppertinoRowProps = PuppertinoDataAttributes & Omit<ComponentPropsWithoutRef<'tr'>, 'children' | 'dangerouslySetInnerHTML'>;
+export type PuppertinoCellProps = PuppertinoDataAttributes & Omit<ComponentPropsWithoutRef<'td'>, 'children' | 'dangerouslySetInnerHTML'>;
+export interface PuppertinoTableProps<T extends RowData> extends PuppertinoTableOptions<T> {
     getRowLabel?: (row: T) => string;
-    selectable?: boolean;
-    disabled?: boolean;
     resizable?: boolean;
-    storageKey?: string;
-    storage?: Pick<Storage, 'getItem' | 'setItem'>;
     cancelMediaQuery?: string;
     ariaLabel: string;
     caption?: ReactNode;
     emptyContent?: ReactNode;
     className?: string;
+    getRowProps?: (row: PuppertinoRow<T>, context: PuppertinoBodyContext<T>) => PuppertinoRowProps | undefined;
+    getCellProps?: (cell: PuppertinoCell<T>, context: PuppertinoBodyContext<T>) => PuppertinoCellProps | undefined;
+    /** Render semantic <tr> elements before data rows, including when data is empty. */
+    leadingRows?: ReactNode | ((table: PuppertinoTableInstance<T>, context: PuppertinoBodyContext<T>) => ReactNode);
 }
-export declare function PuppertinoTable<T extends RowData>({ data, columns, getRowId, sorting, onSortingChange, manualSorting, rowSelection: controlledSelection, onRowSelectionChange, getRowLabel, selectable, disabled, resizable, storageKey, storage, cancelMediaQuery, ariaLabel, caption, emptyContent, className }: PuppertinoTableProps<T>): import("react").JSX.Element;
+export declare function PuppertinoTable<T extends RowData>({ data, columns, getRowId, sorting, onSortingChange, initialSorting, initialRowSelection, manualSorting, rowSelection: controlledSelection, onRowSelectionChange, getRowLabel, selectable, disabled, resizable, storageKey, storage, cancelMediaQuery, ariaLabel, caption, emptyContent, className, getRowProps, getCellProps, leadingRows }: PuppertinoTableProps<T>): import("react").JSX.Element;

package/dist/table.js

@@ -1,38 +1,12 @@
 "use client";
+import { createElement as _createElement } from "react";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { memo, useMemo, useState } from 'react';
-import { useTable } from '@tanstack/react-table';
-import { puppertinoTableFeatures } from './model.js';
-import { columnSizeBounds, readColumnSizing } from './sizing.js';
+import { memo } from 'react';
+import { usePuppertinoTable } from './use-puppertino-table.js';
 import { useColumnResize } from './use-column-resize.js';
-export function PuppertinoTable({ data, columns, getRowId, sorting, onSortingChange, manualSorting = true, rowSelection: controlledSelection, onRowSelectionChange, getRowLabel, selectable = false, disabled = false, resizable = true, storageKey, storage, cancelMediaQuery, ariaLabel, caption, emptyContent = 'No rows', className = '' }) {
-    const [localSelection, setLocalSelection] = useState({});
-    const rowSelection = controlledSelection ?? localSelection;
-    const canSelect = selectable && !disabled && (controlledSelection === undefined || !!onRowSelectionChange);
-    const bounds = useMemo(() => columnSizeBounds(columns), [columns]);
-    const sizedColumns = useMemo(() => {
-        const byId = new Map(bounds.map(bound => [bound.id, bound]));
-        const decorate = (defs) => defs.map(def => {
-            if ('columns' in def && def.columns)
-                return { ...def, columns: decorate(def.columns) };
-            const id = def.id ?? ('accessorKey' in def ? String(def.accessorKey).replaceAll('.', '_') : '');
-            return { ...def, ...byId.get(id) };
-        });
-        return decorate(columns);
-    }, [columns, bounds]);
-    const [initialWidths] = useState(() => {
-        try {
-            return readColumnSizing(bounds, storageKey, storage || localStorage);
-        }
-        catch {
-            return readColumnSizing(bounds);
-        }
-    });
-    const table = useTable({ features: puppertinoTableFeatures, columns: sizedColumns, data, getRowId,
-        manualSorting, enableMultiSort: false, enableSortingRemoval: false, enableRowSelection: canSelect,
-        enableSubRowSelection: false, initialState: { columnSizing: initialWidths },
-        state: { sorting, rowSelection }, onSortingChange, onRowSelectionChange: onRowSelectionChange ?? setLocalSelection,
-    }, state => ({ sorting: state.sorting, rowSelection: state.rowSelection }));
+export function PuppertinoTable({ data, columns, getRowId, sorting, onSortingChange, initialSorting, initialRowSelection, manualSorting = true, rowSelection: controlledSelection, onRowSelectionChange, getRowLabel, selectable = false, disabled = false, resizable = true, storageKey, storage, cancelMediaQuery, ariaLabel, caption, emptyContent = 'No rows', className = '', getRowProps, getCellProps, leadingRows }) {
+    const table = usePuppertinoTable({ data, columns, getRowId, sorting, onSortingChange, initialSorting, initialRowSelection, manualSorting,
+        rowSelection: controlledSelection, onRowSelectionChange, selectable, disabled, storageKey, storage });
     const options = { enabled: resizable && !disabled, storageKey, storage, cancelMediaQuery };
     const { handle } = useColumnResize(table, options);
     const groups = table.getHeaderGroups();
@@ -42,11 +16,19 @@ export function PuppertinoTable({ data, columns, getRowId, sorting, onSortingCha
                                     const sorted = column.getIsSorted();
                                     const leaf = column.columns.length === 0;
                                     return _jsxs("th", { colSpan: header.colSpan, scope: leaf ? 'col' : 'colgroup', "aria-sort": sorted ? sorted === 'asc' ? 'ascending' : 'descending' : undefined, children: [!header.isPlaceholder && (column.getCanSort() ? _jsxs("button", { type: "button", className: "pt-sort", "aria-label": `Sort by ${label}`, disabled: disabled, onClick: () => column.toggleSorting(), children: [_jsx(table.FlexRender, { header: header }), _jsx("span", { className: "pt-sort-arrow", "aria-hidden": "true", "data-direction": sorted || 'none', children: "\u2304" })] }) : _jsx(table.FlexRender, { header: header })), leaf && !header.isPlaceholder && resizable && !disabled && _jsx("span", { className: "pt-resizer", role: "separator", tabIndex: 0, "aria-orientation": "vertical", "aria-label": `Resize ${label} column`, "aria-valuemin": column.columnDef.minSize, "aria-valuemax": column.columnDef.maxSize, "aria-valuenow": header.getSize(), "aria-valuetext": `${header.getSize()} pixels`, title: "Drag to resize. Double-click or Enter to reset. Arrows adjust width; Escape cancels a drag.", ...handle(column.id) })] }, header.id);
-                                })] }, group.id)) }), _jsx(MemoTableBody, { table: table, selectable: selectable, getRowLabel: getRowLabel, emptyContent: emptyContent })] }) }) });
+                                })] }, group.id)) }), _jsx(MemoTableBody, { table: table, selectable: selectable, disabled: disabled, getRowLabel: getRowLabel, emptyContent: emptyContent, getRowProps: getRowProps, getCellProps: getCellProps, leadingRows: leadingRows })] }) }) });
 }
 /** Geometry updates do not rerender cells. State and data changes still do. */
-function TableBody({ table, selectable, getRowLabel, emptyContent }) {
+function TableBody({ table, selectable, disabled, getRowLabel, emptyContent, getRowProps, getCellProps, leadingRows }) {
     const rows = table.getRowModel().rows;
-    return _jsx("tbody", { children: rows.length ? rows.map(row => _jsxs("tr", { className: row.getIsSelected() ? 'p-selected' : undefined, children: [selectable && _jsx("td", { className: "pt-selection", children: _jsx("input", { type: "checkbox", "aria-label": `Select ${getRowLabel?.(row.original) ?? row.id}`, checked: row.getIsSelected(), disabled: !row.getCanSelect(), onClick: event => { event.stopPropagation(); row.getToggleSelectedHandler()(event); }, onChange: () => { } }) }), row.getAllCells().map(cell => _jsx("td", { children: _jsx(table.FlexRender, { cell: cell }) }, cell.id))] }, row.id)) : _jsx("tr", { children: _jsx("td", { colSpan: table.getAllLeafColumns().length + (selectable ? 1 : 0), children: emptyContent }) }) });
+    const context = { table, selectable, disabled, columnCount: table.getAllLeafColumns().length + (selectable ? 1 : 0) };
+    return _jsxs("tbody", { children: [typeof leadingRows === 'function' ? leadingRows(table, context) : leadingRows, rows.length ? rows.map(row => {
+                const props = getRowProps?.(row, context);
+                const className = [row.getIsSelected() ? 'p-selected' : '', props?.className].filter(Boolean).join(' ') || undefined;
+                return _createElement("tr", { ...props, key: row.id, className: className },
+                    selectable && _jsx("td", { className: "pt-selection", children: _jsx("input", { type: "checkbox", "aria-label": `Select ${getRowLabel?.(row.original) ?? row.id}`, checked: row.getIsSelected(), disabled: !row.getCanSelect(), onClick: event => { event.stopPropagation(); row.getToggleSelectedHandler()(event); }, onChange: () => { } }) }),
+                    row.getAllCells().map(cell => _createElement("td", { ...getCellProps?.(cell, context), key: cell.id },
+                        _jsx(table.FlexRender, { cell: cell }))));
+            }) : _jsx("tr", { children: _jsx("td", { colSpan: context.columnCount, children: emptyContent }) })] });
 }
 const MemoTableBody = memo(TableBody);

package/dist/use-column-resize.d.ts

@@ -1,6 +1,6 @@
 import type { RowData } from '@tanstack/react-table';
 import { type PointerEvent, type KeyboardEvent } from 'react';
-import type { PuppertinoTableInstance } from "./model.js";
+import type { PuppertinoTableInstance } from './model.js';
 export interface ColumnResizeOptions {
     enabled?: boolean;
     storageKey?: string;
@@ -8,7 +8,7 @@ export interface ColumnResizeOptions {
     cancelMediaQuery?: string;
     dragClassName?: string;
 }
-export declare function useColumnResize<T extends RowData>(table: PuppertinoTableInstance<T>, { enabled, storageKey, storage, cancelMediaQuery, dragClassName }?: ColumnResizeOptions): {
+export declare function useColumnResize<T extends RowData>(table: PuppertinoTableInstance<T>, options?: ColumnResizeOptions): {
     handle: (id: string) => {
         onPointerDown: (event: PointerEvent<HTMLElement>) => void;
         onPointerMove: (event: PointerEvent<HTMLElement>) => void;

package/dist/use-column-resize.js

@@ -10,106 +10,140 @@ function markDrag(name, delta) {
         activeClasses.delete(name);
     document.documentElement.classList.toggle(name, count > 0);
 }
-export function useColumnResize(table, { enabled = true, storageKey, storage, cancelMediaQuery, dragClassName = "pt-resizing" } = {}) {
-    const bounds = (id) => {
+/** One gesture and one set of global listeners for each table's sizing store. */
+function createController() {
+    const members = new Set();
+    let drag = null;
+    const snapshot = (table) => Object.fromEntries(table.getAllLeafColumns().map(column => [column.id, column.getSize()]));
+    const bounds = (table, id) => {
         const column = table.getColumn(id);
         return { id, size: column.columnDef.size ?? 150, minSize: column.columnDef.minSize ?? 20, maxSize: column.columnDef.maxSize ?? Number.MAX_SAFE_INTEGER };
     };
-    const clamp = (id, value) => clampSize(value, bounds(id));
-    const snapshot = () => Object.fromEntries(table.getAllLeafColumns().map(column => [column.id, column.getSize()]));
-    const save = () => { try {
-        if (storageKey)
-            (storage || localStorage).setItem(storageKey, JSON.stringify(snapshot()));
-    }
-    catch { /* Resizing still works without storage. */ } };
-    const reset = (id) => { table.getColumn(id).resetSize(); save(); };
-    const drag = useRef(null);
-    const apply = (next, persist = false) => {
-        table.setColumnSizing(next);
-        if (persist)
-            save();
+    const save = ({ table, options }) => {
+        try {
+            if (options.storageKey)
+                (options.storage || localStorage).setItem(options.storageKey, JSON.stringify(snapshot(table)));
+        }
+        catch { /* Storage is optional. */ }
     };
     const finish = (cancel = false) => {
-        const active = drag.current;
+        const active = drag;
         if (!active)
             return;
-        drag.current = null;
-        markDrag(dragClassName, -1);
+        drag = null;
+        active.removeMedia();
+        markDrag(active.className, -1);
         if (active.target.hasPointerCapture(active.pointer))
             active.target.releasePointerCapture(active.pointer);
-        apply(cancel ? active.before : snapshot(), !cancel);
+        active.member.table.setColumnSizing(cancel ? active.before : snapshot(active.member.table));
+        if (!cancel)
+            save(active.member);
     };
-    useEffect(() => { if (!enabled)
-        finish(true); }, [enabled]);
-    useEffect(() => {
-        const cancel = (event) => { if (event.key === 'Escape' && drag.current) {
-            event.preventDefault();
-            finish(true);
-        } };
-        const blur = () => finish(true);
-        const compact = cancelMediaQuery ? window.matchMedia(cancelMediaQuery) : undefined;
-        const modeChange = () => { if (compact?.matches)
-            finish(true); };
-        compact?.addEventListener("change", modeChange);
-        window.addEventListener('keydown', cancel);
-        window.addEventListener('blur', blur);
-        return () => {
-            compact?.removeEventListener("change", modeChange);
-            window.removeEventListener('keydown', cancel);
-            window.removeEventListener('blur', blur);
-            // Never save a gesture interrupted by route or display-mode changes.
-            const active = drag.current;
-            drag.current = null;
-            if (active)
-                markDrag(dragClassName, -1);
-            if (active?.target.hasPointerCapture(active.pointer))
-                active.target.releasePointerCapture(active.pointer);
-            if (active)
-                table.setColumnSizing(active.before);
-        };
-    }, [table.atoms.columnSizing, cancelMediaQuery, dragClassName]);
-    return { handle: (id) => ({
-            onPointerDown: (event) => {
-                if (!enabled || event.button !== 0 || drag.current)
-                    return;
-                event.preventDefault();
-                event.stopPropagation();
-                event.currentTarget.focus();
-                const before = snapshot();
-                drag.current = { id, x: event.clientX, width: before[id], before, target: event.currentTarget, pointer: event.pointerId };
-                event.currentTarget.setPointerCapture(event.pointerId);
-                markDrag(dragClassName, 1);
-            },
-            onPointerMove: (event) => {
-                const active = drag.current;
-                if (active && active.pointer === event.pointerId)
-                    apply({ ...snapshot(), [active.id]: clamp(active.id, active.width + event.clientX - active.x) });
-            },
-            onPointerUp: (event) => { if (event.pointerId === drag.current?.pointer)
-                finish(!enabled || !!(cancelMediaQuery && window.matchMedia(cancelMediaQuery).matches)); },
-            onPointerCancel: (event) => { if (event.pointerId === drag.current?.pointer)
-                finish(true); },
-            onLostPointerCapture: (event) => { if (event.pointerId === drag.current?.pointer)
-                finish(true); },
-            onDoubleClick: () => { if (enabled)
-                reset(id); },
-            onKeyDown: (event) => {
-                if (!enabled || drag.current)
-                    return;
-                if (event.key === "Enter") {
+    const cancel = (event) => { if (event.key === 'Escape' && drag) {
+        event.preventDefault();
+        finish(true);
+    } };
+    const blur = () => finish(true);
+    const cancelMember = (member) => { if (drag?.member === member)
+        finish(true); };
+    return {
+        cancelMember,
+        retain(member) {
+            if (!members.size) {
+                window.addEventListener('keydown', cancel);
+                window.addEventListener('blur', blur);
+            }
+            members.add(member);
+            return () => {
+                cancelMember(member);
+                members.delete(member);
+                if (!members.size) {
+                    window.removeEventListener('keydown', cancel);
+                    window.removeEventListener('blur', blur);
+                }
+            };
+        },
+        handle(id, member) {
+            const reset = () => { member.table.getColumn(id).resetSize(); save(member); };
+            return {
+                onPointerDown: (event) => {
+                    const { table, options } = member;
+                    if (options.enabled === false || event.button !== 0 || drag || !members.has(member))
+                        return;
+                    const media = options.cancelMediaQuery ? window.matchMedia(options.cancelMediaQuery) : undefined;
+                    if (media?.matches)
+                        return;
                     event.preventDefault();
                     event.stopPropagation();
-                    reset(id);
-                    return;
-                }
-                const step = event.shiftKey ? 40 : 16;
-                const widths = snapshot();
-                const next = event.key === 'ArrowLeft' ? widths[id] - step : event.key === 'ArrowRight' ? widths[id] + step : event.key === 'Home' ? bounds(id).minSize : event.key === 'End' ? bounds(id).maxSize : undefined;
-                if (next === undefined)
-                    return;
-                event.preventDefault();
-                event.stopPropagation();
-                apply({ ...snapshot(), [id]: clamp(id, next) }, true);
-            },
-        }) };
+                    event.currentTarget.focus();
+                    const before = snapshot(table);
+                    const modeChange = () => { if (media?.matches)
+                        finish(true); };
+                    drag = { member, id, x: event.clientX, width: before[id], before, target: event.currentTarget,
+                        pointer: event.pointerId, className: options.dragClassName ?? 'pt-resizing', media,
+                        removeMedia: () => media?.removeEventListener('change', modeChange) };
+                    media?.addEventListener('change', modeChange);
+                    event.currentTarget.setPointerCapture(event.pointerId);
+                    markDrag(drag.className, 1);
+                },
+                onPointerMove: (event) => {
+                    const active = drag;
+                    if (active?.member === member && active.pointer === event.pointerId) {
+                        const { table } = member;
+                        table.setColumnSizing({ ...snapshot(table), [active.id]: clampSize(active.width + event.clientX - active.x, bounds(table, active.id)) });
+                    }
+                },
+                onPointerUp: (event) => {
+                    if (drag?.member === member && event.pointerId === drag.pointer)
+                        finish(member.options.enabled === false || !!drag.media?.matches);
+                },
+                onPointerCancel: (event) => { if (drag?.member === member && event.pointerId === drag.pointer)
+                    finish(true); },
+                onLostPointerCapture: (event) => { if (drag?.member === member && event.pointerId === drag.pointer)
+                    finish(true); },
+                onDoubleClick: () => { if (member.options.enabled !== false && !drag)
+                    reset(); },
+                onKeyDown: (event) => {
+                    if (member.options.enabled === false || drag)
+                        return;
+                    if (event.key === 'Enter') {
+                        event.preventDefault();
+                        event.stopPropagation();
+                        reset();
+                        return;
+                    }
+                    const { table } = member;
+                    const step = event.shiftKey ? 40 : 16;
+                    const widths = snapshot(table);
+                    const next = event.key === 'ArrowLeft' ? widths[id] - step : event.key === 'ArrowRight' ? widths[id] + step : event.key === 'Home' ? bounds(table, id).minSize : event.key === 'End' ? bounds(table, id).maxSize : undefined;
+                    if (next === undefined)
+                        return;
+                    event.preventDefault();
+                    event.stopPropagation();
+                    table.setColumnSizing({ ...widths, [id]: clampSize(next, bounds(table, id)) });
+                    save(member);
+                },
+            };
+        },
+    };
+}
+// The atom survives table wrapper rerenders. Weak keys allow discarded tables to be collected.
+const controllers = new WeakMap();
+export function useColumnResize(table, options = {}) {
+    const key = table.atoms.columnSizing;
+    let controller = controllers.get(key);
+    if (!controller) {
+        controller = createController();
+        controllers.set(key, controller);
+    }
+    const member = useRef({ table, options });
+    member.current.table = table;
+    member.current.options = options;
+    useEffect(() => controller.retain(member.current), [controller]);
+    useEffect(() => {
+        if (options.enabled === false)
+            controller.cancelMember(member.current);
+        return () => controller.cancelMember(member.current);
+    }, [controller, options.enabled, options.storageKey, options.storage, options.cancelMediaQuery, options.dragClassName]);
+    return { handle: (id) => controller.handle(id, member.current) };
 }

package/dist/use-puppertino-table.d.ts

@@ -0,0 +1,22 @@
+import type { RowData, SortingState, RowSelectionState, OnChangeFn } from '@tanstack/react-table';
+import { type PuppertinoColumnDef, type PuppertinoTableInstance } from './model.js';
+export interface PuppertinoTableOptions<T extends RowData> {
+    data: readonly T[];
+    columns: readonly PuppertinoColumnDef<T>[];
+    getRowId: (row: T, index: number) => string;
+    /** Omit for local state. Supply a callback alongside controlled sorting to allow edits. */
+    sorting?: SortingState;
+    onSortingChange?: OnChangeFn<SortingState>;
+    initialSorting?: SortingState;
+    initialRowSelection?: RowSelectionState;
+    /** Preserve host-owned order by default, including server-paginated data. */
+    manualSorting?: boolean;
+    rowSelection?: RowSelectionState;
+    onRowSelectionChange?: OnChangeFn<RowSelectionState>;
+    selectable?: boolean;
+    disabled?: boolean;
+    storageKey?: string;
+    storage?: Pick<Storage, 'getItem' | 'setItem'>;
+}
+/** Shared state wiring for complete tables and custom semantic layouts. */
+export declare function usePuppertinoTable<T extends RowData>({ data, columns, getRowId, sorting: controlledSorting, onSortingChange, initialSorting, initialRowSelection, manualSorting, rowSelection: controlledSelection, onRowSelectionChange, selectable, disabled, storageKey, storage }: PuppertinoTableOptions<T>): PuppertinoTableInstance<T>;

package/dist/use-puppertino-table.js

@@ -0,0 +1,48 @@
+"use client";
+import { useTable } from '@tanstack/react-table';
+import { useCallback, useMemo, useState } from 'react';
+import { puppertinoTableFeatures } from './model.js';
+import { columnSizeBounds, readColumnSizing } from './sizing.js';
+/** Shared state wiring for complete tables and custom semantic layouts. */
+export function usePuppertinoTable({ data, columns, getRowId, sorting: controlledSorting, onSortingChange, initialSorting = [], initialRowSelection = {}, manualSorting = true, rowSelection: controlledSelection, onRowSelectionChange, selectable = false, disabled = false, storageKey, storage }) {
+    const [localSelection, setLocalSelection] = useState(() => initialRowSelection);
+    const [localSorting, setLocalSorting] = useState(() => initialSorting);
+    const sorting = controlledSorting ?? localSorting;
+    const changeSorting = useCallback(update => {
+        if (controlledSorting === undefined)
+            setLocalSorting(update);
+        onSortingChange?.(update);
+    }, [controlledSorting, onSortingChange]);
+    const changeSelection = useCallback(update => {
+        if (controlledSelection === undefined)
+            setLocalSelection(update);
+        onRowSelectionChange?.(update);
+    }, [controlledSelection, onRowSelectionChange]);
+    const rowSelection = controlledSelection ?? localSelection;
+    const canSelect = selectable && !disabled && (controlledSelection === undefined || !!onRowSelectionChange);
+    const bounds = useMemo(() => columnSizeBounds(columns), [columns]);
+    const sizedColumns = useMemo(() => {
+        const byId = new Map(bounds.map(bound => [bound.id, bound]));
+        const decorate = (defs) => defs.map(def => {
+            if ('columns' in def && def.columns)
+                return { ...def, columns: decorate(def.columns) };
+            const id = def.id ?? ('accessorKey' in def ? String(def.accessorKey).replaceAll('.', '_') : '');
+            return { ...def, ...byId.get(id) };
+        });
+        return decorate(columns);
+    }, [columns, bounds]);
+    const [initialWidths] = useState(() => {
+        try {
+            return readColumnSizing(bounds, storageKey, storage || localStorage);
+        }
+        catch {
+            return readColumnSizing(bounds);
+        }
+    });
+    const table = useTable({ features: puppertinoTableFeatures, columns: sizedColumns, data, getRowId,
+        manualSorting, enableSorting: controlledSorting === undefined || !!onSortingChange, enableMultiSort: false, enableSortingRemoval: false, enableRowSelection: canSelect,
+        enableSubRowSelection: false, initialState: { columnSizing: initialWidths },
+        state: { sorting, rowSelection }, onSortingChange: changeSorting, onRowSelectionChange: changeSelection,
+    }, state => ({ sorting: state.sorting, rowSelection: state.rowSelection }));
+    return table;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puppertino-table",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "publishConfig": {
     "access": "public",