@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/api/components-column-chooser.mdx

@@ -0,0 +1,310 @@
+---
+sidebar_position: 12
+title: ColumnChooser
+---
+
+# ColumnChooser
+
+A dropdown component that allows users to show/hide columns in the grid. Displays a list of all columns with checkboxes, and provides "Select All" and "Clear All" actions.
+
+## Import
+
+
+<Tabs groupId="framework">
+<TabItem value="react" label="React">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="angular" label="Angular">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="vue" label="Vue">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="js" label="Vanilla JS">
+
+```typescript
+// ColumnChooser is an internal component in vanilla JS
+```
+
+</TabItem>
+</Tabs>
+
+## Props (React)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `IColumnDefinition[]` | **Required** | Array of all columns (visible and hidden). |
+| `visibleColumns` | `Set<string>` | **Required** | Set of currently visible column IDs. |
+| `onVisibilityChange` | `(columnKey: string, visible: boolean) => void` | **Required** | Callback when a column's visibility is toggled. |
+| `className` | `string` | `undefined` | Additional CSS class for the root element. |
+
+## IColumnDefinition
+
+Minimal column info used by the column chooser:
+
+```typescript
+interface IColumnDefinition {
+  columnId: string;
+  name: string;
+  required?: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `columnId` | `string` | Unique column identifier. |
+| `name` | `string` | Display name shown in the dropdown. |
+| `required` | `boolean` | When `true`, the checkbox is disabled (column cannot be hidden). |
+
+## Usage
+
+### Basic Example (React)
+
+```tsx
+
+function MyApp() {
+  const columns: IColumnDefinition[] = [
+    { columnId: 'id', name: 'ID', required: true },
+    { columnId: 'name', name: 'Product Name' },
+    { columnId: 'price', name: 'Price' },
+    { columnId: 'category', name: 'Category' },
+  ];
+
+  const [visibleColumns, setVisibleColumns] = useState<Set<string>>(
+    new Set(['id', 'name', 'price'])
+  );
+
+  const handleVisibilityChange = (columnKey: string, visible: boolean) => {
+    const newSet = new Set(visibleColumns);
+    if (visible) {
+      newSet.add(columnKey);
+    } else {
+      newSet.delete(columnKey);
+    }
+    setVisibleColumns(newSet);
+  };
+
+  return (
+    <ColumnChooser
+      columns={columns}
+      visibleColumns={visibleColumns}
+      onVisibilityChange={handleVisibilityChange}
+    />
+  );
+}
+```
+
+### With Required Columns (React)
+
+```tsx
+
+const columns: IColumnDefinition[] = [
+  { columnId: 'id', name: 'ID', required: true }, // Cannot be hidden
+  { columnId: 'name', name: 'Product Name', required: true }, // Cannot be hidden
+  { columnId: 'price', name: 'Price' },
+  { columnId: 'stock', name: 'Stock' },
+];
+
+function MyApp() {
+  // ... (same as above)
+  return (
+    <ColumnChooser
+      columns={columns}
+      visibleColumns={visibleColumns}
+      onVisibilityChange={handleVisibilityChange}
+    />
+  );
+}
+```
+
+The "ID" and "Product Name" columns will have disabled checkboxes and cannot be hidden.
+
+## Angular Usage
+
+In Angular packages, the component uses `@Input()` and `@Output()` decorators:
+
+```typescript
+
+@Component({
+  selector: 'app-my-grid',
+  standalone: true,
+  imports: [ColumnChooserComponent],
+  template: `
+    <ogrid-column-chooser
+      [columns]="columns"
+      [visibleColumns]="visibleColumns"
+      (onVisibilityChange)="handleVisibilityChange($event)"
+    />
+  `
+})
+export class MyGridComponent {
+  columns: IColumnDefinition[] = [
+    { columnId: 'id', name: 'ID', required: true },
+    { columnId: 'name', name: 'Product Name' },
+    { columnId: 'price', name: 'Price' },
+  ];
+
+  visibleColumns = new Set(['id', 'name', 'price']);
+
+  handleVisibilityChange(event: { columnKey: string; visible: boolean }) {
+    if (event.visible) {
+      this.visibleColumns.add(event.columnKey);
+    } else {
+      this.visibleColumns.delete(event.columnKey);
+    }
+    this.visibleColumns = new Set(this.visibleColumns); // Trigger change detection
+  }
+}
+```
+
+## Vue Usage
+
+In Vue packages, the component accepts props via `v-bind` or shorthand `:`:
+
+```vue
+<template>
+  <ColumnChooser
+    :columns="columns"
+    :visible-columns="visibleColumns"
+    @visibility-change="handleVisibilityChange"
+  />
+</template>
+
+<script setup lang="ts">
+
+const columns: IColumnDefinition[] = [
+  { columnId: 'id', name: 'ID', required: true },
+  { columnId: 'name', name: 'Product Name' },
+  { columnId: 'price', name: 'Price' },
+];
+
+const visibleColumns = ref<Set<string>>(new Set(['id', 'name', 'price']));
+
+const handleVisibilityChange = (columnKey: string, visible: boolean) => {
+  if (visible) {
+    visibleColumns.value.add(columnKey);
+  } else {
+    visibleColumns.value.delete(columnKey);
+  }
+  visibleColumns.value = new Set(visibleColumns.value); // Trigger reactivity
+};
+</script>
+```
+
+## Behavior
+
+### Select All / Clear All
+
+The dropdown includes two action buttons:
+- **Select All** — Shows all columns (except those marked as `required: false` — these remain hidden)
+- **Clear All** — Hides all optional columns (required columns remain visible)
+
+### Visual Indicator
+
+The trigger button shows the current visibility count: `"Column Visibility (3 of 5)"`.
+
+### Checkbox States
+
+- **Checked** — Column is visible
+- **Unchecked** — Column is hidden
+- **Disabled + Checked** — Column is required and cannot be hidden
+
+## Accessibility
+
+`ColumnChooser` implements WCAG 2.1 AA standards with full keyboard and screen reader support.
+
+### ARIA Attributes
+
+```html
+<button aria-expanded="false" aria-haspopup="listbox">
+  Column Visibility (3 of 5)
+</button>
+<div role="dialog" aria-label="Column visibility">
+  <input type="checkbox" id="col-name" />
+  <label for="col-name">Product Name</label>
+</div>
+```
+
+| Attribute | Element | Purpose |
+|-----------|---------|---------|
+| `aria-expanded` | Trigger button | Indicates dropdown open/closed state (`"true"` / `"false"`) |
+| `aria-haspopup="listbox"` | Trigger button | Indicates the button triggers a listbox |
+| `role="dialog"` | Dropdown | Identifies the dropdown as a modal dialog |
+| `aria-label="Column visibility"` | Dropdown | Provides context for the dialog |
+| `id` / `for` | Checkbox + label | Associates each checkbox with its label |
+| `disabled` | Checkbox | Indicates required columns that cannot be hidden |
+
+### Keyboard Navigation
+
+- `Enter` / `Space` (on trigger button) — Open/close dropdown
+- `Tab` / `Shift+Tab` — Navigate between checkboxes and action buttons
+- `Space` — Toggle focused checkbox
+- `Enter` (on action buttons) — Execute "Select All" or "Clear All"
+- `Escape` — Close dropdown
+
+### Focus Management
+
+- **Focus trap:** Focus is trapped within the dropdown when open
+- **Focus restoration:** When closing the dropdown, focus returns to the trigger button
+- **Focus visible:** `:focus-visible` styles show 2px solid outline (`--ogrid-accent`)
+
+### Screen Reader Support
+
+Screen readers announce:
+- **Trigger button:** "Column Visibility (3 of 5) button, collapsed/expanded"
+- **Checkbox state:** "Product Name checkbox, checked/unchecked"
+- **Required columns:** "ID checkbox, checked, disabled, required column"
+- **Action buttons:** "Select All button", "Clear All button"
+
+Tested with NVDA, JAWS, VoiceOver, and Narrator.
+
+### High Contrast Mode
+
+- Checkboxes remain visible in high contrast mode
+- Focus indicators use system `Highlight` color
+- Dropdown borders use system `ButtonText` color
+
+See the [Accessibility Guide](/docs/guides/accessibility) for complete documentation.
+
+## Styling
+
+All UI packages provide default styles matching their design system. Styles are scoped to avoid conflicts.
+
+**CSS custom properties** (all packages):
+- `--ogrid-header-bg` — Trigger button and popover background color
+- `--ogrid-border` — Border color
+- `--ogrid-fg` — Foreground text color
+
+## Placement in OGrid
+
+The `columnChooser` prop on `OGrid` controls where the column chooser renders:
+
+- `true` or `'toolbar'` (default) — Renders in the toolbar strip (recommended)
+- `'sidebar'` — Only available via the sidebar columns panel (no toolbar button)
+- `false` — Hidden entirely (useful when you want full control over visibility)
+
+## Related Components
+
+- [DataGridTable](./components-datagrid-table.mdx) — Main grid component
+- [SideBar](./components-sidebar.mdx) — Sidebar with columns panel (alternative placement)
+- [OGrid](./ogrid-props.mdx) — Top-level wrapper that integrates the column chooser
+
+## See Also
+
+- [Column Definition](./column-def.mdx#icolumnmeta) — Column metadata reference
+- [Grid API](./grid-api.mdx) — `getColumnState()` and `applyColumnState()` methods

package/bundled-docs/api/components-column-header-filter.mdx

@@ -0,0 +1,363 @@
+---
+sidebar_position: 11
+title: ColumnHeaderFilter
+---
+
+# ColumnHeaderFilter
+
+A column header component that combines sorting and filtering UI. Displays the column name, sort indicator, and filter icon. Clicking the filter icon opens a popover with filter controls (text input, multi-select checkboxes, people picker, or date range).
+
+## Import
+
+
+<Tabs groupId="framework">
+<TabItem value="react" label="React">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="angular" label="Angular">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="vue" label="Vue">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="js" label="Vanilla JS">
+
+```typescript
+// ColumnHeaderFilter is an internal component in vanilla JS
+```
+
+</TabItem>
+</Tabs>
+
+## Props (React)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columnKey` | `string` | **Required** | Unique column identifier. |
+| `columnName` | `string` | **Required** | Display name shown in the header. |
+| `filterType` | `ColumnFilterType` | **Required** | Filter type: `'none'`, `'text'`, `'multiSelect'`, `'people'`, or `'date'`. |
+| `isSorted` | `boolean` | `false` | Whether this column is currently sorted. |
+| `isSortedDescending` | `boolean` | `false` | Sort direction (only relevant when `isSorted` is true). |
+| `onSort` | `() => void` | `undefined` | Callback when user clicks the header to sort. |
+| `selectedValues` | `string[]` | `[]` | Selected values for multi-select filter. |
+| `onFilterChange` | `(values: string[]) => void` | `undefined` | Callback when multi-select filter is applied. |
+| `options` | `string[]` | `[]` | Available options for multi-select filter. |
+| `isLoadingOptions` | `boolean` | `false` | Loading state for multi-select options. |
+| `textValue` | `string` | `''` | Current text filter value. |
+| `onTextChange` | `(value: string) => void` | `undefined` | Callback when text filter is applied. |
+| `selectedUser` | `UserLike` | `undefined` | Selected user for people filter. |
+| `onUserChange` | `(user: UserLike \| undefined) => void` | `undefined` | Callback when people filter is applied or cleared. |
+| `peopleSearch` | `(query: string) => Promise<UserLike[]>` | `undefined` | Async search function for people picker. |
+| `dateValue` | `IDateFilterValue` | `undefined` | Current date range filter value. |
+| `onDateChange` | `(value: IDateFilterValue \| undefined) => void` | `undefined` | Callback when date filter is applied or cleared. |
+
+## Filter Types
+
+### Text Filter (`filterType: 'text'`)
+
+Shows a text input. The user types a query and clicks "Apply" to filter rows containing the text (case-insensitive).
+
+**Required props:** `textValue`, `onTextChange`
+
+### Multi-Select Filter (`filterType: 'multiSelect'`)
+
+Shows a searchable list of checkboxes. The user selects one or more values and clicks "Apply" to filter rows matching any selected value.
+
+**Required props:** `selectedValues`, `onFilterChange`, `options`
+
+**Optional props:** `isLoadingOptions`
+
+### People Filter (`filterType: 'people'`)
+
+Shows a people picker with async search. The user types a name or email, selects a person from the results, and clicks "Apply" to filter rows assigned to that person.
+
+**Required props:** `selectedUser`, `onUserChange`, `peopleSearch`
+
+### Date Filter (`filterType: 'date'`)
+
+Shows a date range picker with "From" and "To" inputs (ISO `YYYY-MM-DD` format). The user selects a date range and clicks "Apply" to filter rows within that range.
+
+**Required props:** `dateValue`, `onDateChange`
+
+### No Filter (`filterType: 'none'`)
+
+No filter icon is shown. Only the sort indicator is displayed (if the column is sortable).
+
+## Usage
+
+### Text Filter (React)
+
+```tsx
+
+function MyHeader() {
+  const [textValue, setTextValue] = useState('');
+
+  return (
+    <ColumnHeaderFilter
+      columnKey="name"
+      columnName="Product Name"
+      filterType="text"
+      textValue={textValue}
+      onTextChange={setTextValue}
+    />
+  );
+}
+```
+
+### Multi-Select Filter (React)
+
+```tsx
+
+function MyHeader() {
+  const [selectedValues, setSelectedValues] = useState<string[]>([]);
+  const options = ['Active', 'Pending', 'Completed'];
+
+  return (
+    <ColumnHeaderFilter
+      columnKey="status"
+      columnName="Status"
+      filterType="multiSelect"
+      selectedValues={selectedValues}
+      onFilterChange={setSelectedValues}
+      options={options}
+    />
+  );
+}
+```
+
+### People Filter (React)
+
+```tsx
+
+function MyHeader() {
+  const [selectedUser, setSelectedUser] = useState<UserLike | undefined>();
+
+  const searchPeople = async (query: string): Promise<UserLike[]> => {
+    // Call your user directory API
+    const response = await fetch(`/api/users/search?q=${query}`);
+    return response.json();
+  };
+
+  return (
+    <ColumnHeaderFilter
+      columnKey="assignee"
+      columnName="Assigned To"
+      filterType="people"
+      selectedUser={selectedUser}
+      onUserChange={setSelectedUser}
+      peopleSearch={searchPeople}
+    />
+  );
+}
+```
+
+### With Sorting (React)
+
+```tsx
+
+function MyHeader() {
+  const [sortBy, setSortBy] = useState('name');
+  const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');
+
+  const handleSort = () => {
+    if (sortBy === 'name') {
+      setSortDirection(sortDirection === 'asc' ? 'desc' : 'asc');
+    } else {
+      setSortBy('name');
+      setSortDirection('asc');
+    }
+  };
+
+  return (
+    <ColumnHeaderFilter
+      columnKey="name"
+      columnName="Product Name"
+      filterType="text"
+      isSorted={sortBy === 'name'}
+      isSortedDescending={sortDirection === 'desc'}
+      onSort={handleSort}
+      textValue=""
+      onTextChange={() => {}}
+    />
+  );
+}
+```
+
+## Angular Usage
+
+In Angular packages, the component has the same prop interface but uses `@Input()` decorators:
+
+```typescript
+
+@Component({
+  selector: 'app-my-header',
+  standalone: true,
+  imports: [ColumnHeaderFilterComponent],
+  template: `
+    <ogrid-column-header-filter
+      [columnKey]="'status'"
+      [columnName]="'Status'"
+      [filterType]="'multiSelect'"
+      [selectedValues]="selectedValues"
+      (onFilterChange)="handleFilterChange($event)"
+      [options]="options"
+    />
+  `
+})
+export class MyHeaderComponent {
+  selectedValues: string[] = [];
+  options = ['Active', 'Pending', 'Completed'];
+
+  handleFilterChange(values: string[]) {
+    this.selectedValues = values;
+  }
+}
+```
+
+## Vue Usage
+
+In Vue packages, the component accepts props via `v-bind` or shorthand `:`:
+
+```vue
+<template>
+  <ColumnHeaderFilter
+    column-key="status"
+    column-name="Status"
+    filter-type="multiSelect"
+    :selected-values="selectedValues"
+    @filter-change="handleFilterChange"
+    :options="options"
+  />
+</template>
+
+<script setup lang="ts">
+
+const selectedValues = ref<string[]>([]);
+const options = ['Active', 'Pending', 'Completed'];
+
+const handleFilterChange = (values: string[]) => {
+  selectedValues.value = values;
+};
+</script>
+```
+
+## Accessibility
+
+`ColumnHeaderFilter` implements WCAG 2.1 AA standards with full keyboard and screen reader support.
+
+### ARIA Attributes
+
+```html
+<th scope="col">
+  <button aria-label="Sort by Product Name, currently unsorted">
+    Product Name
+  </button>
+  <button aria-label="Filter Product Name" aria-expanded="false" aria-haspopup="dialog">
+    ▼
+  </button>
+</th>
+```
+
+| Attribute | Element | Purpose |
+|-----------|---------|---------|
+| `scope="col"` | `<th>` | Associates header with its column for screen readers |
+| `aria-label` (sort button) | `<button>` | Describes current sort state: "Sort by X, currently unsorted/ascending/descending" |
+| `aria-label` (filter button) | `<button>` | Describes filter action: "Filter X" |
+| `aria-expanded` | Filter button | Indicates popover open/closed state (`"true"` / `"false"`) |
+| `aria-haspopup="dialog"` | Filter button | Indicates the button triggers a dialog |
+| `role="dialog"` | Filter popover | Identifies the popover as a modal dialog |
+| `aria-label` | Filter popover | Provides context: "Filter Product Name" |
+
+### Keyboard Navigation
+
+**Header Interaction:**
+- `Tab` — Move focus to sort button, then filter button
+- `Enter` / `Space` — Activate focused button (toggle sort or open filter)
+- `Shift+Tab` — Move focus backwards
+
+**Filter Popover (All Types):**
+- `Escape` — Close popover without applying changes
+- `Tab` / `Shift+Tab` — Navigate inputs and buttons
+- `Enter` (on Apply button) — Apply filter and close popover
+
+**Text Filter:**
+- Type to enter filter text
+- `Enter` — Apply filter immediately (no button click needed)
+
+**Multi-Select Filter:**
+- `↑` `↓` — Navigate checkbox list
+- `Space` — Toggle focused checkbox
+- `Ctrl+A` — Select all options
+- Type to search options
+
+**People Filter:**
+- Type to search people
+- `↓` — Move to search results list
+- `↑` `↓` — Navigate search results
+- `Enter` — Select focused person
+- `Backspace` — Clear selected person
+
+**Date Filter:**
+- `Tab` — Move between "From" and "To" inputs
+- Type date in `YYYY-MM-DD` format
+- Date picker (if supported): Arrow keys to navigate calendar
+
+### Focus Management
+
+- **Focus trap:** Focus is trapped within the filter popover when open
+- **Focus restoration:** When closing the popover, focus returns to the filter button
+- **Focus visible:** `:focus-visible` styles show 2px solid outline (`--ogrid-accent`) on keyboard navigation
+
+### Screen Reader Support
+
+Screen readers announce:
+- **Header navigation:** "Product Name column header, sortable"
+- **Sort state:** "Sorted by Product Name, ascending"
+- **Filter button:** "Filter Product Name button, collapsed/expanded"
+- **Filter applied:** "Filter applied: Status equals Active"
+- **Filter cleared:** "Filter cleared from Status column"
+
+Tested with NVDA, JAWS, VoiceOver, and Narrator.
+
+### High Contrast Mode
+
+- Filter icons remain visible in high contrast mode
+- Focus indicators use system `Highlight` color
+- Popover borders use system `ButtonText` color
+
+See the [Accessibility Guide](/docs/guides/accessibility) for complete documentation.
+
+## Styling
+
+All UI packages provide default styles matching their design system (Radix UI, Fluent UI, Material UI, PrimeNG, Vuetify, PrimeVue). Styles are scoped to avoid conflicts.
+
+**CSS custom properties** (all packages):
+- `--ogrid-header-bg` — Header background color
+- `--ogrid-border` — Border color
+- `--ogrid-fg` — Foreground text color
+
+## Related Components
+
+- [DataGridTable](./components-datagrid-table.mdx) — Main grid component that renders column headers
+- [ColumnChooser](./components-column-chooser.mdx) — Column visibility dropdown
+- [Types: FilterValue](./types.mdx#filtervalue) — Filter value discriminated union
+
+## See Also
+
+- [Column Definition](./column-def.mdx#icolumnfilterdef) — Filter configuration reference
+- [Filtering Feature Guide](/docs/features/filtering) — Complete filtering documentation