@opencorestack/opengridx 1.0.5 → 1.0.6

package/docs/API_REFERENCE.md

@@ -164,6 +164,59 @@ The main component for displaying and interacting with data.
 
 ---
 
+## 🛠️ `GridToolbar`
+
+The built-in toolbar component. Mount it via `slots={{ toolbar: GridToolbar }}`. All props below are passed through `slotProps.toolbar` (or directly when building a custom wrapper).
+
+### `GridToolbarProps`
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `columns` | `GridColDef[]` | `[]` | Column definitions — injected automatically when used via `slots`. |
+| `baseColumns` | `GridColDef[]` | — | Pre-pivot columns shown in the Pivot panel instead of synthetic pivot columns. |
+| `aggregationModel` | `GridAggregationModel` | `{}` | Current aggregation configuration. |
+| `onAggregationModelChange` | `(model: GridAggregationModel) => void` | — | Called when the user changes aggregation settings. |
+| `pivotModel` | `GridPivotModel` | — | Current pivot configuration. Presence of this prop renders the Pivot button. |
+| `onPivotModelChange` | `(model: GridPivotModel) => void` | — | Called when the user changes pivot settings. |
+| `filterModel` | `GridFilterModel` | — | Current filter model. Presence of this prop renders the search bar and Filter button. |
+| `onFilterModelChange` | `(model: GridFilterModel) => void` | — | Called when the user changes filters or the quick-search value. |
+| `columnVisibilityModel` | `Record<string, boolean>` | `{}` | Current column visibility map. |
+| `onColumnVisibilityModelChange` | `(model: Record<string, boolean>) => void` | — | Called when the user shows or hides a column. Presence renders the Columns button. |
+| `onColumnReorder` | `(from: string, to: string) => void` | — | Called when the user drags a column in the Columns panel. |
+| `onColumnOrderReset` | `() => void` | — | Called when the user clicks "Reset order" in the Columns panel. |
+| `forceColumnsOpen` | `boolean` | — | Forces the Columns panel open (used internally by the column header context menu). |
+| `onColumnsPanelClose` | `() => void` | — | Called when the Columns panel closes after a `forceColumnsOpen`. |
+| `children` | `ReactNode` | — | Content rendered on the **left** side of the toolbar, before the spacer. |
+| `rightContent` | `ReactNode` | — | Content rendered on the **right** side, after all built-in buttons. |
+| `className` | `string` | — | Additional CSS class on the toolbar root `<div>`. Use for visual theme overrides. |
+| `style` | `CSSProperties` | — | Inline styles on the toolbar root. |
+| `renderColumnsButton` | `(props: ToolbarButtonRenderProps) => ReactNode` | — | Replace the built-in Columns toggle button. The Columns panel still functions normally. |
+| `renderFilterButton` | `(props: ToolbarButtonRenderProps) => ReactNode` | — | Replace the built-in Filters toggle button. The Filter panel still functions normally. |
+| `renderAggregationButton` | `(props: ToolbarButtonRenderProps) => ReactNode` | — | Replace the built-in Summaries toggle button. The Aggregation panel still functions normally. |
+| `renderExportButton` | `() => ReactNode` | — | Inject an Export button after the Aggregation button. No built-in export button exists. |
+| `renderQuickFilter` | `(props: ToolbarQuickFilterRenderProps) => ReactNode` | — | Replace the built-in `GlobalSearch` input with your own component. |
+
+### `ToolbarButtonRenderProps`
+
+Passed to `renderColumnsButton`, `renderFilterButton`, and `renderAggregationButton`.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `onClick` | `() => void` | Toggle the associated panel open or closed. |
+| `isOpen` | `boolean` | Whether the associated panel is currently open. |
+| `activeCount` | `number` | Active items: hidden columns for Columns, applied filters for Filter, configured aggregations for Summaries. |
+
+### `ToolbarQuickFilterRenderProps`
+
+Passed to `renderQuickFilter`.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `value` | `string` | Current search string. |
+| `onChange` | `(value: string) => void` | Call with the updated string when the input changes. |
+
+---
+
 ## 🕹️ Imperative API (`GridApi`)
 
 Access these methods via the `apiRef` prop.

package/docs/components/toolbar.md

@@ -1,40 +1,221 @@
-# `<Toolbar />`
+# `GridToolbar`
 
-The toolbar is an optional component rendered at the top of the grid. It typically contains global actions like exporting, filtering, and column management.
+The toolbar is an optional component rendered at the top of the grid. It provides global search, column visibility management, advanced filters, aggregation configuration, and pivot mode — all in one composable component.
 
-## 🛠️ Provided Component: `GridToolbar`
+## Basic usage
 
-OpenGridX includes a pre-built `GridToolbar` that bundles common actions.
-
-### Usage
 ```tsx
 import { DataGrid, GridToolbar } from '@opencorestack/opengridx';
 
 <DataGrid
-  slots={{
-    toolbar: GridToolbar
+  rows={rows}
+  columns={columns}
+  filterModel={filterModel}
+  onFilterModelChange={setFilterModel}
+  columnVisibilityModel={columnVisibilityModel}
+  onColumnVisibilityModelChange={setColumnVisibilityModel}
+  aggregationModel={aggregationModel}
+  onAggregationModelChange={setAggregationModel}
+  slots={{ toolbar: GridToolbar }}
+/>
+```
+
+`GridToolbar` automatically hides buttons for features whose callbacks are not wired. For example, if you don't pass `onFilterModelChange` the search bar and filter button are not rendered.
+
+---
+
+## `GridToolbarProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `GridColDef[]` | `[]` | Column definitions (injected automatically when used via `slots`). |
+| `baseColumns` | `GridColDef[]` | — | Pre-pivot column definitions, used by the Pivot panel to avoid showing synthetic columns. |
+| `aggregationModel` | `GridAggregationModel` | `{}` | Current aggregation configuration. |
+| `onAggregationModelChange` | `(model) => void` | — | Called when the user changes aggregation settings. |
+| `pivotModel` | `GridPivotModel` | — | Current pivot configuration. |
+| `onPivotModelChange` | `(model) => void` | — | Called when the user changes pivot settings. Presence of this prop shows the Pivot button. |
+| `filterModel` | `GridFilterModel` | — | Current filter model. Presence of this prop shows the search bar and Filter button. |
+| `onFilterModelChange` | `(model) => void` | — | Called when the user changes filters or the search query. |
+| `columnVisibilityModel` | `Record<string, boolean>` | `{}` | Current column visibility state. |
+| `onColumnVisibilityModelChange` | `(model) => void` | — | Called when the user shows/hides columns. Presence shows the Columns button. |
+| `onColumnReorder` | `(from, to) => void` | — | Called when the user drags a column in the Columns panel. |
+| `onColumnOrderReset` | `() => void` | — | Called when the user clicks "Reset order" in the Columns panel. |
+| `forceColumnsOpen` | `boolean` | — | When `true`, opens the Columns panel immediately (used internally by the column header menu). |
+| `onColumnsPanelClose` | `() => void` | — | Called when the Columns panel closes after a `forceColumnsOpen`. |
+| `children` | `ReactNode` | — | Content rendered in the **left** side of the toolbar (before the spacer). |
+| `rightContent` | `ReactNode` | — | Content rendered in the **right** side of the toolbar (after all built-in buttons). |
+| `className` | `string` | — | Additional CSS class applied to the toolbar root `<div>`. Use for visual overrides without replacing the component. |
+| `style` | `CSSProperties` | — | Inline style applied to the toolbar root `<div>`. |
+| `renderColumnsButton` | `(props: ToolbarButtonRenderProps) => ReactNode` | — | Replace the built-in Columns button. The Columns panel still opens and closes normally. |
+| `renderFilterButton` | `(props: ToolbarButtonRenderProps) => ReactNode` | — | Replace the built-in Filters button. The Filter panel still opens and closes normally. |
+| `renderAggregationButton` | `(props: ToolbarButtonRenderProps) => ReactNode` | — | Replace the built-in Summaries button. The Aggregation panel still opens and closes normally. |
+| `renderExportButton` | `() => ReactNode` | — | Inject an Export button after the Aggregation button. No built-in export button exists — this is the slot for it. |
+| `renderQuickFilter` | `(props: ToolbarQuickFilterRenderProps) => ReactNode` | — | Replace the built-in quick-filter search input with your own component. |
+
+---
+
+## Render prop types
+
+### `ToolbarButtonRenderProps`
+
+Passed to `renderColumnsButton`, `renderFilterButton`, and `renderAggregationButton`.
+
+```ts
+interface ToolbarButtonRenderProps {
+  onClick: () => void;     // Toggle the associated panel open/closed
+  isOpen: boolean;         // Whether the panel is currently open
+  activeCount: number;     // Active items (hidden columns, applied filters, etc.)
+}
+```
+
+### `ToolbarQuickFilterRenderProps`
+
+Passed to `renderQuickFilter`.
+
+```ts
+interface ToolbarQuickFilterRenderProps {
+  value: string;                  // Current search string
+  onChange: (value: string) => void; // Call with new string on input change
+}
+```
+
+---
+
+## Customization patterns
+
+### Add content to left or right sides
+
+Use `children` (left) and `rightContent` (right) to inject elements without touching the built-in buttons:
+
+```tsx
+<DataGrid
+  slots={{ toolbar: GridToolbar }}
+  slotProps={{
+    toolbar: {
+      children: <span style={{ fontWeight: 600 }}>My Grid</span>,
+      rightContent: (
+        <button onClick={handleExport}>Export CSV</button>
+      ),
+    },
+  }}
+/>
+```
+
+### Custom search bar
+
+Replace only the search input while keeping the rest of the toolbar intact:
+
+```tsx
+function MySearchBar({ value, onChange }: ToolbarQuickFilterRenderProps) {
+  return (
+    <input
+      className="my-search"
+      value={value}
+      onChange={e => onChange(e.target.value)}
+      placeholder="Search…"
+    />
+  );
+}
+
+<DataGrid
+  slots={{ toolbar: GridToolbar }}
+  slotProps={{
+    toolbar: {
+      renderQuickFilter: (props) => <MySearchBar {...props} />,
+    },
   }}
 />
 ```
 
-### Features
-- **Quick Search**: Search across all visible columns.
-- **Export Menu**: Download data as CSV, Print, or [Advanced Excel](../features/export-guide.md).
-- **Column Visibility**: Toggle which columns are shown via a dropdown [Visibility Panel](column-visibility.md).
-- **Density**: Switch between Compact, Standard, and Comfortable row heights.
+### Custom action buttons (panels still work)
 
-## 🎨 Custom Toolbar
+Replace individual trigger buttons while keeping their panels fully functional:
 
-You can provide your own component to the `toolbar` slot. It will receive props to interact with the grid state.
+```tsx
+function MyFilterButton({ onClick, isOpen, activeCount }: ToolbarButtonRenderProps) {
+  return (
+    <button
+      className={`my-btn ${isOpen ? 'my-btn--active' : ''}`}
+      onClick={onClick}
+    >
+      Filters {activeCount > 0 && <span className="badge">{activeCount}</span>}
+    </button>
+  );
+}
+
+<DataGrid
+  slots={{ toolbar: GridToolbar }}
+  slotProps={{
+    toolbar: {
+      renderFilterButton: (props) => <MyFilterButton {...props} />,
+      renderColumnsButton: (props) => <MyColumnsButton {...props} />,
+      renderAggregationButton: (props) => <MyAggButton {...props} />,
+    },
+  }}
+/>
+```
+
+### Add an Export button
+
+There is no built-in export button in the toolbar. Use `renderExportButton` to add one:
 
 ```tsx
-const MyToolbar = () => {
+import { exportToCsv, useGridApiRef } from '@opencorestack/opengridx';
+
+const apiRef = useGridApiRef();
+
+<DataGrid
+  apiRef={apiRef}
+  slots={{ toolbar: GridToolbar }}
+  slotProps={{
+    toolbar: {
+      renderExportButton: () => (
+        <button onClick={() => exportToCsv(apiRef.current.getAllRows(), columns)}>
+          Export CSV
+        </button>
+      ),
+    },
+  }}
+/>
+```
+
+### Theme override via `className`
+
+Style the toolbar to match your brand without replacing the component:
+
+```css
+/* your-styles.css */
+.my-toolbar {
+  background: linear-gradient(135deg, #1e1b4b, #312e81);
+  border-bottom: none;
+  border-radius: 8px 8px 0 0;
+  padding: 10px 16px;
+}
+```
+
+```tsx
+<DataGrid
+  slots={{ toolbar: GridToolbar }}
+  slotProps={{ toolbar: { className: 'my-toolbar' } }}
+/>
+```
+
+---
+
+## Fully custom toolbar
+
+If the render props don't give you enough control, replace the entire toolbar via `slots.toolbar`:
+
+```tsx
+function MyToolbar() {
   return (
-    <div className="custom-toolbar">
-      <button onClick={...}>Custom Action</button>
+    <div className="my-toolbar-root">
+      <span>Custom toolbar</span>
     </div>
   );
-};
+}
 
 <DataGrid slots={{ toolbar: MyToolbar }} />
 ```
+
+The custom component receives all `GridToolbarProps` via `slotProps.toolbar`.

package/docs/features/toolbar-customization.md

@@ -0,0 +1,205 @@
+# Toolbar Customization
+
+**Available from:** `@opencorestack/opengridx` v1.0.6
+
+Replace individual toolbar controls — search bar, column button, filter button, aggregation button — without replacing the entire toolbar. All panels (columns, filters, aggregation) continue to work; only the trigger elements change.
+
+---
+
+## Quick start
+
+```tsx
+import {
+  DataGrid,
+  GridToolbar,
+  type ToolbarButtonRenderProps,
+  type ToolbarQuickFilterRenderProps,
+} from '@opencorestack/opengridx';
+
+<DataGrid
+  rows={rows}
+  columns={columns}
+  filterModel={filterModel}
+  onFilterModelChange={setFilterModel}
+  columnVisibilityModel={columnVisibilityModel}
+  onColumnVisibilityModelChange={setColumnVisibilityModel}
+  slots={{ toolbar: GridToolbar }}
+  slotProps={{
+    toolbar: {
+      renderQuickFilter: ({ value, onChange }: ToolbarQuickFilterRenderProps) => (
+        <input
+          className="my-search"
+          value={value}
+          onChange={e => onChange(e.target.value)}
+          placeholder="Search…"
+        />
+      ),
+    },
+  }}
+/>
+```
+
+---
+
+## New props on `GridToolbarProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderColumnsButton` | `(props: ToolbarButtonRenderProps) => ReactNode` | Replace the Columns toggle button. The Columns panel still opens and closes normally. |
+| `renderFilterButton` | `(props: ToolbarButtonRenderProps) => ReactNode` | Replace the Filters toggle button. The Filter panel still opens and closes normally. |
+| `renderAggregationButton` | `(props: ToolbarButtonRenderProps) => ReactNode` | Replace the Summaries toggle button. The Aggregation panel still opens and closes normally. |
+| `renderExportButton` | `() => ReactNode` | Insert an Export button after the Aggregation button. No built-in export button exists — this is the slot for it. |
+| `renderQuickFilter` | `(props: ToolbarQuickFilterRenderProps) => ReactNode` | Replace the built-in search input with your own component. |
+| `className` | `string` | Additional CSS class on the toolbar root `<div>` for theme overrides. |
+
+---
+
+## Render prop types
+
+### `ToolbarButtonRenderProps`
+
+```ts
+interface ToolbarButtonRenderProps {
+  onClick: () => void;   // toggle the panel
+  isOpen: boolean;       // whether the panel is open
+  activeCount: number;   // hidden columns / applied filters / active aggregations
+}
+```
+
+### `ToolbarQuickFilterRenderProps`
+
+```ts
+interface ToolbarQuickFilterRenderProps {
+  value: string;
+  onChange: (value: string) => void;
+}
+```
+
+Both types are exported from the package:
+
+```ts
+import type { ToolbarButtonRenderProps, ToolbarQuickFilterRenderProps } from '@opencorestack/opengridx';
+```
+
+---
+
+## Examples
+
+### Custom search bar
+
+```tsx
+function MySearchBar({ value, onChange }: ToolbarQuickFilterRenderProps) {
+  return (
+    <div className="search-wrap">
+      <SearchIcon />
+      <input
+        value={value}
+        onChange={e => onChange(e.target.value)}
+        placeholder="Search…"
+      />
+      {value && <button onClick={() => onChange('')}>✕</button>}
+    </div>
+  );
+}
+
+slotProps={{
+  toolbar: {
+    renderQuickFilter: (props) => <MySearchBar {...props} />,
+  },
+}}
+```
+
+### Custom filter button with active-count badge
+
+```tsx
+function MyFilterBtn({ onClick, isOpen, activeCount }: ToolbarButtonRenderProps) {
+  return (
+    <button
+      className={`btn ${isOpen ? 'btn--active' : ''}`}
+      onClick={onClick}
+    >
+      Filters
+      {activeCount > 0 && <span className="badge">{activeCount}</span>}
+    </button>
+  );
+}
+
+slotProps={{
+  toolbar: {
+    renderFilterButton: (props) => <MyFilterBtn {...props} />,
+  },
+}}
+```
+
+### Export button wired to `apiRef`
+
+```tsx
+import { exportToCsv, useGridApiRef } from '@opencorestack/opengridx';
+
+const apiRef = useGridApiRef();
+
+<DataGrid
+  apiRef={apiRef}
+  slots={{ toolbar: GridToolbar }}
+  slotProps={{
+    toolbar: {
+      renderExportButton: () => (
+        <button onClick={() => exportToCsv(apiRef.current.getAllRows(), columns, { filename: 'export' })}>
+          Export CSV
+        </button>
+      ),
+    },
+  }}
+/>
+```
+
+### Replacing all buttons at once
+
+```tsx
+slotProps={{
+  toolbar: {
+    renderQuickFilter:       (props) => <MySearch {...props} />,
+    renderColumnsButton:     (props) => <MyColumnsBtn {...props} />,
+    renderFilterButton:      (props) => <MyFilterBtn {...props} />,
+    renderAggregationButton: (props) => <MyAggBtn {...props} />,
+    renderExportButton:      ()      => <MyExportBtn />,
+  },
+}}
+```
+
+### Theme override via `className`
+
+```css
+/* your-styles.css */
+.toolbar-dark {
+  background: linear-gradient(135deg, #1e1b4b, #312e81);
+  border-bottom: none;
+  padding: 10px 16px;
+}
+```
+
+```tsx
+slotProps={{
+  toolbar: { className: 'toolbar-dark' },
+}}
+```
+
+---
+
+## How panels stay functional
+
+When you provide a custom button, the toolbar renders your element as the trigger but keeps its own open/close state. The panel (Columns, Filters, or Aggregation) is positioned relative to the wrapper `<div>` surrounding your custom button, so placement is automatic — you don't need to pass any refs.
+
+Panel close behaviour is unchanged: Escape key closes, click-outside closes (except the Filter panel, which requires an explicit Close button to let users type without it dismissing).
+
+---
+
+## What is NOT replaced
+
+These built-in features are unaffected regardless of which render props you provide:
+
+- Column panel content (drag-to-reorder, show/hide toggles)
+- Filter panel content (operators, values, logic operator)
+- Aggregation panel content (per-column function pills)
+- Pivot panel (if `onPivotModelChange` is wired)
+- `children` / `rightContent` slot behaviour