comins-table 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.1.8 - 2026-08-28
+
+- Added responsive left/right Column Pinning for leaf Columns and atomic Header Groups, including persisted pin intent, position locking, resize-aware sticky offsets, wider-side inner-block demotion with a 48px center budget, opaque Header/Body/Skeleton/Summary surfaces, and Summary `colSpan` zone splitting while keeping full-width structural Rows non-sticky.
+- Added application-created Cross-Table Drag Coordinators for flat and grouped Rows and complete Group bundles, target-owned permission and reject/overwrite conflict callbacks, persistent empty Groups, immutable atomic source/target results, destination focus recovery, duplicate registration fail-closed behavior, and target-only vertical edge auto-scroll.
+- Added matching Korean/English Playground routes and public guides for Column Pinning and Cross-Table Row/Group Drag, including model ownership, supported combinations, destructive overwrite semantics, layout persistence, and responsive behavior.
+- Added non-blocking pointer-adjacent `Duplicate ID` rejection feedback with a reusable internal Tooltip Surface, restrained target outline, viewport collision handling, accessible live status, renderer/duration/disable controls, CSS theme tokens, and structured `onTransferRejected` notifications.
+- Corrected the Column Pinning Playground to guarantee observable horizontal overflow, and capped direct resize of effective pinned Columns and Header Groups at the 48px center budget so the active pinned surface no longer demotes beneath scrolling content.
+- Moved the single native horizontal scrollbar to the bottom of the complete Table, after Summary when configured, while preserving Body wheel input, vertical virtualization, synchronized Header/Body/Summary scrolling, and a visible final Row boundary when native scrollbar chrome auto-hides.
+- Corrected the bottom scrollbar range to use the Body's actual horizontal viewport width across native scrollbar layouts, so direct rail input reaches the final horizontal content without desynchronizing Header, Body, or Summary.
+
+## 0.1.7 - 2026-08-27
+
+- Added controlled client-side Column Filtering with text, number, UTC calendar-day date, and boolean operators; application-owned Filter/open-popover state; semantic Header controls; filtered sorting, pagination, virtualization, Summary, and Row Grouping projection; explicit Group preservation; Row Drag and remote/Tree exclusions; and matching Korean/English Playground documentation.
+- Added controlled client-side single-depth Row Grouping with application-owned ordered Groups and persistent empty Groups, Group CRUD ownership, Group/Row Drag including cross-Group Row moves, full-width custom-renderable Group Rows, typed per-Group Row `className`/`style`, neutral-gray theme tokens, expand/fold Ref methods, per-Group Row sorting, built-in aggregation, fixed/mixed virtualization, leaf-only selection and Clipboard semantics, grouped Row Detail, runtime/type exclusions, and matching Korean/English Playground documentation.
+- Corrected the Row Grouping Playground layout so every Table fills its example container without clipping or unused fixed-height space, and demonstrated custom Group content and Group Row styling together.
+- Added a fail-closed, value-free npm maintainer identity gate immediately before trusted staged publishing.
+
 ## 0.1.6 - 2026-08-14
 
 - Updated automatic Row Detail measurement to apply each accepted Detail delta through the virtual height index in O(log N), preserving coalesced scroll-anchor correction; observer reads now use one atomically committed `{ projection, contentWidth, viewportHeight }` snapshot, including concurrent Suspense and StrictMode coverage.

package/README.md

@@ -1,6 +1,6 @@
 # Comins Table
 
-Comins Table is a controlled React data table for data-heavy application screens, with virtualized rendering, precise selection, movable headers, controlled Row Expand Details, Summary Row aggregation, Tree Grid data, built-in component cells, and framework-independent core helpers.
+Comins Table is a controlled React data table for data-heavy application screens, with virtualized rendering, precise selection, movable and pinned headers, controlled Column Filtering, Row Grouping and Row Expand Details, Cross-Table Row/Group Drag, Summary Row aggregation, Tree Grid data, built-in component cells, and framework-independent core helpers.
 
 [![npm version](https://img.shields.io/npm/v/comins-table)](https://www.npmjs.com/package/comins-table)
 [![TypeScript declarations](https://img.shields.io/npm/types/comins-table)](https://www.npmjs.com/package/comins-table)
@@ -15,8 +15,8 @@ Comins Table is a controlled React data table for data-heavy application screens
 | --- | --- |
 | Controlled data | Application-owned `data`, CRUD helpers, `onChangeData`, pagination, sorting, and layout callbacks |
 | Rendering and scale | Fixed-height virtualization with a tested 100,000-row route, infinite scroll, append-mode lazy loading, loading, and empty states |
-| Interaction | Accessible single and opt-in multi-column Header sorting, resize, 6-pixel horizontal column reorder with source placeholder, Row and Cell selection, ranges, clipboard, and context menu callbacks |
-| Data structure | Controlled flat Row Expand Details, Summary Row aggregation, and controlled Tree Grid expand/fold |
+| Interaction | Accessible single and opt-in multi-column Header sorting, controlled Column Filtering, resize, responsive Column Pinning, 6-pixel horizontal column reorder, Cross-Table Row/Group Drag, Row and Cell selection, ranges, clipboard, and context menu callbacks |
+| Data structure | Controlled client-side flat Row Grouping, flat Row Expand Details, Summary Row aggregation, and controlled Tree Grid expand/fold |
 | Custom UI | Cell/Header renderers, built-in button/input/checkbox/radio/select/toggle/progress/menu/Virtual List components, and CSS-variable themes |
 
 Comins Table is standalone and does not wrap another table or grid implementation.
@@ -136,6 +136,10 @@ A left-button mouse interaction activates column movement after a 6-pixel horizo
 
 Use `getColumnLayout()` and `setColumnLayout()` through the Ref API, or `serializeCominsColumnLayout()` and `applyCominsColumnLayout()` from `comins-table/core`, to persist and restore order, widths, and visibility.
 
+Set `pinned: "left"` or `pinned: "right"` on a Column or Header Group to keep its atomic block visible during horizontal scrolling and lock its configured position. Direct resize of an effective pinned block stops before it would consume the 48px center budget and demote itself; independent container resize can still temporarily demote inner pinned blocks without changing the persisted layout intent. Header, Body, Skeleton, and Summary use the same offsets; Group Rows and Row Details remain full-width non-sticky cells. See the [Column Pinning guide](https://github.com/kim1124/comins-table/blob/main/docs/user/22-column-pinning.md) and [`/examples/column-pinning`](http://127.0.0.1:4002/examples/column-pinning).
+
+When columns overflow horizontally, Comins Table renders one native horizontal scrollbar at the bottom of the complete Table. A configured Summary Row stays above that scrollbar, while Body trackpad or Shift-wheel input and direct scrollbar input keep Header, Body, and Summary `scrollLeft` synchronized.
+
 ## Rows, Cells, And Selection
 
 Rows expose click, double-click, keyboard, and context-menu callbacks. Cells expose the corresponding Cell callbacks plus `format`, `renderer`, and props hooks.
@@ -164,6 +168,36 @@ Row Expand is controlled by stable owner business Row IDs. An interactive disclo
 
 Tree Grid Row Details, general automatic height for owner data Rows, and nested Details managed by Comins Table remain unsupported.
 
+## Row Grouping
+
+See the [Row Grouping guide](https://github.com/kim1124/comins-table/blob/main/docs/user/20-row-grouping.md) and run the [`/examples/row-grouping`](http://127.0.0.1:4002/examples/row-grouping) Playground route.
+
+`rowGrouping.groups` is an application-owned single-depth Group model whose array order remains the actual display order, including empty Groups. Stable Group IDs control expansion, Group Drag reorders the `groups` model, and existing Row Drag can reorder within a Group or use `setRowGroupId` to move across Groups. Applications own Group CRUD and write `onChangeGroups`, `onChangeData`, and expansion callbacks back to their controlled state. Pure `moveCominsRowGroup` and `moveCominsRowToGroup` helpers provide the corresponding JavaScript model transitions.
+
+Each synthetic Group Row is one full-width colspan Cell with a distinct neutral-gray background. Use `getGroupRowProps` for a typed per-Group `className` or `style`, and override `--comins-table-group-row-background` and `--comins-table-group-row-color` for theme-level styling. The Table owns disclosure and Drag controls while `renderGroupContent` can replace its inner label, count, aggregate, badge, or business-action content. Header sorting never reorders Groups; the existing Row sort policy runs independently inside every Group. Built-in `count`, `sum`, `avg`, `min`, and `max` aggregations remain available.
+
+Synthetic Group Rows never masquerade as `TData`: ordinary Row/Cell callbacks, selection, Clipboard, Cell renderers, formatters, and Row Detail remain leaf-only. Row Grouping supports fixed-height virtualization and grouped leaf Row Detail, but cannot be combined with pagination, infinite/lazy loading, or Tree Grid. Multi-depth grouping remains deferred.
+
+## Cross-Table Row And Group Drag
+
+See the [Cross-Table Drag guide](https://github.com/kim1124/comins-table/blob/main/docs/user/23-cross-table-drag.md) and run the [`/examples/cross-table-drag`](http://127.0.0.1:4002/examples/cross-table-drag) Playground route.
+
+Create a `createCominsTableTransferCoordinator()` and pass the same Coordinator, `scope`, and unique `tableId` through `tableTransfer` to participating Tables. Existing Row Drag moves one Row between compatible flat or grouped Tables. Group Drag moves the Group plus every member Row; moving the last Row preserves the empty source Group, while moving a Group removes it from the source model.
+
+Duplicate IDs reject by default. A rejected duplicate displays a post-drop, pointer-adjacent `Duplicate ID` Tooltip and a restrained target Table outline without intercepting pointer events. The target can replace the Tooltip body through `rejectionFeedback.renderTooltip`, change its duration, disable default feedback, and customize its CSS variables. `Coordinator.onTransferRejected` receives the structured duplicate conflict for application Toasts or logging.
+
+The target can reject through `canTransfer` or explicitly return `"overwrite"` from `resolveConflict`; Group overwrite replaces the complete target Group bundle and never merges it. The Coordinator emits one immutable source/target result, and the application applies both controlled models atomically. Cross-Table Transfer is unavailable with Tree Grid, Column Filtering, Infinite Scroll, and Lazy Load.
+
+## Column Filtering
+
+See the [Column Filtering guide](https://github.com/kim1124/comins-table/blob/main/docs/user/21-column-filtering.md) and run the [`/examples/column-filtering`](http://127.0.0.1:4002/examples/column-filtering) Playground route.
+
+Each Column opts into `text`, `number`, UTC calendar-day `date`, or `boolean` filtering through `columns[].filter`. The application owns the complete `columnFiltering.model` and the currently open Header Filter popover. Rules across Columns use AND; invalid rules are ignored, text comparison is case-insensitive by default, and `between` uses an inclusive normalized range.
+
+Filtering runs before Row Grouping membership, sorting, flat pagination, virtualization, and Summary aggregation. Explicit Group positions and empty Groups remain visible while counts and aggregates use filtered leaf Rows. Header sorting does not change the Filter model. Selected Row and expanded Detail IDs remain dormant when hidden, while invalid hidden Cell/range addresses are cleared.
+
+Column Filtering cannot be combined with Tree Grid, Infinite/Lazy Loading, `loadingMore`, or Row Drag. Group Drag remains available in the supported Row Grouping combination because it changes only the explicit Group model.
+
 ## Virtualization And Loading
 
 Set `virtualized`, `rowHeight`, and `"buffer-size"` for fixed-height windowed rendering. The performance Playground includes a tested 100,000-row route while keeping only the current window and buffer mounted.
@@ -200,7 +234,7 @@ Use `exportCominsRowsToCsv` and `exportCominsRowsToJson` with the exact rows and
 
 The package stylesheet exposes module-local `--comins-table-*` CSS variables and does not apply a global reset. The six shipped theme classes are `comins-table-theme--basic`, `comins-table-theme--dark`, `comins-table-theme--skyblue`, `comins-table-theme--mint`, `comins-table-theme--gray`, and `comins-table-theme--orange`.
 
-Use `theme.className`, `theme.style`, Row class/style hooks, Cell props, and renderer output for application-specific presentation. Keep virtualized `rowHeight` aligned with `--comins-table-row-height` when overriding height tokens.
+Use `theme.className`, `theme.style`, Row and Group Row class/style hooks, Cell props, and renderer output for application-specific presentation. Keep virtualized `rowHeight` aligned with `--comins-table-row-height` when overriding height tokens.
 
 ## Ref API
 
@@ -234,17 +268,17 @@ tableRef.current?.fold(); // all Tree Grid branches
 npm run dev
 ```
 
-The local Playground starts at [`/docs/getting-started`](http://127.0.0.1:4002/docs/getting-started). Key routes include [`/examples/selection-clipboard`](http://127.0.0.1:4002/examples/selection-clipboard), [`/examples/row-expand`](http://127.0.0.1:4002/examples/row-expand), [`/examples/summary-row`](http://127.0.0.1:4002/examples/summary-row), [`/examples/tree-grid`](http://127.0.0.1:4002/examples/tree-grid), [`/examples/component`](http://127.0.0.1:4002/examples/component), and [`/performance/virtualization`](http://127.0.0.1:4002/performance/virtualization).
+The local Playground starts at [`/docs/getting-started`](http://127.0.0.1:4002/docs/getting-started). Key routes include [`/examples/selection-clipboard`](http://127.0.0.1:4002/examples/selection-clipboard), [`/examples/row-expand`](http://127.0.0.1:4002/examples/row-expand), [`/examples/row-grouping`](http://127.0.0.1:4002/examples/row-grouping), [`/examples/column-filtering`](http://127.0.0.1:4002/examples/column-filtering), [`/examples/summary-row`](http://127.0.0.1:4002/examples/summary-row), [`/examples/tree-grid`](http://127.0.0.1:4002/examples/tree-grid), [`/examples/component`](http://127.0.0.1:4002/examples/component), and [`/performance/virtualization`](http://127.0.0.1:4002/performance/virtualization).
 
 ## Documentation
 
-Start with the [English Quick Start](https://github.com/kim1124/comins-table/blob/main/docs/user/01-quick-start.md), then browse [all English feature guides](https://github.com/kim1124/comins-table/tree/main/docs/user). The detailed [Tree Grid](https://github.com/kim1124/comins-table/blob/main/docs/user/17-tree-grid.md), [Summary Row](https://github.com/kim1124/comins-table/blob/main/docs/user/18-summary-row.md), and [Row Expand](https://github.com/kim1124/comins-table/blob/main/docs/user/19-row-expand.md) contracts include runnable examples and edge cases. [Korean guides](https://github.com/kim1124/comins-table/tree/main/docs/ko) are retained as secondary documentation.
+Start with the [English Quick Start](https://github.com/kim1124/comins-table/blob/main/docs/user/01-quick-start.md), then browse [all English feature guides](https://github.com/kim1124/comins-table/tree/main/docs/user). The detailed [Tree Grid](https://github.com/kim1124/comins-table/blob/main/docs/user/17-tree-grid.md), [Summary Row](https://github.com/kim1124/comins-table/blob/main/docs/user/18-summary-row.md), [Row Expand](https://github.com/kim1124/comins-table/blob/main/docs/user/19-row-expand.md), [Row Grouping](https://github.com/kim1124/comins-table/blob/main/docs/user/20-row-grouping.md), and [Column Filtering](https://github.com/kim1124/comins-table/blob/main/docs/user/21-column-filtering.md) contracts include runnable examples and edge cases. [Korean guides](https://github.com/kim1124/comins-table/tree/main/docs/ko) are retained as secondary documentation.
 
 Use the [source repository](https://github.com/kim1124/comins-table) for development context, review the [changelog](https://github.com/kim1124/comins-table/blob/main/CHANGELOG.md) for version history, and follow the [security policy](https://github.com/kim1124/comins-table/blob/main/SECURITY.md) for vulnerability reporting.
 
 ## Current Boundaries
 
-Comins Table currently ships a CSR controlled data model. Server-side Row models, Row grouping, pivoting, charts, AI assistance, remote Tree loading, hierarchy pagination, Tree Row drag, Tree Row copy/paste, Tree Grid Row Details, general automatic owner Row height, nested managed Details, Firefox, Safari, and SSR are not shipped or supported.
+Comins Table currently ships a CSR controlled data model. Server-side Row models and filtering, custom Filter editor renderers, Tree filtering, pivoting, charts, AI assistance, remote Tree loading, hierarchy pagination, Tree Row drag, Tree Row copy/paste, Tree Grid Row Details, general automatic owner Row height, nested managed Details, Firefox, Safari, and SSR are not shipped or supported.
 
 The visual fill handle is not shipped or supported. `fillCominsCellRange` remains available as a core helper without a drag-handle UI.
 

package/dist/clipboard.js

@@ -1,2 +1,2 @@
-import { copyCominsCell as e, copyCominsCellRange as t, copyCominsRow as n, fillCominsCellRange as r, pasteCominsCell as i, pasteCominsCellRange as a, pasteCominsRow as o } from "./core.js";
-export { e as copyCominsCell, t as copyCominsCellRange, n as copyCominsRow, r as fillCominsCellRange, i as pasteCominsCell, a as pasteCominsCellRange, o as pasteCominsRow };
+import { M as e, N as t, P as n, c as r, o as i, p as a, s as o } from "./core-BF1H3EEK.js";
+export { i as copyCominsCell, o as copyCominsCellRange, r as copyCominsRow, a as fillCominsCellRange, e as pasteCominsCell, t as pasteCominsCellRange, n as pasteCominsRow };

package/dist/column-filter.d.ts

@@ -0,0 +1,11 @@
+import { type CominsColumnFilterKind, type CominsColumnFilterRule, type CominsNormalizedColumnFilterRule } from "./filtering";
+export declare function CominsColumnFilterControl<TData>({ columnId, columnLabel, kind, onChangeRule, onOpenChange, open, rule, }: {
+    columnId: string;
+    columnLabel: string;
+    kind: CominsColumnFilterKind;
+    onChangeRule?: (rule: CominsColumnFilterRule | null) => void;
+    onOpenChange?: (columnId: string | null) => void;
+    open: boolean;
+    rule?: CominsNormalizedColumnFilterRule<TData>;
+}): import("react").JSX.Element;
+//# sourceMappingURL=column-filter.d.ts.map

package/dist/column-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-filter.d.ts","sourceRoot":"","sources":["../src/column-filter.tsx"],"names":[],"mappings":"AAQA,OAAO,EAEL,KAAK,sBAAsB,EAE3B,KAAK,sBAAsB,EAC3B,KAAK,gCAAgC,EACtC,MAAM,aAAa,CAAC;AAgErB,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,EAC/C,QAAQ,EACR,WAAW,EACX,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,IAAI,GACL,EAAE;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,sBAAsB,CAAC;IAC7B,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,KAAK,IAAI,CAAC;IAC7D,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACjD,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,gCAAgC,CAAC,KAAK,CAAC,CAAC;CAChD,+BAkRA"}

package/dist/column-pinning.d.ts

@@ -0,0 +1,25 @@
+export type CominsColumnPinned = "left" | "right";
+export type CominsColumnPinningBlock = {
+    columnIds: readonly string[];
+    columnWidths: readonly number[];
+    id: string;
+    pinned?: CominsColumnPinned;
+};
+export type CominsResolvedPinnedColumn = {
+    boundary?: boolean;
+    offset?: number;
+    pinned?: CominsColumnPinned;
+};
+export type CominsResolvedColumnPinning = {
+    columns: ReadonlyMap<string, CominsResolvedPinnedColumn>;
+    orderedColumnIds: readonly string[];
+};
+export type CominsColumnPinningSpanFragment = CominsResolvedPinnedColumn & {
+    colSpan: number;
+    startIndex: number;
+};
+export declare function normalizeCominsColumnPinned(value: unknown): CominsColumnPinned | undefined;
+export declare function resolveCominsColumnPinning(blocks: readonly CominsColumnPinningBlock[], containerWidth: number): CominsResolvedColumnPinning;
+export declare function getCominsPinnedBlockResizeMaxWidth(blocks: readonly CominsColumnPinningBlock[], resolved: CominsResolvedColumnPinning, blockId: string, containerWidth: number, minimumCenterWidth?: number): number | undefined;
+export declare function getCominsColumnPinningSpanFragments(resolved: CominsResolvedColumnPinning, startIndex: number, colSpan: number): CominsColumnPinningSpanFragment[];
+//# sourceMappingURL=column-pinning.d.ts.map

package/dist/column-pinning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-pinning.d.ts","sourceRoot":"","sources":["../src/column-pinning.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IACzD,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,0BAA0B,GAAG;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAE1F;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,wBAAwB,EAAE,EAC3C,cAAc,EAAE,MAAM,GACrB,2BAA2B,CAoF7B;AAED,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,SAAS,wBAAwB,EAAE,EAC3C,QAAQ,EAAE,2BAA2B,EACrC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,kBAAkB,SAAK,GACtB,MAAM,GAAG,SAAS,CA+BpB;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,2BAA2B,EACrC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,+BAA+B,EAAE,CA+BnC"}