comins-table 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -1,6 +1,44 @@
 # Comins Table
 
-## Unreleased
+## 0.1.10 (Unreleased)
+
+### Added
+
+- Controlled Tree Row drag at every depth through `treeRowDrag`, with opt-in `allowReparent`, immutable `moveCominsTreeNode` subtree moves, drop validation, drag lifecycle callbacks, and pointer/keyboard navigation through virtualized Rows.
+- Numeric per-Row and automatic business Row heights through `getRowHeight` and `estimatedRowHeight`, shared mounted-row measurement, variable-height virtualization, and scroll-anchor preservation. Flat, Grouped business, and Tree Rows are supported; expanded Row Details are measured independently.
+- Known-count Viewport Datasource loading through `useCominsViewport`, with controlled snapshot/reducer APIs, bounded data and height caches, cancellable range requests, stale-response protection, explicit retry, absolute-index callbacks, and loaded Cell editing. Automatic heights, distant scrolling, and cache eviction/remeasurement are supported; server queries and edit persistence remain application-owned.
+- Independent Row/Cell selection through `rowSelectionOnClick={false}`, plus `getSelectedRows()`, `getSelectedCells()`, and `getSelection()` Ref APIs. Reads return available data without requesting unloaded Viewport Rows.
+- Opt-in OS keyboard copy through `clipboard` and explicit `copySelection("auto" | "cells" | "rows")`. Automatic copy prioritizes multiple Cells, selected Rows, then a single Cell. Discontiguous selection produces a TSV rectangle with empty unselected positions; internal paste skips those positions.
+- Matching English/Korean guides and Playground routes for automatic height and Viewport loading, with public type checks, browser geometry coverage, and focused performance budgets.
+
+### Changed
+
+- Aligned Playground Column labels with data keys. CRUD uses `column1` through `column6` and preserves its `column4` Row ID when editing.
+- Expanded the Lazy Load example to 1,000 deterministic Rows in batches of 100, with simulated asynchronous delay and cancellation.
+- Equalized initial sibling Header Group widths, enabled movement in the Column Pinning Group example, moved movement restrictions into Row Grouping controls, and aligned Summary label/value spans with visible Columns and pin boundaries.
+- Enabled parent changes and automatic height by default in the Tree drag Playground example. Package defaults remain opt-in: `treeRowDrag` is omitted, `allowReparent` is false, automatic height requires `getRowHeight`, `rowSelectionOnClick` is true, and `clipboard` is false.
+
+### Fixed
+
+- Kept populated-table loading overlays visible when reloading after scrolling.
+- Restored Tree drag focus after controlled data and virtual-window updates, and Header Menu Escape handling from menu items. Connected Playground Group disclosure state and added Context Menu keyboard navigation and focus recovery.
+- Corrected Boolean Cell formatting and kept fixed-height Viewport Renderer content within its chosen height.
+- Fixed Cell pointer and Shift-range focus so keyboard copy uses selected values instead of page text, while preserving native interaction with Renderer controls. Keyboard copy refreshes the internal paste buffer for the latest selection.
+
+### Compatibility notes
+
+- Existing fixed-height rendering, Row-click selection, and internal clipboard behavior remain the defaults. OS clipboard import/paste is not included; Ctrl/Cmd+V continues to use the Table's internal buffer.
+- Viewport requires a known count, stable globally unique Row IDs, and arbitrary index-range access. It does not combine with Tree, Row Grouping, Row Detail, Row Drag, append loading, pagination, built-in sorting/filtering, or automatic Summary aggregation.
+- Tree parent changes remain explicit, active sorting disables manual Tree movement, and cross-table Tree movement and Tree Row copy/paste remain unsupported.
+
+## 0.1.9 - 2026-08-31
+
+- Added the packaged `DESIGN.md`, componentization guidance, a canonical Feature Manifest, full public-export and CSS-token classification, structured feature restrictions, and annotated/typechecked documentation examples.
+- Added Ctrl/Cmd discontiguous Cell selection while preserving the active Cell and rectangular range contracts, plus Row Drag lifecycle callbacks for before-start cancellation, semantic target changes, and final moved/cancelled/rejected results.
+- Preserved the last known Column order when dynamic Header Group Columns are hidden and restored, kept Row Group content visible during horizontally pinned scrolling, and connected Header Group and Rows Playground drag examples to controlled data and lifecycle feedback.
+- Standardized Playground toggle contrast, added deterministic collapse-all-Details coverage, and retained the existing Summary Row visible-column `colSpan` contract and example.
+- Added localized event and method reference tables above related Playground examples.
+- Clarified the browser compatibility contract versus Chromium-only automated evidence and expanded documentation/package gates so unclassified exports, tokens, examples, restrictions, or missing packaged design guidance fail closed.
 
 ## 0.1.8 - 2026-08-28
 

package/DESIGN.md

@@ -0,0 +1,134 @@
+# Comins Table Design Contract
+
+Comins Table uses a restrained, data-first visual language. The application owns business meaning and data; the Table owns structural clarity, interaction feedback, focus visibility, and consistent state treatment. This document describes the public styling contract shipped with the package stylesheet.
+
+## Principles
+
+- Preserve density without hiding structure: borders, pinned boundaries, Group Rows, Details, and Summary remain distinguishable.
+- Use color to communicate state, not decoration. Selection and valid actions use the accent family; invalid and rejected drops use the danger family.
+- Keep focus visible independently from hover and selection.
+- Keep application overrides local. Importing `comins-table/styles.css` does not install a global reset.
+- Prefer container-driven behavior. Horizontal overflow, responsive pin demotion, and compact density respond to the Table container rather than the browser viewport.
+
+The default stylesheet targets light surfaces. The built-in dark theme supplies its own values. Applications that replace surface tokens are responsible for maintaining readable foreground, border, focus, disabled, and drag-feedback contrast.
+
+## Foundations
+
+Typography inherits the application font. Default text is compact, with Header and control labels using stronger weight rather than larger type. Spacing is based on Cell padding and Row/Header height tokens. Borders are one CSS pixel except for focus, selection, and drop indicators. The outer frame uses a small radius; internal Rows remain square so adjacent borders align.
+
+Motion is limited to short color, opacity, position, and resize feedback. Motion must not delay a model update or hide the final state. Overlays, menus, and Tooltip surfaces render above pinned content; application portals remain application-owned unless a documented Table component explicitly owns the portal.
+
+## Surfaces and states
+
+| Surface | Contract |
+| --- | --- |
+| Frame | Owns the outer border, radius, background, and the final horizontal scrollbar. |
+| Header | Uses an accent surface by default and retains visible focus, resize, sort, move, and pinned boundaries. |
+| Body Cell | Keeps grid borders and application Row backgrounds visible beneath selection indicators. |
+| Group Row | Uses one semantic full-width Cell. Its content remains visible at the Body viewport start during horizontal scrolling. |
+| Detail Row | Follows its owner Row and remains outside Cell selection and Clipboard addressing. |
+| Summary | Uses the same Column geometry and pin zones as Header and Body and remains above the final scrollbar. |
+| Tooltip | Is non-blocking drag feedback with `pointer-events: none`; it does not replace application Toasts or error handling. |
+
+Rest, hover, active, `focus-visible`, selected, disabled, loading, invalid, drag-source, valid-drop, and rejected-drop states must remain visually distinct. A custom renderer may change inner content but must not remove the owning semantic Cell, focus behavior, disabled state, or interaction feedback unless the corresponding public contract explicitly delegates those responsibilities.
+
+## Density and responsive behavior
+
+`theme.density` selects the built-in Row and Header measurements. Applications may override the documented height and padding tokens, but fixed-height virtualization still requires the resolved `rowHeight` contract to match the logical Row height. Pinned zones preserve a center-content budget and may demote inner pinned blocks when the container becomes too narrow; this is a rendering decision and does not change persisted pin intent.
+
+For variable business Row heights, `getRowHeight` owns the layout policy. Returning `"auto"` measures normal-flow Cell content; `estimatedRowHeight` supplies the initial estimate without imposing a limit on the Renderer. Group headings retain their fixed `rowHeight`, and Row Details keep their independent height policy. CSS height overrides alone do not update virtual geometry. Viewport loading estimates unloaded heights and may adjust the scrollbar as content is measured.
+
+## CSS token stability
+
+The canonical machine-readable inventory is `docs/feature-manifest.json`. Stability means:
+
+- `public-stable`: supported theme input. Removal or incompatible meaning requires a breaking release.
+- `public-experimental`: available for advanced styling, but name or behavior may change in a minor release with CHANGELOG notice.
+- `internal`: implementation plumbing. Do not override it in application styles.
+
+### Public stable
+
+```text
+--comins-table-accent
+--comins-table-accent-foreground
+--comins-table-accent-soft
+--comins-table-background
+--comins-table-border
+--comins-table-cell-border
+--comins-table-cell-height
+--comins-table-focus
+--comins-table-foreground
+--comins-table-group-row-background
+--comins-table-group-row-color
+--comins-table-header-background
+--comins-table-header-border
+--comins-table-header-color
+--comins-table-header-split-border
+--comins-table-range-background
+--comins-table-row-border
+--comins-table-row-disabled-background
+--comins-table-row-disabled-color
+--comins-table-row-even-background
+--comins-table-row-height
+--comins-table-row-odd-background
+--comins-table-row-selected-background
+--comins-table-scrollbar-corner
+--comins-table-scrollbar-thumb
+--comins-table-scrollbar-track
+--comins-table-tooltip-danger-background
+--comins-table-tooltip-danger-border
+--comins-table-tooltip-danger-color
+--comins-table-tooltip-danger-muted
+--comins-table-tooltip-shadow
+```
+
+### Public experimental
+
+```text
+--comins-table-accent-strong
+--comins-table-cell-background
+--comins-table-cell-color
+--comins-table-cell-padding-x
+--comins-table-cell-padding-y
+--comins-table-component-accent
+--comins-table-component-accent-foreground
+--comins-table-component-accent-soft
+--comins-table-component-accent-strong
+--comins-table-component-border
+--comins-table-component-button-foreground
+--comins-table-component-focus
+--comins-table-component-foreground
+--comins-table-component-muted
+--comins-table-component-surface
+--comins-table-component-surface-muted
+--comins-table-component-virtual-list-height
+--comins-table-detail-background
+--comins-table-detail-border
+--comins-table-detail-padding
+--comins-table-drop-invalid
+--comins-table-drop-invalid-background
+--comins-table-drop-marker
+--comins-table-drop-valid
+--comins-table-drop-valid-background
+--comins-table-header-height
+--comins-table-muted
+--comins-table-resize-handle
+--comins-table-selected-range-background
+--comins-table-skeleton-background
+--comins-table-skeleton-highlight
+--comins-table-surface
+--comins-table-surface-muted
+--comins-table-virtual-list-item-height
+```
+
+### Internal
+
+```text
+--comins-table-row-custom-background
+```
+
+Stable tokens inherit through the Table root and use the current theme value as their fallback. Experimental component and structural tokens fall back to the related stable accent, surface, foreground, border, or resolved Row geometry. Internal tokens have no compatibility guarantee.
+
+## Extension choice
+
+Use a formatter for value presentation, a renderer for typed React content, a built-in component when the Table must own interaction isolation and accessibility, a CSS token for reusable visual policy, and `className`/`style` for one application instance or business state. See the [componentization guide](https://github.com/kim1124/comins-table/blob/main/docs/design/componentization.md) for the full decision contract.

package/README.md

@@ -1,26 +1,44 @@
 # Comins Table
 
-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.
+Comins Table is a controlled React data table for data-heavy application screens. Applications keep ownership of their data and business models while the Table provides virtualized rendering, structured Rows, configurable Headers, precise selection, and customizable cells.
 
 [![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)
 [![Verify](https://github.com/kim1124/comins-table/actions/workflows/verify.yml/badge.svg?branch=main)](https://github.com/kim1124/comins-table/actions/workflows/verify.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-![Comins Table sorting, column reorder, Row selection, Summary Row, and Tree Grid demo](https://raw.githubusercontent.com/kim1124/comins-table/main/docs/assets/comins-table-demo.gif)
+![Comins Table controlled Rows, Column Pinning, Row Grouping, Filtering, Tree Grid, and Cross-Table Drag overview](https://raw.githubusercontent.com/kim1124/comins-table/main/docs/assets/comins-table-overview.gif)
 
 ## Why Comins Table
 
 | Area | Shipped capabilities |
 | --- | --- |
 | 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 |
+| Rendering and scale | Fixed and automatic Row heights, variable-height virtualization, a tested 100,000-row route, bounded Viewport range loading, infinite scroll, append-mode lazy loading, loading, and empty states |
 | 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 |
+| Data structure | Controlled client-side flat Row Grouping, flat Row Expand Details, Summary Row aggregation, and Tree Grid expand/fold and subtree drag |
 | 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.
 
+### Version 0.1.10
+
+This source version adds Tree Row drag, automatic business Row heights with variable-height virtualization, and known-count Viewport Datasource loading. Row and Cell selection can be managed independently, with separate Ref getters and opt-in OS clipboard copying. See the [0.1.10 changelog](https://github.com/kim1124/comins-table/blob/main/CHANGELOG.md) for the complete change list.
+
+### Feature catalog
+
+This catalog is a consumer-oriented summary, not the complete status registry. Use the [Canonical Feature Manifest](https://github.com/kim1124/comins-table/blob/main/docs/feature-manifest.json) and the language indexes for every shipped, unsupported, and evidence-linked feature.
+
+| Area | Shipped capabilities | Live examples | Guides |
+| --- | --- | --- | --- |
+| Getting started | Controlled data, CRUD, Core state, loading, and empty states | [`Getting Started`](http://127.0.0.1:4002/docs/getting-started), [`CRUD`](http://127.0.0.1:4002/examples/crud) | [Quick Start](https://github.com/kim1124/comins-table/blob/main/docs/user/01-quick-start.md), [Data And CRUD](https://github.com/kim1124/comins-table/blob/main/docs/user/02-data-and-crud.md) |
+| Header and layout | Sort, multi-sort, resize, move, Header Groups, Filtering, and Pinning | [`Header`](http://127.0.0.1:4002/examples/header), [`Filtering`](http://127.0.0.1:4002/examples/column-filtering), [`Pinning`](http://127.0.0.1:4002/examples/column-pinning) | [Header](https://github.com/kim1124/comins-table/blob/main/docs/user/06-header.md), [Filtering](https://github.com/kim1124/comins-table/blob/main/docs/user/21-column-filtering.md), [Pinning](https://github.com/kim1124/comins-table/blob/main/docs/user/22-column-pinning.md) |
+| Rows, cells, and selection | Row and Cell callbacks, selection, Clipboard, Context Menu, and Row Expand | [`Selection`](http://127.0.0.1:4002/examples/selection-clipboard), [`Row Expand`](http://127.0.0.1:4002/examples/row-expand) | [Row](https://github.com/kim1124/comins-table/blob/main/docs/user/07-row.md), [Cell](https://github.com/kim1124/comins-table/blob/main/docs/user/08-cell.md), [Selection](https://github.com/kim1124/comins-table/blob/main/docs/user/10-selection.md) |
+| Structured rows | Summary Row, Tree Grid, Row Grouping, and Cross-Table Row/Group Drag | [`Summary`](http://127.0.0.1:4002/examples/summary-row), [`Tree`](http://127.0.0.1:4002/examples/tree-grid), [`Grouping`](http://127.0.0.1:4002/examples/row-grouping), [`Transfer`](http://127.0.0.1:4002/examples/cross-table-drag) | [Summary](https://github.com/kim1124/comins-table/blob/main/docs/user/18-summary-row.md), [Tree](https://github.com/kim1124/comins-table/blob/main/docs/user/17-tree-grid.md), [Grouping](https://github.com/kim1124/comins-table/blob/main/docs/user/20-row-grouping.md), [Transfer](https://github.com/kim1124/comins-table/blob/main/docs/user/23-cross-table-drag.md) |
+| Loading and performance | Pagination, fixed/variable-height virtualization, automatic heights, Viewport Datasource, Infinite Scroll, and Lazy Load | [`Virtualization`](http://127.0.0.1:4002/performance/virtualization), [`Automatic height`](http://127.0.0.1:4002/performance/auto-row-height), [`Viewport`](http://127.0.0.1:4002/performance/viewport-datasource) | [Virtualization](https://github.com/kim1124/comins-table/blob/main/docs/user/11-virtualization.md), [Automatic height](https://github.com/kim1124/comins-table/blob/main/docs/user/24-auto-row-height.md), [Viewport](https://github.com/kim1124/comins-table/blob/main/docs/user/25-viewport-datasource.md), [Lazy Load](https://github.com/kim1124/comins-table/blob/main/docs/user/16-lazy-load.md) |
+| Rendering and styling | Built-in components, custom renderers, themes, CSS variables, and export helpers | [`Components`](http://127.0.0.1:4002/examples/component), [`Theme`](http://127.0.0.1:4002/examples/theme), [`Export`](http://127.0.0.1:4002/examples/export) | [Cell](https://github.com/kim1124/comins-table/blob/main/docs/user/08-cell.md), [Styling](https://github.com/kim1124/comins-table/blob/main/docs/user/04-styling.md), [Export](https://github.com/kim1124/comins-table/blob/main/docs/user/14-export.md) |
+| API and utilities | Ref controls, framework-independent Core helpers, Clipboard, and selection helpers | [`Ref API`](http://127.0.0.1:4002/api/ref), [`Props`](http://127.0.0.1:4002/api/props) | [Core State](https://github.com/kim1124/comins-table/blob/main/docs/user/03-core-state.md), [Clipboard](https://github.com/kim1124/comins-table/blob/main/docs/user/09-clipboard.md) |
+
 ## Support
 
 | Surface | Support |
@@ -34,12 +52,15 @@ Comins Table is standalone and does not wrap another table or grid implementatio
 | SSR | Client boundary required; server rendering is not currently supported |
 | Runtime network behavior | No package-owned requests, remote assets, telemetry, or error reporting |
 
+The Chrome and Edge row is the compatibility contract. The automated browser gate is evidence from Playwright-bundled Chromium only; it is not a claim that Firefox, Safari, or every installed Edge build was tested.
+
 ## Installation
 
 ```bash
 npm install comins-table react react-dom
 ```
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 import { CominsTable, type CominsTableColumn } from "comins-table";
 import "comins-table/styles.css";
@@ -47,8 +68,22 @@ import "comins-table/styles.css";
 
 React and React DOM are peer dependencies. Import `comins-table/styles.css` when the default table shell, themes, and built-in component skin are required.
 
+### Run the Playground locally
+
+The Playground is a repository development server, not a command installed into a consumer application.
+
+```bash
+git clone https://github.com/kim1124/comins-table.git
+cd comins-table
+npm ci
+npm run dev
+```
+
+Open [`http://127.0.0.1:4002/docs/getting-started`](http://127.0.0.1:4002/docs/getting-started).
+
 ## Quick Start
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 import { useState } from "react";
 import { CominsTable, type CominsTableColumn } from "comins-table";
@@ -95,9 +130,9 @@ export function UsersTable() {
 
 ## Controlled Model
 
-Comins Table is a CSR-focused controlled component for application-owned data. The application owns the `data` array.
+Comins Table is a CSR-focused controlled component for application-owned data. The application owns the Row array or Viewport snapshot passed through `data`.
 
-For table-owned data mutations, `onChangeData` emits the next flat Row array or Tree Grid node array; pass that array back through `data` to retain the mutation. Other controlled models use their matching callback and value prop rather than `onChangeData`.
+For table-owned data mutations, `onChangeData` emits the next flat Row array or Tree Grid node array; pass that array back through `data` to retain the mutation. Viewport mode uses a controlled block snapshot instead of a full array; `useCominsViewport` connects that snapshot and its callbacks. Other controlled models use their matching callback and value prop rather than `onChangeData`.
 
 Selection, column layout, and sort are internal view state. `onChangeSelection`, `onChangeColumnLayout`, `onChangeSort`, and `onChangeSortModel` observe those changes so an application can coordinate or persist them externally; the table updates the corresponding view state even when a callback is omitted.
 
@@ -107,6 +142,7 @@ Where restoration is supported, use the supported Ref API: `setSelectedRow` and
 
 Set `multiSort` to opt into ordered multi-column sorting. Normal Header click or `Enter`/`Space` keeps single sorting; hold `Shift` while using the same input to add, update, or remove one rule without replacing the others. Active Headers display their 1-based priority.
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 <CominsTable
   columns={columns}
@@ -136,7 +172,9 @@ 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).
+### Column Pinning
+
+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 spanning cells; Row Group inner content stays visible at the Body viewport start while horizontally scrolling. 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.
 
@@ -144,12 +182,17 @@ When columns overflow horizontally, Comins Table renders one native horizontal s
 
 Rows expose click, double-click, keyboard, and context-menu callbacks. Cells expose the corresponding Cell callbacks plus `format`, `renderer`, and props hooks.
 
-A normal Row interaction selects one Row, `Ctrl`/`Cmd` toggles a Row, and `Shift` extends the visible Row range from the selection anchor. Cell selection supports a single Cell, `Ctrl`/`Cmd` multi-selection, and `Shift` or pointer-drag ranges. Built-in component interactions remain isolated from `onClickCell` and `onClickRow` callback payloads so component actions do not also trigger the owning Cell or Row action.
+A normal Row interaction selects one Row, `Ctrl`/`Cmd` toggles a Row, and `Shift` extends the visible Row range from the selection anchor. Cell selection supports a single Cell, visible `Ctrl`/`Cmd` discontiguous selection, and `Shift` or pointer-drag rectangular ranges. `CominsSelectionState.cell` is the active Cell, `cells` records the discontiguous set, and `range` records the rectangle. Built-in component interactions remain isolated from `onClickCell` and `onClickRow` callback payloads so component actions do not also trigger the owning Cell or Row action.
+
+Set `rowSelectionOnClick={false}` to preserve selected Rows while clicking or right-clicking Cells. Application checkboxes or `setSelectedRows` can control the Row selection independently. `getSelectedRows()`, `getSelectedCells()`, and `getSelection()` read Row data, raw Cell values, and the selection snapshot separately. The default `rowSelectionOnClick={true}` keeps the existing Row-click behavior.
+
+Row Drag exposes `onBeforeRowDrag`, `onRowDrag`, and `onAfterDragRow`. The before callback can cancel prior to listener registration, target updates emit only on identity or validity changes, and the after callback reports one `moved`, `cancelled`, or `rejected` result per started gesture. Data changes remain controlled through `onChangeData` or the Cross-Table Coordinator.
 
 ### Row Expand
 
 See the [Row Expand guide](https://github.com/kim1124/comins-table/blob/main/docs/user/19-row-expand.md) and run the [`/examples/row-expand`](http://127.0.0.1:4002/examples/row-expand) Playground route.
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 const [expandedRowIds, setExpandedRowIds] = useState<readonly string[]>([]);
 
@@ -166,7 +209,7 @@ const [expandedRowIds, setExpandedRowIds] = useState<readonly string[]>([]);
 
 Row Expand is controlled by stable owner business Row IDs. An interactive disclosure requires the application to feed the next value from `onChangeExpandedRowIds` back into `expandedRowIds`; when that callback is omitted, the disclosure is disabled and read-only. A finite positive CSS pixel height is fixed and retains its inline height. Missing values, invalid numeric values, and `"auto"` use measured automatic height with no inline height. Before an automatic Detail has a matching-width measurement, a valid finite positive `estimatedRowDetailHeight` is used; otherwise the resolved `rowHeight` is the estimate. Details render as semantic owner-following Rows, stay outside selection and clipboard addressing, and preserve dormant IDs across sorting and pagination.
 
-Tree Grid Row Details, general automatic height for owner data Rows, and nested Details managed by Comins Table remain unsupported.
+Owner data Rows can use `getRowHeight` independently of Detail height. Tree Grid Row Details and nested Details managed by Comins Table remain unsupported.
 
 ## Row Grouping
 
@@ -176,7 +219,7 @@ See the [Row Grouping guide](https://github.com/kim1124/comins-table/blob/main/d
 
 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.
+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 or automatic business Row heights, variable-height virtualization, and grouped leaf Row Detail; Group headings keep the fixed `rowHeight`. It cannot be combined with pagination, infinite/lazy loading, Viewport Datasource, or Tree Grid. Multi-depth grouping remains deferred.
 
 ## Cross-Table Row And Group Drag
 
@@ -188,6 +231,16 @@ Duplicate IDs reject by default. A rejected duplicate displays a post-drop, poin
 
 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.
 
+## Automatic Heights and Viewport Loading
+
+Use `getRowHeight={() => "auto"}` for content-driven business Row heights, or return a positive number for an individual Row. Omitting the callback keeps the numeric `rowHeight` default of 36. `estimatedRowHeight` supplies an initial estimate, not a height limit. Custom Renderers do not need per-Cell height calculations; use normal-flow content and enable wrapping where required. Automatic heights work with Flat, Grouped business, and Tree Rows, including `treeRowDrag` where that mode supports dragging.
+
+`useCominsViewport({ rowCount, queryKey, getRows })` loads blocks around the scroll region and connects them to the Table through `tableProps`. It enables virtualization and can be combined with `getRowHeight={() => "auto"}`. The application supplies a known total count, globally stable Row IDs, and arbitrary `[startIndex, endIndex)` range requests. Change `queryKey` when server sorting, filtering, or index order changes.
+
+Viewport bounds cached data and measured heights; distant scrolling does not fetch every earlier page or require a full dataset array. Unloaded heights are estimated, so scrollbar size can change as content is measured. Selection getters and copy operate on loaded data without fetching missing Rows. The application owns network requests and edit persistence. Tree, Row Grouping, Row Detail, Row Drag, append loading, pagination, built-in sorting/filtering, and automatic Summary aggregation are unavailable in Viewport mode.
+
+See [automatic height](https://github.com/kim1124/comins-table/blob/main/docs/user/24-auto-row-height.md), [Viewport Datasource](https://github.com/kim1124/comins-table/blob/main/docs/user/25-viewport-datasource.md), and [Tree drag](https://github.com/kim1124/comins-table/blob/main/docs/user/17-tree-grid.md) for examples, defaults, and combination limits.
+
 ## 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.
@@ -200,7 +253,7 @@ Column Filtering cannot be combined with Tree Grid, Infinite/Lazy Loading, `load
 
 ## 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.
+Set `virtualized`, `rowHeight`, and `"buffer-size"` for fixed-height windowed rendering; add `getRowHeight` for numeric per-Row or measured automatic heights. The performance Playground includes a tested 100,000-row route while keeping only the current window and buffer mounted. With ordinary virtualization, the application still supplies the full array. Viewport Datasource additionally bounds loaded data; Infinite Scroll and Lazy Load append to an application-owned array.
 
 `infiniteScroll` requests application-owned append loading near the body viewport boundary. `lazyLoad` supports asynchronous append-mode batches with an `AbortSignal`. When `loading` is true, an empty table renders skeleton Rows and a populated table keeps its Rows visible under a loading overlay. `emptyComponent` controls the no-data content.
 
@@ -218,6 +271,8 @@ Set `tree` and provide controlled `{ item, expand, children }` nodes. `defaultEx
 
 Tree Grid reuses `cell.components` and `cell.renderer`, so component cells and custom React renderers work against each node's `item`. The Tree Grid Playground includes an exactly 10,000-node virtual example.
 
+Set `treeRowDrag={{}}` and connect `onChangeData` to reorder siblings at every depth. `treeRowDrag={{ allowReparent: true }}` also moves entire subtrees between parents or back to the root. Parent changes default to disabled. `canDrop` and Row guards restrict destinations and sources; cycles are rejected and sorting disables manual movement. `moveCominsTreeNode` exposes the immutable move helper. Handles support pointer dragging and Space, arrow keys, Enter, and Escape. The Playground drag example starts with parent changes and automatic heights enabled; these are example settings.
+
 ## Components And Renderers
 
 Cell components include `button`, `input`, `checkbox`, `radio`, `select`, `toggle`, `progress`, and `virtual-list`; Header components also support `menu`. Use `cell.renderer` or `header.renderer` when the built-in component types are not sufficient.
@@ -226,6 +281,10 @@ Virtual List Item activation follows the normal Row selection modifiers. More se
 
 ## Clipboard And Export
 
+Set `clipboard` to enable OS keyboard copy. It defaults to `false`, preserving the existing internal copy buffer. With OS copy enabled, the default priority is multiple selected Cells → selected Rows → one selected Cell. Five selected Rows and three selected Cells copy the three Cells while retaining all five selected Rows. Discontiguous Cells produce a TSV rectangle with unselected positions empty; internal paste skips those positions.
+
+Call `copySelection("auto" | "cells" | "rows")` from a button or context menu to choose the target explicitly. This Ref method writes to the OS clipboard regardless of the `clipboard` prop, returns `Promise<string | null>`, and rejects if writing is unavailable or denied. Native text editing keeps its own copy behavior. Ctrl/Cmd+V uses the Table's internal buffer; importing arbitrary OS clipboard content is outside this version. See the [Clipboard guide](https://github.com/kim1124/comins-table/blob/main/docs/user/09-clipboard.md) for guards, TSV escaping, and loaded-data limits.
+
 `copyCominsRow`, `copyCominsCell`, and `copyCominsCellRange` read Row or Cell selections. `pasteCominsRow`, `pasteCominsCell`, and `pasteCominsCellRange` apply clipboard data while respecting `props.copyable`, `props.pasteable`, and disabled guards. `fillCominsCellRange` remains a framework-independent core helper; no visual fill handle is presented as shipped UI.
 
 Use `exportCominsRowsToCsv` and `exportCominsRowsToJson` with the exact rows and export columns the application wants to serialize. Export remains independent of visible pagination, filtering, and selection unless the application passes those rows.
@@ -234,10 +293,13 @@ 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 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.
+Use `theme.className`, `theme.style`, Row and Group Row class/style hooks, Cell props, and renderer output for application-specific presentation. For uniform fixed-height virtualization, keep `rowHeight` aligned with `--comins-table-row-height` when overriding height tokens. Use `getRowHeight` for variable or automatic business Row heights; CSS height alone does not update the virtual layout.
+
+The [Design Contract](https://github.com/kim1124/comins-table/blob/main/DESIGN.md) classifies every Table token as public stable, public experimental, or internal. The [Componentization Guide](https://github.com/kim1124/comins-table/blob/main/docs/design/componentization.md) defines when to use a formatter, renderer, built-in component, future typed slot, token, or instance override.
 
 ## Ref API
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 const tableRef = useRef<CominsTableRef<UserRow>>(null);
 
@@ -253,6 +315,11 @@ tableRef.current?.setSortModel([
 tableRef.current?.clearSort();
 tableRef.current?.setSelectedRow(0);
 tableRef.current?.setSelectedRows([0, 1]);
+tableRef.current?.getSelectedRows();
+tableRef.current?.getSelectedCells();
+tableRef.current?.getSelection();
+// In a user-initiated handler; handle unavailable or denied clipboard access:
+await tableRef.current?.copySelection("rows");
 tableRef.current?.setMoveTargetRow(3, 1);
 tableRef.current?.expand(["department-1", "team-1-1"]);
 tableRef.current?.fold(["team-1-1"]);
@@ -260,25 +327,23 @@ tableRef.current?.expand(); // all Tree Grid branches
 tableRef.current?.fold(); // all Tree Grid branches
 ```
 
-`setSelectedRow`, `setSelectedRows`, and `setMoveTargetRow` use the visible Row index after current sorting and pagination. `getColumnLayout`, `setColumnLayout`, `getSortState`, `setSortState`, `getSortModel`, `setSortModel`, and `clearSort` read and update the current Header view state. `expand(nodeIds?)` and `fold(nodeIds?)` accept readonly Tree Grid node-id arrays; flat tables ignore them.
+For ordinary array-backed Tables, `setSelectedRow`, `setSelectedRows`, and `setMoveTargetRow` use the visible Row index after current sorting and pagination. Viewport selection setters use absolute dataset indexes and skip unloaded Rows; movement is unavailable. `getColumnLayout`, `setColumnLayout`, `getSortState`, `setSortState`, `getSortModel`, `setSortModel`, and `clearSort` read and update the current Header view state. `expand(nodeIds?)` and `fold(nodeIds?)` accept readonly Tree Grid node-id arrays; flat tables ignore them.
 
-## Playground
+`getSelectedRows()` returns loaded selected business data in data order. `getSelectedCells()` returns `{ rowId, columnId, value }` for available selected Cells; ranges use projected display order. `getSelection()` copies the selection IDs and addresses, including Row IDs retained after Viewport cache eviction. Row objects and Cell values remain application-owned references.
 
-```bash
-npm run dev
-```
+## Playground
 
-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).
+After the repository setup under Installation, 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/column-pinning`](http://127.0.0.1:4002/examples/column-pinning), [`/examples/cross-table-drag`](http://127.0.0.1:4002/examples/cross-table-drag), [`/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), [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.
+Start with the [English Quick Start](https://github.com/kim1124/comins-table/blob/main/docs/user/01-quick-start.md), [documentation index](https://github.com/kim1124/comins-table/blob/main/docs/README.md), [English feature guides](https://github.com/kim1124/comins-table/blob/main/docs/user/README.md), or [Korean feature guides](https://github.com/kim1124/comins-table/blob/main/docs/ko/README.md). Use the [Design Contract](https://github.com/kim1124/comins-table/blob/main/DESIGN.md), [Componentization Guide](https://github.com/kim1124/comins-table/blob/main/docs/design/componentization.md), and [Canonical Feature Manifest](https://github.com/kim1124/comins-table/blob/main/docs/feature-manifest.json) for visual stability, extension ownership, complete feature status, and evidence mapping. Each category links the detailed usage contract, runnable Playground route, related features, and the matching guide in the other language.
 
 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 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.
+Comins Table provides CSR arrays and known-count Viewport range loading. Server-side Row models and built-in server filtering, custom Filter editor renderers, Tree filtering, pivoting, charts, AI assistance, remote Tree loading, hierarchy pagination, Tree Row copy/paste, Tree Grid Row Details, 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.
 
@@ -295,7 +360,7 @@ npm run verify
 npm run docs:readme-gif
 ```
 
-`npm run docs:readme-gif` is a maintainer command that captures the real hidden Playground fixture and regenerates the checked-in README animation.
+`npm run docs:readme-gif` is a maintainer command that captures the real hidden Playground fixtures and regenerates the overview animation plus four detailed feature animations.
 
 ## Trusted Publishing
 

package/dist/clipboard.js

@@ -1,2 +1,2 @@
-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";
+import { M as e, N as t, P as n, c as r, o as i, p as a, s as o } from "./core-D01wEe-7.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/component-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-renderer.d.ts","sourceRoot":"","sources":["../src/component-renderer.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EACV,yBAAyB,EACzB,0BAA0B,EAG1B,2BAA2B,EAC3B,4BAA4B,EAE7B,MAAM,QAAQ,CAAC;AA4vBhB,MAAM,MAAM,iCAAiC,GAAG;IAC9C,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC9B,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;QACpF,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;KACjC,KAAK,OAAO,CAAC;CACf,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EACxD,SAAS,EAAE,yBAAyB,CAAC,KAAK,EAAE,MAAM,CAAC,EACnD,OAAO,EAAE,0BAA0B,CAAC,KAAK,EAAE,MAAM,CAAC,EAClD,WAAW,CAAC,EAAE,iCAAiC,GAC9C,KAAK,CAAC,SAAS,CAAC;AACnB,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EACxD,SAAS,EAAE,2BAA2B,CAAC,KAAK,EAAE,MAAM,CAAC,EACrD,OAAO,EAAE,4BAA4B,CAAC,KAAK,EAAE,MAAM,CAAC,EACpD,WAAW,CAAC,EAAE,iCAAiC,GAC9C,KAAK,CAAC,SAAS,CAAC"}
+{"version":3,"file":"component-renderer.d.ts","sourceRoot":"","sources":["../src/component-renderer.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EACV,yBAAyB,EACzB,0BAA0B,EAG1B,2BAA2B,EAC3B,4BAA4B,EAE7B,MAAM,QAAQ,CAAC;AAmwBhB,MAAM,MAAM,iCAAiC,GAAG;IAC9C,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC9B,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,iBAAiB,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;QACpF,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;KACjC,KAAK,OAAO,CAAC;CACf,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EACxD,SAAS,EAAE,yBAAyB,CAAC,KAAK,EAAE,MAAM,CAAC,EACnD,OAAO,EAAE,0BAA0B,CAAC,KAAK,EAAE,MAAM,CAAC,EAClD,WAAW,CAAC,EAAE,iCAAiC,GAC9C,KAAK,CAAC,SAAS,CAAC;AACnB,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EACxD,SAAS,EAAE,2BAA2B,CAAC,KAAK,EAAE,MAAM,CAAC,EACrD,OAAO,EAAE,4BAA4B,CAAC,KAAK,EAAE,MAAM,CAAC,EACpD,WAAW,CAAC,EAAE,iCAAiC,GAC9C,KAAK,CAAC,SAAS,CAAC"}