@geovi/the-datagrid 0.0.9 → 0.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geo Vi and the-datagrid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,6 +12,7 @@ Documentation and live examples: https://geo-vi.github.io/the-datagrid/
 - Opt-in global table search through a separate, tree-shakeable entry
 - Opt-in contextual column-visibility toolbar with a right-side action slot
 - Column management (reorder, resize, auto-size)
+- Stacked and nested column headers with split/rejoin and group resizing
 - Pagination (local + remote)
 - Row selection (checkbox column)
 - Modern shadcn-aligned look-and-feel with packaged styles
@@ -26,13 +27,14 @@ public API and observable behavior of
 After changing the package dependency and import specifier, public
 Inovua-shaped application business logic should not require a rewrite.
 
-That statement is the product contract, **not a claim that the current release
-has already completed parity**. Compatibility covers more than similarly named
-TypeScript fields: it includes defaults, runtime behavior, callback payloads
-and timing, controlled/uncontrolled state, local and remote data flow, layout,
-keyboard and focus interaction, and accessibility behavior.
+The audited Community 5.10.2 release gate is implemented and backed by
+type, runtime, browser, packed-package, and performance tests. Compatibility
+covers more than similarly named TypeScript fields: it includes defaults,
+runtime behavior, callback payloads and timing, controlled/uncontrolled state,
+local and remote data flow, layout, keyboard and focus interaction, and
+accessibility behavior.
 
-The audited Issue 17, Issue 31, and Issue 48 compatibility batches now implement and
+The Issue 17 and Issue 31–45 compatibility batches implement and
 regression-test:
 
 - Inovua's `idProperty`, theme, row/filter height, text-selection, filter-menu,
@@ -49,6 +51,9 @@ regression-test:
 - inline editing (`editable`, `editStartEvent`, column editors, lifecycle
   callbacks, cancellation, focus, and keyboard navigation);
 - object- or function-valued whole-row `rowStyle`.
+- stacked and nested column groups, custom group headers, split/rejoin
+  reordering, controlled group moves, proportional group resizing, and
+  horizontal-virtualization geometry;
 - the standalone
   `@geovi/the-datagrid/packages/TextInput` compatibility entry, including its
   value-first callbacks, clear tool, legacy class hooks, and imperative ref;
@@ -56,14 +61,14 @@ regression-test:
 - `getVirtualList().adjustHeights()` for instantiated variable-height rows in
   virtual and non-virtual layouts.
 
-This closes those audited differences; it does not certify the entire Inovua
-Community API as complete. Remaining mismatches stay in the public status
-ledger until their types and observable behavior have executable evidence. No
-technical-impossibility exceptions are currently approved. Any future exception
-must identify the exact upstream contract, prove why equivalent behavior is
-technically impossible, document consumer impact and a safe migration path, and
-carry executable coverage. Cost, bundle size, schedule, or architectural
-preference alone do not qualify.
+This closes the audited Community gate. The
+[source release ledger](docs/inovua-community-5.10.2-compatibility.md) maps
+every child issue to executable evidence, and
+[`community-api-manifest.json`](community-api-manifest.json) records the
+behavior-backed computed API, plugins, types, and Enterprise exclusions.
+Unknown computed method names are absent instead of being fabricated as no-op
+functions. Any future mismatch is a compatibility regression and must be
+tracked with executable coverage.
 
 Issue 48 explicitly adopts Inovua's standalone `TextInput` toolkit path. Migrate
 its default import to `@geovi/the-datagrid/packages/TextInput`; the package also
@@ -79,8 +84,7 @@ before treating the current package as a drop-in runtime replacement.
 ## Implemented today
 
 The following inventory describes behavior that ships in the current package.
-It is a statement of current capability, not a declaration that the wider
-Inovua compatibility audit is complete. The public docs contain the full
+The public docs contain the full
 [source-backed implemented-surface reference](https://geo-vi.github.io/the-datagrid/docs/reference/implemented-surface),
 including exact defaults, timing, transform order, exports, and imperative
 method allowlists.
@@ -107,7 +111,9 @@ method allowlists.
 - **Columns and cells:** stable `id`/`name` identity, controlled rendered order,
   callback-driven drag reordering, explicit visibility, custom headers and cell
   renderers, per-column sorting/filtering/search configuration, alignment, cell
-  classes/styles, and header props.
+  classes/styles, and header props. Root `groups`, `column.group`, and nested
+  `groups[].group` render accessible stacked headers with automatic split/rejoin
+  segments, block dragging, and proportional min/max-clamped resizing.
 - **Column and row sizing:** controlled `width`/`flex`, uncontrolled
   `defaultWidth`/`defaultFlex`, `minWidth`/`maxWidth` clamps, proportional flex
   allocation, the upstream 40px implicit column minimum (while preserving an
@@ -119,9 +125,10 @@ method allowlists.
 - **Filtering and sorting:** inferred or explicitly controlled filter-row
   visibility, uncontrolled local filters, externally owned controlled filter
   state, custom filter registries and editors, filter operator menus, single
-  sorting, Shift-assisted multi-sorting, configurable initial direction, and
-  optional unsorting. Filter and sort changes reset pagination to the first
-  page.
+  sorting, persistent array-valued multi-sorting, custom comparator registries
+  and sort tools, configurable initial direction, optional unsorting, and
+  configurable scroll reset behavior. Filter and sort changes reset pagination
+  to the first page.
 - **Pagination:** controlled or uncontrolled `skip` and `limit`, local and remote
   modes, configurable page sizes, a built-in accessible pager, an
   Inovua-shaped `renderPaginationToolbar` contract, and reload/refresh/page
@@ -165,9 +172,8 @@ method allowlists.
   observers.
   The editing subset includes `startEdit`, `tryStartEdit`, `completeEdit`,
   `cancelEdit`, `getCurrentEditInfo`, `isInEdit`, and
-  `currentEditCompletePromise`. This is an implemented subset;
-  compatibility-shaped placeholder methods are not a claim of working
-  behavior.
+  `currentEditCompletePromise`. The API is explicit and behavior-backed;
+  unknown method-like properties resolve to `undefined`.
 
 ### Migration: data-transform ownership
 
@@ -193,30 +199,41 @@ for rationale and migration examples.
 
 The main entry, `@geovi/the-datagrid`, exports:
 
-- default and named `ReactDataGrid`, plus the compatibility-shaped `plugins`
-  empty list;
-- `DateFilter`, `NumberFilter`, `SelectFilter`, `CheckBox`, and the named
+- default and named `ReactDataGrid`, plus executable descriptors for the
+  built-in sorting, filtering, menu, and cell-selection plugins;
+- `BoolEditor`, `DateEditor`, `NumericEditor`, `StringFilter`, `BoolFilter`,
+  `DateFilter`, `NumberFilter`, `SelectFilter`, `CheckBox`, and the named
   `TextInput`;
 - `DEFAULT_FILTER_TYPES` and its `filterTypes` alias;
 - the public types `CellProps`, `IColumn`, `SortDirection`, `TypeColumn`,
   `TypeColumns`, `TypeColumnEditorProps`, `TypeColumnResizeContext`,
   `TypeColumnResizeInfo`, `TypeColumnEditorCell`, `TypeComputedColumn`,
   `TypeComputedColumnsMap`, `TypeComputedProps`, `TypeDataGridProps`,
-  `TypeDataSourceArgs`, `TypeDataSource`, `TypeDataSourceResult`,
+  `TypeColumnGroup`, `TypeColumnGroupDOMProps`,
+  `TypeColumnGroupHeaderProps`, `TypeDataSourceArgs`, `TypeDataSource`,
+  `TypeDataSourceResult`,
   `TypePaginationProps`, `TypeLoadMaskProps`, `TypeEditInfo`, `TypeStartEditArgs`,
   `TypeTryStartEditArgs`, `TypeCompleteEditArgs`, `TypeCancelEditArgs`,
   `TypeFilterOperator`, `TypeFilterType`, `TypeFilterTypes`, `TypeFilterValue`,
   `TypeGetColumnByParam`, `TypeI18n`, `TypeOnSelectionChangeArg`,
   `TypePaginationMode`, `TypeRowSelection`, `TypeRowStyle`, `TypeRowStyleArgs`,
   `TypeRowStyleProps`, `TypeShowCellBorders`, `TypeSize`, `TypeSingleFilterValue`,
-  `TypeSingleSortInfo`, `TypeSortInfo`, `TypeCheckboxColumn`,
-  `TypeCheckboxProps`, `TextInputProps`, `TypeTextInputProps`, and the
-  TextInput callback/input/wrapper/clear-button helper types.
+  `TypeSingleSortInfo`, `TypeSortInfo`, `TypeSortFunction`,
+  `TypeSortFunctions`, `TypeColumnSort`, `TypeSortToolProps`,
+  `TypeRenderSortTool`, `TypeCheckboxColumn`, `TypeCheckboxProps`,
+  `TextInputProps`, `TypeTextInputProps`, and the TextInput
+  callback/input/wrapper/clear-button helper types.
+
+The same editors and filters are available through their documented deep
+imports. `@geovi/the-datagrid/types` and the documented
+`@geovi/the-datagrid/types/Type*` paths expose the migration type vocabulary.
+The main and Community compatibility entries publish both ESM and CommonJS.
 
 The optional `@geovi/the-datagrid/search` entry exports `RDGSearchProvider`,
 `RDGSearchBar`, `RDGSearchTarget`, and their prop types. The explicit stylesheet
-fallbacks are `@geovi/the-datagrid/style.css` and
-`@geovi/the-datagrid/search/style.css`.
+fallbacks include `@geovi/the-datagrid/index.css`,
+`@geovi/the-datagrid/base.css`, every documented default/amber/blue/green/pink
+light/dark theme path, and `@geovi/the-datagrid/search/style.css`.
 
 The optional `@geovi/the-datagrid/components` entry is the one-import choice for
 mixed contextual controls. It exports `RDGProvider`, `RDGTarget`,
@@ -250,9 +267,9 @@ number comparison/range operators, and date/time comparison/range operators.
 Operator definitions can opt into empty-value filtering, initialize a value
 when selected, or disable the editor for value-free operations.
 
-Current caveat: an unseeded `bool`/`boolean` filter resolves through the generic
-`contains` fallback even though those registries expose only `eq`/`neq`. Seed an
-`eq` or `neq` filter entry until that implementation gap is corrected.
+Unseeded `bool` and `boolean` filters default to `eq`, matching their shipped
+operator registry. Other defaults are `contains` for strings, `gte` for
+numbers, `eq` for selects, and `afterOrOn` for date/time values.
 
 Custom filter types are shallow-merged by registry key with the built-ins:
 
@@ -640,11 +657,13 @@ fallbacks, omits columns with `hideable={false}`, and does not allow the final
 visible column to be hidden. Button state is exposed through `aria-pressed`; no
 eye icon or parallel application visibility state is required.
 
-Set `visible: false` on a column that should start hidden and `hideable: false`
-on one that must not be toggled. `defaultVisible` and `defaultHidden` remain
-ignored compatibility fields. Visibility clicks update grid-owned runtime
-state; a real grid remount discards those overrides and initializes again from
-the current column props.
+Set controlled `visible: false`, uncontrolled `defaultVisible: false`, or the
+legacy `defaultHidden: true` alias on a column that should start hidden.
+`hideable: false` disables menu/toolbar toggles but does not block the
+imperative API. `onColumnVisibleChange({ column, visible })` receives every
+effective proposal. A declarative `visible` value remains authoritative until
+the parent applies that proposal; otherwise the grid persists the change in
+its own runtime state.
 
 The default title is a level-two heading that labels the toolbar region. The
 toggle group keeps its `ariaLabel`, and the description is associated with both
@@ -763,11 +782,12 @@ Note: this is a curated overview. For the complete contract, refer to the export
 
 ### Core
 
-| Prop         | Type             | Default  | Description                                                  |
-| ------------ | ---------------- | -------- | ------------------------------------------------------------ |
-| `idProperty` | `string`         | `"id"`   | Property name used as unique row identifier; JSX may omit it |
-| `columns`    | `TypeColumns`    | required | Column definitions                                           |
-| `dataSource` | `TypeDataSource` | required | Data source (array, function, or promise)                    |
+| Prop         | Type                | Default  | Description                                                  |
+| ------------ | ------------------- | -------- | ------------------------------------------------------------ |
+| `idProperty` | `string`            | `"id"`   | Property name used as unique row identifier; JSX may omit it |
+| `columns`    | `TypeColumns`       | required | Column definitions                                           |
+| `groups`     | `TypeColumnGroup[]` | `[]`     | Stacked and nested column-header descriptors                 |
+| `dataSource` | `TypeDataSource`    | required | Data source (array, function, or promise)                    |
 
 ### Display
 
@@ -807,17 +827,41 @@ custom cell metadata. That callback value preserves upstream’s raw shape:
 
 ### Columns
 
-| Prop                   | Type                        | Default | Description                                                                   |
-| ---------------------- | --------------------------- | ------- | ----------------------------------------------------------------------------- |
-| `columnOrder`          | `string[]`                  | -       | Ordered array of column ids/names                                             |
-| `onColumnOrderChange`  | `(order: string[]) => void` | -       | Fired when column order changes; drag reordering requires this callback       |
-| `reorderColumns`       | `boolean`                   | `true`  | Disable user drag reordering while continuing to render `columnOrder`         |
-| `resizable`            | `boolean`                   | `true`  | Enable header resize handles                                                  |
-| `liveColumnResize`     | `boolean`                   | `false` | Resize header and body geometry during drag; callbacks remain completion-only |
-| `onColumnResize`       | `(info, context) => void`   | -       | Reports proposed width/flex and reserved viewport width                       |
-| `enableColumnAutosize` | `boolean`                   | `true`  | Estimate widths from a bounded row sample when no numeric width is supplied   |
-| `skipHeaderOnAutoSize` | `boolean`                   | `false` | Skip header text when estimating an automatic width                           |
-| `showColumnMenuTool`   | `boolean`                   | `true`  | Show the header menu tool                                                     |
+| Prop                       | Type                            | Default | Description                                                                     |
+| -------------------------- | ------------------------------- | ------- | ------------------------------------------------------------------------------- |
+| `columnOrder`              | `string[]`                      | -       | Controlled ordered array of column ids/names                                    |
+| `defaultColumnOrder`       | `string[]`                      | columns | Initial order for grid-owned ordering                                           |
+| `onColumnOrderChange`      | `(order: string[]) => void`     | -       | Receives reorder proposals; optional for grid-owned ordering                    |
+| `onColumnVisibleChange`    | `({ column, visible }) => void` | -       | Receives controlled or uncontrolled visibility proposals                        |
+| `reorderColumns`           | `boolean`                       | `true`  | Disable user drag reordering                                                    |
+| `allowGroupSplitOnReorder` | `boolean`                       | `true`  | Allow reordering to split one logical group into visual segments                |
+| `resizable`                | `boolean`                       | `true`  | Enable header resize handles                                                    |
+| `columnDefaultWidth`       | `number`                        | `150`   | Root fallback when a column has no width/defaultWidth                           |
+| `columnMinWidth`           | `number`                        | `40`    | Root fallback when a column has no minWidth                                     |
+| `columnMaxWidth`           | `number \| null`                | `null`  | Root fallback when a column has no maxWidth                                     |
+| `shareSpaceOnResize`       | `boolean`                       | `false` | Resize the adjacent visible column in the opposite direction                    |
+| `columnResizeHandleWidth`  | `number`                        | `24`    | Header resize pointer-target width                                              |
+| `columnResizeProxyWidth`   | `number`                        | `5`     | Deferred resize-proxy width                                                     |
+| `liveColumnResize`         | `boolean`                       | `false` | Resize rendered geometry during drag; callbacks remain completion-only          |
+| `onColumnResize`           | `(info, context) => void`       | -       | Reports each proposed width/flex and reserved viewport width                    |
+| `onBatchColumnResize`      | `(entries, context) => void`    | -       | Reports one coherent callback for every resize transaction                      |
+| `enableColumnAutosize`     | `boolean`                       | `true`  | Estimate widths from a bounded row sample when no numeric width is supplied     |
+| `skipHeaderOnAutoSize`     | `boolean`                       | `false` | Skip header text when estimating an automatic width                             |
+| `showColumnMenuTool`       | `boolean`                       | `true`  | Show sort, visibility, auto-size, and fit actions in the accessible column menu |
+
+When `columnOrder` is omitted, `defaultColumnOrder` seeds grid-owned ordering
+and drag changes persist even without a callback. When `columnOrder` is
+supplied, it is authoritative: `onColumnOrderChange` receives the proposal and
+the display changes only after the parent returns it. The same ownership rule
+applies to `column.visible` versus `defaultVisible`/`defaultHidden`.
+
+Column sizing precedence is controlled `width`, column `defaultWidth` and
+`minWidth`/`maxWidth`, then the root fallbacks. An uncontrolled flex column
+retains flex ownership by default; set `column.keepFlex: false` to convert it to
+fixed sizing after a no-share resize. Shared-space resize preserves the adjacent
+pair's total width and handles fixed/fixed, flex/flex, and mixed pairs.
+Controlled `width` and `flex` values remain prop-owned while both resize
+callbacks receive the proposal.
 
 Set `column.locked` to `"start"` or `"end"` to keep it visible at that
 horizontal edge; `true` is the Inovua-compatible alias for `"start"`. Locked
@@ -844,15 +888,21 @@ those compatibility metrics.
 
 ### Filtering
 
-| Prop                            | Type                               | Default           | Description                                               |
-| ------------------------------- | ---------------------------------- | ----------------- | --------------------------------------------------------- |
-| `enableFiltering`               | `boolean`                          | inferred          | Explicitly show or hide the filter row                    |
-| `filterValue`                   | `TypeFilterValue`                  | -                 | Controlled display state; data ownership remains external |
-| `defaultFilterValue`            | `TypeFilterValue`                  | -                 | Uncontrolled initial state and local filtering input      |
-| `onFilterValueChange`           | `(value: TypeFilterValue) => void` | -                 | Fired on filter change                                    |
-| `filterTypes`                   | `TypeFilterTypes`                  | built-in registry | Extend or override filter types and operators             |
-| `enableColumnFilterContextMenu` | `boolean`                          | `true`            | Operator, activation, Clear, and Clear All menu           |
-| `filteredRowsCount`             | `(count: number) => void`          | -                 | Reports filtered row count                                |
+| Prop                                    | Type                                           | Default            | Description                                               |
+| --------------------------------------- | ---------------------------------------------- | ------------------ | --------------------------------------------------------- |
+| `enableFiltering`                       | `boolean`                                      | inferred           | Explicitly show or hide the filter row                    |
+| `filterValue`                           | `TypeFilterValue`                              | -                  | Controlled display state; data ownership remains external |
+| `defaultFilterValue`                    | `TypeFilterValue`                              | -                  | Uncontrolled initial state and local filtering input      |
+| `onFilterValueChange`                   | `(value: TypeFilterValue) => void`             | -                  | Fired on filter change                                    |
+| `filterTypes`                           | `TypeFilterTypes`                              | built-in registry  | Extend or override filter types and operators             |
+| `enableColumnFilterContextMenu`         | `boolean`                                      | `true`             | Operator, activation, Clear, and Clear All menu           |
+| `scrollTopOnFilter`                     | `boolean`                                      | `true`             | Reset vertical scroll after a filter commits              |
+| `renderColumnFilterContextMenu`         | `TypeRenderColumnFilterContextMenu`            | -                  | Render a custom operator menu with grid/cell context      |
+| `columnFilterContextMenuAlignPositions` | `string[]`                                     | built-in fallbacks | Configure custom/operator menu alignment candidates       |
+| `columnFilterContextMenuConstrainTo`    | `boolean \| HTMLElement \| string \| function` | `true`             | Supply the custom menu constraint target                  |
+| `columnFilterContextMenuPosition`       | `string`                                       | `"absolute"`       | Supply the custom menu positioning mode                   |
+| `updateMenuPositionOnScroll`            | `boolean`                                      | `true`             | Request custom menu repositioning while scrolling         |
+| `filteredRowsCount`                     | `(count: number) => void`                      | -                  | Reports filtered row count                                |
 
 For Inovua 5.10.2 compatibility, filter-row visibility and local array
 transformation are separate decisions. With no explicit `enableFiltering`, a
@@ -869,13 +919,42 @@ Disable are explicit menu actions, and Clear All emits one aggregate update.
 
 ### Sorting
 
-| Prop                      | Type                           | Default | Description                   |
-| ------------------------- | ------------------------------ | ------- | ----------------------------- |
-| `sortInfo`                | `TypeSortInfo`                 | -       | Controlled sort state         |
-| `defaultSortInfo`         | `TypeSortInfo`                 | -       | Uncontrolled initial sort     |
-| `onSortInfoChange`        | `(info: TypeSortInfo) => void` | -       | Fired on sort change          |
-| `allowUnsort`             | `boolean`                      | `true`  | Allow returning to “unsorted” |
-| `defaultSortingDirection` | `"asc" \| "desc"`              | `"asc"` | Default sort direction        |
+| Prop                      | Type                           | Default       | Description                                                    |
+| ------------------------- | ------------------------------ | ------------- | -------------------------------------------------------------- |
+| `sortInfo`                | `TypeSortInfo`                 | -             | Controlled sort state                                          |
+| `defaultSortInfo`         | `TypeSortInfo`                 | -             | Uncontrolled initial sort                                      |
+| `onSortInfoChange`        | `(info: TypeSortInfo) => void` | -             | Fired on sort change                                           |
+| `sortable`                | `boolean`                      | `true`        | Root sorting switch; `column.sortable` can override it         |
+| `allowUnsort`             | `boolean`                      | `true`        | Allow a single sort to return to “unsorted”                    |
+| `defaultSortingDirection` | `"asc" \| "desc"`              | `"asc"`       | Default sort direction                                         |
+| `sortFunctions`           | `TypeSortFunctions`            | date registry | Comparator registry addressed by `column.type`                 |
+| `renderSortTool`          | `TypeRenderSortTool`           | built-in icon | Root sort-indicator renderer; `column.renderSortTool` wins     |
+| `scrollTopOnSort`         | `boolean \| "always"`          | `true`        | Reset vertical scroll on sort, never, or on every data refresh |
+
+An object-valued `sortInfo` is single-sort mode. An array-valued sort state is
+persistent multi-sort mode, including when the array contains zero or one
+descriptor; ordinary click, Enter, Space, header-menu, mobile, and imperative
+sort actions retain that array shape without requiring Shift. Descriptor order
+is sort priority, and retoggling a descriptor preserves its position until it
+is removed.
+
+Local sorting uses `column.sort` first, then a descriptor `fn`, a
+`sortFunctions[column.type]` registry entry, and finally the built-in
+`number`/`date`/`string` comparator. A named column comparator receives
+`(value1, value2, column, data1, data2, sortInfo)`. An id-only column receives
+the complete rows as `value1` and `value2`. Controlled `sortInfo` remains
+externally owned and is not applied again to local array order.
+
+Migration notes for the completed Inovua sorting contract:
+
+- Previous releases inferred numeric ordering when both values were
+  number-like. Untyped columns now use Inovua's string comparator; declare
+  `type: "number"` (or provide a comparator) for numeric ordering.
+- Shift no longer changes a single descriptor into multi-sort mode. Initialize
+  `sortInfo` or `defaultSortInfo` as an array to opt into persistent multi-sort.
+- `TypeSingleSortInfo.fn`, `column.sort`, and registered sort functions now
+  expose their exact comparator argument lists while retaining Inovua's
+  `number | boolean` result compatibility.
 
 ### Selection
 
@@ -944,6 +1023,18 @@ The stable `TypeComputedProps` ref exposes these editing methods and fields:
 | `isInEdit.current`                                    | Exposes the upstream lifecycle edit flag.                                                                                                                                                                                              |
 | `currentEditCompletePromise.current`                  | Tracks the current completion callback promise.                                                                                                                                                                                        |
 
+It also exposes behavior-backed column-state methods:
+
+| Member                                               | Behavior                                                                                                     |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `setColumnVisible(column, visible)`                  | Uses the same controlled/uncontrolled ownership and callback path as the built-in menu and optional toolbar. |
+| `setColumnOrder(order)`                              | Applies an uncontrolled order or emits a controlled proposal without mutating consumer state.                |
+| `setColumnSizes(action)` / `setColumnFlexes(action)` | Replace grid-owned width/flex maps; declarative `width`/`flex` values remain authoritative.                  |
+| `onBatchColumnResize(entries, context?)`             | Applies a width/flex transaction and emits per-column plus batch completion callbacks.                       |
+| `setColumnSizeAuto(id, skipHeader?)`                 | Deterministically auto-sizes one resizable visible column.                                                   |
+| `setColumnsSizesAuto(config?)`                       | Auto-sizes selected or all resizable visible columns as one batch.                                           |
+| `setColumnSizesToFit()`                              | Fits resizable visible columns to the viewport while honoring min/max bounds.                                |
+
 Completion is session-safe: an older async completion settling cannot clear or
 navigate a newer edit. The editor is already stopped when `onEditComplete`
 runs; rejecting its Promise leaves it stopped and suppresses keyboard

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,10 @@
+# Third-party notices
+
+the-datagrid provides a compatibility layer for the public Community API of
+`@inovua/reactdatagrid-community@5.10.2`. Inovua ReactDataGrid is Copyright
+INOVUA TRADING and is distributed under the MIT License. Its license is
+available in the upstream package and repository:
+https://github.com/inovua/reactdatagrid
+
+This notice documents API provenance. the-datagrid's implementation and
+shadcn/Tailwind presentation are maintained independently.