grid/new-api-components

README.md

@@ -90,8 +90,8 @@ export function App() {
           age: [23, 34, 45]
         }}
       />
-      <Column columnId="name" headerFormat="Name" />
-      <Column columnId="age" dataType="number" headerFormat="Age" />
+      <Column id="name" headerFormat="Name" />
+      <Column id="age" dataType="number" headerFormat="Age" />
     </Grid>
   );
 }
@@ -135,8 +135,8 @@ export function App() {
           age: [23, 34, 45]
         }}
       />
-      <Column columnId="name" headerFormat="Name" />
-      <Column columnId="age" dataType="number" headerFormat="Age" />
+      <Column id="name" headerFormat="Name" />
+      <Column id="age" dataType="number" headerFormat="Age" />
     </Grid>
   );
 }

packages/grid-lite-react/README.md

@@ -78,7 +78,7 @@ export function App() {
 ### Using components
 
 ```jsx
-import { Grid, Caption, Data, Column, Pagination } from '@highcharts/grid-lite-react';
+import { Grid, Caption, Data, Column, Header, Pagination } from '@highcharts/grid-lite-react';
 
 export function App() {
   return (
@@ -91,15 +91,18 @@ export function App() {
           city: ['New York', 'Oslo', 'Paris']
         }}
       />
-      <Column columnId="name" headerFormat="Name" sortingEnabled />
-      <Column columnId="age" dataType="number" headerFormat="Age" />
-      <Column columnId="city" headerFormat="City" />
+      <Header options={['name', 'age', 'city']} />
+      <Column id="name" headerFormat="Name" sortingEnabled />
+      <Column id="age" dataType="number" headerFormat="Age" />
+      <Column id="city" headerFormat="City" />
       <Pagination pageSize={5} />
     </Grid>
   );
 }
 ```
 
+Each option component also accepts an `options` prop with the same JSON as the Grid JS API. Flattened props override that object.
+
 ## Grid props
 
 The grid is rendered inside a container. You can pass layout and theme props directly to `Grid`:

packages/grid-lite-react/src/Grid.tsx

@@ -17,6 +17,11 @@ import type { Options } from '@highcharts/grid-lite/es-modules/Grid/Core/Options
 import type { GridProps } from '@highcharts/grid-shared-react';
 import { buildGridOptions } from './utils/buildGridOptions';
 
+/**
+ * Grid Lite React component.
+ *
+ * Links to Grid.Options
+ */
 export default function GridLite(props: GridProps<Options>) {
     const {
         gridRef,

packages/grid-pro-react/README.md

@@ -84,6 +84,7 @@ import {
   Caption,
   Data,
   Column,
+  Header,
   Pagination
 } from '@highcharts/grid-pro-react';
 
@@ -98,15 +99,18 @@ export function App() {
           city: ['New York', 'Oslo', 'Paris']
         }}
       />
-      <Column columnId="name" headerFormat="Name" sortingEnabled />
-      <Column columnId="age" dataType="number" headerFormat="Age" />
-      <Column columnId="city" headerFormat="City" />
+      <Header options={['name', 'age', 'city']} />
+      <Column id="name" headerFormat="Name" sortingEnabled />
+      <Column id="age" dataType="number" headerFormat="Age" />
+      <Column id="city" headerFormat="City" />
       <Pagination pageSize={5} />
     </Grid>
   );
 }
 ```
 
+Each option component also accepts an `options` prop with the same JSON as the Grid JS API. Flattened props override that object.
+
 ## Grid props
 
 The grid is rendered inside a container. You can pass layout, theme, and Pro event props directly to `Grid`:

packages/grid-pro-react/src/Grid.tsx

@@ -19,6 +19,11 @@ import {
 } from './utils/mappers/grid';
 import { buildGridOptions } from './utils/buildGridOptions';
 
+/**
+ * Grid Pro React component.
+ *
+ * Links to Grid.Options
+ */
 export default function GridPro(props: GridProProps) {
     const { gridRef, children, options, callback, className } = props;
     const { gridOptions, columnKey } = useDeclarativeGridOptions(

packages/grid-pro-react/src/utils/mappers/column/columnOptions.ts

@@ -17,33 +17,72 @@ import type {
 } from '@highcharts/grid-pro/es-modules/Grid/Pro/GridEvents.js';
 
 /**
- * Column-level event props mapped to `columns[].events`.
+ * Column-level event props mapped to `columns[].events`. Grid Pro.
  */
 export interface ColumnLevelEventProps {
+    /**
+     * Links to Grid.Options.columns.events.afterResize
+     */
     onAfterResize?: ColumnEventCallback;
+    /**
+     * Links to Grid.Options.columns.events.beforeSort
+     */
     onBeforeSort?: ColumnEventCallback;
+    /**
+     * Links to Grid.Options.columns.events.afterSort
+     */
     onAfterSort?: ColumnEventCallback;
+    /**
+     * Links to Grid.Options.columns.events.beforeFilter
+     */
     onBeforeFilter?: ColumnEventCallback;
+    /**
+     * Links to Grid.Options.columns.events.afterFilter
+     */
     onAfterFilter?: ColumnEventCallback;
 }
 
 /**
- * Cell-level event props mapped to `columns[].cells.events`.
+ * Cell-level event props mapped to `columns[].cells.events`. Grid Pro.
  */
 export interface CellLevelEventProps {
+    /**
+     * Links to Grid.Options.columns.cells.events.click
+     */
     onCellClick?: CellEventCallback;
+    /**
+     * Links to Grid.Options.columns.cells.events.dblClick
+     */
     onCellDblClick?: CellEventCallback;
+    /**
+     * Links to Grid.Options.columns.cells.events.mouseOver
+     */
     onCellMouseOver?: CellEventCallback;
+    /**
+     * Links to Grid.Options.columns.cells.events.mouseOut
+     */
     onCellMouseOut?: CellEventCallback;
+    /**
+     * Links to Grid.Options.columns.cells.events.afterRender
+     */
     onCellAfterRender?: CellEventCallback;
+    /**
+     * Links to Grid.Options.columns.cells.events.afterEdit
+     */
     onCellAfterEdit?: CellEventCallback;
 }
 
 /**
- * Header-level event props mapped to `columns[].header.events`.
+ * Header-level event props mapped to `columns[].header.events`. Grid Pro.
  */
 export interface HeaderLevelEventProps {
+    /**
+     * Links to Grid.Options.columns.header.events.click
+     */
     onHeaderClick?: ColumnEventCallback;
+    /**
+     * Links to Grid.Options.columns.header.events.afterRender
+     */
     onHeaderAfterRender?: ColumnEventCallback;
 }
 

packages/grid-pro-react/src/utils/mappers/grid/gridOptions.ts

@@ -29,25 +29,54 @@ export type GridProOptions = GridPro.Options & {
 export type GridOptions = GridProOptions;
 
 /**
- * Grid-level event props mapped to `options.events`.
+ * Grid-level event props mapped to `options.events`. Grid Pro.
  */
 export interface GridLevelEventProps {
+    /**
+     * Links to Grid.Options.events.beforeLoad
+     */
     onBeforeLoad?: GridEventCallback;
+    /**
+     * Links to Grid.Options.events.afterLoad
+     */
     onAfterLoad?: GridEventCallback;
+    /**
+     * Links to Grid.Options.events.beforeUpdate
+     */
     onBeforeUpdate?: GridEventCallback;
+    /**
+     * Links to Grid.Options.events.afterUpdate
+     */
     onAfterUpdate?: GridEventCallback;
+    /**
+     * Links to Grid.Options.events.beforeRedraw
+     */
     onBeforeRedraw?: GridEventCallback;
+    /**
+     * Links to Grid.Options.events.afterRedraw
+     */
     onAfterRedraw?: GridEventCallback;
+    /**
+     * Links to Grid.Options.events.beforeTreeRowToggle
+     */
     onBeforeTreeRowToggle?: (e: BeforeTreeRowToggleEvent) => void;
+    /**
+     * Links to Grid.Options.events.afterTreeRowToggle
+     */
     onAfterTreeRowToggle?: (e: AfterTreeRowToggleEvent) => void;
 }
 
 /**
- * Row pinning event props mapped to
- * `options.rendering.rows.pinning.events`.
+ * Row pinning event props. Grid Pro.
  */
 export interface RowPinningEventProps {
+    /**
+     * Links to Grid.Options.rendering.rows.pinning.events.beforeRowPin
+     */
     onBeforeRowPin?: RowPinningChangeEventCallback;
+    /**
+     * Links to Grid.Options.rendering.rows.pinning.events.afterRowPin
+     */
     onAfterRowPin?: RowPinningChangeEventCallback;
 }
 
@@ -60,6 +89,8 @@ export interface GridProProps
     extends BaseGridProps<GridProOptions>, GridEventProps {
     /**
      * Grid Pro license key.
+     *
+     * Links to Grid.Options.gridKey
      */
     gridKey: string;
 }

packages/grid-pro-react/src/utils/mappers/pagination/paginationOptions.ts

@@ -19,12 +19,24 @@ import type {
 } from '@highcharts/grid-pro/es-modules/Grid/Pro/Pagination/PaginationComposition.js';
 
 /**
- * Pagination event props mapped to `pagination.events`.
+ * Pagination event props mapped to `pagination.events`. Grid Pro.
  */
 export interface PaginationEventProps {
+    /**
+     * Links to Grid.Options.pagination.events.beforePageChange
+     */
     onBeforePageChange?: (e: BeforePageChangeEvent) => void;
+    /**
+     * Links to Grid.Options.pagination.events.afterPageChange
+     */
     onAfterPageChange?: (e: AfterPageChangeEvent) => void;
+    /**
+     * Links to Grid.Options.pagination.events.beforePageSizeChange
+     */
     onBeforePageSizeChange?: (e: BeforePageSizeChangeEvent) => void;
+    /**
+     * Links to Grid.Options.pagination.events.afterPageSizeChange
+     */
     onAfterPageSizeChange?: (e: AfterPageSizeChangeEvent) => void;
 }
 

packages/grid-shared-react/src/components/BaseGrid.tsx

@@ -15,21 +15,23 @@
 } from '../hooks/useGrid';
 
 /**
- * Ref handle exposed by Grid components
+ * Ref handle exposed by Grid components.
  */
 export interface GridRefHandle<TOptions> {
     /**
-     * Access to the underlying grid instance
+     * Access to the underlying grid instance.
      */
     readonly grid: GridInstance<TOptions> | null;
 }
 
 /**
- * Props for Grid component
+ * Props for the Grid component.
  */
 export interface GridProps<TOptions> {
     /**
      * Options JSON, same as in the Grid JS API.
+     *
+     * Links to Grid.Options
      */
     options?: TOptions;
     /**
@@ -40,24 +42,27 @@
     /**
      * Optional CSS class names mapped to Core `rendering.table.className` on
      * `.hcg-table`. Independent of `className` / `theme`.
+     *
+     * Links to Grid.Options.rendering.table.className
      */
     tableClassName?: string;
     /**
-     * Optional theme name passed to Grid Core as `rendering.theme`.
-     * Omitted → Core default (`hcg-theme-default`).
-     * Defined (including `''`) → that value only.
+     * Omitted uses the Core default (`hcg-theme-default`). An empty string
+     * disables the theme.
+     *
+     * Links to Grid.Options.rendering.theme
      */
     theme?: string;
     /**
      * Declarative option components (e.g. Caption) passed as children.
      */
     children?: ReactNode;
     /**
-     * Optional ref to access the grid instance
+     * Ref to access the grid instance.
      */
     gridRef?: ForwardedRef<GridRefHandle<TOptions>>;
     /**
-     * Optional callback to be called when the grid is initialized
+     * Callback to be called when the grid is initialized.
      */
     callback?: (grid: GridInstance<TOptions>) => void;
 }
@@ -93,7 +98,7 @@
                 return currGridRef.current;
             }
         }),
         []
     );
 
     return <div ref={containerRef} className={className} />;

packages/grid-shared-react/src/components/options/caption/Caption.tsx

@@ -11,20 +11,32 @@ import { ReactNode } from 'react';
 
 export interface CaptionProps<TOptions = unknown> {
     /**
-     * The custom CSS class name for the table caption.
+     * Links to Grid.Options.caption.className
      */
     className?: string;
     /**
-     * The HTML tag to use for the caption.
+     * Links to Grid.Options.caption.htmlTag
      */
     htmlTag?: string;
     /**
      * Options JSON, same as in the Grid JS API (`caption`).
+     *
+     * Links to Grid.Options.caption
      */
     options?: TOptions;
+    /**
+     * Caption text, passed as the component children.
+     *
+     * Links to Grid.Options.caption.text
+     */
     children?: ReactNode;
 }
 
+/**
+ * Table caption. Pass the caption text as children.
+ *
+ * Links to Grid.Options.caption
+ */
 export function Caption<TOptions = unknown>(_props: CaptionProps<TOptions>) {
     return null;
 }

packages/grid-shared-react/src/components/options/columns/Column.tsx

@@ -9,6 +9,11 @@
 
 import type { ColumnProps } from './columnProps';
 
+/**
+ * Per-column configuration. Flattened React props map onto `columns[]`.
+ *
+ * Links to Grid.Options.columns
+ */
 export function Column<TOptions = unknown>(_props: ColumnProps<TOptions>) {
     return null;
 }