puppertino-table 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## Unreleased
+## 0.5.0 — 2026-10-12
+
+- Add scoped native/compact/comfortable density and explicit row/padding/icon metrics across tables and custom layouts; preserve native defaults.
+- Add a caller-rendered, independently resizable column browser with whole-panel fitting, selected/path states and controlled/read-only widths.
+- Share resize lifecycle/event adaptation between table columns and browser panels instead of duplicating gesture handling.
+- Add right-click and keyboard context-menu primitives with viewport fitting, disabled-item navigation, dismissal and focus restoration, plus realistic light/dark resource-browser Storybook workflows.
+
+- Add opt-in anchored row-selection gestures for custom layouts, with mixed leading/data items, Command/Ctrl toggles, shrinking Shift ranges and controlled/atom/disabled ownership guards.
+- Export a React-independent selection reducer and whole-column browser geometry helper, with unit, Storybook, browser and packed-consumer checks. Existing checkbox selection remains unchanged.
+
+- Extract hydration-safe preference restoration into a dedicated persistence lifecycle hook.
+- Add typed external atom ownership for sorting, selection and sizing; reject conflicting owners and changed bindings without a remount.
+- Add external-atom integration docs, Storybook coverage and production pointer profiling with cell-render regression checks.
 
 ## 0.4.0 — 2026-10-12
 

package/README.md

@@ -17,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.4.0 @tanstack/react-table@9.2.8 @codedgar/puppertino@2 react@19.3.0 react-dom@19.3.0
+pnpm add puppertino-table@0.5.0 @tanstack/react-table@9.2.8 @codedgar/puppertino@2 react@19.3.0 react-dom@19.3.0
 ```
 
 React 19.3.0 or a compatible newer React 19 release is required (`^19.3.0`). React 18 and React 20 are outside the supported range. 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.
@@ -84,6 +84,127 @@ const [columnSizing, setColumnSizing] = useState<ColumnSizingState>({ name: 240
 
 The callback receives a value or functional updater, like a React state setter. Supplying widths without a callback makes sizing read-only. The callback is used only with controlled widths; omit both props for TanStack-owned sizing and its fine-grained geometry subscription. Controlled widths ignore saved preferences: the app owns restoration and persistence, so omit `storageKey` from controlled resize handles. Uncontrolled sorting and selection also stay in TanStack’s internal atoms; callbacks can observe their changes without owning the state. React-controlled sizing rerenders its state owner; for high-frequency custom layouts, TanStack v9 also supports external atoms through `useTable`.
 
+### External atom ownership
+
+For shared app-owned state with fine-grained subscriptions, pass `atoms` to the complete table or hook. Install `@tanstack/react-store@0.11.2` in the app to create and subscribe to the atoms:
+
+```tsx
+import { useCreateAtom, useSelector } from '@tanstack/react-store';
+import type { ColumnSizingState, RowSelectionState, SortingState } from '@tanstack/react-table';
+
+function ItemsTable() {
+  const columnSizing = useCreateAtom<ColumnSizingState>({ name: 240 });
+  const sorting = useCreateAtom<SortingState>([]);
+  const rowSelection = useCreateAtom<RowSelectionState>({});
+  return <PuppertinoTable data={items} columns={columns} getRowId={(row) => row.id}
+    ariaLabel="Items" selectable atoms={{ columnSizing, sorting, rowSelection }} />;
+}
+```
+
+`PuppertinoTableAtoms` is exported for typed custom integrations. A state slice has one owner: supplying an atom together with that slice's value or callback throws a clear error. Different slices may use different ownership modes. Atom bindings must stay identical for the lifetime of the table, as required by the installed v9 adapter; changing bindings requires remounting with a new React `key`. You may recreate the map when it contains the same atom instances. Initial sorting/selection values apply only to internally owned slices; initialize app atoms yourself. Atom-owned sizing bypasses automatic preference restoration, and the complete component also disables automatic saving. In primitive layouts, omit `storageKey` from resize options when the app owns sizing restoration and saving. Read with `atom.get()` for a snapshot, or use `useSelector(atom)` in the smallest component that needs reactive state. No callback is needed for atom-owned slices. Width changes retain the existing geometry subscription rather than rerendering the table's row body.
+
+### Shared density
+
+The density, column-browser and context-menu APIs below are available starting in version 0.5.0.
+
+Complete tables accept `density="native" | "compact" | "comfortable"`. Native is the default and preserves the existing Puppertino table geometry. Compact uses 24px minimum rows, 3px block padding, 8px inline padding and 16px icons. Comfortable uses 36px rows, 8px block padding, 12px inline padding and 20px icons. Content can make a row taller; text and icons are never clipped to force a height.
+
+Use `DensityScope` around layouts built with the table primitives, or pass `densityMetrics` to `PuppertinoTable` and `ColumnBrowser` for explicit overrides. Metrics are CSS pixels: `rowHeight`, `rowPaddingBlock`, `rowPaddingInline` and `iconSize`. `DensityScope` calls the same object `metrics`. Heights and icon sizes must be positive; padding may be zero. Styles stay scoped to each wrapper, so adjacent components can use different densities. Put caller-owned artwork in a `.pt-icon` span to share sizing; the library does not replace your icons.
+
+```tsx
+<PuppertinoTable {...tableProps} density="compact" densityMetrics={{ iconSize: 18 }} />
+<DensityScope density="comfortable" metrics={{ rowPaddingInline: 16 }}>
+  <MyCustomLayout />
+</DensityScope>
+```
+
+The corresponding CSS properties are `--pt-row-height`, `--pt-row-padding-block`, `--pt-row-padding-inline` and `--pt-icon-size`. Explicit metrics are applied on the scope; ordinary host CSS can customize them. Native density leaves default table header/cell styling intact unless metrics are explicitly supplied. Density changes layout only, not sorting, selection or saved widths.
+
+### Column-browser component
+
+`ColumnBrowser` renders caller-owned panels in order; the last is the current panel. Ancestors scroll vertically on their own. The surface scrolls horizontally and reveals the current panel beside whole ancestors after navigation, resizing or container changes. Each ancestor can be resized independently with a pointer or the keyboard, using the same cancel/reset lifecycle as table columns. The current panel fills spare room and fits containers narrower than its preferred minimum.
+
+```tsx
+import { ColumnBrowser, ColumnBrowserItem } from 'puppertino-table';
+
+<ColumnBrowser ariaLabel="Projects" density="compact" panels={[
+  { id: 'workspace', label: 'Workspace', content:
+    <ColumnBrowserItem pathSelected onClick={showProjects}>Projects</ColumnBrowserItem> },
+  { id: 'projects', label: 'Projects', width: 260, minWidth: 160, maxWidth: 600,
+    content: projectButtons },
+  { id: 'current', label: 'Selected project', content: resourceButtons },
+]} />
+```
+
+Panels require unique stable `id`, an accessible `label` for their region, and caller-rendered `content`. Ancestors default to 224px, bounded to 120–640px. `minimumCurrentWidth` defaults to 288px. Give the component or its parent a bounded height; it fills that height. The default density is compact. Optional `widths` and `onWidthsChange` provide controlled ancestor sizing. Widths without a callback are read-only and omit resize handles. `resizable={false}` or `resizeDisabled` cancels active gestures; `cancelMediaQuery` can cancel when a responsive layout removes the controls. Panel removal and changed bounds also cancel. Completed gestures remain in local state until unmount; the component does not write preferences. Change callbacks include previews and cancellations, so they are not approval or persistence receipts.
+
+`ColumnBrowserItem` is a native button with `icon`, `trailing`, `selected` and `pathSelected` slots/states. It shares density metrics, ellipsis, hover and keyboard-focus styling. Selection and path indication are separate. Standard button props provide actions, labels, disabled state and context-menu triggers. The browser does not fetch records, enter folders, select items or open documents. Compose your navigation, `useRowSelectionGestures`, and custom content around it. Its geometry is measured only after hydration; initial server markup uses deterministic panel widths.
+
+### Right-click and keyboard context menus
+
+`useContextMenu<T>()` supplies `state`, `open(context, event)`, `close()` and `getTriggerProps(context)`. The trigger props open on right-click, Shift+F10 or the Context Menu key and advertise a menu popup. They are opt-in: items without them keep the browser's native context menu. If you already handle key events, compose that handler with the returned `onKeyDown` instead of overwriting either one.
+
+```tsx
+const menu = useContextMenu<string>();
+<ColumnBrowserItem {...menu.getTriggerProps(item.id)}>{item.name}</ColumnBrowserItem>
+<ContextMenu ariaLabel="Item commands" position={menu.state?.position ?? null}
+  returnFocus={menu.state?.returnFocus} onClose={menu.close}
+  actions={menu.state ? commandsFor(menu.state.context) : []} />
+```
+
+For tables, spread trigger props in `getRowProps` and make the target keyboard-focusable, or attach them to a button inside a cell. `ContextMenu` accepts actions with stable `id`, `label`, optional `disabled`, and `onSelect`. It fits the viewport, focuses the first enabled action, supports arrows/Home/End, skips disabled actions, closes on Escape/Tab/outside pointer/scroll/resize/blur, and restores the invoking target's focus. It uses a manual popover where supported so a table or panel's overflow does not clip it. Place it in the same themed DOM subtree as its trigger. Commands, right-click selection policy and authorization remain caller-owned; the component never invents file operations.
+
+### Anchored item selection in custom layouts
+
+`useRowSelectionGestures(table, options)` adds opt-in desktop item selection to a custom list, card grid or table. A normal click replaces the selection, Command/Ctrl-click toggles one item, and Shift-click extends or shrinks a range from its original anchor. Shift with a toggle modifier adds a range. This policy is separate from the existing checkbox range behavior.
+
+```tsx
+import { useRef } from 'react';
+import { usePuppertinoTable, useRowSelectionGestures } from 'puppertino-table';
+
+function ItemList() {
+  const table = usePuppertinoTable({ data: items, columns, getRowId: item => item.id, selectable: true });
+  const anchor = useRef<string | null>(null);
+  const { select, clearSelection } = useRowSelectionGestures(table, { anchor });
+  return (
+    <table.Subscribe source={table.atoms.rowSelection}>
+      {selected => <>
+        {table.getRowModel().rows.map(row => <button
+          key={row.id} type="button" aria-pressed={!!selected[row.id]}
+          disabled={!row.getCanSelect()}
+          onClick={event => select(row.id, { shift: event.shiftKey, toggle: event.metaKey || event.ctrlKey })}
+        >{row.original.name}</button>)}
+        <button type="button" onClick={clearSelection}>Clear selection</button>
+      </>}
+    </table.Subscribe>
+  );
+}
+```
+
+The hook works with uncontrolled state, React-controlled state and external selection atoms. Disabled or read-only tables reject gestures without moving the anchor; `options.disabled` also disables just this hook. Nonselectable rows are excluded from ranges. `select` accepts an item ID and `{ shift?, toggle? }`, rather than a DOM event. Call it from native button activation or your own keyboard controller; the hook does not install keyboard listeners, move focus, open items or choose ARIA roles.
+
+`options.orderedIds` supplies a caller-owned visible order, including leading items outside the table row model. The default is the current rendered row order. Extra IDs are supported with boolean row-selection eligibility; a table's row predicate cannot authorize an item outside its data model. The caller still owns rendering and selected-state announcements. Share `options.anchor` between layouts to retain the original range anchor. `clearSelection()` clears selection and anchor; `resetAnchor()` only clears the anchor, useful when replacing a collection or changing its order. Without an external ref, the anchor lasts for this hook's mount.
+
+`applySelectionGesture(orderedIds, selection, anchor, id, modifiers)` exports the same pure reducer without React. It returns `{ selection, anchor }`, never mutates caller inputs and ignores unknown target IDs. A stale anchor becomes the clicked item. Toggle gestures preserve selected IDs outside the supplied order; replacing gestures clear them. Only the caller-supplied IDs participate in a range; the package never assumes a loaded page is the entire dataset. Selection does not authorize application actions.
+
+### Whole-column browser geometry
+
+`fitColumnBrowser({ availableWidth, ancestorWidth, ancestorCount, minimumCurrentWidth })` is a pure helper for a caller-rendered hierarchical column browser. It returns `{ currentWidth, scrollLeft, visibleAncestors }`. Use the current width for the final panel and the scroll offset to reveal that panel beside whole ancestors, avoiding a cut-off filename at the left edge after resizing.
+
+```ts
+import { fitColumnBrowser } from 'puppertino-table';
+
+const layout = fitColumnBrowser({
+  availableWidth: 724,
+  ancestorWidth: 224,
+  ancestorCount: 3,
+  minimumCurrentWidth: 288,
+});
+// { currentWidth: 500, scrollLeft: 448, visibleAncestors: 1 }
+```
+
+Widths are outer panel widths in CSS pixels; use border-box panels and measure the available scroll surface. The final panel takes spare room and fits surfaces narrower than its preferred minimum. A root with no ancestors takes the entire width. Dimensions must be finite and nonnegative, the ancestor width positive, and the count an integer; invalid inputs throw `RangeError`. The helper remains available for manual layouts. `ColumnBrowser` owns resize observation and scrolling for caller-rendered panels; hierarchy, loading and data access remain app-owned.
+
 ### Resizing
 
 Drag a header's right edge. Double-click or Enter resets that column to its definition's initial size. Left/Right adjusts 16 pixels; Shift uses 40 pixels. Home/End reaches its limits, and Escape cancels an unfinished gesture. Pointer cancellation, losing window focus, unmounting, or disabling resizing also cancels.
@@ -251,7 +372,7 @@ pnpm format # apply formatting, import organization and safe lint fixes
 pnpm check
 ```
 
-Checks include TypeScript, independent controller ownership/cancellation/persistence tests, preference/schema unit tests, real SSR hydration and controlled-sizing browser 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 nineteen Storybook stories, and tarball installation with typed imports, server rendering and CSS exports in fresh React 19.3.0 consumers. Set `PLAYWRIGHT_CHROMIUM_EXECUTABLE` to a system Chromium path, or install a browser with `pnpm exec playwright install chromium`.
+Checks include TypeScript, independent controller ownership/cancellation/persistence tests, preference/schema unit tests, real SSR hydration and controlled-sizing browser 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 twenty Storybook stories, and tarball installation with typed imports, server rendering and CSS exports in fresh React 19.3.0 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.
 
@@ -263,7 +384,7 @@ The unscoped **`puppertino-table`** package is public on npm. Stable releases us
 
 ```sh
 pnpm check
-npm publish test-results/package/puppertino-table-0.4.0.tgz --dry-run --ignore-scripts --access public
+npm publish test-results/package/puppertino-table-0.5.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 19.3.0 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.
@@ -279,3 +400,7 @@ MIT. Puppertino, React and TanStack Table remain independently maintained projec
 Dependabot checks npm dependencies and GitHub Actions every Monday at 08:00 America/Los_Angeles. It groups compatible npm patch/minor updates and proposes major changes separately. React and React DOM, including their type packages, stay on the supported React 19 line; versions 20 and later are excluded.
 
 Dependency updates must pass verification on the current PR head before merging. Review major migrations separately. Releases remain explicitly authorized actions; dependency maintenance does not publish npm versions or alter trusted-publisher settings.
+
+### Pointer profiling
+
+Run `pnpm profile:pointer` to measure the production table with 100 rows and 10, 40 and 100 columns, under 4× Chromium CPU throttling. The harness uses one warmup and three measured drags per size, records dispatch timings and browser task/layout totals, and asserts that pointer resizing does not rerender cells. Results are written to `test-results/pointer-profile/results.json`. These synthetic samples guide optimization; they do not guarantee real-device latency. Use the existing browser executable environment variable when needed. The [recorded profile](https://github.com/kahwee/puppertino-table/blob/main/docs/pointer-performance.md) shows zero cell rerenders and increasing browser task cost for very wide tables. Immediate updates remain in place until a burst-workload comparison demonstrates that frame batching helps without weakening gesture semantics.

package/dist/column-browser-layout.d.ts

@@ -0,0 +1,20 @@
+export interface ColumnBrowserLayoutOptions {
+    availableWidth: number;
+    ancestorWidth: number;
+    ancestorCount: number;
+    minimumCurrentWidth: number;
+}
+/** Variable-width equivalent used by independently resizable browser panels. */
+export declare function fitColumnPanels(availableWidth: number, ancestorWidths: readonly number[], minimumCurrentWidth: number): {
+    currentWidth: number;
+    scrollLeft: number;
+    visibleAncestors: number;
+};
+/** Fit whole ancestor panels beside a current panel, independent of data and rendering.
+ * Apply currentWidth to the final panel and scrollLeft to the horizontal scroll surface.
+ */
+export declare function fitColumnBrowser({ availableWidth, ancestorWidth, ancestorCount, minimumCurrentWidth, }: ColumnBrowserLayoutOptions): {
+    currentWidth: number;
+    scrollLeft: number;
+    visibleAncestors: number;
+};

package/dist/column-browser-layout.js

@@ -0,0 +1,42 @@
+/** Variable-width equivalent used by independently resizable browser panels. */
+export function fitColumnPanels(availableWidth, ancestorWidths, minimumCurrentWidth) {
+    if (!Number.isFinite(availableWidth) ||
+        availableWidth < 0 ||
+        !Number.isFinite(minimumCurrentWidth) ||
+        minimumCurrentWidth < 0 ||
+        ancestorWidths.some((width) => !Number.isFinite(width) || width <= 0))
+        throw new RangeError('Panel dimensions must be finite and nonnegative, with positive ancestor widths.');
+    let visibleWidth = 0, visibleAncestors = 0;
+    for (let index = ancestorWidths.length - 1; index >= 0; index--) {
+        const width = ancestorWidths[index];
+        if (visibleWidth + width + minimumCurrentWidth > availableWidth)
+            break;
+        visibleWidth += width;
+        visibleAncestors++;
+    }
+    return {
+        currentWidth: availableWidth - visibleWidth,
+        scrollLeft: ancestorWidths.reduce((sum, width) => sum + width, 0) - visibleWidth,
+        visibleAncestors,
+    };
+}
+/** Fit whole ancestor panels beside a current panel, independent of data and rendering.
+ * Apply currentWidth to the final panel and scrollLeft to the horizontal scroll surface.
+ */
+export function fitColumnBrowser({ availableWidth, ancestorWidth, ancestorCount, minimumCurrentWidth, }) {
+    if (!Number.isFinite(availableWidth) ||
+        availableWidth < 0 ||
+        !Number.isFinite(ancestorWidth) ||
+        ancestorWidth <= 0 ||
+        !Number.isInteger(ancestorCount) ||
+        ancestorCount < 0 ||
+        !Number.isFinite(minimumCurrentWidth) ||
+        minimumCurrentWidth < 0)
+        throw new RangeError('Column dimensions must be finite and nonnegative, with a positive ancestor width and an integer ancestor count.');
+    const visibleAncestors = Math.min(ancestorCount, Math.floor(Math.max(0, availableWidth - minimumCurrentWidth) / ancestorWidth));
+    return {
+        currentWidth: availableWidth - visibleAncestors * ancestorWidth,
+        scrollLeft: (ancestorCount - visibleAncestors) * ancestorWidth,
+        visibleAncestors,
+    };
+}

package/dist/column-browser.d.ts

@@ -0,0 +1,34 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import { type DensityMetrics, type TableDensity } from './density.js';
+export interface ColumnBrowserPanel {
+    id: string;
+    label: string;
+    content: ReactNode;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+}
+export type ColumnBrowserWidths = Record<string, number>;
+export interface ColumnBrowserProps {
+    panels: readonly ColumnBrowserPanel[];
+    ariaLabel: string;
+    density?: TableDensity;
+    densityMetrics?: DensityMetrics;
+    minimumCurrentWidth?: number;
+    resizable?: boolean;
+    resizeDisabled?: boolean;
+    cancelMediaQuery?: string;
+    widths?: ColumnBrowserWidths;
+    onWidthsChange?: (widths: ColumnBrowserWidths) => void;
+    className?: string;
+    style?: ComponentPropsWithoutRef<'div'>['style'];
+}
+/** Caller-rendered hierarchy. No fetching, navigation, selection or application commands. */
+export declare function ColumnBrowser({ panels, ariaLabel, density, densityMetrics, minimumCurrentWidth, resizable, resizeDisabled: disabled, cancelMediaQuery, widths: controlled, onWidthsChange, className, style, }: ColumnBrowserProps): import("react").JSX.Element;
+export interface ColumnBrowserItemProps extends ComponentPropsWithoutRef<'button'> {
+    icon?: ReactNode;
+    trailing?: ReactNode;
+    selected?: boolean;
+    pathSelected?: boolean;
+}
+export declare function ColumnBrowserItem({ icon, trailing, selected, pathSelected, className, children, ...props }: ColumnBrowserItemProps): import("react").JSX.Element;

package/dist/column-browser.js

@@ -0,0 +1,76 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useRef, useState, } from 'react';
+import { fitColumnPanels } from './column-browser-layout.js';
+import { DensityScope } from './density.js';
+import { clampSize, columnSizeBounds } from './sizing.js';
+import { useResizeGesture } from './use-resize-gesture.js';
+/** Caller-rendered hierarchy. No fetching, navigation, selection or application commands. */
+export function ColumnBrowser({ panels, ariaLabel, density = 'compact', densityMetrics, minimumCurrentWidth = 288, resizable = true, resizeDisabled: disabled = false, cancelMediaQuery, widths: controlled, onWidthsChange, className = '', style, }) {
+    const ids = panels.map((panel) => panel.id);
+    if (ids.some((id) => !id) || new Set(ids).size !== ids.length)
+        throw new Error('Browser panels need unique stable IDs.');
+    if (!Number.isFinite(minimumCurrentWidth) || minimumCurrentWidth <= 0)
+        throw new RangeError('The current panel minimum must be positive and finite.');
+    const bounds = columnSizeBounds(panels.slice(0, -1).map((panel) => ({
+        id: panel.id,
+        size: panel.width ?? 224,
+        minSize: panel.minWidth ?? 120,
+        maxSize: panel.maxWidth ?? 640,
+    })));
+    const [localWidths, setLocalWidths] = useState({});
+    const widths = Object.fromEntries(bounds.map((bound) => [bound.id, clampSize((controlled ?? localWidths)[bound.id], bound)]));
+    const snapshot = useRef(widths);
+    const surface = useRef(null);
+    const owner = useRef({});
+    const apply = (next) => {
+        const normalized = Object.fromEntries(bounds.map((bound) => [bound.id, clampSize(next[bound.id], bound)]));
+        if (controlled === undefined)
+            setLocalWidths(normalized);
+        onWidthsChange?.(normalized);
+    };
+    const resize = useResizeGesture(owner.current, {
+        snapshot: () => snapshot.current,
+        bounds: (id) => {
+            const bound = bounds.find((bound) => bound.id === id);
+            if (!bound)
+                throw new Error(`Unknown browser panel: ${id}`);
+            return bound;
+        },
+        apply,
+        reset: (id) => apply({ ...snapshot.current, [id]: bounds.find((bound) => bound.id === id)?.size ?? 224 }),
+    }, {
+        enabled: resizable && !disabled && (controlled === undefined || !!onWidthsChange),
+        cancelMediaQuery,
+    });
+    const schema = JSON.stringify(bounds);
+    useLayoutEffect(() => {
+        snapshot.current = widths;
+    });
+    // Panel removal or changed bounds cancel a drag just as table schema changes do.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: Cancellation is keyed to stable schema values, not newly created handler objects.
+    useEffect(() => () => resize.cancel(), [schema]);
+    const geometry = JSON.stringify(bounds.map((bound) => widths[bound.id]));
+    useLayoutEffect(() => {
+        const element = surface.current;
+        if (!element)
+            return;
+        const ancestorWidths = JSON.parse(geometry);
+        const fit = () => {
+            const layout = fitColumnPanels(element.clientWidth, ancestorWidths, minimumCurrentWidth);
+            element.style.setProperty('--pt-current-panel-width', `${layout.currentWidth}px`);
+            element.scrollLeft = layout.scrollLeft;
+        };
+        fit();
+        const observer = new ResizeObserver(fit);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [geometry, minimumCurrentWidth]);
+    return (_jsx(DensityScope, { ref: surface, density: density, metrics: densityMetrics, className: `pt-column-browser ${className}`, style: style, role: "region", tabIndex: 0, "aria-label": ariaLabel, children: panels.map((panel, index) => {
+            const bound = bounds[index];
+            return (_jsxs("section", { className: "pt-browser-panel", "aria-label": panel.label, style: { flexBasis: bound ? widths[panel.id] : 'var(--pt-current-panel-width, 100%)' }, children: [_jsx("div", { className: "pt-browser-panel-content", children: panel.content }), bound && resizable && !disabled && (controlled === undefined || !!onWidthsChange) && (_jsx("span", { className: "pt-panel-resizer", role: "separator", tabIndex: 0, "aria-orientation": "vertical", "aria-label": `Resize ${panel.label} panel`, "aria-valuemin": bound.minSize, "aria-valuemax": bound.maxSize, "aria-valuenow": widths[panel.id], title: "Drag to resize. Arrow keys adjust width; Enter resets and Escape cancels.", ...resize.handle(panel.id) }))] }, panel.id));
+        }) }));
+}
+export function ColumnBrowserItem({ icon, trailing, selected = false, pathSelected = false, className = '', children, ...props }) {
+    return (_jsxs("button", { type: "button", ...props, className: `pt-browser-item ${selected ? 'p-selected' : ''} ${pathSelected ? 'pt-path-selected' : ''} ${className}`, "aria-pressed": selected, "aria-current": pathSelected ? 'location' : undefined, children: [icon && (_jsx("span", { className: "pt-icon", "aria-hidden": "true", children: icon })), _jsx("span", { className: "pt-item-label", children: children }), trailing && (_jsx("span", { className: "pt-item-trailing", "aria-hidden": "true", children: trailing }))] }));
+}

package/dist/context-menu.d.ts

@@ -0,0 +1,34 @@
+import { type KeyboardEvent, type MouseEvent } from 'react';
+export interface ContextMenuPosition {
+    x: number;
+    y: number;
+}
+export interface ContextMenuAction {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    onSelect(): void;
+}
+export interface ContextMenuProps {
+    position: ContextMenuPosition | null;
+    actions: readonly ContextMenuAction[];
+    ariaLabel: string;
+    onClose(): void;
+    returnFocus?: HTMLElement | null;
+}
+export declare function useContextMenu<T>(): {
+    state: {
+        context: T;
+        position: ContextMenuPosition;
+        returnFocus: HTMLElement;
+    } | null;
+    close: () => void;
+    open: (context: T, event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>) => void;
+    getTriggerProps: (context: T) => {
+        'aria-haspopup': 'menu';
+        onContextMenu: (event: MouseEvent<HTMLElement>) => void;
+        onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    };
+};
+/** Caller-owned commands; popover placement, keyboard navigation and focus stay shared. */
+export declare function ContextMenu({ position, actions, ariaLabel, onClose, returnFocus, }: ContextMenuProps): import("react").JSX.Element | null;

package/dist/context-menu.js

@@ -0,0 +1,117 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, } from 'react';
+export function useContextMenu() {
+    const [state, setState] = useState(null);
+    const close = useCallback(() => setState(null), []);
+    const open = useCallback((context, event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        const target = event.currentTarget;
+        const candidate = event.target instanceof Element
+            ? event.target.closest('button,a[href],input,select,textarea,[tabindex]')
+            : null;
+        const focusTarget = candidate instanceof HTMLElement && target.contains(candidate) ? candidate : target;
+        const rect = focusTarget.getBoundingClientRect();
+        const pointer = 'clientX' in event && (event.clientX !== 0 || event.clientY !== 0);
+        setState({
+            context,
+            position: pointer
+                ? { x: event.clientX, y: event.clientY }
+                : { x: rect.left + 8, y: rect.bottom },
+            returnFocus: focusTarget,
+        });
+    }, []);
+    return {
+        state,
+        close,
+        open,
+        getTriggerProps: (context) => ({
+            'aria-haspopup': 'menu',
+            onContextMenu: (event) => open(context, event),
+            onKeyDown: (event) => {
+                if (event.key === 'ContextMenu' || (event.shiftKey && event.key === 'F10'))
+                    open(context, event);
+            },
+        }),
+    };
+}
+/** Caller-owned commands; popover placement, keyboard navigation and focus stay shared. */
+export function ContextMenu({ position, actions, ariaLabel, onClose, returnFocus, }) {
+    const menu = useRef(null);
+    const close = useRef(onClose);
+    close.current = onClose;
+    useLayoutEffect(() => {
+        const element = menu.current;
+        if (!position || !element)
+            return;
+        element.showPopover?.();
+        const rect = element.getBoundingClientRect();
+        element.style.left = `${Math.max(8, Math.min(position.x, innerWidth - rect.width - 8))}px`;
+        element.style.top = `${Math.max(8, Math.min(position.y, innerHeight - rect.height - 8))}px`;
+        (element.querySelector('button:not(:disabled)') ?? element).focus();
+        return () => {
+            if (returnFocus?.isConnected)
+                returnFocus.focus({ preventScroll: true });
+        };
+    }, [position, returnFocus]);
+    useEffect(() => {
+        if (!position)
+            return;
+        const outside = (event) => {
+            if (!menu.current?.contains(event.target))
+                close.current();
+        };
+        const dismiss = () => close.current();
+        const outsideScroll = (event) => {
+            if (!menu.current?.contains(event.target))
+                close.current();
+        };
+        const onEscape = (event) => {
+            if (event.key === 'Escape') {
+                event.preventDefault();
+                event.stopPropagation();
+                close.current();
+            }
+        };
+        document.addEventListener('pointerdown', outside, true);
+        document.addEventListener('keydown', onEscape, true);
+        document.addEventListener('scroll', outsideScroll, true);
+        window.addEventListener('resize', dismiss);
+        window.addEventListener('blur', dismiss);
+        return () => {
+            document.removeEventListener('pointerdown', outside, true);
+            document.removeEventListener('keydown', onEscape, true);
+            document.removeEventListener('scroll', outsideScroll, true);
+            window.removeEventListener('resize', dismiss);
+            window.removeEventListener('blur', dismiss);
+        };
+    }, [position]);
+    if (!position)
+        return null;
+    const navigate = (event) => {
+        const buttons = Array.from(menu.current?.querySelectorAll('button:not(:disabled)') ?? []);
+        const current = buttons.indexOf(document.activeElement);
+        let next = current;
+        if (event.key === 'ArrowDown')
+            next = (current + 1) % buttons.length;
+        else if (event.key === 'ArrowUp')
+            next = (current - 1 + buttons.length) % buttons.length;
+        else if (event.key === 'Home')
+            next = 0;
+        else if (event.key === 'End')
+            next = buttons.length - 1;
+        else if (event.key === 'Tab') {
+            close.current();
+            return;
+        }
+        else
+            return;
+        event.preventDefault();
+        buttons[next]?.focus();
+    };
+    return (_jsx("div", { ref: menu, popover: "manual", className: "pt-context-menu", role: "menu", tabIndex: -1, "aria-label": ariaLabel, onKeyDown: navigate, onContextMenu: (event) => event.preventDefault(), style: { left: position.x, top: position.y }, children: actions.map((action) => (_jsx("button", { type: "button", role: "menuitem", disabled: action.disabled, onClick: () => {
+                onClose();
+                action.onSelect();
+            }, children: action.label }, action.id))) }));
+}

package/dist/density.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentPropsWithRef, CSSProperties } from 'react';
+export type TableDensity = 'native' | 'compact' | 'comfortable';
+export interface DensityMetrics {
+    rowHeight?: number;
+    rowPaddingBlock?: number;
+    rowPaddingInline?: number;
+    iconSize?: number;
+}
+export interface DensityScopeProps extends ComponentPropsWithRef<'div'> {
+    density?: TableDensity;
+    metrics?: DensityMetrics;
+}
+export declare function densityStyle(metrics?: DensityMetrics): CSSProperties;
+/** The same scoped metrics apply to complete tables, custom layouts and browser items. */
+export declare function DensityScope({ density, metrics, className, style, ...props }: DensityScopeProps): import("react").JSX.Element;

package/dist/density.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function densityStyle(metrics = {}) {
+    const properties = {
+        rowHeight: '--pt-row-height',
+        rowPaddingBlock: '--pt-row-padding-block',
+        rowPaddingInline: '--pt-row-padding-inline',
+        iconSize: '--pt-icon-size',
+    };
+    return Object.fromEntries(Object.entries(properties).flatMap(([key, property]) => {
+        const value = metrics[key];
+        if (value === undefined)
+            return [];
+        if (!Number.isFinite(value) ||
+            value < 0 ||
+            ((key === 'rowHeight' || key === 'iconSize') && value === 0))
+            throw new RangeError(`Invalid density metric: ${key}.`);
+        return [[property, `${value}px`]];
+    }));
+}
+/** The same scoped metrics apply to complete tables, custom layouts and browser items. */
+export function DensityScope({ density = 'native', metrics, className = '', style, ...props }) {
+    return (_jsx("div", { ...props, className: `pt-density ${className}`, "data-pt-density": density, "data-pt-metrics": metrics ? 'custom' : undefined, style: { ...densityStyle(metrics), ...style } }));
+}

package/dist/index.d.ts

@@ -1,12 +1,18 @@
+export { ColumnBrowser, ColumnBrowserItem, type ColumnBrowserItemProps, type ColumnBrowserPanel, type ColumnBrowserProps, type ColumnBrowserWidths, } from './column-browser.js';
+export { type ColumnBrowserLayoutOptions, fitColumnBrowser } from './column-browser-layout.js';
+export { ContextMenu, type ContextMenuAction, type ContextMenuPosition, type ContextMenuProps, useContextMenu, } from './context-menu.js';
+export { type DensityMetrics, DensityScope, type DensityScopeProps, type TableDensity, } from './density.js';
 export { createPuppertinoColumnHelper, type PuppertinoColumnDef, type PuppertinoTableInstance, puppertinoTableFeatures, } from './model.js';
 export { ColumnResizeHandle } from './resize-handle.js';
 export type { ColumnResizeHandleProps, ColumnResizeOptions } from './resize-types.js';
 export { RowSelectionCheckbox } from './row-selection-checkbox.js';
+export { applySelectionGesture, type SelectionGestureResult, type SelectionModifiers, } from './selection-gestures.js';
 export { type ColumnSizeBounds, clampSize, columnSizeBounds, readColumnSizing } from './sizing.js';
 export { PuppertinoTable } from './table.js';
 export { TableBody } from './table-body.js';
 export { TableHeader } from './table-header.js';
-export type { PuppertinoTableOptions } from './table-options.js';
+export type { PuppertinoTableAtoms, PuppertinoTableOptions } from './table-options.js';
 export type { PuppertinoBodyContext, PuppertinoBodyOptions, PuppertinoCell, PuppertinoCellProps, PuppertinoDataAttributes, PuppertinoRow, PuppertinoRowProps, PuppertinoTableProps, RowSelectionCheckboxProps, TableBodyProps, TableHeaderProps, } from './table-types.js';
 export { useColumnResize } from './use-column-resize.js';
 export { usePuppertinoTable } from './use-puppertino-table.js';
+export { type RowSelectionGestureOptions, useRowSelectionGestures, } from './use-row-selection-gestures.js';

package/dist/index.js

@@ -1,9 +1,15 @@
+export { ColumnBrowser, ColumnBrowserItem, } from './column-browser.js';
+export { fitColumnBrowser } from './column-browser-layout.js';
+export { ContextMenu, useContextMenu, } from './context-menu.js';
+export { DensityScope, } from './density.js';
 export { createPuppertinoColumnHelper, puppertinoTableFeatures, } from './model.js';
 export { ColumnResizeHandle } from './resize-handle.js';
 export { RowSelectionCheckbox } from './row-selection-checkbox.js';
+export { applySelectionGesture, } from './selection-gestures.js';
 export { clampSize, columnSizeBounds, readColumnSizing } from './sizing.js';
 export { PuppertinoTable } from './table.js';
 export { TableBody } from './table-body.js';
 export { TableHeader } from './table-header.js';
 export { useColumnResize } from './use-column-resize.js';
 export { usePuppertinoTable } from './use-puppertino-table.js';
+export { useRowSelectionGestures, } from './use-row-selection-gestures.js';

package/dist/selection-gestures.d.ts

@@ -0,0 +1,14 @@
+import type { RowSelectionState } from '@tanstack/react-table';
+/** Normal click replaces, toggle-click toggles, and Shift extends a fixed anchor. */
+export interface SelectionModifiers {
+    shift?: boolean;
+    toggle?: boolean;
+}
+export interface SelectionGestureResult {
+    selection: RowSelectionState;
+    anchor: string | null;
+}
+/** Caller-owned order can include leading items and custom layouts, not only table rows.
+ * Toggle gestures preserve selections outside that order; replacing gestures clear them.
+ */
+export declare function applySelectionGesture(orderedIds: readonly string[], selection: RowSelectionState, anchor: string | null, id: string, { shift, toggle }?: SelectionModifiers): SelectionGestureResult;

package/dist/selection-gestures.js

@@ -0,0 +1,21 @@
+/** Caller-owned order can include leading items and custom layouts, not only table rows.
+ * Toggle gestures preserve selections outside that order; replacing gestures clear them.
+ */
+export function applySelectionGesture(orderedIds, selection, anchor, id, { shift = false, toggle = false } = {}) {
+    const ids = [...new Set(orderedIds)];
+    const end = ids.indexOf(id);
+    if (end === -1)
+        return { selection, anchor };
+    const start = anchor === null ? -1 : ids.indexOf(anchor);
+    if (shift && start !== -1) {
+        const range = Object.fromEntries(ids.slice(Math.min(start, end), Math.max(start, end) + 1).map((key) => [key, true]));
+        return { selection: toggle ? { ...selection, ...range } : range, anchor };
+    }
+    if (toggle) {
+        const next = { ...selection, [id]: true };
+        if (selection[id] === true)
+            delete next[id];
+        return { selection: next, anchor: id };
+    }
+    return { selection: { [id]: true }, anchor: id };
+}