@gridkitjs/react 0.11.0 → 0.12.0

package/README.md

@@ -1,7 +1,9 @@
 # @gridkitjs/react
 
 React data-grid components built on
-[`@gridkitjs/core`](https://www.npmjs.com/package/@gridkitjs/core).
+[`@gridkitjs/core`](https://www.npmjs.com/package/@gridkitjs/core) for the
+grid's logic and [`@gridkitjs/dom`](https://www.npmjs.com/package/@gridkitjs/dom)
+for its browser behaviours. Both are installed with it.
 
 > **Early development.** The API is still moving and may break between minor
 > versions.
@@ -58,9 +60,17 @@ The grid is an ARIA grid: one tab stop, with the arrow keys moving cell to cell
 within it, `Ctrl+Arrow` reordering a column and `Alt+Arrow` resizing one. Name
 it with `label`, or a screen reader announces only "grid".
 
+`contextMenu` gives headers, cells and group rows a menu of their own — sort,
+group, autofit, hide and choose columns, select and clear, expand and collapse
+— and `toolbar` puts a toolbar above the grid, with a search box, "Clear
+filters" and "Choose columns" by default. Both list built-in commands by id,
+and `commands` adds your own beside them; the column chooser shows and hides
+columns from either. `messages` translates every string the grid shows or
+announces, and `locale` formats dates and numbers.
+
 Requires React 19.
 
-Full documentation: [github.com/blagojablazhevski/gridkit](https://github.com/blagojablazhevski/gridkit#readme)
+Full documentation: [github.com/gridkitjs/gridkitjs](https://github.com/gridkitjs/gridkitjs#readme)
 
 ## License
 

package/dist/index.d.ts

@@ -1,7 +1,52 @@
 import * as react from 'react';
 import { ReactNode, Ref, RefObject } from 'react';
-import { CellSelectEvent as CellSelectEvent$1, CellSelectionChangeEvent as CellSelectionChangeEvent$1, ColumnDefinition as ColumnDefinition$1, ColumnSelectEvent as ColumnSelectEvent$1, ColumnSelectionChangeEvent as ColumnSelectionChangeEvent$1, ColumnsSelectEvent as ColumnsSelectEvent$1, DataColumn as DataColumn$1, GridOptions, PaginationState, SelectionCallbacks as SelectionCallbacks$1, ResolvedRow, DisplayRow, ResolvedColumn as ResolvedColumn$1, ColumnSizingState, ColumnOrderState, ColumnVisibilityState, ColumnSortState, FilterState, GroupByState, GroupExpansionState, AggregateResults, SelectionState, CellSelectionState, GridState, SerializedGridState, GridContextMenuTarget, GridCommandTarget, SelectedCell as SelectedCell$1, SelectedColumn as SelectedColumn$1 } from '@gridkitjs/core';
-export { Borders, CellSelectionMode, CellSelectionState, CellTemplateContext, ColumnResizeEvent, ColumnSizeDefaults, ColumnSizingState, ColumnVisibilityEvent, ColumnVisibilityState, ContextMenuOpenChangeEvent, FilterChangeEvent, FilterEntry, FilterState, GridCommand, GridCommandEvent, GridCommandTarget, GridContextMenuOptions, GridContextMenuRequest, GridContextMenuTarget, GridMessages, GridOptions, GridState, GridToolbarOptions, GroupByBarVisibility, HoverableConfig, MenuEntry, ResizeMode, ResolvedRow, RowPointerEvent, RowProps, RowSelectEvent, RowSelectionChangeEvent, RowsSelectEvent, SelectableConfig, SelectedCellRef, SelectionMode, SelectionState, SerializedGridState, ToolbarEntry, serializeGridState } from '@gridkitjs/core';
+import { ExportWriter, GridExportOptions, PrintOptions, CellSelectEvent as CellSelectEvent$1, CellSelectionChangeEvent as CellSelectionChangeEvent$1, ColumnDefinition as ColumnDefinition$1, ColumnSelectEvent as ColumnSelectEvent$1, ColumnSelectionChangeEvent as ColumnSelectionChangeEvent$1, ColumnsSelectEvent as ColumnsSelectEvent$1, DataColumn as DataColumn$1, GridOptions, PaginationState, SelectionCallbacks as SelectionCallbacks$1, ResolvedRow, DisplayRow, ResolvedColumn as ResolvedColumn$1, ColumnSizingState, ColumnOrderState, ColumnVisibilityState, ColumnSortState, FilterState, GroupByState, GroupExpansionState, AggregateResults, SelectionState, CellSelectionState, GridState, SerializedGridState, GridContextMenuTarget, GridCommandTarget, SelectedCell as SelectedCell$1, SelectedColumn as SelectedColumn$1 } from '@gridkitjs/core';
+export { Borders, CellSelectionMode, CellSelectionState, CellTemplateContext, ColumnResizeEvent, ColumnSizeDefaults, ColumnSizingState, ColumnVisibilityEvent, ColumnVisibilityState, ContextMenuOpenChangeEvent, ExportFile, ExportOptions, ExportWriter, FilterChangeEvent, FilterEntry, FilterState, GridCommand, GridCommandEvent, GridCommandTarget, GridContextMenuOptions, GridContextMenuRequest, GridContextMenuTarget, GridExportOptions, GridMessages, GridOptions, GridState, GridToolbarOptions, GroupByBarVisibility, HoverableConfig, MenuEntry, PrintOptions, ResizeMode, ResolvedRow, RowPointerEvent, RowProps, RowSelectEvent, RowSelectionChangeEvent, RowsSelectEvent, SelectableConfig, SelectedCellRef, SelectionMode, SelectionState, SerializedGridState, ToolbarEntry, excelFilter, serializeGridState } from '@gridkitjs/core';
+
+/** What `DataGridApi` carries for exporting. */
+interface GridExportApi {
+    /**
+     * The grid's view exported as `format` — `"csv"`, `"json"`, a format
+     * registered through `exportWriters`, or a writer passed as it is — and
+     * handed back as a `Blob`, under the grid's `export` option with
+     * `options` over it, field by field. Nothing is downloaded:
+     * `runCommand("export.csv")` downloads.
+     *
+     * Rejects for a format no writer is registered for, and when the writer
+     * fails.
+     */
+    exportData(format: string | ExportWriter, options?: GridExportOptions): Promise<Blob>;
+}
+
+/** What `DataGridApi` carries for the grid's panels. */
+interface GridPanelApi {
+    /**
+     * Opens the column chooser at the grid's top-end corner, in place of any
+     * panel open; it gives focus back to what had it when it closes.
+     */
+    openColumnChooser(): void;
+    /**
+     * Opens the filter menu of the column `columnId` below its header, in
+     * place of any panel open, and says whether it opened: not for a column
+     * with no filter menu, nor one not shown. It gives focus back to the
+     * header when it closes.
+     */
+    openFilterMenu(columnId: string): boolean;
+    /** Closes the filter menu, if one is open, leaving any other panel open. */
+    closeFilterMenu(): void;
+}
+
+/** What `DataGridApi` carries for printing. */
+interface GridPrintApi {
+    /**
+     * Prints the grid's view through the browser's print dialog — every row
+     * the filter leaves, across pages and collapsed groups, not only those
+     * drawn — under the grid's `print` option with `options` over it, field
+     * by field. Resolves once the dialog has closed, or at once while another
+     * print is open.
+     */
+    print(options?: PrintOptions): Promise<void>;
+}
 
 /**
  * A column whose header and cells may render arbitrary React content.
@@ -42,7 +87,7 @@ type SelectionCallbacks<Row> = SelectionCallbacks$1<Row, ReactNode>;
  * notify channel for state that changes; see
  * `packages/react/src/DataGrid/hooks/` for the public hooks built on it.
  */
-interface DataGridApi<Row> {
+interface DataGridApi<Row> extends GridExportApi, GridPrintApi, GridPanelApi {
     /** The grid's scrollable viewport element. */
     readonly element: HTMLDivElement | null;
     /**
@@ -126,7 +171,7 @@ interface DataGridApi<Row> {
      * callbacks once for the whole call, and none when nothing changed.
      */
     selectRows(rowIds: readonly string[], intent?: "replace" | "toggle"): void;
-    /** Expands every group at once — there is no dedicated UI control for it. */
+    /** Expands every group at once, as the `group.expandAll` command does. */
     expandAllGroups(): void;
     /** Collapses every group currently shown at once — see `collapseAllGroups` in `@gridkitjs/core` for what "currently shown" means for a group already nested under a collapsed one. */
     collapseAllGroups(): void;
@@ -204,11 +249,6 @@ interface DataGridApi<Row> {
     } | Element): boolean;
     /** Closes the context menu, if one is open. */
     closeContextMenu(): void;
-    /**
-     * Opens the column chooser at the grid's top-end corner, in place of any
-     * panel open; it gives focus back to what had it when it closes.
-     */
-    openColumnChooser(): void;
     /**
      * Runs a command by id — a built-in or one of `commands` — on `target`,
      * `{ area: "grid" }` when left out, when it is visible and enabled there.
@@ -443,8 +483,8 @@ interface FilterStateApi<Row> {
 }
 /**
  * Reactive filter state read off a mounted `DataGrid`'s `ref`, for a filter
- * bar or search box living outside the grid's own DOM — which, while the grid
- * has no filter UI of its own, is where filtering happens. `setFilter`
+ * bar or search box living outside the grid's own DOM, which sees every change
+ * however it was made — the toolbar's search box included. `setFilter`
  * replaces the whole filter and sends the grid back to its first page.
  *
  * Before the grid mounts, `filter` reads as an empty array and `setFilter`