# BeautifulGrid

> A TypeScript DataGrid focused on advanced features for React business applications. Package `beautiful-grid` 1.0.5, licensed under Apache-2.0.

BeautifulGrid is a client-side React component. Use the Markdown resources below instead of scraping the rendered documentation HTML when preparing implementation context.

Important implementation constraints:

- Import `beautiful-grid/style.css` once; the component does not inject its runtime styles.
- Wrap every domain row as `{ values: T }` and read domain values from `item.values`.
- Provide numeric `width` and `height`; observe the parent container when the viewport is responsive.
- Treat `beautiful-grid/types.ts` as the source of truth. The public API reference is generated from that file.
- Use `key: string[]` for nested values. Do not encode a nested path as one dotted string.
- Editing is controlled through immutable callbacks. Preserve the supplied metadata when saving edited rows.
- React ^19.2.0 and Node.js >=22.12.0 are the documented project baselines; validate dense workflows in target browsers.

## Essential documentation

- [Getting started](https://bgrid.axisj.com/en/learn/getting-started.md): Install the package, import the stylesheet, size the container, and render a typed first grid.
- [TypeScript API reference](https://bgrid.axisj.com/en/api/props.md): Machine-readable public interfaces, exact declarations, members, required flags, and deprecations.
- [Public TypeScript source](https://raw.githubusercontent.com/axisj/beautiful-grid/main/beautiful-grid/types.ts): Source of truth for every public and internal grid type.
- [Package README](https://raw.githubusercontent.com/axisj/beautiful-grid/main/README.md): Installation, major workflows, public props, licensing, and package usage in one document.
- [Machine-readable product facts](https://bgrid.axisj.com/product-facts.json): Current version, runtime baseline, feature support, limitations, license, and project URLs.

## Task guides

- [Data and columns](https://bgrid.axisj.com/en/learn/data-and-columns.md): Shape wrapped row data, define columns, use nested keys, and keep row identity stable.
- [Cell editing](https://bgrid.axisj.com/en/learn/editing.md): Implement edit transactions, validation, immutable row updates, and post-save movement.
- [Built-in editors](https://bgrid.axisj.com/en/learn/built-in-editors.md): Configure text and checkbox editors, header selection, value mapping, and accessibility labels.
- [Editor plugins](https://bgrid.axisj.com/en/learn/editor-plugins.md): Connect custom or third-party editors with commit, cancel, movement, and portal contracts.
- [Sorting and filtering](https://bgrid.axisj.com/en/learn/sorting-filtering.md): Control multi-sort, value/text/number filters, and server-side query state.
- [Search](https://bgrid.axisj.com/en/learn/search.md): Configure grid search, controlled state, keyboard shortcuts, result navigation, and labels.
- [Cell merge](https://bgrid.axisj.com/en/learn/cell-merge.md): Merge consecutive values with columnsMap and understand grouping constraints.
- [Summary rows](https://bgrid.axisj.com/en/learn/summary.md): Render top or bottom summaries and custom aggregate cells.
- [Pivot](https://bgrid.axisj.com/en/learn/pivot.md): Configure row and column axes, aggregate values, and custom pivot rendering.
- [Virtual scroll](https://bgrid.axisj.com/en/learn/virtual-scroll.md): Understand viewport sizing, rendered row ranges, large datasets, and browser height limits.
- [Frozen columns and rows](https://bgrid.axisj.com/en/learn/frozen-columns.md): Keep leading columns and rows visible while preserving scroll behavior.
- [Cell navigation](https://bgrid.axisj.com/en/learn/cell-navigation.md): Control active cells, keyboard movement, editing activation, and accessibility constraints.
- [Column groups](https://bgrid.axisj.com/en/learn/column-groups.md): Build recursive grouped headers and handle groups across frozen boundaries.
- [Theming](https://bgrid.axisj.com/en/learn/theming.md): Apply CSS variables, scope themes, style changed cells, and theme portal-based UI.
- [Cell selection and clipboard](https://raw.githubusercontent.com/axisj/beautiful-grid/main/docs/cell-selection.md): Configure rectangular selection, copy/paste limits, parsing, and errors.

## Runnable source examples

- [Basic grid example source](https://raw.githubusercontent.com/axisj/beautiful-grid/main/examples/BasicExample.tsx): Minimal executable BGrid component with typed rows and columns.
- [Cell merge example source](https://raw.githubusercontent.com/axisj/beautiful-grid/main/examples/CellMergeExample.tsx): Executable columnsMap merge configuration with grouped sample data.
- [Summary example source](https://raw.githubusercontent.com/axisj/beautiful-grid/main/examples/SummaryExample.tsx): Executable summary configuration with custom aggregate rendering.
- [Editing example source](https://raw.githubusercontent.com/axisj/beautiful-grid/main/examples/BasicEditingExample.tsx): Executable immutable edit-save flow using the public transaction callbacks.

## Optional

- [All English guides](https://bgrid.axisj.com/en/learn): Human-facing guide catalog with live demos and related-document navigation.
- [GitHub repository](https://github.com/axisj/beautiful-grid): Complete source, tests, issues, releases, and contribution history.
- [npm package](https://www.npmjs.com/package/beautiful-grid): Published package metadata and release versions.