@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/features/server-side-data.mdx

@@ -0,0 +1,291 @@
+---
+sidebar_position: 16
+title: Server-Side Data
+description: Fetch pages of data from a server with sorting, filtering, and people search
+---
+
+
+# Server-Side Data
+
+Pass a `dataSource` instead of a `data` array to delegate sorting, filtering, and pagination to your server.
+
+## Live Demo
+
+<ServerSideDemo />
+
+:::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.
+:::
+
+## Quick Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+interface Employee {
+  id: number;
+  name: string;
+  department: string;
+  salary: number;
+}
+
+const dataSource: IDataSource<Employee> = {
+  async fetchPage(params: IFetchParams): Promise<IPageResult<Employee>> {
+    const query = new URLSearchParams({
+      page: String(params.page),
+      pageSize: String(params.pageSize),
+      ...(params.sort && {
+        sortField: params.sort.field,
+        sortDir: params.sort.direction,
+      }),
+    });
+    const res = await fetch(`/api/employees?${query}`);
+    return res.json(); // { items: Employee[], totalCount: number }
+  },
+};
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      dataSource={dataSource}
+      getRowId={(e) => e.id}
+      defaultPageSize={25}
+    />
+  );
+}
+```
+
+:::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
+
+interface Employee {
+  id: number;
+  name: string;
+  department: string;
+  salary: number;
+}
+
+const dataSource: IDataSource<Employee> = {
+  async fetchPage(params: IFetchParams): Promise<IPageResult<Employee>> {
+    const query = new URLSearchParams({
+      page: String(params.page),
+      pageSize: String(params.pageSize),
+      ...(params.sort && {
+        sortField: params.sort.field,
+        sortDir: params.sort.direction,
+      }),
+    });
+    const res = await fetch(`/api/employees?${query}`);
+    return res.json();
+  },
+};
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns: columns,
+    dataSource,
+    getRowId: (e: Employee) => e.id,
+    defaultPageSize: 25,
+  };
+}
+```
+
+:::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">
+
+interface Employee {
+  id: number;
+  name: string;
+  department: string;
+  salary: number;
+}
+
+const dataSource: IDataSource<Employee> = {
+  async fetchPage(params: IFetchParams): Promise<IPageResult<Employee>> {
+    const query = new URLSearchParams({
+      page: String(params.page),
+      pageSize: String(params.pageSize),
+      ...(params.sort && {
+        sortField: params.sort.field,
+        sortDir: params.sort.direction,
+      }),
+    });
+    const res = await fetch(`/api/employees?${query}`);
+    return res.json();
+  },
+};
+
+const gridProps = {
+  columns,
+  dataSource,
+  getRowId: (e: Employee) => e.id,
+  defaultPageSize: 25,
+};
+</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,
+  dataSource: {
+    async fetchPage({ page, pageSize, sort, filters }) {
+      const query = new URLSearchParams({
+        page: String(page),
+        pageSize: String(pageSize),
+        ...(sort && {
+          sortField: sort.field,
+          sortDir: sort.direction,
+        }),
+      });
+      const res = await fetch(`/api/employees?${query}`);
+      return res.json(); // { items: Employee[], totalCount: number }
+    },
+  },
+  getRowId: (e) => e.id,
+  pageSize: 25,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+The grid fetches the first page on mount and re-fetches whenever page, sort, or filters change.
+
+## IDataSource&lt;T&gt; Reference
+
+```typescript
+interface IDataSource<T> {
+  fetchPage(params: IFetchParams): Promise<IPageResult<T>>;
+  fetchFilterOptions?(field: string): Promise<string[]>;
+  searchPeople?(query: string): Promise<UserLike[]>;
+  getUserByEmail?(email: string): Promise<UserLike | undefined>;
+}
+```
+
+| Method | Required | Description |
+|--------|----------|-------------|
+| `fetchPage` | Yes | Fetches a page of data. Called on page/sort/filter changes. |
+| `fetchFilterOptions` | No | Returns options for `multiSelect` filters with `optionsSource: 'api'`. |
+| `searchPeople` | No | Searches people for `people`-type column filters. |
+| `getUserByEmail` | No | Resolves a user by email (for restoring saved people filters). |
+
+### IFetchParams
+
+```typescript
+interface IFetchParams {
+  page: number;        // 1-indexed
+  pageSize: number;
+  sort?: { field: string; direction: 'asc' | 'desc' };
+  filters: IFilters;   // See Types reference for FilterValue shapes
+}
+```
+
+### IPageResult&lt;T&gt;
+
+```typescript
+interface IPageResult<T> {
+  items: T[];
+  totalCount: number;  // drives pagination controls
+}
+```
+
+## Filter Options & People Search
+
+```tsx
+const dataSource: IDataSource<Employee> = {
+  async fetchPage(params) { /* ... */ },
+
+  async fetchFilterOptions(field: string): Promise<string[]> {
+    const res = await fetch(`/api/employees/filter-options/${field}`);
+    return res.json(); // ['Engineering', 'Marketing', 'Sales']
+  },
+
+  async searchPeople(query: string): Promise<UserLike[]> {
+    const res = await fetch(`/api/people/search?q=${query}`);
+    return res.json();
+  },
+
+  async getUserByEmail(email: string): Promise<UserLike | undefined> {
+    const res = await fetch(`/api/people/${email}`);
+    if (!res.ok) return undefined;
+    return res.json();
+  },
+};
+```
+
+## Error Handling & Loading
+
+```tsx
+<OGrid
+  columns={columns}
+  dataSource={dataSource}
+  getRowId={(e) => e.id}
+  onError={(error) => {
+    console.error('Grid fetch failed:', error);
+    showToast('Failed to load data.');
+  }}
+/>
+```
+
+The grid manages loading state automatically. You can also control it via `gridRef.current?.setLoading(true)`.
+
+## Client-Side vs. Server-Side
+
+| | Client-side (`data`) | Server-side (`dataSource`) |
+|---|---|---|
+| Data location | All rows in memory | Fetched per page |
+| Sorting / Filtering | In-memory by the grid | Your server handles it |
+| Best for | < 10,000 rows | Large datasets, real-time data |
+
+## Related
+
+- [Filtering](./filtering) -- filter types and configuration
+- [Grid API](../api/grid-api) -- `setFilterModel()` for programmatic filtering
+- [Types](../api/types) -- `IFilters`, `FilterValue`, `UserLike` shapes

package/bundled-docs/features/sidebar.mdx

@@ -0,0 +1,234 @@
+---
+sidebar_position: 15.5
+title: Side Bar
+description: Collapsible side panel with Columns and Filters panels for managing column visibility and filtering.
+---
+
+
+# Side Bar
+
+The Side Bar adds a collapsible panel alongside the grid with two built-in panels: **Columns** (toggle column visibility with Select All / Clear All) and **Filters** (inline text, multi-select, and date filters). Click the tab icons to open or close panels.
+
+## Live Demo
+
+<SideBarDemo />
+
+:::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}
+  sideBar
+  columnChooser="sidebar"
+  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,
+    sideBar: true,
+    columnChooser: 'sidebar' 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,
+  sideBar: true,
+  columnChooser: 'sidebar' 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,
+  sideBar: true,
+  columnChooser: 'sidebar',
+  pagination: true,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+Set `sideBar` to `true` to enable both panels with default settings. Set `columnChooser="sidebar"` to move the column chooser from the toolbar into the sidebar's Columns panel.
+
+## Panels
+
+### Columns Panel
+
+The Columns panel lists every column with a checkbox. Users can:
+
+- Toggle individual columns on or off
+- **Select All** to show every column
+- **Clear All** to hide all non-required columns
+
+Columns with `required: true` cannot be hidden — their checkboxes are disabled.
+
+### Filters Panel
+
+The Filters panel shows inline filter controls for every filterable column:
+
+| Column filter type | Sidebar control |
+|---|---|
+| `text` | Text input |
+| `multiSelect` | Checkbox list of options |
+| `date` | From / To date inputs |
+
+Filters applied in the sidebar work the same as column header filters — they share state.
+
+## Configuration
+
+Pass an `ISideBarDef` object instead of `true` to customize panels, position, and default state.
+
+### Left Position
+
+<SideBarLeftDemo />
+
+```tsx
+
+const sideBarDef: ISideBarDef = {
+  position: 'left',
+  defaultPanel: 'filters',
+};
+
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  sideBar={sideBarDef}
+  columnChooser="sidebar"
+/>
+```
+
+### Columns Panel Only
+
+<SideBarColumnsOnlyDemo />
+
+```tsx
+const sideBarDef: ISideBarDef = {
+  panels: ['columns'],
+  defaultPanel: 'columns',
+};
+
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  sideBar={sideBarDef}
+  columnChooser="sidebar"
+/>
+```
+
+### Filters Panel Only
+
+```tsx
+const sideBarDef: ISideBarDef = {
+  panels: ['filters'],
+};
+
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  sideBar={sideBarDef}
+/>
+```
+
+## Props
+
+### `sideBar` (on `IOGridProps`)
+
+| Value | Behavior |
+|-------|----------|
+| `false` / omitted | No side bar |
+| `true` | Both panels, right position, collapsed on mount |
+| `ISideBarDef` | Full configuration (see below) |
+
+### `ISideBarDef`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `panels` | `SideBarPanelId[]` | `['columns', 'filters']` | Which panels to include. |
+| `defaultPanel` | `SideBarPanelId` | -- | Panel to open automatically on mount. |
+| `position` | `'left' \| 'right'` | `'right'` | Which side of the grid the bar appears on. |
+
+### `SideBarPanelId`
+
+```ts
+type SideBarPanelId = 'columns' | 'filters';
+```
+
+## Related
+
+- [Column Chooser](./column-chooser) -- standalone column visibility dropdown
+- [Toolbar & Layout](./toolbar) -- the container that wraps sidebar + grid
+- [Filtering](./filtering) -- column header filters (shared state with sidebar)