@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/features/toolbar.mdx

@@ -0,0 +1,284 @@
+---
+sidebar_position: 14.5
+title: Toolbar & Layout
+description: Unified bordered container with configurable toolbar strip, sidebar, and column chooser placement.
+---
+
+
+# Toolbar & Layout
+
+OGrid wraps your grid in a **single bordered container** with three sections: a toolbar strip, the grid area, and a footer. Every section is optional — the container adapts to what you enable.
+
+## Layout Anatomy
+
+<LayoutDiagram />
+
+Every combination is valid — you can use just the grid, add a toolbar, add pagination, enable the sidebar, or use all of them together. The bordered container handles spacing and borders automatically.
+
+## Default Layout
+
+With no extra props, OGrid renders a toolbar strip containing only the column chooser button on the right, plus the grid. Click the columns button to toggle column visibility.
+
+<ToolbarDefaultDemo />
+
+:::tip Try it in your framework
+The demo above uses Radix UI for styling. To see this feature with your framework's design system (Fluent UI, Material UI, Vuetify, PrimeNG, etc.), click **"Open in online demo"** below the demo.
+:::
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  columnChooser="toolbar"
+  pagination
+/>
+```
+
+:::tip Switching UI libraries
+The `OGrid` component has the same props across all React UI packages. To switch, just change the import:
+
+- **Radix** (lightweight, default): `from '@alaarab/ogrid-react-radix'`
+- **Fluent UI** (Microsoft 365 / SPFx): `from '@alaarab/ogrid-react-fluent'` — wrap in `<FluentProvider>`
+- **Material UI** (MUI v7): `from '@alaarab/ogrid-react-material'` — wrap in `<ThemeProvider>`
+:::
+
+  </TabItem>
+  <TabItem value="angular" label="Angular">
+
+```typescript
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns: columns,
+    data: items,
+    getRowId: (item: Item) => item.id,
+    columnChooser: 'toolbar' as const,
+    pagination: true,
+  };
+}
+```
+
+:::tip Switching UI libraries
+Same component API across Angular packages. To switch, just change the import:
+
+- **Radix (CDK)**: `from '@alaarab/ogrid-angular-radix'` *(default, lightweight)*
+- **Angular Material**: `from '@alaarab/ogrid-angular-material'`
+- **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
+
+All components are standalone — no NgModule required.
+:::
+
+  </TabItem>
+  <TabItem value="vue" label="Vue">
+
+```vue
+<script setup lang="ts">
+
+const gridProps = {
+  columns,
+  data: items,
+  getRowId: (item) => item.id,
+  columnChooser: 'toolbar' as const,
+  pagination: true,
+};
+</script>
+
+<template>
+  <OGrid :gridProps="gridProps" />
+</template>
+```
+
+:::tip Switching UI libraries
+Same component API across Vue packages. To switch, just change the import:
+
+- **Radix (Headless UI)**: `from '@alaarab/ogrid-vue-radix'` *(default, lightweight)*
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'` — wrap in `<v-app>` for theming
+- **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
+:::
+
+  </TabItem>
+  <TabItem value="js" label="Vanilla JS">
+
+```js
+
+const grid = new OGrid(document.getElementById('grid'), {
+  columns: columns,
+  data: items,
+  getRowId: (item) => item.id,
+  columnChooser: true,
+  pagination: true,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## Custom Toolbar Content
+
+The `toolbar` prop places your content on the **left** side of the toolbar strip. The column chooser stays on the **right**. Use this for action buttons, search inputs, status text, or anything else.
+
+<ToolbarCustomDemo />
+
+```tsx
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  toolbar={
+    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+      <button onClick={handleExport}>Export CSV</button>
+      <button onClick={handleSelectAll}>Select All</button>
+      <span>{data.length} rows</span>
+    </div>
+  }
+  columnChooser="toolbar"
+  pagination
+/>
+```
+
+## Secondary Toolbar Row
+
+The `toolbarBelow` prop renders a **secondary row** below the primary toolbar strip. Use it for active filter chips, breadcrumbs, search bars, or any contextual content that should sit between the toolbar and the grid.
+
+<ToolbarBelowDemo />
+
+```tsx
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  toolbar={
+    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+      <button onClick={handleExport}>Export CSV</button>
+      <span>{data.length} rows</span>
+    </div>
+  }
+  toolbarBelow={
+    <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap' }}>
+      <span style={{ padding: '2px 8px', background: '#e0e0e0', borderRadius: 12, fontSize: 12 }}>
+        Department: Engineering ✕
+      </span>
+      <span style={{ padding: '2px 8px', background: '#e0e0e0', borderRadius: 12, fontSize: 12 }}>
+        Status: Active ✕
+      </span>
+    </div>
+  }
+  columnChooser="toolbar"
+  pagination
+/>
+```
+
+:::tip
+The secondary toolbar row shares the same background and border styling as the primary toolbar. It only renders when `toolbarBelow` is provided — no empty space when omitted.
+:::
+
+## Column Chooser Placement
+
+The `columnChooser` prop controls where the column visibility control appears:
+
+| Value | Behavior |
+|-------|----------|
+| `true` or `'toolbar'` | Column chooser button in the toolbar strip (default) |
+| `'sidebar'` | Column chooser moves to the sidebar's Columns panel |
+| `false` | Hidden entirely — columns are locked |
+
+### Sidebar Mode
+
+When `columnChooser="sidebar"`, the column chooser button is removed from the toolbar. Instead, users toggle column visibility from the sidebar's Columns panel. This is useful when you have many columns and want a dedicated panel for managing them.
+
+<ToolbarSidebarDemo />
+
+```tsx
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  columnChooser="sidebar"
+  sideBar
+  pagination
+/>
+```
+
+:::tip
+The sidebar also includes a **Filters** panel with inline filter controls. Click the filter icon tab to switch panels.
+:::
+
+### Hidden
+
+Set `columnChooser={false}` when you want to lock the visible columns and prevent users from changing them.
+
+```tsx
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  columnChooser={false}
+/>
+```
+
+## Full Layout
+
+Here is every layout feature enabled at once — toolbar with custom buttons, column chooser, sidebar, cell selection with status bar aggregations, and pagination:
+
+<ToolbarFullDemo />
+
+```tsx
+<OGrid
+  ref={gridRef}
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  columnChooser="toolbar"
+  sideBar
+  statusBar
+  cellSelection
+  pagination
+  toolbar={
+    <div style={{ display: 'flex', gap: 8 }}>
+      <button onClick={() => gridRef.current?.deselectAll()}>
+        Clear Selection
+      </button>
+    </div>
+  }
+/>
+```
+
+## Headings and Titles
+
+The `title` prop is **deprecated**. Render headings outside the `<OGrid>` component for full control over styling:
+
+```tsx
+<div>
+  <h1>Projects Dashboard</h1>
+  <p>Manage all active projects below.</p>
+  <OGrid columns={columns} data={projects} getRowId={(p) => p.id} />
+</div>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `toolbar` | `ReactNode` | -- | Custom content in the left side of the toolbar strip. |
+| `toolbarBelow` | `ReactNode` | -- | Secondary toolbar row below the primary toolbar (e.g. filter chips, breadcrumbs). |
+| `columnChooser` | `boolean \| 'toolbar' \| 'sidebar'` | `true` | Where to place the column chooser. `true`/`'toolbar'` = toolbar, `'sidebar'` = sidebar panel only, `false` = hidden. |
+| `sideBar` | `boolean \| ISideBarDef` | `false` | Enable sidebar panels. Required for `columnChooser="sidebar"`. |
+| `statusBar` | `boolean` | `false` | Show status bar below the grid with row counts and aggregations. |
+| `pagination` | `boolean \| IPaginationProps` | `false` | Show pagination in the footer strip. |
+| `cellSelection` | `boolean` | `true` | Enable cell range selection (needed for status bar aggregations). |
+
+## Related
+
+- [Column Chooser](./column-chooser) -- toggle column visibility
+- [Status Bar](./status-bar) -- row counts and aggregations
+- [Pagination](./pagination) -- paginate data rows